tegwick
ebe6032059
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
151 lines
9.3 KiB
Markdown
151 lines
9.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Repository status
|
||
|
||
`gate-house` is currently **specification-only**. There is no source code, build system,
|
||
test runner, or dependency manifest — the repo is Markdown documents plus its repo-manager
|
||
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.
|
||
|
||
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 **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.
|
||
|
||
> **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 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.**
|
||
|
||
## Document hierarchy — read in this order
|
||
|
||
1. **`spec/ActiveSecretsManagementCanon_v0.3.md`** — the normative standard Gate House
|
||
implements. Uses RFC-style MUST/SHOULD/MAY. Owns the numbered invariants `INV-01`…`INV-12`
|
||
and the assurance tests `T-01`…`T-10`. Gate House conforms to the Canon; the Canon is not
|
||
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. **`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 decision record wins over everything, then the Canon, then INTENT,
|
||
then the Blueprint. Fix the lower document rather than diverging.
|
||
|
||
## The doctrine Gate House maintains
|
||
|
||
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.
|
||
- **Tool availability is not permission.** MCP tool registration/discovery means the operation
|
||
exists, not that invoking it is allowed. No token passthrough — downstream authority is
|
||
separately issued and bound to the target resource.
|
||
- **Principal, actor, and runtime identity stay distinct** and are never collapsed into one
|
||
field. Delegation attenuates and never widens.
|
||
- **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.** 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.
|
||
- **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
|
||
governed path and high-value security telemetry.
|
||
- **Audit evidence is protected from the actor being audited**, and every privileged action
|
||
must be reconstructable from it.
|
||
- **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
|
||
|
||
Registered with repo-manager as `category: tooling`, `domain: infotech` (secondary: `agents`),
|
||
workplan prefix **`GH-WP`** (owned in `~/repo-manager/config/workplan-prefix-registry.yaml`).
|
||
`.repo-classification.yaml`, `SCOPE.md`, `AGENTS.md`, and `workplans/` are that baseline.
|
||
|
||
```bash
|
||
rmgr conform --path . # check against tooling-flavor standards
|
||
rmgr observe --path . # snapshot JSON
|
||
rmgr workplan update --path . --workplan-id GH-WP-0001 --status active
|
||
rmgr update-task-status --path . --task-id GH-WP-0001-T01 --status progress
|
||
```
|
||
|
||
`rmgr` lives at `~/repo-manager/.venv/bin/rmgr`. Workplan and task state is edited through
|
||
these commands (file + git commit), not by hand-registering anything in the State Hub: write
|
||
the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep them consistent.
|
||
|
||
## Conventions
|
||
|
||
- **Stable identifiers.** Invariants (`INV-nn`, `A-nn`), tests (`T-nn`), use cases (`UC-nn`),
|
||
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 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 `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/`, 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.
|