mosaicstack/stack
1
0
Fork 1
Code Issues 245 Pull Requests 7 Actions Packages Projects Releases 15 Wiki Activity

docs: track canonical reports normally

Browse Source
This commit is contained in:
Jason Woltje
2026-08-10 17:51:06 -05:00
parent 2082ac061b
commit 306985990c
3 changed files with 16 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
-1
View File
@@ -9,7 +9,6 @@ coverage
*.tsbuildinfo
.pnpm-store
__pycache__/
docs/reports/
docs/.obsidian
# Step-CA dev password — real file is gitignored; commit only the .example
docs/reports/documentation/2026-08-10-docs-catalog-audit.md
+12 -12
View File
@@ -7,7 +7,7 @@
## Executive summary
- **283 baseline documentation artifacts** are cataloged: 11 current root files, 269 files under `docs/_old_structure/`, two prior plans, and one prior scratchpad. The three DOCS-IA-002 artifacts are listed separately.
- `.gitignore` currently ignores `docs/reports/`, conflicting with the documentation contract. This report must be force-added, and the ignore policy needs a separate remediation decision.
- At the audit baseline, `.gitignore` ignored `docs/reports/`, conflicting with the documentation contract. The migration subsequently removed that blanket rule so canonical reports can be tracked normally.
- The current navigation surface contains **97 internal links, 83 legacy/unresolved links**, plus 2 intentional future blueprint wikilinks in the new `docs/README.md`.
- The historical archive contains **122 links, 12 unresolved links**. These do not represent current navigation, but they matter if pages are promoted again.
- The current broken-link problem is concentrated in `docs/SITEMAP.md` (66), `docs/MISSION-MANIFEST.md` (7), `docs/TASKS.md` (7), and `docs/PRD.md` (3).
@@ -58,7 +58,7 @@ A document can have two labels, such as `partially-verified/contradicted`, when
- `docs/plans/2026-08-10-docs-catalog-audit.md` — approved audit method and evidence statuses.
- `docs/scratchpads/DOCS-IA-002-catalog-audit.md` — active audit progress and command log.
- `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` — this human-readable report; it is force-added because `docs/reports/` is currently ignored.
- `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` — this human-readable report; it required force-add at the audit baseline, before the blanket report ignore rule was removed.
- These artifacts are current working/evidence documentation and must not be mistaken for product requirements or shipped behavior.
## Archived catalog by category
@@ -472,15 +472,15 @@ High-risk consumers include `packages/mosaic/src/commands/fleet.ts`, fleet path-
## Truth-audit evidence collected
| Surface | Evidence | Result |
| --------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| SSO provider environment contract | `packages/auth/src/sso.ts`, auth tests, `.env.example` | Provider core names and partial-config behavior align; web feature-flag claim does not. |
| SSO web flow | `apps/web` login/provider pages and `/api/sso/providers` calls | Dynamic provider discovery is current; `NEXT_PUBLIC_*_ENABLED` documentation is stale. |
| Performance report | Seven named implementation files exist; DB pool, upsert, indexes, GC, and Next config markers found | Static implementation alignment is partial; performance metrics and production traffic are unverified. |
| Tess OpenAPI | PyYAML parse of `docs/openapi-tess.yaml` | Valid OpenAPI 3.1 syntax with 17 paths; legacy location and incomplete full-gateway coverage remain. |
| TUI documents | `packages/cli` and old worktree absent; `packages/mosaic/src/tui` exists | TUI document paths are contradicted/stale. |
| Root navigation | Relative link resolver and repository reference scan | Current docs and code still depend on pre-archive paths. |
| Documentation root hygiene | `.gitignore` line 12 and `guides/DOCUMENTATION.md` | `docs/reports/` is required for evidence but ignored for new files; this audit report requires a force-add until the policy is remediated. |
| Surface | Evidence | Result |
| --------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| SSO provider environment contract | `packages/auth/src/sso.ts`, auth tests, `.env.example` | Provider core names and partial-config behavior align; web feature-flag claim does not. |
| SSO web flow | `apps/web` login/provider pages and `/api/sso/providers` calls | Dynamic provider discovery is current; `NEXT_PUBLIC_*_ENABLED` documentation is stale. |
| Performance report | Seven named implementation files exist; DB pool, upsert, indexes, GC, and Next config markers found | Static implementation alignment is partial; performance metrics and production traffic are unverified. |
| Tess OpenAPI | PyYAML parse of `docs/openapi-tess.yaml` | Valid OpenAPI 3.1 syntax with 17 paths; legacy location and incomplete full-gateway coverage remain. |
| TUI documents | `packages/cli` and old worktree absent; `packages/mosaic/src/tui` exists | TUI document paths are contradicted/stale. |
| Root navigation | Relative link resolver and repository reference scan | Current docs and code still depend on pre-archive paths. |
| Documentation root hygiene | Baseline `.gitignore` and `guides/DOCUMENTATION.md` | `docs/reports/` is required for evidence; the conflicting blanket ignore rule was identified and subsequently removed. |
## Recommended migration order
@@ -507,7 +507,7 @@ The following decisions require product-owner or maintainer confirmation rather
- This is a static repository audit. It did not start Gateway/Web, PostgreSQL, Valkey, Compose, or external identity providers.
- No external agent session was used because the existing fleet sessions were explicitly standing down; parallel discovery was performed with isolated read-only scans in this coordinating session.
- `docs/reports/` is currently ignored by `.gitignore`; the report must be force-added and the ignore rule should be addressed in a separate, explicitly scoped change.
- At the audit baseline, `docs/reports/` was ignored by `.gitignore` and this report required force-add. The migration subsequently removed the blanket ignore rule.
- “Historical/unverified” does not mean the original author was wrong; it means the page is not safe to treat as current without evidence.
- Claims involving production topology, external services, latency, security certification, or merged PR state need independent evidence beyond file presence.
docs/scratchpads/DOCS-IA-002-catalog-audit.md
+4 -3
View File
@@ -51,6 +51,7 @@ The four isolated worktrees were clean and removed after report collection.
- [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, security, mutator-gate, and compaction-revocation contracts with their navigation and acceptance-test consumers.
- [x] Remove the blanket `docs/reports/` ignore rule so canonical evidence can be staged and linted normally.
## Initial findings
@@ -62,7 +63,7 @@ The four isolated worktrees were clean and removed after report collection.
- 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 baseline `.gitignore` ignored `docs/reports/`, conflicting with the new documentation contract and lint-staged. The blanket rule is now removed so canonical evidence can be tracked normally.
- 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.
@@ -97,8 +98,8 @@ The four isolated worktrees were clean and removed after report collection.
| 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 |
| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; baseline ignored-path conflict was identified and later resolved |
| Commit hook behavior | RESOLVED — lint-staged exposed the blanket `docs/reports/` ignore conflict; the rule was removed and report paths can now be staged normally |
| 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 |