diff --git a/docs/SITEMAP.md b/docs/SITEMAP.md index 72f83cad..73a49354 100644 --- a/docs/SITEMAP.md +++ b/docs/SITEMAP.md @@ -14,6 +14,7 @@ - [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny tool authorization and launch choke point. - [Compaction revocation lifecycle](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — Claude/Pi lifecycle observers, generation fencing, and residual boundary. - [API documentation index](API/README.md) — scaffold for the consolidated gateway contract. +- [Reports index](reports/README.md) — review, audit, QA, security, and retained evidence. - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations. - [User quickstart](USER-GUIDE/getting-started/quickstart.md) — installed-CLI first-use path. - [SSO provider runbook](ADMIN-GUIDE/security/sso-providers.md) — current Authentik, WorkOS, and Keycloak configuration. diff --git a/docs/reports/README.md b/docs/reports/README.md new file mode 100644 index 00000000..7ee9c8ec --- /dev/null +++ b/docs/reports/README.md @@ -0,0 +1,36 @@ +# Documentation Reports + +> **Status:** Current evidence index. Reports record reviews, tests, audits, and deferred findings; they are not requirements or operational instructions by themselves. + +Use the canonical guide, API contract, source, and tests to determine current behavior. A report retains the scope and verdict of its original review unless a later report explicitly supersedes it. + +## Documentation evidence + +- [Documentation catalog and truth audit](documentation/2026-08-10-docs-catalog-audit.md) — migration inventory and static truth assessment. +- [Issue #756 documentation checklist](documentation/756-discord-plugin-checklist.md) — historical completion checklist for the official Discord plugin workstream. + +## Code-review evidence + +- [Issue #756 independent code review](code-review/756-code-review.md) — historical exact-scope review of the official Discord plugin workstream. + +## Security evidence + +- [Issue #756 security review](security/756-security-review.md) — historical security review of Discord ingress, authorization, routing, and residual risks. + +## QA evidence + +- [P8-003 performance optimization report](qa/p8-003-performance-optimization.md) — historical implementation evidence; not a current SLO or production benchmark. + +## Retention rules + +- Preserve report wording and verdicts when migrating historical evidence. +- Keep the reviewed commit, issue, scope, and date visible when present. +- Do not treat an old approval as approval of later code. +- Link each tracked report from this index or an explicitly scoped child index. +- Put current operator procedures in the administrator guide, not in reports. + +## Related + +- [[README|Documentation contract]] +- [[SITEMAP|Documentation sitemap]] +- [[archive/README|Documentation archive]] diff --git a/docs/_old_structure/reports/code-review/756-code-review.md b/docs/reports/code-review/756-code-review.md similarity index 100% rename from docs/_old_structure/reports/code-review/756-code-review.md rename to docs/reports/code-review/756-code-review.md diff --git a/docs/_old_structure/reports/documentation/756-discord-plugin-checklist.md b/docs/reports/documentation/756-discord-plugin-checklist.md similarity index 100% rename from docs/_old_structure/reports/documentation/756-discord-plugin-checklist.md rename to docs/reports/documentation/756-discord-plugin-checklist.md diff --git a/docs/_old_structure/reports/security/756-security-review.md b/docs/reports/security/756-security-review.md similarity index 100% rename from docs/_old_structure/reports/security/756-security-review.md rename to docs/reports/security/756-security-review.md diff --git a/docs/scratchpads/DOCS-IA-002-catalog-audit.md b/docs/scratchpads/DOCS-IA-002-catalog-audit.md index eda26478..0caa35f2 100644 --- a/docs/scratchpads/DOCS-IA-002-catalog-audit.md +++ b/docs/scratchpads/DOCS-IA-002-catalog-audit.md @@ -52,6 +52,7 @@ The four isolated worktrees were clean and removed after report collection. - [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. +- [x] Migrate the three-file #756 Discord evidence batch byte-identically and add a reports index. ## Initial findings @@ -71,6 +72,7 @@ The four isolated worktrees were clean and removed after report collection. - 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, security, mutator-gate, and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract family without changing runtime behavior. +- The #756 Discord code-review, security-review, and documentation-checklist reports had no source/test consumers and moved byte-identically to their canonical report categories. `docs/reports/README.md` labels their historical evidence boundary. ## Method @@ -109,3 +111,4 @@ The four isolated worktrees were clean and removed after report collection. | 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 — four contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed | +| #756 evidence migration | PASS — three reports moved byte-identically by SHA-256, no source/test consumers found, reports index and sitemap updated |