56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
|
# 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.
|