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]>
This commit is contained in:
1 parent
1ddc14b918
commit
250fb54154
43 files changed
+1672
-575
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user