docs: bring the specification in line with the accepted implementation

The operator ruled the implementation repo's main (50c8719) the latest
and accepted state. Sync the spec to it.

Accepted changes are reflected: one bare-metal environment, TrueNAS bulk
storage, R2 off-cluster backup, CloudNativePG, single-node VPN gateway
with Cilium fail-closed, inbound WireGuard, per-app auth sidecars,
Renovate, the CI gate as approver, and the pm-agent. New ADR-0017..0025;
ADR-0016 corrected and accepted; R-* IDs unchanged, eight amended.

Where the implementation has simply not met a requirement, the
requirement stands and the shortfall is recorded in docs/16-known-gaps.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

agents/coordination-protocol.md

@@ -3,9 +3,9 @@
 How agents work together without stepping on each other. Read alongside [`roles.md`](roles.md),
 [`../roadmap/workstreams.md`](../roadmap/workstreams.md), and [`../AGENTS.md`](../AGENTS.md).
 
-## 1. Claim before you build
-- Take an item from [`task-board.md`](task-board.md), set its owner and status to `in-progress`.
-- Respect `blocked-by`. Do not start blocked work; help unblock it instead.
+## 1. Take work from an issue, in your own workspace
+- Implementation work is taken up through issues on the implementation repo, on a branch of its own.
+- Do not start work that depends on something unfinished; help unblock it instead.
 - Keep items small and single-responsibility.
 
 ## 2. Contracts are sacred
@@ -14,7 +14,7 @@ the ServiceDefinition schema, StorageClasses, the network policy/egress renderin
 Gateway, the observability contract, the update-policy contract.
 
 - **Consume** a contract freely.
-- **Change** a contract only by: (1) proposing the change on the task board with the affected
+- **Change** a contract only by: (1) proposing the change in an implementation-repo issue with the affected
   workstreams tagged, (2) getting the owning role's sign-off, (3) updating the spec that defines the
   contract in the *same* change. Never silently break a downstream consumer.
 - The **ServiceDefinition schema** is the highest-traffic contract; treat schema changes as
@@ -25,12 +25,12 @@ Gateway, the observability contract, the update-policy contract.
   are human-owned and immutable to agents (R-TEST-06, [`../AGENTS.md` §11](../AGENTS.md)).
 - Anything that changes a locked choice ⇒ **draft** a superseding ADR and **escalate to the human**
   ([`../decisions/README.md`](../decisions/README.md)); do not self-approve or merge it.
-- Genuine unknowns, or a spec that is wrong/blocking/ambiguous ⇒ **stop and escalate** on the task
-  board as an **Open Question (OQ-n)** for the human to resolve in the spec; don't bury ambiguity in
-  an implementation and don't patch the spec yourself.
+- Genuine unknowns, or a spec that is wrong/blocking/ambiguous ⇒ **stop and escalate** in an
+  implementation-repo issue or directly to the operator, for the human to resolve in the spec; don't
+  bury ambiguity in an implementation and don't patch the spec yourself.
 
 ## 4. Definition of done
