gate-house/CLAUDE.md

# 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.7.md`, accepted).
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`** — the current doctrine architecture: responsibility
   boundaries, domain model, authority context, operating modes, posture and credential
   contracts, MCP doctrine, change dynamics, audit, invariants, and conformance. The
   withdrawn v0.1 authority-plane design is mapped in
   `history/2026-09-01-authority-plane-blueprint-retirement.md` and remains available at
   Git object `75ce372:ArchitectureBlueprint.md` for historical review only.
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 §8 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 — *within the bound in INTENT § Core Rules*: an archive
  proves records were not altered or truncated after arrival, never that one was never sent.
  Do not write doctrine that says "the audit record proves it happened".
- **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`),
  and ADRs (`ADR-nnn`) are referenced across documents. Reuse the existing id when writing
  about a concept; append rather than renumber. The v0.1 milestones (`M0`–`M8`) are
  historical and must not be revived as Gate House implementation milestones.
- **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. External
  standards Gate House conforms to — the Canon — live in `spec/`.
- ADRs → `docs/adr/`, with disposition recorded in Blueprint §17. 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.7.md` is the first, accepted
  2026-08-29 after seven versions; four repositories assented and each returned findings
  that changed it. Its working form is `net-kingdom/SECURITY-COMPANION.md` — read that
  first. For how to get something done in the estate, ask ops-warden, not this repo.
- **No implementation layout.** The v0.1 Blueprint'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. The executable handoff is
  `docs/assurance/asm-t01-t10-executable-targets.md`; results return under
  `docs/contracts/conformance-reporting.md`. Nothing in those documents authorizes a live
  probe.
- Conformance review dispositions → `docs/conformance/`. Store safe references and doctrine
  disposition there, never raw exploit evidence, credential values, severity decisions, or
  another repository's remediation tasks.