253 lines
8.9 KiB
Markdown
253 lines
8.9 KiB
Markdown
---
|
|
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.
|