-Nothing is "done" until its **automated, reproducible behavior test passes green** in **dev/test**,
+Nothing is "done" until its **automated, reproducible behavior test passes green**,
 committed with the change and tagged to its requirement IDs ([`definition-of-done.md`](definition-of-done.md),
 [`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)). "Merged" ≠ "done";
 "demonstrated manually" ≠ "done". You write the test as well as the implementation.
@@ -39,18 +39,19 @@ committed with the change and tagged to its requirement IDs ([`definition-of-don
 - Only work items in the **active phase(s)** ([`../roadmap/phases.md`](../roadmap/phases.md)) unless
   explicitly parallelizable.
 - Respect entry gates; don't start a phase whose predecessor's exit criteria aren't demonstrated.
-- **Prod (Phase 7) is closed** until the operator opens it.
+- **Prod (Phase 7)** was opened by the operator's declaration; production is the one live environment
+  and changes reach it only through the PR gate and Flux.
 
 ## 6. Handoffs
 When your output feeds another workstream:
 - State the interface you're delivering and where it's documented.
 - Provide the demonstrable proof (the gate you passed) so the consumer can trust it.
-- If you changed a shared contract, announce it on the board with consumers tagged.
+- If you changed a shared contract, say so in your handoff entry and PR, with consumers tagged.
 
 ## 7. Conflict resolution
 1. Re-read the source-of-truth hierarchy ([`../AGENTS.md` §2](../AGENTS.md)); the higher document
    wins.
-2. If specs genuinely conflict or are silent, escalate to the **Platform Architect** to amend the
+2. If specs genuinely conflict or are silent, escalate to the **System Architect** to amend the
    spec/ADR — fix the documents first, then build.
 3. Never resolve a conflict by silently picking an interpretation in code.
 
@@ -63,7 +64,9 @@ When your output feeds another workstream:
 - **Never weaken a test or a requirement to get green** — that's a defect, not progress.
 
 ## 9. Communication artifacts
-- **task-board.md** — the live who's-doing-what + status + blockers.
+- **Implementation-repo issues** — work intake and escalations.
+- **Implementation handoff log** (`decisions/` there) — what changed, what was verified, what was not.
+- **`./conformance/run.sh --status`** (implementation repo) — the live requirement status.
 - **specs/ADRs** — durable decisions and contracts.
 - **PR descriptions** — reference requirement IDs, specs, ADRs, and the gate demonstrated.
-Keep these three in sync; they are how independent agents stay coherent.
+Keep these in sync; they are how independent agents stay coherent.

agents/definition-of-done.md

@@ -1,7 +1,7 @@
 # Definition of Done
 
 A change is **done** only when an **automated, reproducible, behavior-based test** for each relevant
-gate below **passes green in dev/test**, the test is committed with the change and tagged with the
+gate below **passes green**, the test is committed with the change and tagged with the
 requirement IDs it verifies, and the change is traced to those IDs. A manual demonstration, a
 screenshot, or "it reconciles" is **not** done (R-TEST-01..04, [`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)).
 
@@ -21,7 +21,7 @@ screenshot, or "it reconciles" is **not** done (R-TEST-01..04, [`../docs/14-test
 - [ ] Observability wired (metrics/logs) and at least the relevant alert exists.
 - [ ] No specification/ADR/requirement was modified to achieve this (R-TEST-06); any spec problem was
       escalated, not edited.
-- [ ] Result recorded on the task board / PR with a link to the passing test run.
+- [ ] Result recorded in the PR and a handoff entry, with a link to or ledger row for the passing run.
 
 ## Requirement-class gates (apply those relevant to the change)
 
@@ -55,11 +55,13 @@ screenshot, or "it reconciles" is **not** done (R-TEST-01..04, [`../docs/14-test
 - [ ] `internal` is unreachable publicly; `public` is reachable + TLS-valid.
 - [ ] Internal clients resolving via Pi-hole reach the internal Gateway; via a public resolver, a
       `public` service still works through the tunnel (R-DNS-04).
-- [ ] Non-`public` hostnames get 404 at the tunnel and have no public record (R-DNS-05); the
-      Kubernetes API is not publicly reachable (R-SEC-04).
+- [ ] LAN/VPN-only hostnames get 404 at the tunnel; `internal` services have no public record, except
+      non-HTTP L4 names, which may hold DNS-only records at LAN addresses (R-DNS-05); the Kubernetes
+      API is not publicly reachable (R-SEC-04).
 
 ### Automated updates (R-UPD-*)
-- [ ] Advances to a newer **stable** version automatically on schedule with **no human/AI edit**.
+- [ ] Advances to a newer **stable** version automatically on schedule with **no human/AI edit**, as
+      a machine-authored change through the merge gate (allowed update classes).
 - [ ] A deliberately bad update is health-gated: **auto-rollback** + alert.
 - [ ] A **pinned** service does not advance.
 

agents/roles.md

@@ -6,15 +6,22 @@ not people — one agent may hold several early on; split as work scales.
 
 ## Coordination roles
 
-### Platform Architect (steward of this spec repo)
+### System Architect (steward of this spec repo)
 - Guards the source-of-truth hierarchy ([`../AGENTS.md` §2](../AGENTS.md)); approves/records ADRs.
 - Resolves cross-workstream interface conflicts; keeps requirement traceability honest.
 - Does **not** write implementation code; owns specs, ADRs, roadmap, and this coordination layer.
 
 ### Integration/Release Lead
 - Owns the implementation repo structure, CI gates, and Flux bootstrap health.
-- Runs phase entry/exit reviews against the **automated conformance suite**; keeps the task board
-  truthful.
+- Runs phase entry/exit reviews against the **automated conformance suite**; keeps the handoff log
+  and the derived requirement status truthful.
+
+### Program Manager
+- Decides what should happen about implementation work: starts, revises, or declines it, and briefs
+  workers. Lives in the implementation repo; delegates code and debugging rather than doing them.
+- Does **not** hold the System Architect role: work that needs a spec change is escalated. The
+  in-cluster pm-agent ([ADR-0025](../decisions/adr-0025-in-cluster-ai-program-manager.md)) is an
+  automated instance of this role.
 
 ### QA/Conformance Engineer (WS-TEST)
 - Owns the conformance testing capability ([14](../docs/14-testing-and-conformance.md),
@@ -52,5 +59,5 @@ not people — one agent may hold several early on; split as work scales.
   ([`../decisions/README.md`](../decisions/README.md)).
 - Negotiate interface changes before breaking another workstream's contract
   ([coordination-protocol.md](coordination-protocol.md)).
-- Never build on prod hardware before Phase 7 is opened.
+- Reach production only through the PR gate and Flux (R-ENV-03).
 - Never emit plaintext secrets.

agents/task-board.md

@@ -1,14 +1,18 @@
 # Task Board
 
+> **FROZEN — historical seed.** By the operator's ruling of 2026-08-31 this board is not the status
+> surface; the repository is. **Nobody edits it**, and its contents and the instructions below no
+> longer describe live work. Its `T-*` IDs stay stable because the implementation repo cites them.
+> Live status: `./conformance/run.sh --status` in the implementation repo; dated snapshot:
+> [`../docs/16-known-gaps.md`](../docs/16-known-gaps.md).
+
 The live who's-doing-what. Agents **claim** an item (set Owner + Status) before starting, respect
 `Blocked-by`, and mark `done` only after its **automated, reproducible behavior test passes green**
 ([`definition-of-done.md`](definition-of-done.md), [`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)).
 Seeded from [`../roadmap/phases.md`](../roadmap/phases.md) + [`../roadmap/workstreams.md`](../roadmap/workstreams.md).
 
-> **This board is the one working surface agents may edit** (claim items, update status, add
-> items/escalations). The specs, ADRs, and roadmap are **not** editable by agents (R-TEST-06) —
-> raise spec problems here as an `OQ-*` escalation for the human. Every "**Prove …**" task below is
-> an automated conformance test (co-owned with **WS-TEST**), not a manual demo.
+> The specs, ADRs, and roadmap are **not** editable by agents (R-TEST-06). Every "**Prove …**" task
+> below is an automated conformance test (co-owned with **WS-TEST**), not a manual demo.
 
 **Status values:** `todo` · `in-progress` · `blocked` · `review` · `done`
 **Add new items** at the bottom of the relevant phase; keep IDs stable.