61 lines
5.1 KiB
Markdown
61 lines
5.1 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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 |
|