veronica
12d5258e20
A - docs/README.md:149-190 rewritten. It prescribed a competing front-matter schema
(title/type/audience/status/source_of_truth) adopted by 4 of 128 live documents. Two
documented conventions in one repo is the defect this pass removes, so the README now
documents the contract and the 4 files convert in the same commit: `type` dropped
(kind replaces it), `title`/`audience`/`source_of_truth` kept.
B - source-of-truth leaves the kind enum, which is now 6 values, and returns as an orthogonal
boolean. kind was carrying two independent facts. docs/requirements/native-kanban-sot.md
is stamped `kind: spec` + `source_of_truth: true`, which is what it always was.
C - status gains `completed`. Applied to the two executed plans, on artifact evidence rather
than on their own say-so: --purpose push|merge ships in ci-queue-wait.sh, and every section
the README plan specifies exists in docs/README.md today.
D - kind follows content, never filename. docs/native-kanban-sot/TASKS.md is `kind: spec`
because its body says "a build plan, not a task tracker". The name stays wrong; that is a
rename and it is out of scope here.
E - the contract covers .md only, written into the README as a decision with vision's
YAML.parse measurement as the reason, so the omission does not read as an oversight.
F - channel-protocol.md guide -> spec. Applied, with a correction the reviewer should see: the
ruling cites "7 normative MUSTs" and there are ZERO uppercase RFC2119 terms in that file.
Control: the identical grep returns 25 lines in docs/requirements/native-kanban-sot.md. The
citation half of the finding does hold and is larger than stated. Consequence recorded in
the worklist: the file's own banner now contradicts its header.
Verified: 128 live .md under docs/ (127 baseline + this PR's worklist), 107 stamped, 0 invalid
kinds, 17 operator-held + 3 supersede-stamp deferrals + 1 generated = 21 unstamped. 107+21=128.
Control: the verifier reports valid=False when a kind is corrupted to `nonsense`, so the
0-invalid result is a real result. prettier --check clean across docs/.
kind, status
| kind | status |
|---|---|
| guide | active |
Administrator Guide
Status: Partially migrated. Current SSO and local upgrade/recovery procedures are available; held procedures are labeled non-operative.
This book is the canonical home for installation, configuration, deployment, routine operations, security controls, incident response, and recovery. User workflows belong in USER-GUIDE/; implementation and contributor material belongs in DEVELOPER-GUIDE/.
Start here
- Documentation atlas — placement rules and source-of-truth boundaries.
- Documentation sitemap — resolvable current navigation and authority-gated migration summary.
- Product requirements — normative requirements, currently marked draft.
- Operations index — current local procedures and explicitly held operational outlines.
- Security index — current SSO provider configuration.
Chapter map
| Chapter | Scope | Status |
|---|---|---|
installation/ |
Prerequisites, installation, and first deployment. | Scaffold only. |
configuration/ |
Environment, provider, tier, and runtime configuration. | Scaffold only. |
deployment/ |
Topologies, rollout, migration, and upgrade procedures. | Scaffold only. |
operations/ |
Health, observability, routine operation, and maintenance. | Local upgrade/recovery is current; connector lease operations are held. |
security/ |
Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned. |
recovery/ |
Incident response, backup, rollback, and recovery. | Scaffold only. |
Every promoted page must be added to this index and to SITEMAP.md in the same migration slice.
Evidence — not current operator guidance
P8-003 performance report— 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:
_old_structure/guides/admin-guide.md— quarantined historical source; verify claims before promotion._old_structure/guides/deployment.md— quarantined historical source; deployment commands and assumptions remain held.- See the documentation catalog for file-level dispositions.
Do not treat a migration candidate as current until its commands, paths, permissions, and safety status are checked against source and tests.
Authoring boundary
New administrator documentation belongs under one of the chapter directories above. Operationally sensitive pages must identify prerequisites, ownership, source-of-truth dependencies, and whether any procedure is current, illustrative, held, or non-operative.