Repo hygiene: fill stack-and-commands, normalize workplan statuses

- Fill .claude/rules/stack-and-commands.md (was an empty TODO template)
- Normalize workplan frontmatter statuses to canonical vocabulary
  (completed/done -> finished) per ADR-001
- Repair glued frontmatter delimiter in NK-WP-0001 (superseded_by line)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/rules/stack-and-commands.md

@@ -1,19 +1,22 @@
 ## Stack
 
-<!-- TODO: Fill in language, frameworks, and key dependencies -->
+- **Language:** Kubernetes manifests, Bash Make targets, SOPS-encrypted secret custody
-- **Language:**
+- **Key deps:** Keycloak (SSO/MFA), age/SOPS, KeePassXC-based credential custody, repo-local git hooks
-- **Key deps:**
 
 ## Dev Commands
 
 ```bash
-# TODO: Fill in the standard commands for this repo
+make help                  # list all targets
-
+make hooks && make hooks-test          # secrets-guard git hooks
-# Install dependencies
+make check-secrets         # fail if anything under secrets/ is unencrypted
-
+make sops-edit FILE=secrets/foo.yaml   # edit encrypted file
-# Run tests
+make sops-custody-check    # validate custody age key without writing to disk
-
+make sops-custody-run COMMAND='...'    # run one command with temporary custody key
-# Lint / type check
+make creds-init            # one-time credential custody setup
-
+make creds-generate        # generate service secrets + KeePassXC guide
-# Build / package (if applicable)
+make creds-bundle          # age-encrypt ops bundle for offsite storage
 ```
+
+Credential material never lands in Git, State Hub, or logs — the hooks and
+check-secrets enforce this. Deployment of identity services runs through the
+S2/S5 railiance repos, not from here.

README.md

@@ -1,3 +1,10 @@
 # NetKingdom
 
 NetKingdom provides a dynamic self optimizing full circle security-platform for kubernetes deployed IT-infrastructures.
+
+## Security Infrastructure Documents
+
+- [secrets-engine security infrastructure boundary](docs/secrets-engine-security-infrastructure-boundary.md)
+  defines how secrets-engine participates in the NetKingdom security
+  infrastructure and how it interacts with OpenBao, flex-auth, user-engine,
+  ops-warden, ops-bridge, info-tech-canon, State Hub, and agents.

docs/responsibility-map.md

@@ -76,6 +76,17 @@ and what NetKingdom is responsible for (meta-orchestration).
 | **Repo owns** | operating these stateful services to durability/recovery guarantees behind stable interfaces |
 | **NetKingdom orchestrates** | which platform services a scenario needs; runtime secret-authority boundaries (platform-root vs tenant) and policies; backup/DR requirements; the identity-integration point; runtime-secret-trust readiness |
 
+### `secrets-engine` — secret workflow and delivery orchestration
+
+| | |
+| --- | --- |
+| **Resources held** | non-secret secret-lane catalog, stage policy model, delivery-mode contracts, OpenBao apply/delivery plans, readiness and evidence records |
+| **Repo owns** | workflow and automation mechanics for approved secret establishment, provisioning, verification, delivery, rotation, revocation, and deactivation |
+| **NetKingdom orchestrates** | secret organization concepts; build/test/production stage boundaries; which systems participate in decisions and delivery; OpenBao/flex-auth/user-engine/ops-warden/ops-bridge/info-tech-canon interaction boundaries; the rule that OpenBao remains custody and audit backend |
+
+See `docs/secrets-engine-security-infrastructure-boundary.md` for the canonical
+cross-system boundary and interaction model.
+
 ### `key-cape` — identity
 
 | | |

docs/secrets-engine-security-infrastructure-boundary.md

