report truth (Session C1): byDepth, domainCounts, changeDetection, docPathsUnknown + reconcile-docs (F-455, F-454, F-451, F-459; plugin 0.40.0)

[BradleyDB]

Base branch: dev. Regenerated output: the five derived generators reproduce the committed generated set byte-for-byte (the full npm run build at the pinned CLI moves only the catalog's wall-clock generatedAt stamp, which was restored — it changes only on a CLI adoption).

What

Session C1 of the September rounds (handoff plan items RP-1, RP-2, RP-3, RP-5): the report is the account of KB state, and it now carries depth, domain counts, change-detection honesty and doc_path truth. Plugin 0.40.0.

• RP-1 · F-455 — manifest.mjs report carries byDepth = { full, metadata, listOnly, unrecorded } over documented entries, in total and per domain under a new domains.<domain> row (ruling: four states, per-domain block; a stub under a domain with no describe recording is unrecorded, never folded into metadata — the F-346 false-complete class; nothing new inside byDomain rows because describe-batch's progress probe sums them). One helper, describeStateOf, is now shared by the stub banner and the report. Setup's Phase 5 close, --deep relay, Phase 6 precondition and final report, and the budget-report shapes, quote ONE report invocation at a quiescent point instead of narrating.
• RP-2 · F-454 — domainCounts: { indexed, withAssets, empty }; the Phase 4 relay quotes indexed, names every emptyDomains entry, and names a stamped: false domain separately instead of counting byDomain keys.
• RP-3 · F-451 — per domain changeDetection: "date" | "none" | "unrecorded" (T-2's dateField tri-state; a legacy no-key stamp is never read as none) and datelessEntries; refresh's report ends with a Not checked for change this run: block naming every such domain and count, or the word none — never silence. Honest statement only; fingerprint-based staleness stays Deep ingest performance: concurrent describes + batched marks to fit a full run inside one token lifetime #12.
• RP-5 · F-459 — mark --status documented refuses an entry with no recorded doc_path when none is passed (and a blank value as malformed); report and remove carry docPathsUnknown; new verb reconcile-docs --domain <d> [--dir] [--out] [--dry-run] backfills doc_path from the docs on disk through doc-lib's docNameMatcher — the claimer's read-side twin, both resolving through ONE private resolveStem and both claiming — and names recorded-missing, unmatched and orphan files; it refuses, before any write, a working directory the recorded paths do not resolve from. The reconcile-on-resume step Deep ingest performance: concurrent describes + batched marks to fit a full run inside one token lifetime #12 will reuse.
• Contract: report's output is T-2 v3 (GsReport in manifest.mjs's header), additive, pinned by test/contract-conformance.mjs. docPathFor in doc-lib is the one doc_path spelling (stub, describe-batch, the template writer, reconcile).

Why

• F-455 (rank 4): the user was told a deep crawl had finished while eight domains were entirely stubs, and the report held no fact that could contradict the claim — documented asserted completeness from a status that describes doc existence, not depth (Class: outcome-from-proxy, all four).
• F-454 (polish): the relay's domain count came from a fold over entries, which drops every listed-but-empty domain.
• F-451 (rank 6): nearly half of one production inventory sits outside change detection, and the refresh report said "Unchanged" for rows it could not compare.
• F-459 (normal): documented entries with no recorded doc path are invisible to every path consumer, and a cleanup list read 0 where the truth was unknown — 20 such entries on the sandbox today (down from the 25 logged; the B-V round re-marked five), zero on prod.

Design rulings (Bradley, 2026-09-15, in the bus Fix notes and the plan's As-shipped notes): four-state byDepth in a per-domain block; refuse in mark, count in report and remove, backfill as its own verb — report stays read-only.

Review notes

• Measured locally, read-only, over both real manifests in the consumer workspace: prod reads six list-only domains as listOnly (722 entries), none as metadata, report 1754 dateless under none (2362 across five recorded-none domains); the sandbox reads domainCounts 18/17/1 with its surveys domain empty, five legacy stamps unrecorded, 557 dateless templates under date, docPathsUnknown 20 across three domains. Neither manifest was written.

• Fixtures: test/manifest-ops.mjs "c1" section (42 arms over a manifest carrying all four states, a pre-depth doc, an empty stamp, a legacy stamp, a partial registration; the refusal incl. all-or-nothing and blank-value arms; remove's count; reconcile over a scratch folder — matched, the Co/co collision pair, recorded-missing, unmatched, orphans, dry-run, --out, idempotent re-run, missing folder, CWD-mismatch refusal, win32 folder case); 27 of the original 35 red against the pre-fix script (the rest rig setup and controls). test/doc-lib-fixtures.mjs +18 (matcher, deleted-partner, .MD agreement, docPathFor). test/contract-conformance.mjs +10 (T-2 v3 key sets, byDomain numbers-only, remove's keys). test/relationships-build.mjs and the older manifest-ops arms pass --doc-path on their hand-run marks — the closed route.

• /code-review medium (8 finders + 5 file-batched verifiers): 16 findings, all fixed on the branch — the F-459 Fix note lists them; the matcher's missing claim on a null read (a deleted doc's collision partner as an orphan) was the one real bug.

• Verbatim battery from validate-plugin.yml and docs-drift.yml: 0 failures locally (npm ci + npm run typecheck included); both claude plugin validate … --strict pass; derived generators reproduce the committed output.

• Banked arm (dev/VALIDATION.md, Session C1): F-459 — the tester's reconcile-docs over the three sandbox domains, docPathsUnknown 20 → 0 with every orphan named; report reads over both real manifests; setup and refresh walks (both slash-only).

• Carried, not built: a manifest quiescence sequence (save() counter echoed by report) would make "quoted at a quiescent point" checkable rather than prose; upsert-batch's unchanged folds dateless rows in (named in the F-451 sweep). Draft PR change-request: a Before-building read, and the admin's job in the operating model (plugin 0.39.0) #17 stages 0.39.0 and rebases its bump.

• Plugin version bumped in .claude-plugin/plugin.json with a CHANGELOG entry (user-visible plugin change).

• Safety boundary: this PR does not touch hooks/gs-admin-guard.mjs or ask-rules generation.

• Skill edits: cross-document consistency checked (operating model, managed CLAUDE.md block and the cheatsheet renderer state nothing about report's fields; setup, its mechanics reference, refresh, MAINTAINERS and the CHANGELOG agree), and the changed skills are walked in the tester round (Session C1-V): setup and refresh, both slash-only. Session / verdict: C1-V, pending.

• No test or dev step touched real gs-admin state (~/.gs-admin/, live tenants) — fixtures only; the two real manifests were read, never written.

• No tenant/instance/org-specific data in commit messages or this PR body.