tegwick
35aff380a3
Five rules that governed this repo lived in wiki prose, a workplan, and a comment at the top of catalog.yaml. All were followed; none was addressable. A reader outside ops-warden could not cite one, could not tell whether it was current, and — the point of this change — could not tell whether it was ours to change or someone else's that we merely obey. ADR-0001 The routing catalog is a pointer layer, never a second copy ADR-0002 ops-warden is a transparent conduit, never a secret broker ADR-0003 Cover gaps, but never silently own them ADR-0004 High-risk lanes refuse raw value streaming to agent sessions ADR-0005 Implement one lane narrowly, route everything else Each carries owner: ops-warden, which is the load-bearing field. It says we follow the rule AND we are responsible for changing it — by superseding ADR, never an in-place edit. The failure this prevents runs both ways: a rule we own mistaken for inherited canon never gets fixed, because we wait for an owner who does not exist; inherited canon mistaken for ours gets quietly bent, and the drift is invisible until it breaks a repo that trusted the canonical version. Rules we follow but do not own — NetKingdom canon, the IAM profile, the credential-management standard, the-custodian's ADR-001 workplan convention — are cited, never copied into docs/adr/. Copying them would recreate exactly the second-source-of-truth failure ADR-0001 exists to prevent. architecture.md also now flags the three-digit/four-digit ADR-001 vs ADR-0001 collision, which is itself an ours-versus-inherited confusion waiting to happen. Publication verified rather than assumed: all five render through policy-nexus tools/render.py, and owner reaches the reader in three places — the page eyebrow (render.py:346), the index Owner column (build_site.py:123,137), and the publication manifest. build_site.py:179 makes title/status/owner required, so ownership cannot be dropped on the way out. policy-nexus publishes and never writes back; docs/adr/ stays the source of truth. Documentation adapted: SCOPE.md gains a Governing rules section and an orientation entry; .claude/rules/architecture.md replaced its stub with the ADR index, the owned-versus-inherited rule, and ADR-over-wiki precedence; finding-routing.md's ADR-gap section closed; catalog.yaml's no-double-source header now cites ADR-0001 rather than the originating workplan. uv run pytest -q → 338 passed, 4 deselected. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.5 KiB
Architecture
Our rules are ADRs — docs/adr/
The decisions that govern this repo live in docs/adr/ as addressable records,
not in wiki prose. Read docs/adr/README.md first; it explains the one
distinction that matters here.
| ADR | Rule |
|---|---|
ADR-0001 |
The routing catalog is a pointer layer, never a second copy of an owner's procedure |
ADR-0002 |
ops-warden is a transparent conduit, never a secret broker |
ADR-0003 |
Cover gaps, but never silently own them |
ADR-0004 |
High-risk lanes refuse raw value streaming to agent sessions |
ADR-0005 |
Implement one lane narrowly, route everything else |
Owned versus inherited — check owner: before changing anything
Every ADR carries owner: in its frontmatter, and it decides what you are allowed
to do with the rule:
owner: ops-warden— ours. We are bound by it and we may change it. Changing one means writing a superseding ADR, not editing the decision in place.- any other owner — inherited. We follow it; we do not own it. Dispute it through that owner's process; never amend it here.
Everything in docs/adr/ today is owner: ops-warden. Rules we merely follow —
NetKingdom canon, the IAM profile, the credential-management standard — are cited,
never copied in. Copying them would recreate the second-source-of-truth failure
ADR-0001 exists to prevent.
Naming collision, worth knowing. ADR-001 (three digits) in
workplan-convention.md and session-protocol.md is the-custodian's ADR
establishing the workplan convention across the whole estate. It is inherited and
not ours to change. Our records are four-digit — ADR-0001 … ADR-0005 — and live
in this repo. When writing, say "the-custodian's ADR-001" if that is what you mean.
Precedence
If a wiki page, playbook, or .claude/rules/ file disagrees with an ADR, the ADR
is right and the other file is a defect — fix it rather than working around it.
The rule files are agent-facing operational instructions derived from these
decisions; they should cite an ADR rather than restate its reasoning.
Publication
These ADRs are publishable through policy-nexus at policy.coulomb.social, which
requires title, status and owner, renders owner in the page header and in the
index, and records source repo, path and revision digest in its manifest. Ownership
survives the repo boundary. policy-nexus publishes and never writes back: the file
here is the source of truth.
Quick Reference
~/state-hub/mcp_server/TOOLS.md — MCP tool reference