secrets-engine/workplans/SECRETS-WP-0005-scope-intent-value-gaps.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
SECRETS-WP-0005	workplan	Close high-value SCOPE and INTENT gaps	infotech	secrets-engine	finished	codex	custodian	2026-06-29	2026-06-29	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

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

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

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

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

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

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

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.