0 Fork 0

Files

T

jakman85andClaude Opus 5.5 250fb54154 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]>

2026-11-08 22:46:00 -06:00

4.3 KiB

Raw Blame History

Coordination Protocol

How agents work together without stepping on each other. Read alongside roles.md, ../roadmap/workstreams.md, and ../AGENTS.md.

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

Workstreams communicate through interfaces (listed in ../roadmap/workstreams.md): the ServiceDefinition schema, StorageClasses, the network policy/egress rendering, TLS issuer + Gateway, the observability contract, the update-policy contract.

Consume a contract freely.
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 platform-wide events.

3. Decisions vs. discussion — and the no-spec-change rule

You may not modify the specifications (docs/, requirements, accepted ADRs, roadmap) — they are human-owned and immutable to agents (R-TEST-06, ../AGENTS.md §11).
Anything that changes a locked choice ⇒ draft a superseding ADR and escalate to the human (../decisions/README.md); do not self-approve or merge it.
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, committed with the change and tagged to its requirement IDs (definition-of-done.md, ../docs/14-testing-and-conformance.md). "Merged" ≠ "done"; "demonstrated manually" ≠ "done". You write the test as well as the implementation.

5. Phase discipline

Only work items in the active phase(s) (../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) 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, say so in your handoff entry and PR, with consumers tagged.

7. Conflict resolution

Re-read the source-of-truth hierarchy (../AGENTS.md §2); the higher document wins.
If specs genuinely conflict or are silent, escalate to the System Architect to amend the spec/ADR — fix the documents first, then build.
Never resolve a conflict by silently picking an interpretation in code.

8. Safety rails that never bend

Default-deny + VPN kill-switch are fail-closed — if unsure, deny/close.
Secrets stay encrypted; never printed.
Nothing that risks data ships without a tested backup/restore behind it.
No click-ops except ADR-sanctioned bootstrap steps.
Specs are immutable to you; a spec you can't meet is an escalation, never an edit.
Never weaken a test or a requirement to get green — that's a defect, not progress.

9. Communication artifacts

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 in sync; they are how independent agents stay coherent.

4.3 KiB Raw Blame History