Review/optimize checklist, executive-summary format, build executor (T02-T04)
docs/review-optimize-checklist.md: six checks (naming, TTL/scoping,
redundancy, compaction, ease of use, posture), applied for real to the
rein-openweights plan's section 4 -- including a genuinely useful
finding (credentials.py already expects this exact path/delivery shape,
zero code changes needed to consume it).
docs/executive-summary-format.md: six fixed fields, no bao syntax, no
restating earlier sections, explicit approve/reject/revise decision.
Rendered for real into the plan's section 5 -- ready for an actual
decision.
src/ops_mason/{plan,executor,audit}.py: the phase-4 build executor for
credential_type openbao-approle-kv. Refuses to run against anything but
an approved plan -- verified the refusal never even calls subprocess.run.
role_id/secret_id (the AppRole's own access credential, not the
downstream secret) land as 0600 files, never logged; the HCL policy
goes over stdin, never argv; the audit trail is metadata-only. 12 tests,
all mocked at the bao boundary (no live OpenBao access from this
session).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
123ccfe20c
commit
0d62ac501d
12 changed files with 645 additions and 12 deletions
55
docs/executive-summary-format.md
Normal file
55
docs/executive-summary-format.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
# Executive summary format (phase 3)
|
||||
|
||||
The one mandatory human checkpoint (`INTENT.md` design principle 4). Lives
|
||||
as section 5 of the plan file itself (`docs/construction-plan-format.md`)
|
||||
— generated from sections 1-4, not a separate document that can drift
|
||||
from the plan it's summarizing.
|
||||
|
||||
## Why this shape
|
||||
|
||||
Written so the founder never has to read a `bao` command, a policy JSON
|
||||
blob, or an AppRole config to make the call. Six fixed fields, always in
|
||||
this order, always answerable in one or two sentences each:
|
||||
|
||||
1. **One-line ask.** What is being requested, in a sentence a non-expert
|
||||
would understand.
|
||||
2. **Who/what gets access.** The exact new principal (AppRole, role,
|
||||
service identity) — and an explicit statement that nothing *else*
|
||||
gains anything, if that's true (it almost always should be, per
|
||||
`INTENT.md`'s reuse-before-creation principle).
|
||||
3. **To what.** The exact path/policy/scope — narrow enough that a reader
|
||||
can tell at a glance whether it's proportionate to the ask.
|
||||
4. **For how long.** Token TTL and, separately, whether the underlying
|
||||
AppRole credential itself expires or rotates — these are two different
|
||||
questions and both need an answer, not just the token TTL.
|
||||
5. **Blast radius if the credential leaks.** What could actually be done
|
||||
with it — bounded to what section 3 grants, plus a note on whether the
|
||||
downstream secret itself (e.g. a provider API key) carries its own
|
||||
independent risk that this plan doesn't change either way.
|
||||
6. **Cost to reverse.** How many commands, touching how many other
|
||||
consumers, to undo this if it turns out wrong. If the answer is
|
||||
"everything is isolated, reversing this touches nothing else," say so
|
||||
explicitly — that's exactly the property `INTENT.md`'s
|
||||
reuse-vs-new reasoning is supposed to produce.
|
||||
|
||||
Ends with an explicit three-way decision: **approve**, **reject**, or
|
||||
**send back to phase 1** with what to change. No plan should read as a
|
||||
foregone conclusion — "send back" needs to be as easy to pick as
|
||||
"approve."
|
||||
|
||||
## What this format deliberately excludes
|
||||
|
||||
- No `bao` command syntax, no policy HCL, no JSON.
|
||||
- No restating sections 1-4 in full — the executive summary is a
|
||||
compression of what's already there, findable by scrolling up in the
|
||||
same file if more detail is wanted.
|
||||
- No default recommendation baked into the rendering itself beyond what
|
||||
the plan's own reuse-vs-new reasoning already produced — the summary
|
||||
reports the plan's conclusion, it doesn't editorialize a second opinion
|
||||
on top of it.
|
||||
|
||||
## Worked example
|
||||
|
||||
`plans/rein-openweights-openrouter-approle.md` section 5 — the real
|
||||
executive summary for the first real plan, ready for an actual approve /
|
||||
reject / revise decision.
|
||||
63
docs/review-optimize-checklist.md
Normal file
63
docs/review-optimize-checklist.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
# Review / optimize checklist (phase 2)
|
||||
|
||||
Runs against a draft plan (`plans/<id>.md`, section 2-3 filled in) before
|
||||
it's shown to anyone. Fill in section 4 ("Review notes") of the plan file
|
||||
directly — this checklist is not a separate artifact, it's what section 4
|
||||
*is*. A plan with an empty section 4 is not ready for phase 3.
|
||||
|
||||
This can be run by a human or an agent going through the plan by hand —
|
||||
it does not need to be automated tooling before it's useful. Automating
|
||||
individual checks (e.g. a script that diffs proposed TTLs against
|
||||
existing lanes) is a reasonable future step once there's more than one
|
||||
worked example to generalize a checker from — not before (same
|
||||
generalize-from-a-second-example discipline the `glas-harness` reins use
|
||||
for their own deferred decisions).
|
||||
|
||||
## The checks
|
||||
|
||||
1. **Naming convention.** Does every new object's name follow the
|
||||
`<consumer>-<credential-purpose>` shape already visible in existing
|
||||
lanes (`agent-harness-binky-mail`, `workload-kv-read-<path-slug>`)? A
|
||||
plan proposing an unrelated naming scheme should be flagged, not
|
||||
waved through for "this one's different."
|
||||
|
||||
2. **TTL/scoping match.** Do proposed `token_ttl`/`token_max_ttl`/
|
||||
`token_num_uses`/`secret_id_ttl` values match an existing comparable
|
||||
lane, or is there a stated reason to diverge? Silent divergence (a
|
||||
shorter or longer TTL with no explanation) is a review finding, not a
|
||||
detail to skip past.
|
||||
|
||||
3. **Redundancy check.** Does a policy, AppRole, or KV path already exist
|
||||
that overlaps what's being proposed? This should already have been
|
||||
asked in section 2 (existing-structure survey) — phase 2 is the
|
||||
second pass confirming that answer still holds after the proposed
|
||||
changes are fully drafted, not skipping it because section 2 already
|
||||
looked.
|
||||
|
||||
4. **Compaction opportunity.** Does satisfying this demand make any
|
||||
*existing* lane redundant or mergeable? Not every plan will find one —
|
||||
most won't — but the check should be asked every time, not only when
|
||||
it's obviously true.
|
||||
|
||||
5. **Ease of use for the consumer.** Is the credential-acquisition path
|
||||
this plan builds toward straightforward for the actual consuming code
|
||||
to use (e.g. does it match an env-var/file-path convention the
|
||||
consumer's code already expects, per its own `credentials.py` or
|
||||
equivalent)? A technically-correct plan that's awkward for the
|
||||
consumer to actually integrate is a real review finding.
|
||||
|
||||
6. **Posture check.** Do the choices here (TTL length, rotation policy,
|
||||
`secret_id_ttl` expiry-or-not) match current organizational posture
|
||||
(`ops-warden/wiki/WorkloadSecurityPosture.md` — build phase today) —
|
||||
not assuming production-tier rigor that isn't the current posture, and
|
||||
not assuming dev-tier looseness forever. State the posture assumption
|
||||
explicitly rather than leaving it implicit.
|
||||
|
||||
## Worked example
|
||||
|
||||
`plans/rein-openweights-openrouter-approle.md` section 4 applies all six
|
||||
checks against a real plan — including one genuine finding (the TTL
|
||||
values were carried over from `agent-harness-binky-mail` by direct
|
||||
analogy rather than re-derived from scratch, which is exactly check 2
|
||||
working as intended: matching an existing lane rather than inventing a
|
||||
new number).
|
||||
Loading…
Add table
Add a link
Reference in a new issue