152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# SCOPE.md vs INTENT.md Gap Analysis
|
|
|
|
Date: 2026-06-29
|
|
Author: codex
|
|
|
|
## Executive Summary
|
|
|
|
`SCOPE.md` is now broadly aligned with `INTENT.md`. The core boundary is
|
|
consistent: OpenBao enforces custody/policy/lease/audit; secrets-engine owns the
|
|
workflow, catalog, validation, delivery surface, and non-secret evidence; flex-auth
|
|
and State Hub decisions authorize; key-cape/user-engine own identity;
|
|
ops-warden routes credential needs and keeps SSH certificate issuance.
|
|
|
|
The most important recent alignment improvement is that `SCOPE.md` now covers
|
|
auth-capability lanes, which fit the intent principle of low-friction secure work
|
|
without broad OpenBao power. The remaining gaps are mostly about document role,
|
|
not contradiction: `INTENT.md` is stable and aspirational, while `SCOPE.md` mixes
|
|
boundary, current implementation state, workplan status, and capability registry
|
|
metadata.
|
|
|
|
## Alignment
|
|
|
|
- Both documents describe secrets-engine as the secure interaction and automation
|
|
layer for approved secret custody, delivery, and lifecycle work.
|
|
- Both keep OpenBao as the enforcement backend rather than something this repo
|
|
replaces.
|
|
- Both reject raw secret values in Git, State Hub, chat, prompts, workplans, and
|
|
normal logs.
|
|
- Both place authorization outside this repo, with secrets-engine requiring and
|
|
verifying decisions before privileged actions.
|
|
- Both preserve stage-aware privilege separation across build, test, and
|
|
production.
|
|
- Both treat ops-warden as a routing/front-door integration, not a secret-vending
|
|
subsystem.
|
|
- Both emphasize low-friction operator/agent workflows bounded by narrow grants,
|
|
TTLs, delivery rules, and audit evidence.
|
|
|
|
## Notable Drift
|
|
|
|
### 1. SCOPE.md Is More Current-State Ledger Than Boundary
|
|
|
|
`INTENT.md` explicitly says it is aspirational and stable. `SCOPE.md` is intended
|
|
as a lightweight boundary for agents and contributors, but its `Current State`
|
|
section now includes detailed workplan status, specific test counts, lane names,
|
|
and pending operational gates.
|
|
|
|
This is useful for agents, but it will age quickly. Test counts, active workplan
|
|
states, and named pending gates belong more naturally in workplans, history notes,
|
|
or the generated custodian brief. SCOPE can still summarize current maturity, but
|
|
it should avoid facts that need frequent operational churn.
|
|
|
|
### 2. Service API Direction Is Missing From SCOPE.md
|
|
|
|
`INTENT.md` says the repo should evolve into a CLI and service API that
|
|
ops-warden, agents, CI, and future UI surfaces can use without knowing OpenBao
|
|
internals. `SCOPE.md` currently emphasizes the CLI, catalog, policies, delivery
|
|
modes, and capability blocks, but it does not explicitly name service-mode/API
|
|
as an in-scope future surface.
|
|
|
|
This is a real scope gap if future work is expected to add an API. SCOPE should
|
|
either list the service API as in scope or explicitly defer it to a later
|
|
workplan while keeping it inside the strategic boundary.
|
|
|
|
### 3. Hardening Phase Is Present But Not Mapped
|
|
|
|
`INTENT.md` names a hardening path: replace bootstrap token files with OIDC or
|
|
service auth, wrapped delivery, short leases, dual control for production
|
|
provisioning, and routine rotation/deactivation workflows.
|
|
|
|
`SCOPE.md` includes many of these pieces indirectly, but it does not present the
|
|
hardening posture as a clear phase or checklist. The result is that an agent can
|
|
see what is allowed, but not always which remaining hardening moves are expected
|
|
next.
|
|
|
|
### 4. Auth-Capability Lanes Are In Scope But Not In INTENT.md Vocabulary
|
|
|
|
`SCOPE.md` now correctly includes auth-capability lanes. `INTENT.md` does not use
|
|
that term, but the concept is compatible with its principles: least friction
|
|
without broad power, OpenBao-enforced policy, short-lived credential surfaces,
|
|
and no raw secret movement through coordination systems.
|
|
|
|
This is not a conflict. It is a vocabulary gap. INTENT can remain stable, but a
|
|
future small amendment could mention that secrets-engine also brokers scoped
|
|
OpenBao capabilities, not only stored secret values.
|
|
|
|
### 5. Ops-Warden Wording Needs Care
|
|
|
|
`SCOPE.md` says secrets-engine "mints and custodies the tokens" in the ops-warden
|
|
relationship note. That is directionally true for OpenBao-backed credential
|
|
material, but it can be read too broadly. The intent boundary is that ops-warden
|
|
routes credential use and issues SSH certs, while OpenBao remains the custody
|
|
backend.
|
|
|
|
Safer wording would emphasize that secrets-engine orchestrates OpenBao-backed
|
|
issuance, delivery, and handoff without owning SSH certificate issuance or storing
|
|
secret values itself.
|
|
|
|
### 6. Lifecycle Surface Is Listed But Underdescribed
|
|
|
|
Both documents mention rotation, revocation, deactivation, reversibility, and
|
|
audit evidence. `SCOPE.md` lists these as in scope and includes revoke in the MVP
|
|
path, but it does not provide a dedicated capability block or boundary language
|
|
for routine rotation/deactivation.
|
|
|
|
That gap matters because lifecycle work is central to the intent. A future scope
|
|
update could add a capability block for rotation/revocation/deactivation evidence
|
|
once the implementation is mature enough.
|
|
|
|
## Missing Or Underweighted In SCOPE.md
|
|
|
|
- Service API / service mode as a future but in-bound surface.
|
|
- Dual-control production provisioning expectations.
|
|
- OIDC/service-auth replacement of bootstrap token files as an explicit hardening
|
|
target.
|
|
- Response wrapping and short leases as first-class hardening/delivery concepts,
|
|
not only implied by delivery-mode terminology.
|
|
- Routine rotation/deactivation as a durable capability, separate from one-off
|
|
revoke support.
|
|
- Clearer distinction between OpenBao custody and secrets-engine orchestration
|
|
when describing minted tokens or AppRole material.
|
|
- Stable boundary language separated from volatile implementation status.
|
|
|
|
## Missing Or Underweighted In INTENT.md
|
|
|
|
- Auth-capability lanes as first-class non-KV grants.
|
|
- The ops-warden `warden-sign` use case as an example of routing a scoped
|
|
OpenBao capability without making ops-warden vend secrets.
|
|
- The maturity-gated publication-scope policy concept.
|
|
- The catalog distinction between KV secret lanes and capability lanes.
|
|
|
|
These are small vocabulary/extensions gaps rather than strategic mismatches.
|
|
|
|
## Recommended Follow-Up
|
|
|
|
1. Keep `SCOPE.md` as the operational boundary, but trim volatile status details
|
|
into `history/` or workplans after each milestone.
|
|
2. Add service API/service mode to `SCOPE.md` as an in-scope future surface if
|
|
that remains the intended direction.
|
|
3. Add a short `Hardening Trajectory` section to `SCOPE.md` that mirrors
|
|
`INTENT.md`: OIDC/service auth, wrapped delivery, short leases, dual control,
|
|
routine rotation/deactivation.
|
|
4. Tighten ops-warden wording so it says secrets-engine orchestrates scoped
|
|
OpenBao issuance/handoff while OpenBao keeps custody and ops-warden keeps SSH
|
|
cert issuance.
|
|
5. Consider a small `INTENT.md` update later to name auth-capability lanes as a
|
|
valid class of approved secret-adjacent work.
|
|
|
|
## Assessment
|
|
|
|
No major contradiction was found. `SCOPE.md` is implementation-rich and current;
|
|
`INTENT.md` remains stable and mission-oriented. The gap to manage is keeping
|
|
SCOPE useful to agents without turning it into a second workplan ledger.
|