net-kingdom/workplans/NK-WP-0058-bounded-execution-operability.md

---
id: NK-WP-0058
type: workplan
title: "Bounded execution operability: clear boundaries, lean interfaces, transparent diagnostics"
domain: infotech
repo: net-kingdom
status: proposed
flavor: implementation
owner: claude
topic_slug: netkingdom
created: "2026-11-05"
updated: "2026-11-05"
related:
  - NK-WP-0056
  - NK-WP-0057
state_hub_workstream_id: "30b26339-60cd-510b-97cb-93eaf304a2c3"
---

# 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
state_hub_task_id: "fe618717-0c28-51c5-8edb-e5d2f4ba2252"
```

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]
state_hub_task_id: "a33eeee6-caef-57d4-b067-26231a19a165"
```

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]
state_hub_task_id: "0e403b18-cf7b-5899-bd86-661fc7284014"
```

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]
state_hub_task_id: "9b70a844-edb2-50b3-a06c-be57d3823b3c"
```

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]
state_hub_task_id: "30f8c62e-5707-5395-9d86-178cd650fb59"
```

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]
state_hub_task_id: "6a4c7413-0675-5a06-b471-5f849ce0c721"
```

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]
state_hub_task_id: "a99424ed-ee8b-5db4-9fa7-2ae5fc32c39c"
```

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]
state_hub_task_id: "dd2b72c8-7225-5b89-8936-d44c99f95872"
```

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.