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:
parent
f4353fddbc
commit
ebe6032059
1 changed files with 67 additions and 45 deletions
112
CLAUDE.md
112
CLAUDE.md
|
|
@ -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 (§10–11), policy evaluation order
|
||||
(§13), integration contracts (§16–19), failure modes (§28), API surface (§26), ADR backlog
|
||||
(§40), milestones M0–M8 (§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 (§10–11), 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 (§14–15),
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue