From e39a7457efb84ae886af9f1e020855cf8e2eb8ff Mon Sep 17 00:00:00 2001 From: Han Ngo Date: Sat, 18 Jul 2026 17:11:06 +0700 Subject: [PATCH 1/3] docs: rename the five legs to Shape/Build/Watch/Check/Learn Applies the plain-words rule (CONTRIBUTING.md, docs/research/2026-07-16-plain-words-inventory.md) to ADR-0034's loop taxonomy: Specify/Execute/Observe/Govern -> Shape/Build/Watch/Check (Learn kept), and the container word leg -> stage. Amends ADR-0034 per its own lock (a new "## Amendment" section, decision 3's as-decided historical table left unrewritten). Sweeps the machine registry (lib/config/module-registry.md, old names parenthetical for one release), README's "The five stages" section and mermaid diagram, docs/architecture.md, docs/data-flow.md's prose and ascii diagrams, docs/MANUAL.md's command index, docs/kit-contract.md, commands/onboard.md's welcome tour, and the per-module docs that reference the loop (lib/sync, lib/learn, lib/gate, lib/cosmetic, lib/session/audit). Updates the registry-lint assertions in tests/test-meta.sh and tests/test-config-registry.sh to the new section headers. Leaves historical records (CHANGELOG, shipped specs, archived implementation notes/proof docs) and the unrelated "leg" senses in board-mirror/board-writeback/significance-classify untouched. --- CONTRIBUTING.md | 3 +- README.md | 34 +++++++------- commands/onboard.md | 12 ++--- docs/MANUAL.md | 14 +++--- docs/architecture.md | 4 +- docs/data-flow.md | 36 +++++++------- docs/decisions/0034-harness-loop-taxonomy.md | 28 +++++++++++ docs/kit-contract.md | 8 ++-- lib/config/module-registry.md | 49 +++++++++++--------- lib/cosmetic/README.md | 4 +- lib/gate/README.md | 2 +- lib/learn/README.md | 4 +- lib/session/audit/README.md | 8 ++-- lib/session/audit/docs/feedback-loop.md | 35 +++++++------- lib/sync/README.md | 2 +- tests/test-config-registry.sh | 11 +++-- tests/test-hooks.sh | 2 +- tests/test-meta.sh | 13 +++--- 18 files changed, 152 insertions(+), 117 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f075da38..8abbd35b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,7 +74,8 @@ anything (a command, a config key, a doc heading, a term in help text): this rule was born from). Precedent renames: edge -> profile, surface/spoke/sources -> app, -hub -> board (2026-07-16, sync module). +hub -> board (2026-07-16, sync module), leg -> stage / Specify-Execute-Observe-Govern -> Shape-Build-Watch-Check +(2026-07-18, ADR-0034 amendment; Learn kept). ## Source diff --git a/README.md b/README.md index 708a0eee..47f2d045 100644 --- a/README.md +++ b/README.md @@ -53,33 +53,33 @@ An open loop (the agent roams free and judges its own output) is a fast slop mac | loops until the budget dies | bounded: fix-agent retries max 2, then escalates to a human | | one loop size fits all | risk lanes: tiny work skips the ceremony entirely | -## The five legs +## The five stages -The lifecycle above is what one run looks like. Across runs, the kit is organized as five legs (ADR-0034): **Specify** shapes work into contracts, **Execute** builds inside them, **Observe** records what happened, **Govern** gates every boundary, and **Learn** distills the record into proposals for the next cycle. +The lifecycle above is what one run looks like. Across runs, the kit is organized as five stages (formerly called "legs", ADR-0034): **Shape** turns work into contracts, **Build** builds inside them, **Watch** records what happened, **Check** gates every boundary, and **Learn** distills the record into proposals for the next cycle. ```mermaid flowchart LR - SP([Specify]) --> EX([Execute]) --> OB([Observe]) --> LN([Learn]) - LN -->|cited proposals,
human promotes| SP - GV([Govern]) -. gates every
phase boundary .- EX + SH([Shape]) --> BD([Build]) --> WA([Watch]) --> LN([Learn]) + LN -->|cited proposals,
human promotes| SH + CH([Check]) -. gates every
phase boundary .- BD ``` -This diagram is the legs. For how DATA actually moves through them (telemetry -> proposal -> board -> ship, the ledger write/read paths, and the module map of who calls whom), see [`docs/data-flow.md`](docs/data-flow.md). +This diagram is the stages. For how DATA actually moves through them (telemetry -> proposal -> board -> ship, the ledger write/read paths, and the module map of who calls whom), see [`docs/data-flow.md`](docs/data-flow.md). -Legs are metadata, not directories: each module keeps its name and install unit, and declares a primary leg. The authoritative assignment (machine copy in [`lib/config/module-registry.md`](lib/config/module-registry.md), rendered by `config list`): +Stages are metadata, not directories: each module keeps its name and install unit, and declares a primary stage. The authoritative assignment (machine copy in [`lib/config/module-registry.md`](lib/config/module-registry.md), rendered by `config list`): -| Leg | Modules / subsystems | +| Stage | Modules / subsystems | |---|---| -| Specify | `spec`, `classify`, `goal`, `board` (input side), `sync` (spoke intake; outward mirror is its Observe side) | -| Execute | `queue`, `mega`, `worktree`, `quiz_gate` | -| Observe | `stats`, `session` (capture side), `telemetry`, `sync` (outward mirror side; absorbed the bridge cockpit mirror 2026-07-16) | -| Govern | `gate`, `money_gate`, `advisor` | +| Shape (Specify) | `spec`, `classify`, `goal`, `board` (input side), `sync` (spoke intake; outward mirror is its Watch side) | +| Build (Execute) | `queue`, `mega`, `worktree`, `quiz_gate` | +| Watch (Observe) | `stats`, `session` (capture side), `telemetry`, `sync` (outward mirror side; absorbed the bridge cockpit mirror 2026-07-16) | +| Check (Govern) | `gate`, `money_gate`, `advisor` | | Learn | `learn`, `weekend_batch`, `session` (harvest), `board` (staging/promote), `skill-curator`, `prose_rag` (registry assignment, pending ADR-0034 amendment) | -| (no leg) | `cosmetic` (statusline; orthogonal to the loop) | +| (no stage) | `cosmetic` (statusline; orthogonal to the loop) | -Two modules honestly span legs: **board** (Specify's intake on one side, Learn's staging/promote on the other) and **session** (Observe's capture, Learn's harvest). +Two modules honestly span stages: **board** (Shape's intake on one side, Learn's staging/promote on the other) and **session** (Watch's capture, Learn's harvest). -**What happens to a run's data after it ships:** every gate decision and run outcome appends to the ledgers (append-only, never rewritten). `stats` projects them read-only; `session intel` writes the weekly digest, harness scorecard included; `learn propose` distills cross-run evidence into cited proposals in a staging file; `learn drain` renders that staging for review; `board promote` is the human gate that turns a proposal into a backlog row feeding the next Specify. Every automated leg ends at a staging file or a rendered surface, never a direct write to a board or ledger: propose, never dispose. +**What happens to a run's data after it ships:** every gate decision and run outcome appends to the ledgers (append-only, never rewritten). `stats` projects them read-only; `session intel` writes the weekly digest, harness scorecard included; `learn propose` distills cross-run evidence into cited proposals in a staging file; `learn drain` renders that staging for review; `board promote` is the human gate that turns a proposal into a backlog row feeding the next Shape stage. Every automated stage ends at a staging file or a rendered surface, never a direct write to a board or ledger: propose, never dispose. ## Install @@ -155,7 +155,7 @@ That is the whole loop. The spec is the unit of handoff: a contractor running `/ ``` /kit:start Detect state, suggest next command (entry point) -/kit:onboard Guided first-run: install mode, adopt, module picker, five-leg tour +/kit:onboard Guided first-run: install mode, adopt, module picker, five-stage tour /kit:think Challenge the idea (5 min) /kit:design Opt-in: shape the solution with you before /spec /kit:spec Generate the spec + 4 parallel researchers (15-30 min) @@ -274,7 +274,7 @@ Which hooks BLOCK vs warn vs neither is a declared contract: `docs/architecture. | /kit:review | Review | Paranoid single-pass code review | | /kit:review-team | Review | Parallel 3-lens review (security + architecture + test-coverage); findings confidence-gated, deduped by fingerprint, verdict-driving ones adversarially validated per finding | | /kit:test-plan-review-team | Verify | 5-lens adversarial critique of the spec's `## Test plan`, bounded revise loop, report-only | -| /kit:onboard | Entry | Guided first-run: detect install mode (plugin/bash/both/none), offer /kit:adopt, pick modules, capture consumer knobs, disclose plugin-path gaps, five-leg tour; previews + confirms every write, decline = no-op | +| /kit:onboard | Entry | Guided first-run: detect install mode (plugin/bash/both/none), offer /kit:adopt, pick modules, capture consumer knobs, disclose plugin-path gaps, five-stage tour; previews + confirms every write, decline = no-op | | /kit:adopt | Entry | Retrofit the operate-contract onto an existing repo (AGENTS.md, loader, proof marker, classifiers), idempotently | | /kit:docs | Docs | Cross-reference diff against all doc files, fix drift | | /kit:explain | Understand | Literate-diff explainer (background -> intuition -> prose-ordered diff -> diagram); composes narrate-log + svg-knowledge-diagram, grounded in the diff not the agent's narrative (ADR-0031) | diff --git a/commands/onboard.md b/commands/onboard.md index 425752f6..e4e7b73f 100644 --- a/commands/onboard.md +++ b/commands/onboard.md @@ -170,17 +170,17 @@ nothing. ## G. The welcome tour: the loop in five sentences -Close with the five-leg loop, one sentence per leg, then the next step. Keep it to five sentences: +Close with the five-stage loop, one sentence per stage, then the next step. Keep it to five sentences: -1. **Specify** -- you turn an intent into a spec (`/kit:spec`) and a lane, so the work has a written, +1. **Shape** -- you turn an intent into a spec (`/kit:spec`) and a lane, so the work has a written, testable contract before any code. -2. **Execute** -- the build runs against that spec (`/kit:execute`), worker then verifier then a +2. **Build** -- the build runs against that spec (`/kit:execute`), worker then verifier then a bounded fix retry, the smallest verifiable increment at a time. -3. **Observe** -- every run leaves an append-only trail that `stats` projects on demand, so you can +3. **Watch** -- every run leaves an append-only trail that `stats` projects on demand, so you can see what actually happened without a second source of truth. -4. **Govern** -- the ship-gate blocks a push whose lane skipped a required gate or a stateful change +4. **Check** -- the ship-gate blocks a push whose lane skipped a required gate or a stateful change with no recorded proof, so "done" means proven, not claimed. -5. **Learn** -- retros and the Learn leg distill each run's lessons back into the backlog, closing the +5. **Learn** -- retros and the Learn stage distill each run's lessons back into the backlog, closing the loop so the next cycle starts smarter. Then: **"Next: run `/kit:start` -- it detects where this repo stands and hands you the single right diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 1452d37e..37cc2d09 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -28,15 +28,15 @@ For the full playbook (every scenario, the autonomy dial, the freeform front doo ## Command reference (the kit invokes these from your intent; you rarely type them) -Index by loop leg (ADR-0034; the README's "The five legs" section tells the full story). Front-door and meta commands sit outside the legs on purpose: +Index by loop stage (formerly "leg", ADR-0034; the README's "The five stages" section tells the full story). Front-door and meta commands sit outside the stages on purpose: -| Leg | Commands | +| Stage | Commands | |---|---| | (front door) | `/kit:start`, `/kit:onboard`, `/kit:adopt` | -| Specify | `/kit:grill`, `/kit:think`, `/kit:design`, `/kit:devs-team`, `/kit:visual-team`, `/kit:ui-design`, `/kit:assign`, `/kit:spec`, `/kit:spec-validate`, `/kit:test-plan` | -| Execute | `/kit:execute`, `/kit:next`, `/kit:dispatch`, `/kit:mega`, `/kit:debug` | -| Observe | `/kit:explain`, `/kit:pitch` (render the record outward; the read plane itself is the `stats` skill + `session` CLI, not a command) | -| Govern | `/kit:review`, `/kit:review-team`, `/kit:test-plan-review-team`, `/kit:verify`, `/kit:quiz-gate`, `/kit:ship` | +| Shape | `/kit:grill`, `/kit:think`, `/kit:design`, `/kit:devs-team`, `/kit:visual-team`, `/kit:ui-design`, `/kit:assign`, `/kit:spec`, `/kit:spec-validate`, `/kit:test-plan` | +| Build | `/kit:execute`, `/kit:next`, `/kit:dispatch`, `/kit:mega`, `/kit:debug` | +| Watch | `/kit:explain`, `/kit:pitch` (render the record outward; the read plane itself is the `stats` skill + `session` CLI, not a command) | +| Check | `/kit:review`, `/kit:review-team`, `/kit:test-plan-review-team`, `/kit:verify`, `/kit:quiz-gate`, `/kit:ship` | | Learn | `/kit:retro`, `/kit:docs`, `/kit:absorb` | | (meta) | `/kit:kit-health`, `/kit:draft-agent` | @@ -60,7 +60,7 @@ Index by loop leg (ADR-0034; the README's "The five legs" section tells the full **Reads:** install mode via `lib/onboard-detect.sh` (plugin / bash / both / none); adoption state via `lib/adopt.sh --check`; the module roster + consumer knobs via `bin/config list|explain` (the SPEC-198 registry, never a hardcoded list) **Writes:** nothing of its own -- it only ever drives `lib/adopt.sh` (to inject the contract and/or seed `/.kit.toml` with your module choices), and every such write is previewed (`--dry-run` or a shown plan) and confirmed first; a decline is a strict no-op **When to invoke:** the first ten minutes on a new machine or a repo you have not adopted yet. It ties together the four things that have to line up before the loop works: which install mode is live, whether this repo is adopted, which modules are on, and which env knobs make them non-inert. -**What it does, in order:** (A) detect the install mode and explain it in one line each -- for `both` it discloses the double-hooks hazard and points at the one-path fix but never mutates settings; for `none` it prints the two install paths and stops. (B) offer `/kit:adopt` for the current repo (preview then confirm; an already-adopted repo is reported healthy and nothing is written). (C) pick modules -- the list is generated from the registry, and the choice is written by driving `lib/adopt.sh --with` (this is how the plugin path, which has no `install.sh --with`, still gets per-repo module selection). (D) for the chosen modules only, surface the consumer knobs that make them non-inert -- a `.kit.toml`-keyed knob is offered as a previewed write, an env-only knob (e.g. `PROSE_RAG_INJECT`, `MONEY_GATE_REPOS`) yields printed `export` guidance. (E) on the plugin path, disclose the gaps honestly (no statusLine HUD, a frozen SHA vs `git pull`, the `KIT_FORCE_FULL` escape and its hazard). (F) on the bash path, INSTALL-STAMP staleness is ONE printed line + a `/kit:kit-health` pointer, never an upgrade flow. (G) end with the five-leg loop in five sentences + `/kit:start` as the next step. +**What it does, in order:** (A) detect the install mode and explain it in one line each -- for `both` it discloses the double-hooks hazard and points at the one-path fix but never mutates settings; for `none` it prints the two install paths and stops. (B) offer `/kit:adopt` for the current repo (preview then confirm; an already-adopted repo is reported healthy and nothing is written). (C) pick modules -- the list is generated from the registry, and the choice is written by driving `lib/adopt.sh --with` (this is how the plugin path, which has no `install.sh --with`, still gets per-repo module selection). (D) for the chosen modules only, surface the consumer knobs that make them non-inert -- a `.kit.toml`-keyed knob is offered as a previewed write, an env-only knob (e.g. `PROSE_RAG_INJECT`, `MONEY_GATE_REPOS`) yields printed `export` guidance. (E) on the plugin path, disclose the gaps honestly (no statusLine HUD, a frozen SHA vs `git pull`, the `KIT_FORCE_FULL` escape and its hazard). (F) on the bash path, INSTALL-STAMP staleness is ONE printed line + a `/kit:kit-health` pointer, never an upgrade flow. (G) end with the five-stage loop in five sentences + `/kit:start` as the next step. **Fence (ADR-0034 decision 4):** onboard ORCHESTRATES; it calls start + adopt + config and reimplements none of them. It never changes `install.sh`, `adopt.sh`, or `bin/config`. **Common gotcha:** it is not an upgrade wizard. If the kit is already installed and this repo is already adopted, onboard is a read-only health tour that writes nothing; to change modules later you hand-edit `/.kit.toml [modules]` and re-run `/kit:adopt --refresh`. diff --git a/docs/architecture.md b/docs/architecture.md index f047e76f..051280ef 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Architecture -How dwarves-kit fits together. Read PHILOSOPHY.md first for the WHY; this file is the WHAT and HOW. The harness-level loop story (the five legs: Specify → Execute → Observe → Govern → Learn, and which module serves which) lives in the README's "The five legs" section, backed by ADR-0034 and the machine registry `lib/config/module-registry.md`; this file does not restate it. +How dwarves-kit fits together. Read PHILOSOPHY.md first for the WHY; this file is the WHAT and HOW. The harness-level loop story (the five stages, formerly "legs": Shape → Build → Watch → Check → Learn, and which module serves which) lives in the README's "The five stages" section, backed by ADR-0034 and the machine registry `lib/config/module-registry.md`; this file does not restate it. ## Component layout @@ -143,7 +143,7 @@ Total: 31 commands + 25 agents = **56 entries** (10 build · 3 code · 9 test · |---|---|---|---|---| | `/kit:retro` | command | Reflect | cross-phase | Post-ship narrative mirror of the entire V; captures learnings, not a gate | | `/kit:start` | command | Session entry | cross-phase | Detects project state and recommends the right next command; never executes | -| `/kit:onboard` | command | First-run onboarding | cross-phase | Interactive first-run orchestrator (SPEC-199): detects install mode via `lib/onboard-detect.sh`, offers `/kit:adopt`, picks modules (bridging the plugin path's missing `--with`), captures consumer knobs from the SPEC-198 registry, discloses plugin-path gaps, ends with the five-leg tour; CALLS start/adopt/config, reimplements none (ADR-0034 fence); previews + confirms every write | +| `/kit:onboard` | command | First-run onboarding | cross-phase | Interactive first-run orchestrator (SPEC-199): detects install mode via `lib/onboard-detect.sh`, offers `/kit:adopt`, picks modules (bridging the plugin path's missing `--with`), captures consumer knobs from the SPEC-198 registry, discloses plugin-path gaps, ends with the five-stage tour; CALLS start/adopt/config, reimplements none (ADR-0034 fence); previews + confirms every write | | `/kit:adopt` | command | Repo onboarding | cross-phase | Injects the operate-contract + proof marker + a CLAUDE.md pointer into a target repo (idempotent, via `lib/adopt.sh`); wires the classifiers so the ship-gate engages there | | `/kit:kit-health` | command | Maintainer audit | cross-phase | Self-assessment against PHILOSOPHY.md; run before tagging; not part of the normal cycle | | `/kit:absorb` | command | Upstream maintenance | cross-phase | Audits Credits drift + seed-rescan; proposal-only; maintainer-only connective tissue | diff --git a/docs/data-flow.md b/docs/data-flow.md index a58b0f2e..aa7ea762 100644 --- a/docs/data-flow.md +++ b/docs/data-flow.md @@ -7,16 +7,16 @@ found 14 lifecycle diagrams and zero data-flow ones). Three flows, one per substrate: -1. **The signal path** (Observe -> Learn -> Specify): telemetry becomes a proposal becomes work. -2. **The ledger path** (Execute -> Govern -> Observe): a run writes evidence; the gates and the +1. **The signal path** (Watch -> Learn -> Shape): telemetry becomes a proposal becomes work. +2. **The ledger path** (Build -> Check -> Watch): a run writes evidence; the gates and the lenses read it. -3. **The module map**: who calls whom, grouped by leg. +3. **The module map**: who calls whom, grouped by stage. --- ## 1. The signal path: telemetry -> proposal -> board -> ship -The Learn leg's whole job. Every arrow is code, not intent; the names are the callables. +The Learn stage's whole job. Every arrow is code, not intent; the names are the callables. ``` SOURCES COLLECT + ANALYZE PROPOSE HUMAN WORK @@ -107,7 +107,7 @@ One append-only corpus, one resolver. Every path below is derived, never hardcod ``` ┌────────────────────────────────────────────┐ WRITERS │ kit_resolve_log_dir() │ READERS - (Execute + Govern) │ lib/telemetry/kit-log-dir.sh │ (Observe + Govern) + (Build + Check) │ lib/telemetry/kit-log-dir.sh │ (Watch + Check) │ │ gate-ledger.sh ────► │ KIT_LEDGER_DIR (1) │ ◄──── lane-telemetry START / GATE / │ DWARVES_KIT_LOG_DIR (alias) (2) │ report | misfires @@ -123,10 +123,10 @@ One append-only corpus, one resolver. Every path below is derived, never hardcod ▲ ◄──── mega report / │ mega review hooks (ship-gate, safety-gate, ...) ───┘ ── read the SAME ledger to decide - whether a push may proceed (Govern) + whether a push may proceed (Check) NOT in the ledger, by design: - ~/.claude/intel/{intel,audit}-YYYY-MM-DD.md the Observe reports (dated artifacts) + ~/.claude/intel/{intel,audit}-YYYY-MM-DD.md the Watch reports (dated artifacts) _meta/backlog-staging.md the proposal buffer (flow 1) ~/.claude/dwarves-kit/logs/*.log hook diagnostics (ephemeral, not corpus) ``` @@ -138,13 +138,13 @@ SPEC-097 exists and why C6 of the kit contract lints for it. --- -## 3. The module map, by leg +## 3. The module map, by stage Who calls whom. An arrow is a real invocation (shell-out, source, or import). ``` - SPECIFY EXECUTE GOVERN - ─────── ─────── ────── + SHAPE BUILD CHECK + ───── ───── ───── spec ──► classify queue ──► orchestrate gate ──┬─► gate-ledger │ │ │ │ ├─► proof-ledger ▼ ▼ ▼ ▼ └─► ship-gate hook @@ -152,10 +152,10 @@ Who calls whom. An arrow is a real invocation (shell-out, source, or import). │ advisor (agents/) │ ▲ ▲ │ │ │ - │ every phase boundary asks Govern + │ every phase boundary asks Check │ - │ OBSERVE LEARN - │ ─────── ───── + │ WATCH LEARN + │ ───── ───── │ stats ◄── ledger learn ─┬─► propose ──┐ │ telemetry ◄── ledger ├─► drain │ │ session ─┬─► observe └─► debt │ @@ -168,11 +168,11 @@ Who calls whom. An arrow is a real invocation (shell-out, source, or import). └──────────────────────────────────────────────────── board (staging/promote) the loop closes here - Spanners (one module, two legs), honest and named in ADR-0034: - board = Specify (intake) + Learn (staging/promote) - session = Observe (capture) + Learn (harvest, via audit triage) + Spanners (one module, two stages), honest and named in ADR-0034: + board = Shape (intake) + Learn (staging/promote) + session = Watch (capture) + Learn (harvest, via audit triage) - Off the loop: cosmetic (statusline) prose_rag (recall over the corpus; leg assignment + Off the loop: cosmetic (statusline) prose_rag (recall over the corpus; stage assignment is a documented deviation, see module-registry) ``` @@ -237,7 +237,7 @@ claim against the command that supposedly does it. ## Reading order -- New to the kit: `README.md` (the five legs) -> `docs/WORKFLOW.md` (how a run moves) -> this +- New to the kit: `README.md` (the five stages) -> `docs/WORKFLOW.md` (how a run moves) -> this page (how data moves). - Adding a signal pipeline: `docs/kit-contract.md` (the rules) -> flow 1 above (where your output has to land) -> `docs/specs/SPEC-200-signal-pipelines.md` (why). diff --git a/docs/decisions/0034-harness-loop-taxonomy.md b/docs/decisions/0034-harness-loop-taxonomy.md index bf49ed75..c72a372d 100644 --- a/docs/decisions/0034-harness-loop-taxonomy.md +++ b/docs/decisions/0034-harness-loop-taxonomy.md @@ -153,6 +153,34 @@ Rejected: rotation now (no measured pain, speculative work); TTL deletion (destr Provenance: this area came from Han's 2026-07-12 scope-amendment-2 review (`_meta/megagoals/harness-loop/NOTES.md` event log), not brief §4, which stops at 4.9. +## Amendment (2026-07-18, operator): plain-words rename (leg -> stage; the five leg names) + +No decision change: decision 3 stands (legs, now called stages, remain metadata, never module +renames; the authoritative module-to-leg assignment above is the as-decided historical record and +is not rewritten). Only the vocabulary renames, per CONTRIBUTING.md's Plain Words rule and the +ranked inventory (`docs/research/2026-07-16-plain-words-inventory.md`, "The five legs" section), +which found the blast radius here is docs + one table + one lint, not semantic-everywhere -- so a +same-release sweep is the correct size, not a phased migration. + +**The rename map:** + +| Current | Renamed | Note | +|---|---|---| +| Specify | **Shape** | not "Plan": collides with the planning loop-type + the writing-plans skill | +| Execute | **Build** | the plain PM word | +| Observe | **Watch** | | +| Govern | **Check** | the most corporate of the five; "Guard" is the documented fallback if Check reads too close to verify | +| Learn | **Learn** | kept, already plain, and more accurate than "Improve" (the leg distills, it does not itself improve the product) | +| leg (container word) | **stage** | the everyday word every PM already uses for one step of a workflow | + +Per the Plain Words rule's renaming clause, the old names live as a parenthetical alias for one +release: `lib/config/module-registry.md`'s stage column, README's "The five stages" section, +`docs/data-flow.md` (prose + the module-map diagram), `docs/MANUAL.md`'s command index, +`docs/kit-contract.md`, `commands/onboard.md`'s welcome tour, and the registry-lint assertions in +`tests/test-meta.sh` all sweep to the new names in the same change (`_meta/BACKLOG.md` ID-292). +`prose_rag`'s leg assignment (flagged as a documented deviation in `lib/config/module-registry.md`) +is unaffected by this amendment; it is a separate open question. + ## Consequences - SG-04 executes the census target state in one wave (moves, collapses, new bin entries, skill relocation, call-site repoints incl. the dotfiles companion PR); SG-05/06 build `learn propose`/`drain` in the decision-1 home; SG-08 builds `bin/config` (decision 4) + the one module-metadata registry at `lib/config/module-registry.md` (decision 3); SG-09 builds `/kit:onboard` inside the decision-4 fences; SG-10 retires the per-job plist per decision 9. diff --git a/docs/kit-contract.md b/docs/kit-contract.md index 2856e90b..e99a10f7 100644 --- a/docs/kit-contract.md +++ b/docs/kit-contract.md @@ -100,7 +100,7 @@ merged" as no evidence the PR contained the work. Work the list, in this order. Every step has a check you can run. 1. **Name it by function, not by host.** Module dir `lib//`, env family `_*`, executable named for what it does. Check: `bash tests/test-kit-contract.sh` (C1). -2. **Place it on the loop.** Which of the five legs (Specify / Execute / Observe / Govern / Learn, ADR-0034) does it serve? Add the row to `lib/config/module-registry.md`. A tool that fits no leg is a tool with no reason to be in the kit. +2. **Place it on the loop.** Which of the five stages (Shape / Build / Watch / Check / Learn, ADR-0034) does it serve? Add the row to `lib/config/module-registry.md`. A tool that fits no stage is a tool with no reason to be in the kit. 3. **Wire it before you polish it.** A `bin/` shim or a dispatcher case, in the SAME commit as the first working version. Check: C2. 4. **Pick the verbs from the closed vocabulary** (SPEC-200 I4): `run` (do the job, write the artifact), `show` (print, write nothing), `propose` (stage proposals), `promote` (the human gate), `trace` (one run's story). Do not invent a synonym. 5. **If it proposes anything, use the currency.** `## [staged]` blocks via `staging-format.py`, deduped against staging + board, promoted by a human. Never write a board. Check: C5. @@ -110,10 +110,10 @@ Work the list, in this order. Every step has a check you can run. ## Where this sits in the harness loop -The contract is a **Govern**-leg gate, and it fires at two boundaries: +The contract is a **Check**-stage gate, and it fires at two boundaries: -- **Execute -> Govern**: `tests/test-kit-contract.sh` runs in CI on every PR. Mechanical rules only (naming, wiring, docs presence, currency, root, portability). It cannot judge whether the docs are any *good*. -- **Govern (judgment)**: for that, dispatch the review lenses. `kit:advisor` (the cross-cutting lens) plus a domain reviewer, and for a new module `kit:agent-effectiveness` if it ships an agent. A lint proves the shape; a reviewer proves the substance. Run both; the lint is cheap and the reviewer is not fooled by a technically-compliant README. +- **Build -> Check**: `tests/test-kit-contract.sh` runs in CI on every PR. Mechanical rules only (naming, wiring, docs presence, currency, root, portability). It cannot judge whether the docs are any *good*. +- **Check (judgment)**: for that, dispatch the review lenses. `kit:advisor` (the cross-cutting lens) plus a domain reviewer, and for a new module `kit:agent-effectiveness` if it ships an agent. A lint proves the shape; a reviewer proves the substance. Run both; the lint is cheap and the reviewer is not fooled by a technically-compliant README. Neither replaces the other. The 2026-07-14 sweep found 19 pipelines that all passed CI and still fragmented the kit into five vocabularies, because nothing mechanical was watching the diff --git a/lib/config/module-registry.md b/lib/config/module-registry.md index edff0d69..d6b5b795 100644 --- a/lib/config/module-registry.md +++ b/lib/config/module-registry.md @@ -1,7 +1,8 @@ -# lib/config/module-registry.md , module<->leg + env<->key registry (SPEC-198) +# lib/config/module-registry.md , module<->stage + env<->key registry (SPEC-198) -Machine home pinned by ADR-0034 decision 3: ONE checked-in file carrying both the -module -> primary-leg table (decision 3's authoritative assignment) and the +Machine home pinned by ADR-0034 decision 3 (stage names renamed by the 2026-07-18 amendment, +leg -> stage): ONE checked-in file carrying both the +module -> primary-stage table (decision 3's authoritative assignment) and the env<->key rows (decision 4's `bin/config` read surface). Parsed by `lib/config/config.sh` (the `bin/config` engine) and by `tests/test-config-registry.sh` (the drift + completeness lints). Both readers are @@ -18,36 +19,38 @@ source by hand (no pre-existing table existed before this file), plus every `kit.toml`-declared key (whether or not it has an env override), so `bin/config list` can render "every declared key," not just the env-shaped subset. -## Module legs +## Module stages -Authoritative assignment per ADR-0034 decision 3. Every `KIT_KNOWN_MODULES` entry +Authoritative assignment per ADR-0034 decision 3, renamed by the 2026-07-18 amendment (leg -> +stage; Specify/Execute/Observe/Govern -> Shape/Build/Watch/Check, Learn kept). Old names shown +parenthetically for one release. Every `KIT_KNOWN_MODULES` entry (`install.sh:170`, 12 modules) has exactly one row. `team_mode` is excluded from `KIT_KNOWN_MODULES` itself (install.sh hard-rejects it until team-mode ships), so it is not a row here either , the completeness rule is scoped to `KIT_KNOWN_MODULES`, not to every `[modules]` line in `kit.toml`. -| Module | Primary leg | Notes | +| Module | Primary stage | Notes | |---|---|---| -| board | Specify | spanner: input side (Specify) + staging/promote (Learn) | -| session | Observe | spanner: capture side (Observe) + harvest (Learn); `session audit` is the deep Observe pass (LLM audit, `run`) + a Learn-leg proposer (`triage`) | -| advisor | Govern | | +| board | Shape (Specify) | spanner: input side (Shape) + staging/promote (Learn) | +| session | Watch (Observe) | spanner: capture side (Watch) + harvest (Learn); `session audit` is the deep Watch pass (LLM audit, `run`) + a Learn-stage proposer (`triage`) | +| advisor | Check (Govern) | | | cosmetic | (none) | orthogonal to the loop; statusline | -| queue | Execute | | -| stats | Observe | | -| quiz_gate | Execute | | +| queue | Build (Execute) | | +| stats | Watch (Observe) | | +| quiz_gate | Build (Execute) | | | weekend_batch | Learn | | -| sync | Specify | spanner: spoke intake -> board rows (Specify input side) + outward mirror to Reminders/Notion/Hermes (Observe, presentation). Engine lib/sync/, verb `board sync`, per-repo `[sync]` config. ABSORBED `bridge` 2026-07-16 (same engine surface, zero live consumers at fold time: no `bridge=on` rows, no snapshot, module off): the SPEC-147 cockpit mirror + SPEC-149 writeback become a sync EDGE in the SPEC-002 P2 port (ID-290); the legacy `mirror`/`status`/`writeback` verbs + lib/board/board-mirror.sh + board-writeback.sh stay runnable until then and carry two assets the port must keep: the `row_hash` git-wins conflict rule and the live-probed Hermes reachable-state map {triage, ready, blocked, done}. | -| worktree | Execute | | -| money_gate | Govern | | -| classify | Specify | not a `KIT_KNOWN_MODULES` install toggle (it is spine machinery), but ADR-0034 decision 3 assigns it a leg and pins THIS file as the machine home for that table. Added 2026-07-14: the leg was answerable only from ADR prose. | -| gate | Govern | spine machinery, same as above (ADR-0034 decision 3). | -| spec | Specify | spine machinery (ADR-0034 decision 3). | -| goal | Specify | spine machinery (ADR-0034 decision 3). | -| mega | Execute | spine machinery (ADR-0034 decision 3). | -| learn | Learn | spine machinery; created BY ADR-0034 decision 1 (the Learn leg's home). | -| telemetry | Observe | spine machinery; the durable-root resolver + lane telemetry. | +| sync | Shape (Specify) | spanner: spoke intake -> board rows (Shape input side) + outward mirror to Reminders/Notion/Hermes (Watch, presentation). Engine lib/sync/, verb `board sync`, per-repo `[sync]` config. ABSORBED `bridge` 2026-07-16 (same engine surface, zero live consumers at fold time: no `bridge=on` rows, no snapshot, module off): the SPEC-147 cockpit mirror + SPEC-149 writeback become a sync EDGE in the SPEC-002 P2 port (ID-290); the legacy `mirror`/`status`/`writeback` verbs + lib/board/board-mirror.sh + board-writeback.sh stay runnable until then and carry two assets the port must keep: the `row_hash` git-wins conflict rule and the live-probed Hermes reachable-state map {triage, ready, blocked, done}. | +| worktree | Build (Execute) | | +| money_gate | Check (Govern) | | +| classify | Shape (Specify) | not a `KIT_KNOWN_MODULES` install toggle (it is spine machinery), but ADR-0034 decision 3 assigns it a stage and pins THIS file as the machine home for that table. Added 2026-07-14: the stage was answerable only from ADR prose. | +| gate | Check (Govern) | spine machinery, same as above (ADR-0034 decision 3). | +| spec | Shape (Specify) | spine machinery (ADR-0034 decision 3). | +| goal | Shape (Specify) | spine machinery (ADR-0034 decision 3). | +| mega | Build (Execute) | spine machinery (ADR-0034 decision 3). | +| learn | Learn | spine machinery; created BY ADR-0034 decision 1 (the Learn stage's home). | +| telemetry | Watch (Observe) | spine machinery; the durable-root resolver + lane telemetry. | | skill-curator | Learn | ADR-0034 decision 3 lists it under Learn; installs via hooks, not a `--with` module. | -| prose_rag | Learn | **deviation, not in ADR-0034's decision-3 table** (checked: `grep -n prose_rag docs/decisions/0034-harness-loop-taxonomy.md` has zero hits in the leg table). Assigned Learn by this sub-goal's own judgment: prose-rag is a recall/retrieval read over the user's own accumulated corpus (til/research/learned-ledger), the same read-side shape as the Learn leg's other members, not an Observe-class run-telemetry capture. Flagged for Han; a later ADR-0034 amendment may reassign it. | +| prose_rag | Learn | **deviation, not in ADR-0034's decision-3 table** (checked: `grep -n prose_rag docs/decisions/0034-harness-loop-taxonomy.md` has zero hits in the leg table). Assigned Learn by this sub-goal's own judgment: prose-rag is a recall/retrieval read over the user's own accumulated corpus (til/research/learned-ledger), the same read-side shape as the Learn stage's other members, not a Watch-class run-telemetry capture. Flagged for Han; a later ADR-0034 amendment may reassign it. | ## Env <-> key registry diff --git a/lib/cosmetic/README.md b/lib/cosmetic/README.md index 219e2b62..63cd6a78 100644 --- a/lib/cosmetic/README.md +++ b/lib/cosmetic/README.md @@ -1,8 +1,8 @@ # cosmetic Six hooks that make a session nicer to sit in front of. **None of them is part of the -loop.** ADR-0034 assigns every kit module a primary leg (Specify / Execute / Observe / -Govern / Learn); `cosmetic` is the one module with **`(none)`**, and +loop.** ADR-0034 assigns every kit module a primary stage (Shape / Build / Watch / +Check / Learn, formerly Specify / Execute / Observe / Govern / Learn); `cosmetic` is the one module with **`(none)`**, and `lib/config/module-registry.md` records it as "orthogonal to the loop". That is not a filing accident, it is the module's whole contract. diff --git a/lib/gate/README.md b/lib/gate/README.md index 2cca1d90..2e7c2ebf 100644 --- a/lib/gate/README.md +++ b/lib/gate/README.md @@ -1,6 +1,6 @@ # gate -The **Govern leg's** engine (ADR-0034: Specify / Execute / Observe / Govern / Learn). Every +The **Check stage's** engine (ADR-0034, stage names per the 2026-07-18 amendment: Shape / Build / Watch / Check / Learn; formerly "Govern leg"). Every phase boundary in the kit routes through this module. It is what makes a lane a *contract* instead of a suggestion. diff --git a/lib/learn/README.md b/lib/learn/README.md index 4f16179a..63520e7e 100644 --- a/lib/learn/README.md +++ b/lib/learn/README.md @@ -1,6 +1,6 @@ # learn -The **Learn leg's** home (ADR-0034 decision 1: Specify / Execute / Observe / Govern / Learn). +The **Learn stage's** home (ADR-0034 decision 1, stage names per the 2026-07-18 amendment: Shape / Build / Watch / Check / Learn). The read-and-propose side of the loop. It reads what the harness recorded about itself, distills it, and proposes work. It never does the work, and it never files it. @@ -104,7 +104,7 @@ human-gated edge into the board, and C5 exempts it by name. | Where | What | |---|---| -| `docs/decisions/0034-harness-loop-taxonomy.md` | The five legs, `lib/learn/` as the Learn leg's one home, the three-verb grammar | +| `docs/decisions/0034-harness-loop-taxonomy.md` | The five stages, `lib/learn/` as the Learn stage's one home, the three-verb grammar | | `docs/decisions/0031-understanding-gate.md` | Understanding debt, and why waving is a first-class recorded choice | | `docs/specs/SPEC-195-learn-propose.md` | The cross-run distiller | | `docs/specs/SPEC-196-staging-drain.md` | The staging review + expiry | diff --git a/lib/session/audit/README.md b/lib/session/audit/README.md index e0515580..2b35b3c8 100644 --- a/lib/session/audit/README.md +++ b/lib/session/audit/README.md @@ -23,10 +23,10 @@ Division of labor in `lib/session/`: `session-observe` = deterministic parsing, agentic evidence for change decisions** (weekly / on demand). Measured on a 3-day window: ~$3.5 and ~10 min on Sonnet. -In five-leg terms (ADR-0034): `run` is the deep **Observe** pass for usage -telemetry, `triage` is a **Learn**-leg proposer (same propose-don't-dispose -gate as `learn propose`); the enhance work is the ordinary Specify -> Execute --> Govern lanes, and the measure step is the next run's {PREV} metric diff. +In five-stage terms (ADR-0034): `run` is the deep **Watch** pass for usage +telemetry, `triage` is a **Learn**-stage proposer (same propose-don't-dispose +gate as `learn propose`); the enhance work is the ordinary Shape -> Build +-> Check lanes, and the measure step is the next run's {PREV} metric diff. Full path contract: `docs/feedback-loop.md`. ## Use diff --git a/lib/session/audit/docs/feedback-loop.md b/lib/session/audit/docs/feedback-loop.md index e7f3f815..ceeb4387 100644 --- a/lib/session/audit/docs/feedback-loop.md +++ b/lib/session/audit/docs/feedback-loop.md @@ -1,29 +1,30 @@ -# The usage-telemetry path around the five legs +# The usage-telemetry path around the five stages -The kit's improvement cycle is the five legs (ADR-0034): **Specify -> Execute -> -Observe -> Govern -> Learn**, feedback closing Learn back into Specify. This +The kit's improvement cycle is the five stages (ADR-0034, renamed by the 2026-07-18 +amendment): **Shape -> Build -> Watch -> Check -> Learn**, feedback closing Learn +back into Shape. This page does NOT define a new cycle; it names how session-audit rides that loop for one signal class: usage telemetry from CC session transcripts. One engine, -one truth: where an existing leg verb already owns a step, this tool defers +one truth: where an existing stage verb already owns a step, this tool defers to it. ``` - (existing legs) (this tool's contribution) + (existing stages) (this tool's contribution) - Specify ──► Execute ──► Observe ──────────────── session-audit run - ▲ │ = the deep Observe pass: - │ ▼ dated report, owner tags, - │ Govern metric contracts - │ │ - └────── Learn ◄────────┘ session-audit triage - (propose gate) = a Learn-leg proposer: + Shape ──► Build ──► Watch session-audit run + ▲ │ = the deep Watch pass: + ▼ dated report, owner tags, + Check metric contracts + │ + └────── Learn ◄────┘ session-audit triage + (propose gate) = a Learn-stage proposer: report footer -> kanban proposal rows, human accepts ``` -## The steps, in leg terms +## The steps, in stage terms -1. **Observe (collect + report).** Three depths, same leg: `session observe` +1. **Watch (collect + report).** Three depths, same stage: `session observe` (deterministic parsing, free), `session semantic` (cheap LLM topic signal, cron), `session audit run` (expensive agentic deep audit, weekly / on demand). The audit writes one dated report; every recommendation carries an @@ -40,16 +41,16 @@ to it. promoted) + the board, so a rejected proposal never returns. Human gate unchanged (ADR-0034 decision 2/5): review with `learn drain`, accept with `board promote`. Nothing auto-files. -3. **Specify -> Execute -> Govern (enhance).** An accepted row is ordinary kit +3. **Shape -> Build -> Check (enhance).** An accepted row is ordinary kit work through the normal lanes and gates. Nothing special; the audit only supplied the evidence and the metric. -4. **Observe again (measure).** The next `session audit run` receives the +4. **Watch again (measure).** The next `session audit run` receives the previous report as `{PREV}` automatically and MUST open with a metric-by-metric diff: for each earlier recommendation, did its metric move? A fix whose metric did not move returns to the Learn gate as a new finding, with the failed attempt as context. -## Division of labor inside Observe (why three tools + stats coexist) +## Division of labor inside Watch (why three tools + stats coexist) | Surface | Reads | Depth | Cadence | |---|---|---|---| diff --git a/lib/sync/README.md b/lib/sync/README.md index 2245f75d..9a56e549 100644 --- a/lib/sync/README.md +++ b/lib/sync/README.md @@ -3,7 +3,7 @@ Two-way sync between an adopted repo's kanban `BACKLOG.md` (the hub, source of truth) and its spokes: **Apple Reminders**, a **Notion board**, the **Hermes kanban**, and a **Multica board** (the self-hosted team pilot, see -ops-toolkit `tools/multica-deploy/`). Registered kit module `sync` (leg: Specify) at `lib/sync/`; +ops-toolkit `tools/multica-deploy/`). Registered kit module `sync` (stage: Shape, formerly Specify) at `lib/sync/`; front door is the `board sync` verb, so every adopted repo's `_meta/board` shim already reaches it. Design: `docs/specs/SPEC-001-multi-source-sync.md` (subsystem-local). Spokes plug in per repo via the `[sync]` section of diff --git a/tests/test-config-registry.sh b/tests/test-config-registry.sh index fe7702f6..7d5f0aeb 100755 --- a/tests/test-config-registry.sh +++ b/tests/test-config-registry.sh @@ -9,8 +9,9 @@ # no second bespoke grep, per the goal file's explicit instruction. # AC2 NEGATIVE CONTROL: a planted, unregistered env var matching the seed prefix family IS # flagged an orphan by the same sweep -- proves AC1 is not a vacuous pass. -# AC3 module-leg completeness: every install.sh KIT_KNOWN_MODULES entry has a row in the -# registry's "## Module legs" table. +# AC3 module-stage completeness (formerly "module-leg", renamed by the 2026-07-18 +# amendment): every install.sh KIT_KNOWN_MODULES entry has a row in the +# registry's "## Module stages" table. # AC4 NEGATIVE CONTROL: a planted extra module name (not in KIT_KNOWN_MODULES) does NOT # spuriously satisfy AC3 -- proves the completeness check is keyed off the real list. # AC5 bin/config functional smoke: list/get/explain resolve correctly, and an env override @@ -79,16 +80,16 @@ if printf '%s\n' "$PLANT_OUT" | grep -qF "ORPHAN: KIT_TOTALLY_UNREGISTERED_PLANT assert "the flagged orphan is specifically KIT_TOTALLY_UNREGISTERED_PLANT" $RC echo "" -echo "=== AC3: module-leg completeness -- every KIT_KNOWN_MODULES entry has a registry row ===" +echo "=== AC3: module-stage completeness -- every KIT_KNOWN_MODULES entry has a registry row ===" KNOWN_MODULES="$(grep -o '^KIT_KNOWN_MODULES="[^"]*"' "$KIT_DIR/install.sh" | sed -E 's/^KIT_KNOWN_MODULES="//; s/"$//')" MISSING=0 for m in $KNOWN_MODULES; do if ! grep -qE "^\| $m \|" "$REGISTRY"; then - echo " MISSING module-leg row: $m" >&2 + echo " MISSING module-stage row: $m" >&2 MISSING=$((MISSING+1)) fi done -assert "every KIT_KNOWN_MODULES entry ($(printf '%s' "$KNOWN_MODULES" | wc -w | tr -d ' ') modules) has a Module-legs row" "$MISSING" +assert "every KIT_KNOWN_MODULES entry ($(printf '%s' "$KNOWN_MODULES" | wc -w | tr -d ' ') modules) has a Module-stages row" "$MISSING" echo "" echo "=== AC4: NEGATIVE CONTROL -- a module NOT in KIT_KNOWN_MODULES is correctly absent ===" diff --git a/tests/test-hooks.sh b/tests/test-hooks.sh index 8edebd05..f1a69174 100755 --- a/tests/test-hooks.sh +++ b/tests/test-hooks.sh @@ -1996,7 +1996,7 @@ assert_output_not_contains "pointer does not re-paste the payload" "yyyyyyyyyy" echo "" echo "=== cosmetic module: the non-blocking contract (SPEC-201) ===" # ============================================================ -# The cosmetic module is the ONE module ADR-0034 assigns no loop leg: "orthogonal to the +# The cosmetic module is the ONE module ADR-0034 assigns no loop stage: "orthogonal to the # loop" (lib/config/module-registry.md). Its whole contract is a NEGATIVE one, so it is the # one that rots silently. Nothing asserted it until now, and the audit that wrote SPEC-201 # found two hooks already in breach (slop-cleaner + permission-auto-approve exited 5 on a diff --git a/tests/test-meta.sh b/tests/test-meta.sh index d84cf6f4..0b99ce2a 100755 --- a/tests/test-meta.sh +++ b/tests/test-meta.sh @@ -1607,10 +1607,11 @@ assert_eq "architecture.md headline commands == live ($ARCH_HEAD_CMD == $CMD_COU assert_eq "architecture.md headline agents == live ($ARCH_HEAD_AGT == $AGT_COUNT)" "$AGT_COUNT" "$ARCH_HEAD_AGT" assert_eq "architecture.md headline total == live ($ARCH_HEAD_TOT == $LIVE_COUNT)" "$LIVE_COUNT" "$ARCH_HEAD_TOT" -# The README five-leg table covers every module the registry assigns a leg (ADR-0034 -# decision 3 rendered without omissions; the two tables share one truth). -FIVE_LEG_BLOCK=$(sed -n '/^## The five legs/,/^## /p' "$KIT_DIR/README.md") -REGISTRY_MODULES=$(sed -n '/^## Module legs/,/^## /p' "$KIT_DIR/lib/config/module-registry.md" \ +# The README five-stage table covers every module the registry assigns a stage (ADR-0034 +# decision 3 rendered without omissions; the two tables share one truth). "leg" renamed to +# "stage" by the 2026-07-18 amendment (ID-292). +FIVE_LEG_BLOCK=$(sed -n '/^## The five stages/,/^## /p' "$KIT_DIR/README.md") +REGISTRY_MODULES=$(sed -n '/^## Module stages/,/^## /p' "$KIT_DIR/lib/config/module-registry.md" \ | grep '^| ' | grep -v '^| Module\|^|---' | awk -F'|' '{gsub(/ /,"",$2); print $2}') TOTAL=$((TOTAL + 1)) MISSING_LEG_MODULES="" @@ -1619,10 +1620,10 @@ while IFS= read -r m; do echo "$FIVE_LEG_BLOCK" | grep -q "\`$m\`" || MISSING_LEG_MODULES="$MISSING_LEG_MODULES $m" done <<< "$REGISTRY_MODULES" if [ -z "$MISSING_LEG_MODULES" ]; then - echo -e " ${GREEN}PASS${NC} README five-leg table covers every module-registry leg row" + echo -e " ${GREEN}PASS${NC} README five-stage table covers every module-registry stage row" PASS=$((PASS + 1)) else - echo -e " ${RED}FAIL${NC} README five-leg table missing module(s):$MISSING_LEG_MODULES" + echo -e " ${RED}FAIL${NC} README five-stage table missing module(s):$MISSING_LEG_MODULES" FAIL=$((FAIL + 1)) fi From e4a2edcd8b47b0a2123025cae64cb4031130a563 Mon Sep 17 00:00:00 2001 From: Han Ngo Date: Sat, 18 Jul 2026 17:14:42 +0700 Subject: [PATCH 2/3] docs: add proof-of-done for the leg-to-stage rename --- docs/verification/rename-five-legs.md | 80 +++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/verification/rename-five-legs.md diff --git a/docs/verification/rename-five-legs.md b/docs/verification/rename-five-legs.md new file mode 100644 index 00000000..cf8a7b82 --- /dev/null +++ b/docs/verification/rename-five-legs.md @@ -0,0 +1,80 @@ +# Verification: rename the five legs to Shape/Build/Watch/Check/Learn + +Slug: `rename-five-legs` (branch `docs/rename-five-legs`). Backlog row: `_meta/BACKLOG.md` ID-292. + +## What changed + +A docs-first vocabulary sweep of ADR-0034's loop taxonomy per the Plain Words rule +(`CONTRIBUTING.md`, `docs/research/2026-07-16-plain-words-inventory.md`): Specify -> Shape, +Execute -> Build, Observe -> Watch, Govern -> Check (Learn kept), and the container word +leg -> stage. Amends `docs/decisions/0034-harness-loop-taxonomy.md` per the ADR's own lock +(a new `## Amendment` section; decision 3's as-decided table is left unrewritten, matching +the precedent in `docs/decisions/0029-review-function-naming-and-form.md`). No module +renames, no code-identifier renames; the registry-lint assertions in `tests/test-meta.sh` +and `tests/test-config-registry.sh` were updated to match the renamed section headers +(`## The five stages`, `## Module stages`). + +## 2026-07-18 0000 -- green run + +Command: `bash tests/test-meta.sh && bash tests/test-config-registry.sh && bash tests/test-hooks.sh && bash tests/test-kit-contract.sh` +Exit: 0 (each suite) +Output (excerpt): +``` +tests/test-meta.sh: Passed: 698 / 698 All meta tests passed. +tests/test-config-registry.sh: 19/19 passed +tests/test-hooks.sh: Passed: 480 / 480 All tests passed. +tests/test-kit-contract.sh: kit-contract: 25 passed, 0 failed +``` +Verdict: PASS + +## Negative control (before vs after, throwaway worktree off HEAD~1) + +The rename is a mechanical vocabulary sweep with matching doc + test-assertion pairs on +both sides of the diff, so `tests/test-meta.sh`'s own five-stage/five-leg check is +structurally satisfied either way (empty-block short-circuit: if a header search on +either the README or the registry side comes up empty, the completeness loop simply never +runs rather than failing -- a pre-existing leniency in that assertion, not introduced by +this change). The meaningful negative control here is therefore content presence, not a +test-suite red/green flip: does the new vocabulary actually NOT exist before the commit and +DOES exist after. + +Command (pre-rename baseline, `git worktree add HEAD~1`): +``` +grep -c "The five stages\|Shape (Specify)\|Watch (Observe)\|Check (Govern)" README.md lib/config/module-registry.md + -> README.md:0 lib/config/module-registry.md:0 +grep -c "^## The five legs\|^## Module legs" README.md lib/config/module-registry.md + -> README.md:1 lib/config/module-registry.md:1 +bash tests/test-meta.sh + -> Passed: 698 / 698 (pre-rename baseline also green, as expected for a same-release + vocabulary sweep with no behavior change) +``` +Exit: 0 +Verdict: RED for the new vocabulary (absent), confirming the pre-rename state; suite green +as the honest baseline (not a suite failure, since none was expected here). + +Command (post-rename, same worktree checked out to the branch tip): +``` +grep -c "The five stages\|Shape (Specify)\|Watch (Observe)\|Check (Govern)" README.md lib/config/module-registry.md + -> README.md:4 lib/config/module-registry.md:11 +grep -c "^## The five legs\|^## Module legs" README.md lib/config/module-registry.md + -> README.md:0 lib/config/module-registry.md:0 +``` +Exit: 0 +Verdict: GREEN for the new vocabulary (present, old headers gone), proving the diff is +real content, not a no-op. + +## Reproducible + +``` +git -C worktree add /tmp/kit-negctl HEAD~1 +grep -c "The five stages\|Shape (Specify)\|Watch (Observe)\|Check (Govern)" \ + /tmp/kit-negctl/README.md /tmp/kit-negctl/lib/config/module-registry.md +git -C /tmp/kit-negctl worktree remove /tmp/kit-negctl --force # run from the main checkout +bash tests/test-meta.sh +bash tests/test-config-registry.sh +``` + +[PROOF OF DONE: docs-first vocabulary rename, class=behavioral per proof-ledger.sh's +diff classifier (test-assertion .sh files touched alongside docs), inert per +`lib/gate/proof-gate.sh contract` (a spec-feature/inert task type) -- both suites and this +record capture the honest evidence either way.] From 7d3c3852efa1e12a76b25fac83e33fc8548bccd0 Mon Sep 17 00:00:00 2001 From: Han Ngo Date: Sat, 18 Jul 2026 17:19:01 +0700 Subject: [PATCH 3/3] docs: fix advisor findings on the leg-to-stage rename Repairs the feedback-loop.md ascii diagram's left/right rails (a floating disconnected column, a one-char right-rail kink), rewords the ADR-0034 amendment's alias sentence to stop overclaiming parenthetical aliases in files that are actually a clean cutover, and updates CHANGELOG.md's live Unreleased section (a stale leg-vocabulary mention, plus a new entry documenting the ID-292 rename). --- docs/CHANGELOG.md | 14 +++++++++++--- docs/decisions/0034-harness-loop-taxonomy.md | 11 +++++++---- lib/session/audit/docs/feedback-loop.md | 8 ++++---- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index a44c7700..598243cb 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -43,7 +43,8 @@ All notable changes to dwarves-kit are documented here. nature). Tests: `tests/test-sync-cron-install.sh` + `tests/test-sync-cron-launcher.sh`. - **`sync` module: two-way board↔apps sync (SPEC-001/SPEC-002 P1).** The ops-toolkit - backlog-sync engine graduates into the kit as registered module `sync` (leg Specify) + backlog-sync engine graduates into the kit as registered module `sync` (stage: Shape, + formerly leg Specify -- renamed by ID-292, see below) at `lib/sync/`: `board sync` mirrors an adopted repo's BACKLOG.md to Apple Reminders / Notion / Hermes kanban / Multica with per-app three-way merge (board wins; app deletions tombstone; inbox intake with `#inbox` quarantine). Config on the ADR-0034 @@ -57,8 +58,15 @@ All notable changes to dwarves-kit are documented here. paths). Proof: `lib/sync/docs/proof-of-done.md`. - **Plain words rule (CONTRIBUTING.md) + ranked jargon inventory** (`docs/research/2026-07-16-plain-words-inventory.md`); rename backlog: ID-291 (cheap - cluster), ID-292 (legs → Shape/Build/Watch/Check/Learn, needs an ADR-0034 - amendment), ID-293 (big cluster, parked). + cluster), ID-292 (shipped below), ID-293 (big cluster, parked). +- **The five legs renamed to Shape/Build/Watch/Check/Learn (ID-292).** `Specify`, + `Execute`, `Observe`, `Govern` become `Shape`, `Build`, `Watch`, `Check` (`Learn` + kept); the container word `leg` becomes `stage`. ADR-0034 amended per its own lock + (decision 3's as-decided table left unrewritten); `lib/config/module-registry.md` + carries the old names as a one-release parenthetical alias, README/architecture/ + data-flow/MANUAL/kit-contract/onboard docs and the registry-lint assertions in + `tests/test-meta.sh` swept to the new vocabulary. Docs-first: no module or + code-identifier renames. - **Model-routing enforcement pinned + proven (SPEC-116).** Resolves `orchestrate-hardening` open-fork 3: the enforcement site is `lib/queue/orchestrate.sh` (`_route()` + the serial/wave delegate dispatch sites, which already existed under SPEC-087), not `lib/classify/route-suggest.sh` (a decompose-time diff --git a/docs/decisions/0034-harness-loop-taxonomy.md b/docs/decisions/0034-harness-loop-taxonomy.md index c72a372d..baac34a2 100644 --- a/docs/decisions/0034-harness-loop-taxonomy.md +++ b/docs/decisions/0034-harness-loop-taxonomy.md @@ -174,10 +174,13 @@ same-release sweep is the correct size, not a phased migration. | leg (container word) | **stage** | the everyday word every PM already uses for one step of a workflow | Per the Plain Words rule's renaming clause, the old names live as a parenthetical alias for one -release: `lib/config/module-registry.md`'s stage column, README's "The five stages" section, -`docs/data-flow.md` (prose + the module-map diagram), `docs/MANUAL.md`'s command index, -`docs/kit-contract.md`, `commands/onboard.md`'s welcome tour, and the registry-lint assertions in -`tests/test-meta.sh` all sweep to the new names in the same change (`_meta/BACKLOG.md` ID-292). +release where a reader would otherwise be confused by a hard cutover: `lib/config/module-registry.md`'s +stage column, README's "The five stages" section, and the touched per-module READMEs +(`lib/sync`, `lib/learn`, `lib/gate`, `lib/cosmetic`, `lib/session/audit`). Everywhere else the +rename is a clean sweep with no old-name residue -- `docs/data-flow.md`, `docs/MANUAL.md`'s +command index, `docs/kit-contract.md`, `commands/onboard.md`'s welcome tour, and the +registry-lint assertions in `tests/test-meta.sh` -- all move straight to the new names in the +same change (`_meta/BACKLOG.md` ID-292). `prose_rag`'s leg assignment (flagged as a documented deviation in `lib/config/module-registry.md`) is unaffected by this amendment; it is a separate open question. diff --git a/lib/session/audit/docs/feedback-loop.md b/lib/session/audit/docs/feedback-loop.md index ceeb4387..04a71e5f 100644 --- a/lib/session/audit/docs/feedback-loop.md +++ b/lib/session/audit/docs/feedback-loop.md @@ -13,10 +13,10 @@ to it. Shape ──► Build ──► Watch session-audit run ▲ │ = the deep Watch pass: - ▼ dated report, owner tags, - Check metric contracts - │ - └────── Learn ◄────┘ session-audit triage + │ ▼ dated report, owner tags, + │ Check metric contracts + │ │ + └────── Learn ◄─────┘ session-audit triage (propose gate) = a Learn-stage proposer: report footer -> kanban proposal rows, human accepts