DOCS-IA-002 — Documentation Catalog and Truth Audit

Task: DOCS-IA-002
Internal reference: TASKS:DOCS-IA-002
Plan: docs/plans/2026-08-10-docs-catalog-audit.md
Objective: Catalog all documentation and audit validity/truthfulness before migration.
Mode: Read-only discovery; coordinator reconciles findings.

Parallel Pi audit lanes — 2026-08-10

All lanes used pi --model openai-codex/gpt-5.6-luna:max in detached worktrees with only read and bash tools. No lane edited files, staged changes, committed, or started services.

Lane	Assignment	Outcome
`docs-prd`	Audit `docs/PRD.md`, linked workstream documents, requirements claims, and package/source alignment.	Completed. PRD remains draft/normative; broken fleet/Kanban links and held/contradicted claims require human disposition before promotion.
`docs-api`	Compare `docs/openapi-tess.yaml` with gateway controllers, routes, DTOs, auth guards, and tests.	Completed. Tess contract is scoped and incomplete for the gateway; API migration requires a full route/schema/auth/error inventory and human scope decision.
`docs-control`	Audit `docs/MISSION-MANIFEST.md` and `docs/TASKS.md` without changing orchestrator-owned state.	Completed. Active versus historical MVP/workstream status is unresolved; status, archive/rehome, and control-plane repairs remain orchestrator/human-owned.
`docs-source`	Map live consumers of `docs/fleet`, `docs/federation`, `docs/architecture`, `docs/tess`, and `docs/native-kanban-sot`.	Completed. Legacy roots are absent from current `docs/`; architecture/fleet have source/test consumers, while Tess/Kanban are primarily control-plane/navigation dependencies. Recommended order starts with authority decisions, then architecture security, fleet consumers, and API/Tess migration.

The four isolated worktrees were clean and removed after report collection.

Progress

Confirmed external fleet sessions are standing down; no shared agent session was repurposed.
Established parallel read-only discovery lanes.
Counted current and archived documentation files.
Ran initial link audit.
Complete corrected code-surface audit.
Complete truth triage probes.
Write human-readable catalog/audit report.
Verify report formatting and scope.
Commit audit artifacts without unrelated working-tree changes.
Scaffold audience, architecture, and API indexes without moving legacy content.
Add current scaffold entry points to SITEMAP.md without rewriting its legacy sections.
Select the P8-003 performance report as the first low-risk migration slice.
Archive the contradicted TUI PRD/task pair with unchanged content and an explicit archive index.
Create and promote the verified user quickstart from the empty root placeholder.
Rewrite and promote the SSO administrator runbook from current auth/web source evidence.

Initial findings

Baseline inventory: 283 documentation artifacts — 11 current root files, 269 archived files, two prior plans, and one prior scratchpad; current audit artifacts are listed separately.
Archived inventory: 269 files under docs/_old_structure/, moved unchanged by commit cd4409a.
Initial link scan: 219 internal relative links/wikilinks, 98 unresolved under the baseline checkout; 83 current legacy links remain after excluding two intentional README blueprint links, and 12 archive links are unresolved.
31 source/test/framework files reference legacy documentation roots such as docs/fleet/, docs/federation/, or docs/architecture/.
docs/QUICKSTART.md is empty; docs/SITEMAP.md has 66 broken current links; docs/PRD.md, docs/TASKS.md, and docs/MISSION-MANIFEST.md retain broken pre-archive references.
SSO provider environment names and partial-config behavior align with packages/auth, but the documented NEXT_PUBLIC_*_ENABLED web flow is stale against dynamic /api/sso/providers discovery.
TUI documents reference missing packages/cli and a missing historical worktree; current TUI code is under packages/mosaic.
docs/openapi-tess.yaml parses as OpenAPI 3.1 with 17 paths, but remains a legacy root-level Tess-scoped contract rather than the full API SSOT.
.gitignore ignores docs/reports/, conflicting with the new documentation contract; the audit report must be force-added and ignore remediation deferred to a separate change.
The scaffold slice adds USER-GUIDE/README.md, ADMIN-GUIDE/README.md, ADMIN-GUIDE/security/README.md, DEVELOPER-GUIDE/README.md, DEVELOPER-GUIDE/architecture/README.md, and API/README.md; legacy pages remain unchanged.
SITEMAP.md now has a labeled current-structure section; its legacy sections remain unchanged and explicitly transitional.
docs/PERFORMANCE.md had no live source/test dependency or internal links; it moved unchanged to docs/reports/qa/p8-003-performance-optimization.md. The admin index and current sitemap now classify it as historical evidence, not an operator runbook.
PRD-TUI_Improvements.md and TASKS-TUI_Improvements.md had no live source/test dependencies beyond their internal relative link; both moved unchanged to docs/archive/tui/, and docs/archive/README.md labels them historical.
The empty docs/QUICKSTART.md placeholder was replaced by docs/USER-GUIDE/getting-started/quickstart.md, based on verified installer, wizard, CLI, and runtime-safety behavior. The page explicitly excludes held PostgreSQL/source-checkout routes.
The SSO guide now documents Authentik/WorkOS/Keycloak discovery, OIDC callbacks, Keycloak SAML fallback, partial-config failures, and the absence of frontend feature flags. The root guide and stale .env.example flags were removed.

Method

Resolve relative Markdown links from the source page directory.
Resolve wikilinks from the docs/ vault root.
Compare document claims to current source, package manifests, tests, configuration, and executable paths.
Treat normative PRDs and plans as intent, not shipped behavior.
Treat archived material as historical unless current source/tests demonstrate it remains operative.

Risks and blockers

docs/SITEMAP.md, docs/PRD.md, task manifests, and source/tests still contain legacy paths.
Historical documents may contain commands or security claims that are unsafe if resurfaced as current guidance.
Truth audit is static unless a claim can be verified without starting held services or violating database/runtime safety rules.
docs/TASKS.md is single-writer orchestrator state and will not be edited by this task.
The pre-existing 9a1cc63 commit removed docs/GETTING_STARTED.md and added the .obsidian ignore rule before this audit commit; that state is not attributed to this task.

Verification log

Check	Result
File inventory	PASS — 11 root files, 269 archived files, plus task artifacts
Initial link audit	FINDING — 219 links, 98 unresolved
Code-surface audit	PASS — corrected manifest/script and legacy-reference scans; first attempt was discarded due to a `require()` path bug
Truth probes	PASS — root docs, SSO, performance, TUI, OpenAPI, and source-path evidence triaged
Final report	Written — `docs/reports/documentation/2026-08-10-docs-catalog-audit.md`
Scoped commit	PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit
Report formatting and scope	PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; ignored report path identified and force-add is required
Commit hook behavior	FINDING — lint-staged emitted an ignored `docs/reports` path error during commit even though the report was force-staged; remediation remains open
Index scaffold	PASS — six indexes formatted, all new Markdown/wikilinks resolve, and target directories exist; legacy pages were not changed
Sitemap scaffold	PASS — additive current section is formatted, all seven links resolve, and legacy sections are unchanged
First migration selection	PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move
P8-003 migration	PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit
TUI archive migration	PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit
Quickstart migration	PASS — current page content is source-checked, held routes are labeled, navigation resolves, root placeholder is removed, and formatting passes
SSO migration	PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired
Parallel Pi audits	PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported

12 KiB Raw Blame History