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>
158 lines
7.2 KiB
Markdown
158 lines
7.2 KiB
Markdown
---
|
|
id: MASON-WP-0001
|
|
title: "Foundation: the four-phase construction process, exercised on a real demand"
|
|
status: proposed
|
|
state_hub_workstream_id: "fa60e81b-19f6-4ad5-a584-f049cdec1bdb"
|
|
---
|
|
|
|
First workplan for ops-mason. Stands up the four phases described in
|
|
`INTENT.md` — construction plan, review/optimize, executive summary,
|
|
build — and exercises the whole pipeline on one real, already-waiting
|
|
piece of demand: the `rein-openweights` OpenBao AppRole
|
|
(`glas-harness/workplans/GLAS-WP-0002-T02`, currently blocked on exactly
|
|
the mechanic this repo exists to formalize). That task is not busywork
|
|
invented for this workplan — it's real backlog this pipeline unblocks
|
|
the moment phase 4 lands.
|
|
|
|
## Task: Construction-plan format
|
|
|
|
Design the artifact phase 1 produces: demand description (consumer,
|
|
credential type, scope requested), an existing-structure survey (what
|
|
`bao policy list`/`bao auth list`/`bao secrets list`/ops-warden's
|
|
`registry/routing/catalog.yaml` already cover, and whether any of it
|
|
already satisfies the demand), and the proposed changes (create/modify/
|
|
tear-down, each with a stated reuse-vs-new rationale). Document in
|
|
`docs/construction-plan-format.md`. Plain, versioned markdown/YAML —
|
|
not a database — so a plan can be reviewed in a diff and stored next to
|
|
the workplan that requested it.
|
|
|
|
**Done (2026-07-27).** `docs/construction-plan-format.md`: one file per
|
|
plan at `plans/<id>.md`, YAML frontmatter (`status: draft -> reviewed ->
|
|
approved -> built -> catalogued`, the phase-4 hard gate), six body
|
|
sections (demand, existing-structure survey, proposed changes, phase-2
|
|
review notes, phase-3 executive summary, phase-4 build result) — one
|
|
document threaded through all four phases, not four separate artifacts.
|
|
Proven against a real demand, not a synthetic one:
|
|
`plans/rein-openweights-openrouter-approle.md`, phases 1-2 filled in —
|
|
including a genuine finding in the existing-structure survey (an
|
|
existing `openrouter-llm-connect` catalog lane that could theoretically
|
|
be reused, and an explicit, reasoned decision *not* to reuse it, scoped
|
|
narrowly instead). Phases 3-4 wait on `MASON-WP-0001-T03`/`T04`/`T05`.
|
|
|
|
```task
|
|
id: MASON-WP-0001-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "6b25e7ca-52a0-41c2-b5a0-b5e46c824264"
|
|
```
|
|
|
|
## Task: Review/optimize pass
|
|
|
|
A self-check phase 2 runs over a draft plan before it's shown to
|
|
anyone: flag likely-redundant new policies/roles against what already
|
|
exists, naming/TTL/scoping convention drift against established lanes
|
|
(e.g. the `agent-harness-binky-mail` shape:
|
|
`token_ttl=15m`, `token_max_ttl=30m`, bounded `token_num_uses`), and
|
|
note any compaction opportunity (two existing lanes that could merge).
|
|
This can start as a checklist a human/agent runs manually against a
|
|
draft plan — doesn't need to be automated tooling on day one.
|
|
|
|
**Done (2026-07-27).** `docs/review-optimize-checklist.md`: six checks
|
|
(naming, TTL/scoping, redundancy, compaction, ease of use for the
|
|
consumer, posture) — manual for now, automating a checker deferred until
|
|
there's a second worked example to generalize from. Applied for real to
|
|
`plans/rein-openweights-openrouter-approle.md` §4 — including a
|
|
genuinely useful finding (`credentials.py` already expects exactly this
|
|
plan's path/delivery shape, zero code changes needed to consume it) and
|
|
one explicit posture assumption flagged rather than left silent
|
|
(`secret_id_ttl=0`, carried from `agent-harness-binky-mail`, surfaced
|
|
again in the executive summary for the approval decision to confirm).
|
|
|
|
```task
|
|
id: MASON-WP-0001-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "58a446fb-78d0-42b4-b10a-1119266b1016"
|
|
```
|
|
|
|
## Task: Executive-summary format
|
|
|
|
Design the phase 3 artifact: a short, decidable rendering of a reviewed
|
|
plan — who/what gets access to what, for how long, blast radius if the
|
|
credential leaks, and what it costs to reverse. This is the only
|
|
mandatory human checkpoint (`INTENT.md` design principle 3/4) — it must
|
|
be readable without knowing `bao` syntax. Document in
|
|
`docs/executive-summary-format.md`, with the rein-openweights AppRole
|
|
plan (task T05) as the worked example.
|
|
|
|
**Done (2026-07-27).** `docs/executive-summary-format.md`: six fixed
|
|
fields (one-line ask, who/what gets access, to what, for how long,
|
|
blast radius, cost to reverse) plus an explicit approve/reject/revise
|
|
decision — no `bao` syntax, no restating sections 1-4, no editorializing
|
|
beyond the plan's own reuse-vs-new conclusion. Rendered for real into
|
|
`plans/rein-openweights-openrouter-approle.md` §5 — ready for an actual
|
|
decision, not a mockup.
|
|
|
|
```task
|
|
id: MASON-WP-0001-T03
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "e37debfd-8a00-4780-b036-9376c6a10557"
|
|
```
|
|
|
|
## Task: Build executor
|
|
|
|
Phase 4: given an **approved** construction plan (explicit approval
|
|
marker set after the executive summary was reviewed), execute it against
|
|
OpenBao — policy write, AppRole creation, KV secret path creation
|
|
(**empty path/structure only — never a secret value**, see `INTENT.md`),
|
|
role_id/secret_id delivery to the consuming host, and a proposed
|
|
pointer-only ops-warden catalog entry (`warden_executes: false`, no
|
|
authored `steps`, `status: draft` — a normal commit/PR to the
|
|
`ops-warden` repo, not a live API call). Ends by naming the exact
|
|
`paste_once_provision` step the founder still needs to do (which path,
|
|
which field) — it does not attempt to fill the value itself. Must refuse
|
|
to run against an unapproved or missing-approval-marker plan — this is
|
|
the one place a bug is a real security incident, not a bad UX. Start
|
|
narrow: implement only the operations the first real plan (T05) needs,
|
|
not a general OpenBao automation framework.
|
|
|
|
**Done (2026-07-27).** `src/ops_mason/plan.py` (frontmatter parser +
|
|
`is_approved()`), `src/ops_mason/executor.py`
|
|
(`build_approle_kv_lane` — policy write, AppRole create,
|
|
role_id/secret_id delivery, never the KV path's value), `src/ops_mason/audit.py`
|
|
(metadata-only JSONL build log). 12 tests, all mocked at the `bao`
|
|
subprocess boundary (no live OpenBao access from this session — see
|
|
`GLAS-WP-0002-T02`'s original blocker). Explicitly verified: the refusal
|
|
gate never even calls `subprocess.run` when the plan isn't fully
|
|
approved (`test_refusal_never_calls_bao`); role_id/secret_id land as
|
|
`0600` files and never appear in a log line or exception message; the
|
|
policy HCL goes over stdin, never argv.
|
|
|
|
```task
|
|
id: MASON-WP-0001-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "e949f4b7-5ef4-4e42-8a07-61b6c8040298"
|
|
```
|
|
|
|
## Task: First real build — rein-openweights OpenBao AppRole
|
|
|
|
Run the whole pipeline for real: construction plan for
|
|
Option B from `glas-harness/workplans/GLAS-WP-0002-T02` (dedicated
|
|
`rein-openweights` AppRole + KV secret path at
|
|
`reins/rein-openweights/openrouter`, mirroring `agent-harness-binky-mail`'s
|
|
shape) → review/optimize → executive summary → founder approval → build
|
|
(structure only). Build ends with the founder pasting the real
|
|
OpenRouter key through ops-warden's `paste_once_provision` desk into the
|
|
newly created path/field — that one paste is the only place the live
|
|
value exists outside OpenBao. Once done, notify `glas-harness`/
|
|
`rein-openweights` so `GLAS-WP-0002-T02`'s live OpenBao verification can
|
|
proceed.
|
|
|
|
```task
|
|
id: MASON-WP-0001-T05
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "01782608-aa5a-4f9b-a1fb-9a64f6d9c299"
|
|
```
|