---
id: SECRETS-WP-0005
type: workplan
title: "Close high-value SCOPE and INTENT gaps"
domain: infotech
repo: secrets-engine
status: finished
owner: codex
topic_slug: custodian
created: "2026-06-29"
updated: "2026-06-29"
state_hub_workstream_id: "262e8539-bfd9-435c-81fc-8148c9c5f744"
---

# SECRETS-WP-0005 - Close high-value SCOPE and INTENT gaps

## Goal

Convert the SCOPE/INTENT gap analysis into concrete documentation and planning
changes that improve day-to-day value for agents, operators, and cross-repo
integrators.

The main value target is clarity: keep `SCOPE.md` useful as a stable operating
boundary, make the service/API direction visible, map the hardening trajectory,
and tighten language around OpenBao custody, ops-warden routing, and lifecycle
work.

## Source Analysis

This workplan is based on:

- `history/2026-06-29-scope-intent-gap-analysis.md`
- `SCOPE.md`
- `INTENT.md`
- `docs/netkingdom-security-infrastructure.md`

The assessment found no major contradiction. The gap is that `SCOPE.md` is now
implementation-rich and current, while `INTENT.md` is stable and aspirational.
The best value comes from separating durable boundary language from volatile
status, then making future high-value surfaces explicit enough that agents do
not have to rediscover the direction.

## Value Strategy

Prioritize changes that:

- reduce stale operational text in long-lived boundary docs;
- make future work easier to route without adding new authority;
- clarify custody and routing boundaries before live OpenBao handoffs;
- turn hardening goals into visible acceptance targets;
- preserve current useful context by moving it to `history/` instead of deleting
  it.

## Tasks

## T01 - Separate durable scope from volatile status

```task
id: SECRETS-WP-0005-T01
status: done
priority: high
state_hub_task_id: "37c72cb5-d3fa-42a7-a9a4-28712582539e"
```

2026-06-29: Refactored `SCOPE.md` current-state language to remove exact test counts, active workplan state, and pending live-gate detail. Durable status now points agents to workplans, `.custodian-brief.md`, and `history/`.

Refactor `SCOPE.md` so it remains a stable boundary document rather than a
second workplan ledger.

Keep the current maturity summary, but remove or generalize details that will
stale quickly: exact test counts, active workplan state, and pending live gates.
Move any useful historical detail into `history/` if it is not already captured.

Acceptance:

- `SCOPE.md` still tells agents what this repo owns and does not own.
- `SCOPE.md` no longer depends on exact test counts or active workplan status to
  remain true.
- Current-state details needed for continuity are preserved in `history/` or the
  relevant workplan.
- `git diff --check` is clean.

## T02 - Add service/API direction to the boundary

```task
id: SECRETS-WP-0005-T02
status: done
priority: high
state_hub_task_id: "8703854c-c722-45a9-ab93-1bd914ebd37f"
```

2026-06-29: Added future service/API mode to `SCOPE.md` as an in-bound surface over proven CLI semantics for plans, deliveries, handoffs, lifecycle actions, and evidence.

Represent the `INTENT.md` service-mode direction in `SCOPE.md` without
overcommitting implementation.

The service/API surface should be described as in scope for future work: a
stable interface for ops-warden, agents, CI, workloads, and future UI surfaces
to request approved plans, deliveries, handoffs, and non-secret evidence without
knowing OpenBao internals.

Acceptance:

- `SCOPE.md` names service/API mode as an in-bound future surface.
- The boundary says service mode does not replace OpenBao, flex-auth, key-cape,
  user-engine, or ops-warden.
- No new API contract is promised beyond what this repo can plausibly own.

## T03 - Add a hardening trajectory section

```task
id: SECRETS-WP-0005-T03
status: done
priority: high
state_hub_task_id: "351eea5d-878b-4ddf-9d1f-6dd59929e3b0"
```

2026-06-29: Added a durable `Hardening Trajectory` section to `SCOPE.md`, linked to `docs/hardening-backlog.md`, covering scoped auth, wrapping/leases, dual control, lifecycle, and service/API maturation.

Add a short durable hardening section to `SCOPE.md` that mirrors the direction
in `INTENT.md`.

It should cover:

- replacing bootstrap token files with OIDC, service auth, or other scoped auth;
- response wrapping and short leases;
- dual control for production provisioning;
- routine rotation, revocation, and deactivation;
- evidence that proves delivery and lifecycle actions without exposing values.

Acceptance:

- `SCOPE.md` gives agents a clear next-hardening map.
- The hardening section does not claim these items are already complete.
- The section references existing backlog or workplan locations when useful.

