Construction-plan format + first real plan draft (MASON-WP-0001-T01)
docs/construction-plan-format.md: one file per plan (plans/<id>.md), frontmatter status tracker (draft -> reviewed -> approved -> built -> catalogued, the phase-4 hard gate), six body sections threading all four phases through one document. Proven against real demand: plans/rein-openweights-openrouter-approle.md, phases 1-2 filled in. Found and reasoned through a real existing-structure question along the way -- the openrouter-llm-connect catalog lane could technically be reused, but its auth_method is interactive-caller-shaped and its policy is shared/high-risk; recommends a dedicated, narrowly scoped AppRole instead, same reasoning agent-harness-binky-mail used for its own dedicated lane. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
d3dbad34e1
commit
a762be9e17
3 changed files with 219 additions and 1 deletions
97
docs/construction-plan-format.md
Normal file
97
docs/construction-plan-format.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
# Construction plan format
|
||||
|
||||
The artifact phase 1 (`INTENT.md`) produces. One markdown file per plan,
|
||||
stored at `plans/<plan-id>.md` in this repo — plain, versioned, reviewable
|
||||
in a diff, not a database. `<plan-id>` is kebab-case and traceable to the
|
||||
demand that triggered it (usually a workplan task id from the requesting
|
||||
repo, e.g. `rein-openweights-openrouter-approle` for
|
||||
`glas-harness/GLAS-WP-0002-T02`).
|
||||
|
||||
A plan file is the single source of truth across all four phases: phase 1
|
||||
writes it, phase 2 edits it in place (self-review, not a separate
|
||||
document), phase 3's executive summary is generated *from* it (not a
|
||||
parallel artifact that can drift), and phase 4 reads the same file to
|
||||
execute and appends a result section when done.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: rein-openweights-openrouter-approle
|
||||
demand_source: glas-harness/workplans/GLAS-WP-0002-T02
|
||||
consumer_repo: rein-openweights
|
||||
credential_type: openbao-approle-kv
|
||||
status: draft # draft -> reviewed -> approved -> built -> catalogued
|
||||
approved_by: null # founder identity string, set only at phase 3 -> 4
|
||||
approved_at: null # ISO date, set alongside approved_by
|
||||
created: "2026-07-27"
|
||||
updated: "2026-07-27"
|
||||
---
|
||||
```
|
||||
|
||||
`status` is the phase tracker for the plan itself, distinct from any
|
||||
State Hub task status — it's what the build executor (`MASON-WP-0001-T04`)
|
||||
checks before doing anything: **refuses to execute unless
|
||||
`status: approved` and both `approved_by`/`approved_at` are set.** No
|
||||
other field or file can substitute for this — that's the one hard gate.
|
||||
|
||||
## Body sections
|
||||
|
||||
### 1. Demand
|
||||
|
||||
Plain description: who needs what, why, and what they need it *for* (one
|
||||
paragraph — this feeds the executive summary's plain-language framing
|
||||
directly, so write it for the founder, not for `bao`).
|
||||
|
||||
### 2. Existing-structure survey
|
||||
|
||||
What already exists that might cover this, checked *before* proposing
|
||||
anything new:
|
||||
|
||||
- Relevant `bao policy list` / `bao auth list` / `bao secrets list`
|
||||
entries (paste the actual output, not a paraphrase)
|
||||
- Relevant `ops-warden/registry/routing/catalog.yaml` entries (grep by
|
||||
`owner_repo`/`subsystem`/`need_keywords`)
|
||||
- Explicit answer: **does an existing lane already satisfy this demand?**
|
||||
If yes, the plan's proposed changes should be "bind to existing policy
|
||||
X" or "reuse existing path Y," not "create new." (See
|
||||
`binky-control/integrations/executor-worker-secrets.md`'s own Lane 1 —
|
||||
reused the existing `llm-connect-provider-secrets` secret instead of
|
||||
minting a new one, because the scoping already covered the new
|
||||
consumer.)
|
||||
|
||||
### 3. Proposed changes
|
||||
|
||||
A list, each item tagged `create` / `modify` / `tear-down`, each with a
|
||||
one-line reuse-vs-new rationale referencing section 2. Every item names
|
||||
exactly what OpenBao object it touches (policy name, AppRole name, KV
|
||||
path) — no vague "provision access" line items.
|
||||
|
||||
### 4. Review notes (phase 2)
|
||||
|
||||
Filled in during the self-review pass, before a human ever sees the
|
||||
plan: naming/TTL/scoping convention check against existing lanes (e.g.
|
||||
the `agent-harness-binky-mail` shape — `token_ttl=15m`,
|
||||
`token_max_ttl=30m`, bounded `token_num_uses`), redundancy check, and any
|
||||
compaction opportunity spotted along the way. If this section is empty,
|
||||
the plan is not ready for phase 3.
|
||||
|
||||
### 5. Executive summary (phase 3, generated from sections 1-4)
|
||||
|
||||
See `docs/executive-summary-format.md` (`MASON-WP-0001-T03`) for the
|
||||
exact rendering. Lives in the same plan file so there is one document to
|
||||
read, not two to cross-reference.
|
||||
|
||||
### 6. Build result (phase 4, appended after execution)
|
||||
|
||||
What was actually created/modified/torn down (object names, not values),
|
||||
the ops-warden catalog entry proposed (id + PR/commit reference once
|
||||
filed), and the exact `paste_once_provision` step the founder still needs
|
||||
to run (path, field) if the plan involved a new secret value. This
|
||||
section does not exist until phase 4 has run.
|
||||
|
||||
## Worked example (also the input to `MASON-WP-0001-T05`)
|
||||
|
||||
See `plans/rein-openweights-openrouter-approle.md` once T01 is
|
||||
implemented against this format — the first real plan, not a synthetic
|
||||
one, per `MASON-WP-0001`'s own scoping.
|
||||
Loading…
Add table
Add a link
Reference in a new issue