coulomb/ops-mason
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ops-mason/SCOPE.md
tegwick 0a489116a8 build: keep generated orientation brief local and untracked 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a15374-f59f-7a31-86d2-d23b5d2ed181
2026-10-19 13:44:08 +02:00

4.2 KiB
Raw Blame History

SCOPE

One-liner

Builder of NetKingdom security infrastructure — creates, changes, maintains, and tears down OpenBao AppRoles, policies, and KV secret paths so ops-warden always has something real to route to.

Core Idea

Four-phase process: (1) construction plan — respect/extend/compact existing structure before proposing new; (2) review/optimize against what already exists; (3) executive summary — the one mandatory human decision gate, in plain terms; (4) build, only after approval.

In Scope

  • Construction plans for new/changed/retired OpenBao AppRoles, policies, KV secret path structure (never values)
  • Consistency review — reuse over duplication, compaction over sprawl
  • The executive-summary format that makes a plan decidable at a glance
  • Proposing pointer-only entries (warden_executes: false, no authored steps) in ops-warden's routing catalog for what it builds — a normal git contribution to that repo, not a live API
  • Its own audit trail of what it built, under which approved plan

Out of Scope

  • Deciding whether access should exist — that's architecture/founder, ops-mason builds what's already decided
  • Runtime authorization decisions — access-engine
  • Identity/MFA — key-cape/Keycloak
  • Routing consumers to lanes once built — ops-warden
  • SSH certificate issuance — ops-warden
  • OpenBao cluster init/unseal, platform deploy — railiance-platform
  • Touching secret values at all, even transiently — delivered via ops-warden's existing paste_once_provision desk instead

Current State

The four-phase construction process, OpenBao AppRole/Kubernetes-auth builders, metadata inventory, and guarded Kubernetes-plane CLI are implemented and tested. Construction plans and build evidence live in plans/ and docs/evidence/.

OpenBao builds require an approved plan whose machine-readable specification and approved digest match the supplied execution inputs. Existing policies are content-pinned before reuse. AppRole credentials are delivered through private, exclusive files; the builders do not read downstream KV values. See docs/construction-plan-format.md for review and execution requirements.

Kubernetes apply enforces pinned readiness tiers, the explicit whitehat placement, the dated policy-nexus transition, and recorded emergency activation. See docs/kubernetes-plane.md.

The layer declaration is Staff, with PEP-shaped behavior, in INTENT.md. The founder-approved plan-approval exception and direct-contact gaps remain explicitly declared; this is not a claim of full layer-model conformance.

Remaining work is held in existing blocked workplans: credential descriptions (MASON-WP-0004), the attended Telegram credential lane (MASON-WP-0005), and the 2026-12-21 readiness/approval review (MASON-WP-0006-T06). WORK-RECORDS.md is the generated index; workplan files remain the source of task status.

Getting Oriented

  • Start with: INTENT.md
  • Agent instructions: AGENTS.md
  • Workplans: workplans/

Repository maintenance reuse

The tracked .generated-work-records.json adopts the Custodian staged-source adapter for WORK-RECORDS.md. make generated-work-records uses the existing State Hub renderer through .generated-work-records.mk; the shared pre-commit hook runs this isolated recipe only for opted-in repositories. The corresponding make generated-work-records-check is read-only. Canonical repository identity is explicit and does not depend on the checkout directory.

Unstaged source changes are preserved; conflicts and unstaged generated-file changes stop the commit. For git commit --only, generate first and include WORK-RECORDS.md with the selected source paths. Existing generated-only guards and exact-scope secret scans remain in place. This is repository maintenance, not a runtime service, authorization decision, deployment or publication. Other index generators and hub-derived briefs retain their owner boundaries.

Local orientation brief

.custodian-brief.md is a generated local orientation snapshot. It remains on disk for offline use and is root-ignored rather than versioned. Regenerate it with the State Hub brief renderer; workplans and other authored repository records remain authoritative. Brief refreshes must not create Git commits.