mosaicstack/stack
1
0
Fork 1
Code Issues 246 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
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.