ops-mason/docs/construction-plan-format.md

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

---
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.