Register with repo-manager and add agent guidance

Register gate-house as category: tooling, domain: infotech, workplan
prefix GH-WP, via rmgr scaffold. Baseline files: .repo-classification.yaml,
SCOPE.md, AGENTS.md, workplans/GH-WP-0001-foundation.md. rmgr conform
passes with no findings.

SCOPE.md is derived from INTENT.md; GH-WP-0001 targets milestone M0
(executable skeleton) from ArchitectureBlueprint.md §41.

Move ArchitectureBlueprint.md to the repository root, matching its own
reference layout (§32). spec/ retains the Active Secrets Management Canon,
the external standard Gate House conforms to.

Add CLAUDE.md documenting the document precedence (Canon → INTENT →
Blueprint → README), the load-bearing security invariants, the fixed
domain vocabulary, and the stable identifier scheme.

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-24 20:41:58 +02:00
parent 8604fe6021
commit a97e7c8ee1
6 changed files with 266 additions and 0 deletions

26
.repo-classification.yaml Normal file
View file

@ -0,0 +1,26 @@
repo_classification:
standard: Repo Classification Standard
version: "1.0"
classified_at: "2026-08-24"
classified_by: human
category: tooling
domain: infotech
secondary_domains:
- agents
capability_tags:
- access-control
- identity
- governance
- platform
- evidence
business_stake:
- technology
- operations
business_mechanics:
- control
- operation
notes: >-
Deterministic authority plane for human, workload, and agent actions
across NetKingdom, and the reference implementation of the Active
Secrets Management (ASM) Plane. Long-lived control-plane component
reused across the ecosystem; not a domain hub, not a secrets manager.

4
AGENTS.md Normal file
View file

@ -0,0 +1,4 @@
# Agent instructions — gate-house
Orient: INTENT.md → SCOPE.md → workplans/.
Workplan prefix: `GH-WP-`.

129
CLAUDE.md Normal file
View file

@ -0,0 +1,129 @@
# 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 (§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.
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.
```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 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).

38
SCOPE.md Normal file
View file

@ -0,0 +1,38 @@
# Scope
Derived from `INTENT.md`. Gate House is deliberately narrow: it decides whether
a requested action is authorized, and represents that decision as bounded,
time-limited authority that downstream systems enforce.
## In scope
- deterministic authorization decisions (`GRANT` / `DENY` / `REQUIRE_APPROVAL` / `DEFER`)
- principal / actor / runtime-identity separation
- mandates, delegation, and attenuation
- authority ceilings
- tenant-, environment-, resource-, task-, and time-scoped grants
- approval binding and step-up requirements
- posture intake from King's Guard, restricting only
- change-dynamics limits: quotas, budgets, concurrency, circuit breakers
- credential-binding contract to Secrets Engine / OpenBao
- emergency revocation independent of the actor
- decision evidence, explainability, and protected audit
- policy and decision versioning; fail-closed semantics
## Out of scope
Owned elsewhere in NetKingdom — see the responsibility table in `INTENT.md`:
- human identity lifecycle and memberships — User Engine
- tenant and organizational boundaries — Tenant Engine
- authentication and federation — Key Cape
- credential abstraction and lifecycle orchestration — Secrets Engine
- secret storage, PKI, leases, dynamic secret engines — OpenBao
- operational execution — Ops Warden
- construction, reconciliation, recovery — Ops Mason
- anomaly detection, behavioral risk inference, security memory — King's Guard
- adversarial testing and attack simulation — Whitehat Security
Also out of scope: inventing a new policy language, becoming an IAM suite,
secret scanning, SIEM, autonomous remediation, and supporting every agent
protocol. See "Non-Goals for the First Prototype" in `ArchitectureBlueprint.md` §3.

View file

@ -0,0 +1,69 @@
---
id: GH-WP-0001
type: workplan
title: "Foundation"
domain: infotech
repo: gate-house
status: proposed
---
# Foundation
Establish the repository baseline and reach milestone **M0 — Executable Skeleton**
as defined in `ArchitectureBlueprint.md` §41: a request must produce a
deterministic `GRANT` / `DENY` with structured audit evidence.
```task
id: GH-WP-0001-T01
status: todo
priority: high
```
Establish the repository baseline: classification, scope, agent instructions,
workplan spine.
```task
id: GH-WP-0001-T02
status: todo
priority: high
```
Record the early ADRs that gate implementation choices — ADR-001 canonical
authority request schema, ADR-002 principal/actor/runtime identity model,
ADR-003 policy engine selection. Backlog in `ArchitectureBlueprint.md` §40.
```task
id: GH-WP-0001-T03
status: todo
priority: high
```
Define the canonical authorization request and decision schemas from
`ArchitectureBlueprint.md` §7 and §8.
```task
id: GH-WP-0001-T04
status: todo
priority: medium
```
Implement the `/authorize` service skeleton with static policy and the
evaluation order in `ArchitectureBlueprint.md` §13, monotonic toward restriction.
```task
id: GH-WP-0001-T05
status: todo
priority: medium
```
Emit structured decision evidence for every authorization call, per
`ArchitectureBlueprint.md` §24.
```task
id: GH-WP-0001-T06
status: todo
priority: medium
```
Seed the adversarial test suite with the fail-closed and self-escalation cases
(Canon T-04, T-09; `ArchitectureBlueprint.md` §34.4, §34.8).