@@ -0,0 +1,363 @@
+# NetKingdom Security Infrastructure Boundary
+
+## Purpose
+
+This document defines how `secrets-engine` participates in the NetKingdom
+security infrastructure. It is the first place agents and operators should read
+when they need to understand responsibility boundaries, system interactions,
+secret organization, and stage-specific policy concepts.
+
+`secrets-engine` is the workflow and interaction layer for approved secret work.
+OpenBao remains the custody, policy, lease, and audit backend.
+
+## Core Responsibility
+
+`secrets-engine` turns an approved secret request into a safe, reviewable,
+auditable sequence of actions:
+
+1. Resolve the catalog entry and stage.
+2. Verify the decision or approval state.
+3. Render a plan for OpenBao metadata, value provisioning, verification, and
+   delivery.
+4. Apply only allowed OpenBao changes through the minimal stage role.
+5. Provision or confirm the value without exposing it in coordination systems.
+6. Deliver the secret to a workload or command without printing it.
+7. Record non-secret evidence for audit, troubleshooting, and readiness.
+8. Rotate, revoke, deactivate, or mark compromised secrets through the same
+   catalog and decision model.
+
+## Boundary Map
+
+| System | Owns | secrets-engine interaction | Must not do |
+| --- | --- | --- | --- |
+| OpenBao | Secret custody, ACL policy enforcement, leases, response wrapping, audit logs | Use OpenBao through constrained build, test, and production roles; write policies, auth roles, metadata, and values only through validated plans | Treat OpenBao UI/CLI as the routine operator interface; bypass decision checks; store raw values outside OpenBao |
+| flex-auth | Authorization decisions and policy reasoning | Ask whether an actor may establish, access, rotate, or deactivate a cataloged secret for a purpose | Store or deliver secret values; become the vault |
+| user-engine / key-cape | Human and service identity, user lifecycle, claims, groups, MFA/OIDC context | Consume stable identity claims and service identities for OpenBao auth bindings and decision checks | Own secret lifecycle policy; mint provider tokens |
+| ops-warden | SSH certificate issuance and credential routing front door | Route non-SSH credential requests to secrets-engine; show catalog readiness and safe next commands | Vend API keys, provider tokens, database passwords, or OpenBao tokens |
+| ops-bridge | Remote execution, tunnels, transport, and operator connectivity | Consume secrets through `secrets-engine exec` or scoped delivery when a remote operation needs credentials | Persist secrets in tunnel configs, logs, or reusable shell state |
+| info-tech-canon | Canonical terminology, governance patterns, stage taxonomy, naming conventions, documentation profiles | Reuse canon terms for stage, catalog, approval, delivery, evidence, rotation, and deactivation concepts | Act as runtime authority or store secret values |
+| State Hub | Non-secret workstreams, decisions, progress, review comments, and evidence pointers | Read decisions and write non-secret progress/evidence | Store raw secret values, tokens, wrapped tokens, passwords, or private keys |
+| llm-connect / agents | Reasoning and task execution | Receive non-secret plans and use exec-time delivery only when needed | Place secrets in prompts, chat, model context, or logs |
+
+## System-of-Systems Position
+
+`secrets-engine` sits between request/decision systems and OpenBao operations.
+It is not the source of identity, authorization, or custody. It is the place
+where those systems are composed into an operator- and agent-usable workflow.
+
+```text
+request / ops-warden route
+        |
+        v
+State Hub decision <---- flex-auth authorization
+        |
+        v
+secrets-engine catalog + plan + policy guard
+        |
+        v
+OpenBao role/policy/value operations
+        |
+        v
+verification + evidence + safe delivery
+        |
+        v
+workload, CI job, operator command, or ops-bridge task
+```
+
+## Core Concepts
+
+### Secret Lane
+
+A secret lane is the governed path for one secret use case. It joins a catalog
+id, owner, stage, OpenBao location, fields, consumer binding, approval model,
+delivery modes, verification checks, and revocation behavior.
+
+Example catalog id:
+
+```text
+whynot-design-npm-publish
+```
+
+### Catalog Entry
+
+A catalog entry is non-secret metadata. It is the primary object agents and
+operators should reference. It must never contain raw secret values.
+
+Required concepts:
+
+- catalog id;
+- stage;
+- owner domain, repo, workload, or service;
+- OpenBao backend mount/path and fields;
+- allowed consumers and identity claims;
+- allowed delivery modes;
+- approval/decision requirement;
+- verification requirements;
+- rotation, revocation, and compromised/deactivated behavior;
+- evidence expectations.
+
+### Stage
+
+A stage is a security boundary. The initial stages are:
+
+- `build`;
+- `test`;
+- `production`.
+
+Short aliases such as `prod` may exist in CLI flags, but catalog and policy
+documents should normalize to the canonical names above.
+
+### Decision
+
+A decision is the non-secret approval state that allows a secret lane to be
+created, changed, delivered, rotated, or deactivated. Decisions live outside the
+vault, usually in State Hub and/or flex-auth. A production action must fail
+closed without an approved decision, except for explicit break-glass flows.
+
+### Delivery Mode
+
+A delivery mode defines how a secret reaches a consumer without becoming visible
+in normal coordination surfaces.
+
+Initial allowed modes:
+
+- exec-time environment injection;
+- exec-time temporary config file;
+- response-wrapped handoff;
+- local bootstrap file import for setup only;
+- non-production generated test value.
+
+Denied modes:
+
+- chat;
+- prompts or model context;
+- Git;
+- State Hub message body;
+- command-line argument containing the raw value;
+- normal logs;
+- long-lived untracked local files.
+
+### Evidence
+
+Evidence is non-secret proof that an action happened and what its result was.
+Evidence may include catalog id, actor, stage, decision id, OpenBao path, field
+names, lease accessor, timestamps, audit request ids, and pass/fail status. It
+must not include raw secret values.
+
+## Stage Policy Model
+
+### Build
+
+Purpose:
+
+- local development;
+- disposable integration experiments;
+- generated or synthetic values;
+- quick iteration before stronger policy is justified.
+
+Allowed direction:
+
+- manage build-stage metadata and values under build prefixes;
+- generate fake or low-impact values;
+- use lightweight decisions or repo-owner approval;
+- support fast `exec` flows for development commands.
+
+Restrictions:
+
+- no production mounts or paths;
+- no broad OpenBao sys/auth administration;
+- no reuse of build values in test or production;
+- short TTLs by default.
+
+### Test
+
+Purpose:
+
+- staging and integration verification;
+- proving delivery, rotation, and negative checks;
+- rehearsing production policy with lower impact.
+
+Allowed direction:
+
+- manage approved test-stage metadata and values;
+- run positive and negative access verification;
+- use provider tokens or service credentials with test-only scope;
+- record evidence before a similar production lane is considered ready.
+
+Restrictions:
+
+- no production values;
+- no production auth roles;
+- stricter identity binding than build;
+- explicit denial checks for unrelated consumers.
+
+### Production
+
+Purpose:
+
+- real workload secrets;
+- real provider tokens;
+- auditable delivery to production-capable consumers.
+
+Allowed direction:
+
+- apply approved production metadata such as ACL policies and auth roles;
+- provision values only through approved custody modes;
+- deliver values through exec-time or workload-scoped mechanisms;
+- record evidence and readiness state.
+
+Restrictions:
+
+- no action without approved decision, except explicit break-glass;
+- no broad `platform-root`, `platform-admin`, or wildcard admin semantics;
+- no raw value printing;
+- no default raw reads by agents;
+- rotation, revocation, and compromised/deactivated states must be expressible.
+
+## OpenBao Role Layers
+
+The initial OpenBao-facing roles are:
+
+| Role | Stage | Main capability |
+| --- | --- | --- |
+| `secrets-engine-build` | build | Manage approved build-stage metadata and values under build prefixes. |
+| `secrets-engine-test` | test | Manage approved test-stage metadata and values and run verification. |
+| `secrets-engine-prod` | production | Apply approved production metadata and perform constrained delivery/provisioning actions. |
+
+A temporary bootstrap credential may be used to create these roles and policies.
+Bootstrap credentials must be local-only, outside repositories, mode 0600,
+revocable, and tracked as temporary setup material.
+
+## Secret Organization
+
+The catalog is the stable interface. Physical OpenBao paths may evolve, but
+catalog entries must keep enough structure to enforce stage and ownership.
+
+Recommended logical dimensions:
+
+```text
+stage / tenant-or-org / workload-or-service / bundle / field
+```
+
+Recommended OpenBao path shape when a shared mount is used:
+
+```text
+<mount>/workloads/<stage>/<tenant-or-org>/<workload-or-service>/<bundle>
+```
+
+If a mount is already stage-specific, the stage may be represented by the mount
+instead:
+
+```text
+<stage-mount>/workloads/<tenant-or-org>/<workload-or-service>/<bundle>
+```
+
+The catalog must make the resolved stage explicit in either case. Existing
+legacy paths should be represented by catalog metadata before being normalized.
+
+## Policy Families
+
+The engine should distinguish policy families rather than treating every
+OpenBao policy as a free-form string:
+
+| Family | Purpose |
+| --- | --- |
+| catalog-read | Read non-secret catalog metadata and readiness. |
+| stage-applier | Apply metadata inside one stage boundary. |
+| value-provisioner | Write or import secret values under approved custody. |
+| delivery-runner | Fetch and inject a value only into a child process or workload-specific config. |
+| verifier | Run positive/negative checks without printing values. |
+| revoker | Revoke leases, deactivate lanes, or mark compromised state. |
+| auditor | Produce non-secret reports and evidence summaries. |
+
+Production policy families should be split so that metadata apply, value
+provisioning, and value delivery do not automatically imply each other.
+
+## Main Interaction Flows
+
+### Establish a Secret Lane
+
+1. Actor requests a cataloged secret lane.
+2. flex-auth and/or State Hub records an approval decision.
+3. secrets-engine renders the OpenBao policy/auth/value plan.
+4. Operator or agent reviews the plan.
+5. secrets-engine applies allowed metadata through the minimal stage role.
+6. Secret value is provisioned by approved custody mode.
+7. Positive and negative verification run.
+8. Catalog readiness becomes resolvable for ops-warden and consumers.
+
+### Use a Secret
+
+1. Consumer asks ops-warden or secrets-engine for a catalog id.
+2. secrets-engine checks catalog, stage, readiness, identity, and decision state.
+3. secrets-engine fetches the value through OpenBao using a delivery role.
+4. The value is injected only into the child process or temporary config.
+5. Temporary material is removed.
+6. Non-secret evidence is recorded.
+
+Target shape:
+
+```bash
+secrets-engine exec --catalog whynot-design-npm-publish -- npm publish
+```
+
+### Rotate a Secret
+
+1. Rotation request is linked to the existing catalog entry.
+2. New value is provisioned under approved custody.
+3. Consumers are switched or verified.
+4. Old value is revoked or deactivated.
+5. Evidence records old/new version identifiers without raw values.
+
+### Mark Compromised or Deactivated
+
+1. Actor marks the lane compromised or requests deactivation.
+2. secrets-engine blocks delivery immediately where possible.
+3. OpenBao leases/tokens are revoked.
+4. Related policies or auth roles are disabled if required.
+5. ops-warden readiness becomes not resolvable.
+6. Evidence and follow-up tasks are recorded.
+
+## Explicit Non-responsibilities
+
+secrets-engine must not:
+
+- replace OpenBao;
+- make identity or authorization decisions by itself;
+- issue SSH certificates;
+- establish network tunnels;
+- persist raw secret values outside OpenBao as normal operation;
+- put secrets into prompts, chat, State Hub, Git, or logs;
+- make production changes without an approved decision;
+- normalize insecure bootstrap shortcuts into permanent operations.
+
+## First Pilot
+
+The first pilot lane is:
+
+```text
+catalog id: whynot-design-npm-publish
+field: NPM_AUTH_TOKEN
+consumer: whynot-design npm publish workflow
+```
+
+The pilot should prove:
+
+- a catalog entry can describe the lane without a raw value;
+- an approved decision can drive OpenBao policy and auth role creation;
+- provisioning can happen without secret disclosure;
+- positive and negative verification can be recorded;
+- `secrets-engine exec` can deliver the token to `npm publish` safely;
+- ops-warden can route to secrets-engine and report readiness.
+
+## Canonicalization Tasks
+
+These concepts should be aligned with info-tech-canon as the implementation
+hardens:
+
+- stage names and aliases;
+- catalog entry schema terms;
+- decision states and evidence vocabulary;
+- delivery mode names;
+- compromised, deactivated, rotated, ready, and resolvable states;
+- standard OpenBao path and policy naming patterns.