## T04 - Tighten ops-warden and custody wording

```task
id: SECRETS-WP-0005-T04
status: done
priority: high
state_hub_task_id: "9444e6ba-2853-42d4-a074-e21b350d5d8a"
```

2026-06-29: Tightened `SCOPE.md` and `docs/ops-warden-routing-contract.md` so OpenBao remains the custody backend, secrets-engine orchestrates approved OpenBao-backed flows, and ops-warden remains a conduit-not-broker SSH cert issuer.

Review `SCOPE.md`, `INTENT.md`, and routing docs for wording that could imply
secrets-engine stores raw secret values itself or that ops-warden vends
non-SSH secrets.

Preferred phrasing:

- OpenBao keeps custody, policy, lease, and audit.
- secrets-engine orchestrates cataloged OpenBao-backed issuance, delivery,
  handoff, verification, and revocation.
- ops-warden routes non-SSH credential needs here and issues SSH certificates
  itself.

Acceptance:

- `SCOPE.md` no longer says secrets-engine broadly "custodies tokens" without
  clarifying OpenBao custody.
- Routing docs remain aligned with the conduit-not-broker model.
- No text suggests raw values may move through Git, State Hub, chat, prompts,
  workplans, or normal logs.

## T05 - Make lifecycle capability first-class

```task
id: SECRETS-WP-0005-T05
status: done
priority: medium
state_hub_task_id: "b259a499-a1aa-4b37-bf4d-bf19ed79eb99"
```

2026-06-29: Added a first-class `Lifecycle and non-secret evidence` capability block to `SCOPE.md` for provision, verify, deliver, rotate, revoke, deactivate, and audit workflows.

Add durable boundary language for rotation, revocation, deactivation, and
non-secret lifecycle evidence.

This should not require implementing new lifecycle code immediately. The goal is
to make lifecycle ownership and value clear enough that future implementation
work can be routed cleanly.

Acceptance:

- `SCOPE.md` includes lifecycle as a first-class capability or boundary concern,
  not only as a passing list item.
- The text distinguishes one-off revoke support from routine lifecycle
  management.
- Any follow-up implementation gaps are linked to `docs/hardening-backlog.md` or
  a future workplan.

## T06 - Bring INTENT vocabulary forward carefully

```task
id: SECRETS-WP-0005-T06
status: done
priority: medium
state_hub_task_id: "cdd1c8a1-11ac-4d92-8d67-f239e62b0e62"
```

2026-06-29: Updated `INTENT.md` carefully to acknowledge scoped OpenBao capability grants and auth-capability lanes while keeping the file mission-level and implementation-light.

Consider a small `INTENT.md` update for concepts that have become important
without changing the mission: auth-capability lanes, scoped OpenBao
capabilities, and the distinction between KV secret lanes and non-KV capability
lanes.

This task is intentionally careful because `INTENT.md` should remain stable and
aspirational, not become implementation status.

Acceptance:

- `INTENT.md` acknowledges scoped OpenBao capabilities if the wording improves
  clarity.
- The file remains stable, concise, and mission-oriented.
- Implementation-specific lane names stay in `SCOPE.md`, workplans, or history
  unless they serve as examples.

## T07 - Verify, sync, and record closeout

```task
id: SECRETS-WP-0005-T07
status: done
priority: medium
state_hub_task_id: "5168182e-9fce-4bf4-8e6d-7c6e93cc8f71"
```

2026-06-29: Final documentation checks passed (`git diff --check` clean), docs were reviewed against `docs/netkingdom-security-infrastructure.md`, and State Hub consistency sync applied the SECRETS-WP-0005 task updates.

Run final documentation checks, preserve non-secret closeout evidence, and sync
the workplan state.

Acceptance:

- `git diff --check` is clean.
- The final changed docs are reviewed against
  `docs/netkingdom-security-infrastructure.md`.
- State Hub progress records the closeout.
- After workplan file changes, the custodian consistency sync is run or the
  operator is asked to run `make fix-consistency REPO=secrets-engine`.

## Exit Criteria

- `SCOPE.md` is stable enough for agents to use without frequent status churn.
- `INTENT.md` and `SCOPE.md` agree on the expanded lane model without turning
  INTENT into an implementation ledger.
- Service/API direction, hardening trajectory, custody boundaries, and lifecycle
  ownership are visible and actionable.
- No raw secret values, token material, or sensitive operational details are
  added to Git, State Hub, chat, prompts, workplans, or normal logs.