docs: migrate performance evidence report
This commit is contained in:
Jason Woltje
@@ -23,12 +23,15 @@ This book is the canonical home for installation, configuration, deployment, rou
|
||||
|
||||
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
|
||||
|
||||
## Evidence — not current operator guidance
|
||||
|
||||
- [`P8-003 performance report`](../reports/qa/p8-003-performance-optimization.md) — historical performance evidence; implementation alignment is partial, and production metrics remain unverified. It is not an operational SLO or runbook.
|
||||
|
||||
## Migration backlog — not current operator guidance
|
||||
|
||||
These are source candidates, not verified runbooks:
|
||||
|
||||
- [`SSO-PROVIDERS.md`](../SSO-PROVIDERS.md) — partially verified; its documented web feature flags conflict with current dynamic provider discovery.
|
||||
- [`PERFORMANCE.md`](../PERFORMANCE.md) — historical performance evidence, not an operational SLO or runbook.
|
||||
- [`_old_structure/guides/admin-guide.md`](../_old_structure/guides/admin-guide.md) — historical source; verify claims before promotion.
|
||||
- [`_old_structure/guides/deployment.md`](../_old_structure/guides/deployment.md) — historical source; verify commands and deployment assumptions before promotion.
|
||||
|
||||
|
||||
+5
-5
@@ -192,10 +192,10 @@ For every documentation change:
|
||||
|
||||
## Migration policy
|
||||
|
||||
This initial pass defines the target structure only. It does not move or rewrite the existing documentation set.
|
||||
The initial structure pass defined the target structure without moving or rewriting the existing documentation set. Subsequent migration slices may move or rewrite classified pages deliberately, with repository references and indexes updated together.
|
||||
|
||||
- Treat `_old_structure/` as read-only migration quarantine. Do not add new content there.
|
||||
- Treat the current root-level legacy pages (`QUICKSTART.md`, `PERFORMANCE.md`, `SSO-PROVIDERS.md`, `openapi-tess.yaml`, and the task/mission documents) as migration backlog, not permission to create more root files.
|
||||
- Treat the current root-level legacy pages (`QUICKSTART.md`, `SSO-PROVIDERS.md`, `openapi-tess.yaml`, and the task/mission documents) as migration backlog, not permission to create more root files. Historical evidence such as the P8-003 performance report belongs under `reports/qa/`.
|
||||
- Candidate destinations include `USER-GUIDE/getting-started/`, `ADMIN-GUIDE/security/`, `DEVELOPER-GUIDE/architecture/`, `API/`, `tasks/`, `plans/`, and `archive/`; classify each page before moving it.
|
||||
- Existing source code and tests still reference legacy paths such as `docs/fleet/` and `docs/federation/`. Update those references deliberately as part of the relevant migration slice; do not delete a referenced path blindly.
|
||||
- When a page is moved, update all repository links, source comments, tests, book indexes, and `SITEMAP.md` in the same logical change.
|
||||
@@ -205,12 +205,12 @@ This initial pass defines the target structure only. It does not move or rewrite
|
||||
|
||||
## Current transition state
|
||||
|
||||
The structure is being established before content migration. During this transition:
|
||||
The structure is being established incrementally while classified content migration proceeds. During this transition:
|
||||
|
||||
- The target directories listed above are a blueprint; not all indexes or chapters exist yet.
|
||||
- `docs/_old_structure/` remains available for reference but is not current documentation.
|
||||
- Existing root documentation files remain until their migration destinations are reviewed.
|
||||
- `docs/SITEMAP.md` still contains legacy paths and will be refreshed as pages are migrated.
|
||||
- Existing root documentation files remain until their migration destinations are reviewed; migrated pages must leave a verified navigation path.
|
||||
- `docs/SITEMAP.md` has current scaffold entry points but still contains legacy paths and will be refreshed as pages are migrated.
|
||||
- No external publishing platform is assumed. The canonical source remains this repository under `docs/`.
|
||||
|
||||
## Non-goals for this pass
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
- [Architecture index](DEVELOPER-GUIDE/architecture/README.md) — scaffold for system design, decisions, and RFCs.
|
||||
- [API documentation index](API/README.md) — scaffold for the consolidated gateway contract.
|
||||
- [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations.
|
||||
- [P8-003 performance report](reports/qa/p8-003-performance-optimization.md) — historical performance evidence; not a current SLO or runbook.
|
||||
|
||||
Canonical pages added to a book must be linked from that book's README and this section. Replace or retire legacy entries only after the associated migration slice verifies repository references and claim status.
|
||||
|
||||
|
||||
@@ -19,6 +19,7 @@
|
||||
- [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.
|
||||
|
||||
## Initial findings
|
||||
|
||||
@@ -33,6 +34,7 @@
|
||||
- `.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.
|
||||
|
||||
## Method
|
||||
|
||||
@@ -52,15 +54,17 @@
|
||||
|
||||
## 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 |
|
||||
| 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 |
|
||||
|
||||
Reference in New Issue
Block a user