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.

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.

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:

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 maxim that governs every design decision here:

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 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. 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.

When these conflict, the Canon wins over INTENT, and INTENT wins over the Blueprint. Fix the lower document rather than diverging.

Invariants that constrain any implementation

These are load-bearing. Code or design that violates one is wrong even if it works:

• 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 (Blueprint §13). No stage after the authority ceiling may expand beyond it.
• Fail closed. Unavailable policy engine, unresolvable context, unavailable audit, or stale authoritative state → DENY. Per-dependency semantics are in Blueprint §28.
• 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.

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.

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 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").
• 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.

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).