# 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 - [x] Confirmed external fleet sessions are standing down; no shared agent session was repurposed. - [x] Established parallel read-only discovery lanes. - [x] Counted current and archived documentation files. - [x] Ran initial link audit. - [x] Complete corrected code-surface audit. - [x] Complete truth triage probes. - [x] Write human-readable catalog/audit report. - [x] Verify report formatting and scope. - [x] Commit audit artifacts without unrelated working-tree changes. - [x] Scaffold audience, architecture, and API indexes without moving legacy content. - [x] Add current scaffold entry points to `SITEMAP.md` without rewriting its legacy sections. - [x] Select the P8-003 performance report as the first low-risk migration slice. - [x] Archive the contradicted TUI PRD/task pair with unchanged content and an explicit archive index. - [x] Create and promote the verified user quickstart from the empty root placeholder. - [x] Rewrite and promote the SSO administrator runbook from current auth/web source evidence. - [x] Promote the lease-broker protocol and compaction-revocation contracts with their acceptance-test path consumers. ## 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. - The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract paths without changing runtime behavior. ## 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 | | Lease-broker architecture | PASS — two contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed |