tegwick
0d62ac501d
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>
2.7 KiB
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:
- One-line ask. What is being requested, in a sentence a non-expert would understand.
- 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). - To what. The exact path/policy/scope — narrow enough that a reader can tell at a glance whether it's proportionate to the ask.
- 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.
- 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.
- 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
baocommand 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.