secrets-engine/history/2026-06-29-scope-intent-gap-analysis.md

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.