veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
4.6 KiB
kind, status
| kind | status |
|---|---|
| guide | active |
Deployment Guide
Status: non-operative for PostgreSQL, federated, and bare-metal production. The checked-in Compose PostgreSQL service mounts legacy initialization SQL and the KBN-101 bootstrap, runner, secret-renderer, and process-exec interfaces do not exist yet. This page does not authorize a production deployment, database initialization, manual DDL, secret provisioning, or service activation.
Current safe local route
Use PGlite only for current in-process data-layer work; it requires no PostgreSQL. A Gateway/Web local process is held because its unguarded dotenv loader can inherit a daemon PostgreSQL DSN and reach runtime DDL. If a local queue service is useful, start only Valkey:
docker compose up -d valkey
This command intentionally does not start PostgreSQL. Do not run a broad Compose start, use its PostgreSQL initialization mount, infer that current Compose is a production/federated route, or start Gateway/Web until KBN-101-02 supplies fail-closed local-tier/DSN isolation.
Held future procedure
PostgreSQL local, federated, Compose, and bare-metal production activation are held until these artifacts land and pass their independent gates:
- KBN-101-00 external privileged bootstrap artifact;
- KBN-101-03 sole
mosaic-db-migratorrunner and verified-readiness artifact; and - KBN-101-05 Vault/secret-renderer-backed deployment and consumer-isolation artifact.
The required future order is external bootstrap → TLS/roles → mosaic-db-migrator --run → mosaic-db-migrator --verify → Gateway/Compose readiness.
This is a held, non-operative future activation specification with no current command authority. Do not invoke the named runner, start PostgreSQL, or substitute a Compose/init/manual-SQL route until the owned artifacts are implemented and reviewed.
Future production secret and unit boundary (schematic only)
No current bare-metal production unit or command is published. KBN-101-05 must supply a reviewed,
generation-pinned Vault renderer and a process-exec or systemd LoadCredential interface before
production units can exist. The interface must preserve these exact consumer boundaries:
| Consumer | May receive | Must never receive |
|---|---|---|
| Gateway/runtime | Its own runtime URL and DB client CA at process exec | Migrator URL, importer URL/version, attestation material, signing key, PostgreSQL private key |
| One-shot migrator | Its own migration URL, DB client CA, and runner-only signing capability | Runtime URL, importer consumer copy, Gateway/private PostgreSQL keys |
| Data importer | Its own immutable URL/version copies, importer CA, pinned public key, and sealed attestation | Runtime/migrator URLs, signing key, shared writable mount |
| PostgreSQL | Its own server certificate/key and only its approved server material | Application, migrator, importer, or Gateway secrets |
A future unit specification is non-executable until KBN-101-05 supplies it. It must obtain
credentials through the renderer’s Vault generation and process-exec/LoadCredential boundary;
it must not place credentials in a production environment file, a monorepo auto-load path, a shell
export, command arguments, logs, or a manual secret-activation lifecycle instruction. Rotation and
process replacement semantics must be delivered by the reviewed renderer/interface with generation,
consumer-isolation, mode/owner, and no-mixed-generation evidence—not improvised in this guide.
Readiness and troubleshooting status
Until the future procedure is implemented, do not diagnose PostgreSQL with ad hoc SQL, connection strings, or initialization scripts. The future sanitized runner-verification readiness artifact is the required PostgreSQL readiness authority after its bootstrap/TLS prerequisites pass. For local PGlite development, diagnose application behavior without introducing a PostgreSQL connection.
Non-database local services may be inspected with their ordinary local health/log tools. Those checks do not certify PostgreSQL, federated deployment, or production readiness.