workplans/NK-WP-0001-sso-mfa-platform.md

@@ -9,7 +9,8 @@ topic_slug: netkingdom
 state_hub_workstream_id: 39263c4b-ef70-4053-b782-350834b7e1be
 created: "2026-02-28"
 updated: "2026-03-21"
-superseded_by: NK-WP-0003---
+superseded_by: NK-WP-0003
+---
 
 # SSO & MFA Platform — Keycloak + privacyIDEA on Kubernetes
 

workplans/NK-WP-0002-local-identity.md

@@ -3,7 +3,7 @@ id: NK-WP-0002
 type: workplan
 title: "Local Identity — Bootstrap User Store & Minimal OIDC"
 domain: infotech
-status: completed
+status: finished
 owner: worsch
 topic_slug: netkingdom
 state_hub_workstream_id: 7c9021b1-319c-4b4a-a8be-0642239a1893

workplans/NK-WP-0006-recursive-platform-identity-security-architecture.md

@@ -4,7 +4,7 @@ type: workplan
 title: Recursive platform identity and security architecture
 domain: infotech
 repo: net-kingdom
-status: done
+status: finished
 owner: Bernd Worsch
 topic_slug: netkingdom
 created: 2026-05-17

workplans/NK-WP-0007-object-storage-sts-credential-vending.md

@@ -4,7 +4,7 @@ type: workplan
 title: Object Storage STS Credential Vending
 domain: infotech
 repo: net-kingdom
-status: done
+status: finished
 owner: codex
 topic_slug: netkingdom
 planning_priority: high

workplans/NK-WP-0010-genesis-security-pattern-completion.md

@@ -4,7 +4,7 @@ type: workplan
 title: Genesis Security Pattern Completion
 domain: infotech
 repo: net-kingdom
-status: done
+status: finished
 owner: codex
 topic_slug: netkingdom
 planning_priority: medium