diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 31cda20..fdb691d 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -55,6 +55,7 @@ | workplan | NK-WP-0055 | active | — | workplans/NK-WP-0055-security-platform-production-readiness.md | | workplan | NK-WP-0056 | finished | — | workplans/NK-WP-0056-bounded-executor-path.md | | workplan | NK-WP-0057 | proposed | — | workplans/NK-WP-0057-decision-routing-by-responsibility.md | +| workplan | NK-WP-0058 | proposed | — | workplans/NK-WP-0058-bounded-execution-operability.md | | task | NK-WP-ADHOC-2026-07-02-T01 | done | — | workplans/ADHOC-2026-07-02.md | | task | NK-WP-ADHOC-2026-07-02-T02 | done | — | workplans/ADHOC-2026-07-02.md | | task | NK-WP-ADHOC-2026-08-14-T01 | done | — | workplans/ADHOC-2026-08-14.md | @@ -369,6 +370,14 @@ | task | NK-WP-0057-T02 | todo | — | workplans/NK-WP-0057-decision-routing-by-responsibility.md | | task | NK-WP-0057-T03 | todo | — | workplans/NK-WP-0057-decision-routing-by-responsibility.md | | task | NK-WP-0057-T04 | todo | — | workplans/NK-WP-0057-decision-routing-by-responsibility.md | +| task | NK-WP-0058-T01 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T02 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T03 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T04 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T05 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T06 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T07 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | +| task | NK-WP-0058-T08 | todo | — | workplans/NK-WP-0058-bounded-execution-operability.md | | intake | NK-IN-0001 | closed | blue | docs/intakes/activity-core-ops-sso-operators.md | | intake | NK-IN-0002 | closed | blue | docs/intakes/activity-core-ops-sso-operators.md | | intake | NET-IN-0001 | open | — | intakes/intakes.md | diff --git a/workplans/NK-WP-0058-bounded-execution-operability.md b/workplans/NK-WP-0058-bounded-execution-operability.md new file mode 100644 index 0000000..f9fee07 --- /dev/null +++ b/workplans/NK-WP-0058-bounded-execution-operability.md @@ -0,0 +1,250 @@ +--- +id: NK-WP-0058 +type: workplan +title: "Bounded execution operability: clear boundaries, lean interfaces, transparent diagnostics" +domain: infotech +repo: net-kingdom +status: proposed +flavor: design +owner: claude +topic_slug: netkingdom +created: "2026-11-05" +updated: "2026-11-05" +related: + - NK-WP-0056 + - NK-WP-0057 +--- + +# NK-WP-0058 — Bounded execution operability + +Intake from the founder after NK-WP-0056 finished (2026-11-05). The pilot worked: one admission, one approval, then +an unattended rotation in 30 s. Getting there was the problem: + +- about 50 founder copy-paste rounds; +- one wasted window, because the approver was configured differently in three repos; +- an opaque executor error that took four founder-run diagnostic pods to locate; +- runbook assumptions that failed live (admission policy on Secrets, Argo-managed ConfigMap, warden environment, + `kubectl wait`); +- a write role left open overnight; +- workers in two repos building competing scripts and using different names. + +The review behind this workplan is the session of 2026-11-05. Its findings are in the NK-WP-0056 evidence +(`docs/evidence/2026-11-04-nk56-t06-pilot/`, `docs/evidence/2026-11-05-nk56-t06-pilot/`). + +## Boundary conditions (apply to every task) + +Founder direction, 2026-11-05. A task is not done unless its result meets all four: + +1. **Clear responsibility boundaries between repos.** Every interface has one owner. Every artifact has one source of + truth, which is named, and no repo silently mirrors another's configuration. Where a responsibility is unclear, the + task records the question for NK-WP-0057 (decision routing) or the owning repo, instead of deciding it locally. +2. **Better interfaces between repos and with the human operator.** Cross-repo contracts are written down, versioned + and checked: names, paths, roles, payloads and exit codes. Founder steps are few, short and stateful. Each one + prints a single value-free result and is safe to repeat. +3. **Transparency first, so diagnosis is easy.** + - every failure names where it happened and why, by phase, endpoint or check, never a bare exception type; + - status is readable by the agent identity without secrets; + - every live step leaves a value-free receipt. +4. **Minimal code, carried by fully automated interface tests.** + - Prefer deleting, merging or reusing an owner's tool over adding one. + - Every cross-repo interface used by the bounded-execution path gets automated contract tests, against stubs or + the owner's real source where the service can't run in CI. + - Contract tests replace manual rehearsal wherever they can. + - Tests run in CI; a change to the code an interface depends on, in either repo, fails a test. + +## Tasks + +### Interface and responsibility inventory + +```task +id: NK-WP-0058-T01 +status: todo +priority: high +assignee: claude-code +``` + +List every interface the bounded-execution path crosses. For each, record: + +- **owner and source of truth;** +- **consumer;** +- **the exact contract:** names, paths, payloads, exit codes; +- **how it is tested today** (none, stub, real source, live only); +- **the 2026-11-04/05 failures it caused.** + +Cover at least these pairs: + +- executor ↔ approval-engine, KeyCape, audit-core, informed-decision, OpenBao and LLDAP; +- rapp ↔ net-kingdom; +- railiance-platform CCRs and broker ↔ net-kingdom cases; +- audit-core seed ↔ railiance-platform custody; +- informed-decision routing ↔ access-engine policy; +- Argo ↔ manual applies; +- warden lanes ↔ child scripts; +- founder ↔ each runbook. + +Mark duplicated or unowned pieces, for example the two seeders, the two Secret names, and the approver in three +places. + +**Done when:** a single contract table is in `docs/` with sources, and each row is marked keep, merge, delete or +needs an owner decision. + +### Contract tests for the cross-repo interfaces + +```task +id: NK-WP-0058-T02 +status: todo +priority: high +assignee: claude-code +depends_on: [NK-WP-0058-T01] +``` + +For every interface marked keep or merge, add an automated contract test in CI: + +- against the owner's real source where it runs locally (approval-engine, audit-core, informed-decision intake, + the KeyCape image); +- otherwise against a stub that is generated from, or checked against, the owner's contract. + +Fold the existing exercises (T19 approval identity, T15 audit sender) into this suite instead of keeping them as +separate scripts. A change in either repo that breaks a contract fails CI in the consumer, such as a Secret name, a +role name, a response code or a memo field. + +**Done when:** the suite runs in CI for every interface in the table; each interface that failed on 2026-11-04/05 +has a test that would have caught it; and the code that duplicated a contract by hand is removed. + +### Readiness check before any window opens + +```task +id: NK-WP-0058-T03 +status: todo +priority: high +assignee: claude-code +depends_on: [NK-WP-0058-T01] +``` + +One command that verifies the chain while nothing is at stake, so a window opens only when everything is green: + +- the admission is valid and its pins match the pinned image; +- the admission's approver equals informed-decision's recipient and the approval principal; +- the CCR approvals and bindings are complete; +- the case status, custody delivery and endpoint reachability; +- the write role is absent. + +Add an executor `--preflight-only` mode that runs setup and preflight without consuming. It replaces hand-written +diagnostic pods. + +The check reuses the owners' validators. Where a check needs authority the agent lacks, it names the single +read-only founder command that supplies it. + +**Done when:** the readiness check is tested on stubs, runs with the agent identity wherever possible, and +`--preflight-only` reports every failure it finds by phase and endpoint. + +### Founder interface: few, short, stateful steps + +```task +id: NK-WP-0058-T04 +status: todo +priority: high +assignee: claude-code +depends_on: [NK-WP-0058-T03] +``` + +Replace the copy-paste runbooks for a run with a small command set: `ready`, `request`, `run` (which opens the window +and always closes it), `status` and `close`. Each command: + +- keeps its inputs in a state file, not in shell variables; +- numbers receipts itself; +- is idempotent; +- has no line over 120 characters in its instructions; +- prints one value-free result line. + +Build on `pilot-run.sh`, and delete the runbook prose these commands replace. Record the identity hygiene a step +needs: a browser profile per identity, and when a fresh OTP login is due. + +**Done when:** a full pilot run is at most five short founder commands plus the approval in informed-decision. The +commands are tested on stubs, and T06's runbook shrinks accordingly. + +### Agent status visibility without secrets + +```task +id: NK-WP-0058-T05 +status: todo +priority: medium +assignee: claude-code +needs_human: true +intervention_note: "Founder approves a read-only status grant for the agent identity (owner: railiance-cluster / railiance-platform)." +depends_on: [NK-WP-0058-T01] +``` + +Propose a read-only grant for the agent's Kubernetes identity in the namespaces the path uses. The grant covers: + +- the status and conditions of Jobs, pods, ExternalSecrets and Deployments; +- pod logs of executor Jobs, which are value-free by contract. + +It never covers Secrets, kubeconfigs or exec. Route the grant through its owner as a reviewed change. Record what +stays founder-only and why. + +**Done when:** the grant is decided, and if approved applied and verified with `can-i`. Every status the agent had +to ask the founder for on 2026-11-04/05 is then readable, or explicitly founder-only. + +### Write-role window closed by the platform + +```task +id: NK-WP-0058-T06 +status: todo +priority: medium +assignee: claude-code +depends_on: [NK-WP-0058-T01] +``` + +Make the end of CCR-2026-0058's window not depend on a person remembering. Two candidates, to be chosen with +railiance-platform (the owner): + +- a scheduled close at `not_after`; +- an alert or finding whenever the write role exists outside an open admission window. The latter could reuse + audit-core's stream findings or posture feedback. + +Also settle the open check from 2026-11-05: OpenBao's audit should confirm that no login used the role during the +overnight window. + +**Done when:** an unclosed window is closed or flagged without human memory, tested on a stub, and the 2026-11-05 +check is recorded. + +### Runbook and tooling conventions + +```task +id: NK-WP-0058-T07 +status: todo +priority: medium +assignee: claude-code +depends_on: [NK-WP-0058-T01] +``` + +Turn the 2026-11-04/05 surprises into checked conventions: + +- server-side apply only; +- check the managing controller before writing apply commands; +- poll status instead of `kubectl wait` with several conditions; +- no hard-coded kubeconfigs in owner tools; +- warden strips every token variable (ops-warden owner request); +- receipts are named by the tool, not by the operator. + +Prefer a lint or a test over prose, and remove the hard-coded and duplicated bits it finds. + +**Done when:** the conventions are enforced by a test or lint in CI for the net-kingdom and rapp runbooks and tools, +and the owner requests for other repos are sent and recorded. + +### Multi-repo worker protocol + +```task +id: NK-WP-0058-T08 +status: todo +priority: low +assignee: claude-code +depends_on: [NK-WP-0058-T01] +``` + +Before worker agents start on a cross-repo change, they get one contract excerpt: the names, paths and roles they +touch, and the single owning script per step. Each worker's result is then checked against that excerpt with the +T02 tests. This prevents the competing seeders and mismatched names seen on 2026-11-04. + +**Done when:** the protocol is in the agent instructions, and its first use is checked by the contract tests.