Update CLAUDE.md for the re-cut

The guidance still described Gate House as the deterministic authority plane
and pointed agents at the Blueprint's component architecture and reference
implementation layout — it would have actively misled the next session.

- Lead with the re-cut and the INV-02 argument, and say plainly that any
  proposal having Gate House decide, store, evaluate, or enforce at request
  time is wrong regardless of how well built.
- Add the decision record to the document hierarchy, above the Canon, and
  mark the Blueprint as partly withdrawn with the surviving sections named.
- Reframe the invariants as doctrine Gate House authors rather than
  constraints on code it writes; add the Staff/Tooling rule as binding on
  this repo itself.
- Record the normative demarcations: access lane vs access rule, doctrine vs
  runbook, control plane as Engine vocabulary.
- Replace the implementation-layout guidance with where doctrine artifacts
  go, and note that T-01…T-10 are specifications executed by whitehat.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 2564823@bnt-lap001
Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9
This commit is contained in:
tegwick 2026-08-28 21:22:51 +02:00
parent f4353fddbc
commit ebe6032059

112
CLAUDE.md
View file

@ -9,28 +9,38 @@ test runner, or dependency manifest — the repo is Markdown documents plus its
baseline. Do not invent build/lint/test commands; if asked to "run tests", say there is
nothing to run yet. The only commands that work today are the repo-manager ones below.
The first executable work is defined by milestone **M0** in the Blueprint (§41): a service
skeleton with `/authorize`, canonical request/decision schemas, static policy, and structured
audit output.
It is specification-only **by design**, not by earliness. Gate House is a Staff-layer
repository: its artifacts are specifications, decisions, workplans, and tasks. Do not
propose building a service here. Milestone M0 in the Blueprint (an `/authorize` skeleton)
has lapsed — see the re-cut below.
## What Gate House is
Gate House is the **deterministic authority plane** for NetKingdom — the reference
implementation of the Active Secrets Management (ASM) Plane. It answers exactly one question:
Gate House is the **council where NetKingdom's security and defence doctrine is
established, documented, taught, and supervised** — a **Staff**-layer repository in the
NetKingdom security layer model (`net-kingdom/canon/standards/security-layer-model_v0.1.md`).
It holds no runtime position and renders no authorization decision.
> may this principal/actor, in this tenant and environment, perform this action on this
> resource, under this mandate, with these constraints, until when → GRANT or DENY.
> **The mandate and the operating mode are Gate House's. The decision is access-engine's.
> The credential is secrets-engine's. The perimeter is ops-mason's and ops-warden's.**
The maxim that governs every design decision here:
**The re-cut (2026-08-28) is the single most important thing to know here.** Gate House was
seeded as a deterministic authority plane — `/authorize`, grant storage, revocation — and
that framing was withdrawn on its own argument: a decision point inside Gate House would put
the deterministic authority boundary inside the non-deterministic management layer,
violating INV-02, the first invariant this repo defends. `access-engine` (currently
`flex-auth`) is the only policy decision point in NetKingdom.
Read `decisions/decisions.md` GH-DEC-2026-001 and
`history/2026-08-28-security-layer-model-and-gate-house-recut.md` before proposing any
architecture change. If a proposal has Gate House deciding, storing, evaluating, or
enforcing anything at request time, it is wrong regardless of how well it is built.
The maxim that governs every design decision here — and, read across the layers, the
estate's layering rule:
> **Cognition proposes. Authority disposes. Infrastructure executes.**
Gate House deliberately does **not** own identity lifecycle, tenancy lifecycle,
authentication, secret storage, PKI, anomaly detection, or execution. Those belong to sibling
NetKingdom systems (User Engine, Tenant Engine, Key Cape, Secrets Engine, OpenBao, Ops Warden,
Ops Mason, King's Guard, Whitehat Security). When a proposed feature starts absorbing one of
those responsibilities, that is a design error, not a scope extension.
## Document hierarchy — read in this order
1. **`spec/ActiveSecretsManagementCanon_v0.3.md`** — the normative standard Gate House
@ -39,19 +49,23 @@ those responsibilities, that is a design error, not a scope extension.
edited to accommodate Gate House.
2. **`INTENT.md`** — mission, scope boundaries, domain concepts, the 15 numbered Core Rules,
use cases `UC-01``UC-05`, success criteria. This is the "why".
3. **`ArchitectureBlueprint.md`** — the "how". Domain model (§6), canonical authorization
request (§7) and decision (§8), component architecture (§1011), policy evaluation order
(§13), integration contracts (§1619), failure modes (§28), API surface (§26), ADR backlog
(§40), milestones M0M8 (§41), architectural invariants `A-01``A-15` (§43).
4. **`README.md`** — public-facing summary. Keep it consistent with the above; it is a
derivative, not a source of truth.
3. **`decisions/decisions.md`** — decision records. GH-DEC-2026-001 ratifies the layer
model, the re-cut, and the access-engine reframing. Binding.
4. **`ArchitectureBlueprint.md`** — **predates the re-cut and is only partly valid.** Its
component architecture (§1011), policy evaluation order (§13), API surface (§26), and
storage model (§25) describe an engine and are withdrawn; ADR-003 and milestones M0, M3,
M4 have lapsed. Its domain model (§6), authority context (§7), operating modes (§1415),
change dynamics (§20), MCP integration (§19), and security test program (§34) survive.
Do not cite it without checking a section against INTENT first.
5. **`README.md`** — public-facing summary. A derivative, not a source of truth.
When these conflict, the Canon wins over INTENT, and INTENT wins over the Blueprint. Fix the
lower document rather than diverging.
When these conflict: the decision record wins over everything, then the Canon, then INTENT,
then the Blueprint. Fix the lower document rather than diverging.
## Invariants that constrain any implementation
## The doctrine Gate House maintains
These are load-bearing. Code or design that violates one is wrong even if it works:
These are load-bearing. Gate House authors and maintains them; the engines and Staff
repositories implement them. A document or proposal that violates one is wrong:
- **No privilege from cognition.** An LLM deciding an action is appropriate never makes it
authorized. The final privilege boundary is deterministic policy.
@ -63,10 +77,10 @@ These are load-bearing. Code or design that violates one is wrong even if it wor
- **Posture may only restrict.** King's Guard (or any adaptive input) can reduce authority or
demand step-up; it can never manufacture privilege. See Blueprint §16.2 for the explicitly
forbidden pattern.
- **Evaluation is monotonic toward restriction** (Blueprint §13). No stage after the authority
ceiling may expand beyond it.
- **Evaluation is monotonic toward restriction.** No stage after the authority ceiling may
expand beyond it. (Evaluation itself is access-engine's; Gate House states the property.)
- **Fail closed.** Unavailable policy engine, unresolvable context, unavailable audit, or
stale authoritative state → DENY. Per-dependency semantics are in Blueprint §28.
stale authoritative state → DENY.
- **Assistant mode and Autonomous mode are different security regimes.** A human session
ending must never silently promote the workflow to privileged autonomy.
- **Agents cannot edit their own authority ceiling**; policy self-modification is a separately
@ -76,6 +90,8 @@ These are load-bearing. Code or design that violates one is wrong even if it wor
- **Credentials are implementation artifacts of a grant**, materialized by Secrets Engine /
OpenBao *after* authority exists — never the source of authority, never placed in model
context.
- **Staff never touches Tooling directly.** It acts only through Engine APIs. This binds
Gate House itself: no direct database, OpenBao, or cluster client belongs in this repo.
## Repo-manager registration
@ -100,30 +116,36 @@ the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep the
ADRs (`ADR-nnn`), and milestones (`M0``M8`) are referenced across documents. Reuse the
existing id when writing about a concept; append rather than renumber.
- **Canon prose is normative** — preserve MUST/SHOULD/MAY exactly when editing it.
- **Domain vocabulary is fixed** by Blueprint §6 and INTENT's Domain Concepts: principal,
actor, runtime identity, tenant, environment, mandate, delegation, authority ceiling,
action, resource, grant, denial, approval, posture, credential binding, decision evidence.
Use these terms rather than synonyms ("user", "role", "token", "permission").
- **Domain vocabulary is fixed** by INTENT's Domain Vocabulary: principal, actor, runtime
identity, mandate, delegation, authority ceiling, operating mode, posture, change dynamics
envelope, decision evidence. Use these rather than synonyms ("user", "role", "token",
"permission"). Two demarcations are normative: **access lane** (ops-warden, ops-mason) is
not **access rule** (access-engine); **doctrine** (gate-house) is not **runbook** (the lane
owner). "Control plane" is Engine vocabulary — do not apply it to Gate House.
- Documents carry a frontmatter-style header block (Repository / Project family / Status /
Version / Date). Keep it, and bump Status/Version/Date on substantive edits.
- Diagrams and schema examples are plain ```text``` or ```yaml``` fenced blocks — no Mermaid.
- Decision types are the four in Blueprint §9: `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER`.
- Decision types are `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER` — rendered by
access-engine, named here.
## Where new work goes
- `README.md`, `INTENT.md`, and `ArchitectureBlueprint.md` live at the repo root, matching the
Blueprint's own reference layout (§32). External standards Gate House conforms to — the
Canon — live in `spec/`.
- ADRs → `docs/adr/`, drawn from the backlog in Blueprint §40 (ADR-001 through ADR-014).
- Implementation, when it starts, should follow the reference layout in Blueprint §32
(`api/`, `domain/`, `policy/`, `grants/`, `approvals/`, `limits/`, `integrations/`, `audit/`,
`test/{unit,integration,adversarial,scenarios}`, `deploy/`). That layout is explicitly
labelled a direction, not a constraint — deviate deliberately and say why.
- Technology is intentionally unfixed (Blueprint §31): HTTP/JSON first, OPA/Rego or Cedar as
policy candidates, PostgreSQL for grants/mandates/revocation, OIDC + SPIFFE/SPIRE for
identity. Do not hard-code a choice into the conceptual model — the domain model must not
depend on one policy engine.
- Adversarial tests are a first-class deliverable, not an afterthought: Canon `T-01``T-10`
and Blueprint §34 (malicious model, prompt injection, human disconnect, policy
self-modification, approval replay, cross-tenant, MCP token passthrough, audit loss,
circuit breaker).
- ADRs → `docs/adr/`, from the Blueprint §40 backlog. ADR-003 (policy engine selection) has
lapsed with the re-cut; ADR-001, ADR-002, ADR-006, ADR-009, ADR-010, ADR-013, ADR-014
remain meaningful as contract and doctrine.
- Decision records → `decisions/decisions.md`, via `rmgr decision create|resolve`. Never
hand-write the YAML block; the tool mints identifiers and commits.
- History and reference notes → `history/YYYY-MM-DD-<slug>.md`, matching the convention in
ops-warden, zone-engine, and secrets-engine.
- Doctrine that stabilizes graduates into `net-kingdom/canon/standards/`, owned by gate-house
and published by net-kingdom. `security-layer-model_v0.1.md` is the first.
- **No implementation layout.** Blueprint §32's reference tree (`api/`, `policy/`, `grants/`,
`deploy/`, …) described the withdrawn engine and does not apply. If work here starts
producing services, schemas that resolve, or anything evaluated at request time, stop —
that belongs to an engine.
- Assurance tests `T-01``T-10` are **specifications** authored here and executed by
whitehat-security. Writing the specification is Gate House's job; running the attack and
judging whether the control held is not.