diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 944ba3b..0cc61b9 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ { "name": "working-process", "source": "./plugins/working-process", - "description": "Spec-driven working process on top of superpowers: grilling-session, architect-session, system-designer-session, process-status, process-setup and sync-rules skills, architect and plan-adversary verdict agents, architect-consult and system-designer-consult consultation agents, propagation-auditor and integrity-auditor audit agents, plus distributed process rules" + "description": "Spec-driven working process on top of superpowers: grilling-session, architect-session, system-designer-session, process-status, process-setup, review-loop and sync-rules skills, architect and plan-adversary verdict agents, architect-consult and system-designer-consult consultation agents, propagation-auditor and integrity-auditor audit agents, the wp-phrase-check, wp-document-check and wp-decision-coverage commands, plus distributed process rules" }, { "name": "python-standards", diff --git a/.working-process/.gitignore b/.working-process/.gitignore new file mode 100644 index 0000000..8b9688d --- /dev/null +++ b/.working-process/.gitignore @@ -0,0 +1 @@ +settings.local.md diff --git a/.working-process/settings.md b/.working-process/settings.md new file mode 100644 index 0000000..1ada861 --- /dev/null +++ b/.working-process/settings.md @@ -0,0 +1,19 @@ +# working-process settings + +Which mode does a Process directory get unless an exception names it — tracked or ignored? +dir.default: tracked + +Which mode does docs/code-review/ get, as an exception to dir.default — tracked or ignored? +dir.docs/code-review: ignored + +Which mode does the .superpowers/ family get, as an exception to dir.default — tracked or ignored? +dir..superpowers: ignored + +Is the technical design offered at every consumption gate (on) or never (off)? +design.technical-design-offer: off + +How does the topic branch take the .docs branch at the implementation-ready gate — squash or fast-forward? +docs-branch.merge: squash + +Which directory under docs/ holds one directory per ticket, if the project keeps them? +ticket.root: docs/tickets diff --git a/CLAUDE.md b/CLAUDE.md index 0b3e862..d42d776 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,15 +27,6 @@ happen (see the plugin-versioning rule). When an isolated workspace is used, its git worktree lives at `.claude/worktrees//` — one per topic branch, git-ignored. -## Technical designs - -This repository does not get the technical-design offer by default. Its -product is prose: a part's name is its path and behaviour is already the -shape of the contract, so a technical design here would restate the -design spec and the plan. The declaration switches the default offer -off; it is not a ban. Ask for a technical design explicitly and the -step runs as it would anywhere else. - ## Authoring skills When creating or editing a skill in any plugin, use the `skill-creator` diff --git a/README.md b/README.md index 02f6e5c..7a16d46 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Marketplace of [Claude Code](https://code.claude.com) plugins by Missing Bits. | Plugin | Docs | Description | |--------|------|-------------| -| `working-process` | [README](plugins/working-process/README.md) | Spec-driven working process: grilling-session, architect-session, system-designer-session, process-status, process-setup and sync-rules skills, architect and plan-adversary verdict agents, two verdict-free consultation agents, propagation-auditor and integrity-auditor audit agents, distributed process rules | +| `working-process` | [README](plugins/working-process/README.md) | Spec-driven working process: grilling-session, architect-session, system-designer-session, process-status, process-setup, review-loop and sync-rules skills, architect and plan-adversary verdict agents, two verdict-free consultation agents, propagation-auditor and integrity-auditor audit agents, the `wp-phrase-check`, `wp-document-check` and `wp-decision-coverage` commands, distributed process rules | | `python-standards` | [README](plugins/python-standards/README.md) | Python coding standards for uv + ruff + pytest + pyright: area skills, code-review stack, plan-review checklist, distributed toolchain rule | | `salesforce-standards` | [README](plugins/salesforce-standards/README.md) | Salesforce coding standards for the sf CLI toolchain: area skills (Apex, Apex triggers, LWC, Flow, data/security model, legacy UI), code-review stack, plan-review checklist, distributed toolchain rule | | `project-memory` | [README](plugins/project-memory/README.md) | In-repo project memory: committed Team memory (`docs/memory/`) and per-user Private memory (`.claude/memory/`), with `memory-review-session`, `migrate-memory`, and `redirect-memory` skills, distributed as a Rules payload | diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index f19d51e..d757fb5 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -389,9 +389,30 @@ re-raise against it. On a fold against a line written before the clause existed, the date on that line's own terminal token is the earlier ruling. It closes a finding; a held hit it authorizes closes only once the gate has rechecked the fix. The round-level counterpart -is an Adjudication. +is an Adjudication. A Stand-in's answer is not one: it is a Provisional +decision until the developer confirms it. _Avoid_: developer decision (as the name), developer fix +**Provisional decision**: +A decision no written decision licenses, taken by someone other than +the developer — a Stand-in's answer to a held finding, or a session's +answer to a question no document settles during implementation. It +takes effect at once, is recorded on its disposition line with +`provisional: (stand-in )` or as a line of the +implementation's provisional list, +licenses no later fix, and reaches the developer in one provisional +batch, where it is confirmed into a Ruling or reversed. +_Avoid_: ruling (for an unconfirmed answer), proxy decision + +**Stand-in**: +An agent or tool the developer names in conversation, for one session, +to answer the held findings a review round would put to them. Its +answers are Provisional decisions; during implementation it may also +answer an implementer's question. It never takes loop control, a held +gate hit, a mechanism hold, an Adjudication, a register entry's +withdrawal or deferral, or a `status` move. +_Avoid_: proxy + **Fallback**: The model that actually produced a degraded or chosen verdict, standing in for the prescribed tier; named (as a family alias) in the value of @@ -427,11 +448,11 @@ will ever ask. _Avoid_: usage point **Unfinished-work list**: -The named section of the spec-plan-lifecycle rule holding one entry per -class of unfinished process work — class name, grep command, the owner +The reference file of the `process-status` skill, `UNFINISHED-WORK.md`, +holding one entry per class of unfinished process work — class name, grep command, the owner of the next move, and optionally the entry's own match scope — and the single definition site for which classes exist. A class that accepts -the default scope costs one edit in the rule and none in the consumers +the default scope costs one edit in the list and none in the consumers that run it. Publishing a scope of its own cost a consumer edit once, to teach the consumers section scopes at all; every class publishing one since trades on that lesson for free. A command's output is hits to @@ -481,10 +502,12 @@ _Avoid_: sweep agent, verifier **Hit**: The unit a mechanical check returns — an Unfinished-work list command's -match or a propagation-auditor detection: located, binary, never graded. -Graded problems are Findings and belong to review rounds. The two kinds -part company over disposition: a propagation-auditor hit is confirmed or -dismissed by the dispatcher and the outcome is written as a gate line, +match, a propagation-auditor detection, a Document check's or +`wp-decision-coverage`'s: located, +binary, never graded. Graded problems are Findings and belong to review +rounds. The two kinds part company over disposition: a propagation-gate +hit, the auditor's or a Document check's, is confirmed or dismissed by +the dispatcher and the outcome is written as a gate line, while an Unfinished-work hit has no dismissal at all — its only disposition is ceasing to match, when the state the command anchors is rewritten or annotated closed. A confirmed hit of the coverage duty @@ -493,6 +516,29 @@ developer; its disposition stays open until that decision is recorded and the gate rechecks the changed spec and plan. _Avoid_: mechanical finding +**Verification check**: +A command a plan's step carries, with the result it expects, that shows +the step did what it says — a count of a phrase, a diff, a test run. +It belongs to the plan and runs at execution; a Hit is what the +process's own mechanical checks return, never this. +_Avoid_: sanity check, check (bare, where a Hit is also in view) + +**Vacuous check**: +A Verification check that gives the same result before its step and +after it, so it cannot show the step did anything — including one that +passes because it examined nothing. Declaring that a step leaves a +result unchanged makes such a check intended rather than vacuous. +_Avoid_: no-op check, dead check + +**Document check**: +One of the deterministic checks `wp-document-check` runs over a design +spec, a technical design or a plan — internal references and +citations on all three, table closure on a technical design alone. It returns Hits, +never Findings, and reports what it could not settle as not checked. It +belongs to the gate, not to the plan: a Verification check is the +plan's own and runs at execution. +_Avoid_: check (bare, where a Hit is also in view), script check + **Disposition ledger**: The record a review loop keeps inside the reviewed document, under one `## Review rounds` section: what each round found and what became of it. @@ -549,7 +595,7 @@ The map from each counted identifier of a decision register — each leaf identifier that is neither withdrawn nor deferred by the audited plan — to the plan tasks and Global Constraints entries citing it, in the audited plan or in an implemented predecessor its `**Follows:**` lines -name, derived by the propagation auditor. A counted identifier nothing +name, derived by `wp-decision-coverage`, which the dispatcher runs at the propagation gate. A counted identifier nothing cites, and a task lacking its `**Realizes:**` line where the convention binds, are the two coverage hits. _Avoid_: coverage (bare, for this map — the integrity audit's coverage @@ -559,8 +605,9 @@ tell is another fact) The obligation a diff-scoped LGTM leaves: the document was approved with no whole-document read at the end, so somebody must still take responsibility for the part no round re-read — or explicitly decline to. -The consumption gate owns it, not the loop, which owes nothing further -once it terminates. Discharged three ways: an integrity audit, any later +For a judged document the consumption gate owns it, not the loop, which +owes nothing further once it terminates; for a plan the confirming round +owns it. Discharged three ways: an integrity audit, any later full-document round whatever its verdict, or the developer's recorded decline. What they decline is the gate's pair offer — or, where the document is already implemented and the gate never fired, the question @@ -608,7 +655,8 @@ _Avoid_: review agent (unqualified), reviewer agent **Relay**: The delivery of a background agent's result to the developer before any further action on it — a verdict agent's report before its stamp (a -header carrying the verdict, the model self-report and the counts, then +header carrying the verdict, the model self-report, the counts and — +where a document was reviewed — its size and change, then one line per finding, that list never condensed), a consultation's Contribution digested one paragraph per focusing question. Either way it names the Dispatch record holding the full text. The developer's @@ -618,13 +666,14 @@ _Avoid_: report back, forward (as the term) **Dispatch record**: The file a dispatcher writes before relaying a background agent's result — one dispatch, one file, holding what the agent returned -verbatim under a four-line header (date, agent, model self-report, -subject). Kept per subject under `.claude/working-process//`, -git-ignored, and NOT a Process directory — a per-checkout store under -the `.claude/` config namespace, as Private memory is a per-user one. It -survives compaction, the session's end and a branch switch, and no more: -that bound is what lets a Relay condense. Never a Review report, the -counted document one code-review run writes. +verbatim under a header of date, agent, model self-report, subject and +size, where a document was reviewed. Kept per +subject under `.claude/working-process//`, git-ignored, and NOT a +Process directory — a per-checkout store under the `.claude/` config +namespace, as Private memory is a per-user one. It survives compaction, +the session's end and a branch switch, and no more: that bound is what +lets a Relay condense. Never a Review report, the counted document one +code-review run writes. _Avoid_: dispatch log, transcript file **Session skill**: diff --git a/docs/plans/2026-11-13-cost-discipline-plan.md b/docs/plans/2026-11-13-cost-discipline-plan.md new file mode 100644 index 0000000..1ef6857 --- /dev/null +++ b/docs/plans/2026-11-13-cost-discipline-plan.md @@ -0,0 +1,148 @@ +--- +ticket: none +date: 2026-11-13 +status: implemented +spec: ../specs/2026-11-13-cost-discipline-spec.md +branch: feature/cost-discipline +base: develop +--- + +# Cost discipline Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make the working-process reviewers and the session's triage ask whether a mechanism is worth having, and block only on Critical findings. + +**Architecture:** Prose edits to one shared persona file, two agent cards, the workflow rule and the repo glossary. No script, no settings key, no new file. Each task edits one file and ends with a grep that proves the change landed and the replaced text is gone. + +**Tech Stack:** Markdown agent cards and rules of a Claude Code plugin; `rg`, `claude plugin validate`. + +**Spec:** `docs/specs/2026-11-13-cost-discipline-spec.md` — read its *A mechanism*, *Reviewers*, *Triage*, *Verdict threshold*, *Before drafting*, *Dropped stays dropped* and *Net growth* sections before the task that realizes them. Paths below are relative to the repository root; `plugins/working-process/` is abbreviated `wp/`. + +## Global Constraints + +- All committed text is English; no machine paths, no company or client names (repo-hygiene rule). +- Commit messages: one conventional-commit line, no body, no trailer. +- Rule text names skills and agents conditionally ("when the X agent is available"). +- Every edited prose passage gets an elements-of-style pass when that skill is available; the pass changes wording, never decisions. +- The definition of a mechanism is worded identically in `wp/PERSONA_COMMON.md` and `wp/rules/workflow.md`: "A fix adds a mechanism when it introduces something the document did not have: a part, a task, a command, an option or flag, a state file or field, or a recovery path. Giving an existing part a new check, branch or case adds one too, whichever way it moves what the part accepts. Rewording, correcting a value, deleting text, removing an input, option or case, and adding a test or a verification step that brings no new command or script add none." +- Documents with `status: implemented` keep their wording; only live rules, cards and glossary entries change. +- Implementation commits go to `feature/cost-discipline`. The spec's per-round commits sit on `feature/cost-discipline.docs`; merging that branch into the topic branch happens at the implementation-ready gate, before Task 1. + +## Review Focus + +1. **A card read without the rules installed.** The architect and the plan-adversary must still have the definition and the non-goal sentence: both live in `PERSONA_COMMON.md`, which both cards reach. Task 1 checks the reach. +2. **Consultation personas read `PERSONA_COMMON.md` too.** The added text must not tell a consult agent to hold, grade or block anything. Task 1's wording addresses reviewers only. +3. **A dispatch with no reviewed document** (an architect question). No size line, and the relay shows no size. Task 4 states it. +4. **A previous record with no `size:` line** (every record written before this change). The relay shows the size without a change. Task 4 states it. +5. **A fix that carries out a developer's `ruling:`.** It must not be held a second time by D4. Task 4 states the exemption. + +--- + +### Task 1: Shared persona text — definition and settled non-goals + +**Files:** +- Modify: `wp/PERSONA_COMMON.md` (opening paragraph, and a new section after *The boundary between the personas*) + +**Interfaces:** +- Produces: the section heading `## Cost discipline`, which Tasks 2 and 3 point to by name. + +**Realizes:** D9 + + +- [ ] **Step 1: Add `## Cost discipline` before `## The consultation contract`**, holding two paragraphs, both addressed to reviewers: + - the definition, verbatim from Global Constraints; + - non-goals: a design spec's non-goals are settled; a finding that would reintroduce one says what new evidence it brings, new against the spec's own text. +- [ ] **Step 2: Update the self-description in the opening paragraphs.** "the two duties below" and "All four sections" must match the file after Step 1; the new section is a section, not a duty — recount and reword so both counts are true. +- [ ] **Step 3: Verify.** + Run: `rg -n '^## ' wp/PERSONA_COMMON.md; rg -c 'A fix adds a mechanism when' wp/PERSONA_COMMON.md; sed -n 1,12p wp/PERSONA_COMMON.md` + Expected: five `## ` headings including `## Cost discipline`; count `1`; every count in the opening paragraphs matches the heading list just printed. +- [ ] **Step 4: Verify the reach.** + Run: `rg -n 'PERSONA_COMMON' wp/agents/plan-adversary.md wp/ARCHITECT_PERSONA.md` + Expected: one line in each file. +- [ ] **Step 5: Commit** — `git commit -m "feat(working-process): cost-discipline section in the shared persona file"` + +### Task 2: Architect card — cheaper alternative, threshold, Critical scale + +**Files:** +- Modify: `wp/agents/architect.md` (*Report* list, item 2 and item 3; the severity paragraph after it) + +**Interfaces:** +- Consumes: `## Cost discipline` in `wp/PERSONA_COMMON.md` (Task 1). + +**Realizes:** D1, D6, D12 + + +- [ ] **Step 1: Findings (item 2).** Add: where a finding's suggestion adds a mechanism (definition in `PERSONA_COMMON.md`, *Cost discipline*), the finding names at least one cheaper alternative beside it — narrowing the input, the tool's native behaviour, accepting the gap as a documented limitation, or deferring it. +- [ ] **Step 2: Verdict (item 3).** Replace "`blocking` = at least one Critical or two Important findings" with "`blocking` = at least one Critical finding". The sentence wraps across two lines in the card. +- [ ] **Step 3: Critical.** Extend the Critical definition to also cover a stated requirement the design does not meet, and a data-loss or security defect. Leave Important and Minor unchanged. +- [ ] **Step 4: Verify.** + Run: `rg -n -U 'two\s+Important' wp/agents/architect.md; rg -n 'at least one Critical finding' wp/agents/architect.md; rg -n 'cheaper alternative' wp/agents/architect.md; rg -n -i 'security defect' wp/agents/architect.md` + Expected: the first prints nothing; each of the other three prints one line. +- [ ] **Step 5: Commit** — `git commit -m "feat(working-process): architect blocks on Critical only and names cheaper alternatives"` + +### Task 3: Plan-adversary card — cheaper alternative, threshold, undelivered requirements + +**Files:** +- Modify: `wp/agents/plan-adversary.md` (*Ground rules* severity bullet; dimensions 1, 5 and 6; *Output* verdict line) + +**Interfaces:** +- Consumes: `## Cost discipline` in `wp/PERSONA_COMMON.md` (Task 1). + +**Realizes:** D1, D6, D7 + + +- [ ] **Step 1: Ground rules.** Add the same cheaper-alternative sentence as Task 2 Step 1, plus: the finding also names the requirement that forces the mechanism, with `origin: design-spec`, and proposes no change to that document (the card's *Judged documents: decline* boundary stands). +- [ ] **Step 2: Critical scale.** In the generic scale, add "a requirement the plan does not deliver" to Critical. +- [ ] **Step 3: Regrade exactly three findings from Important to Critical:** dimension 1 "Is every 'done when' delivered by some phase? A gap is Important."; dimension 5 "An uncovered part is an Important finding"; dimension 6 "A decision realized only in part … is an Important finding". The other Important findings in dimension 5 stay Important. +- [ ] **Step 4: Verdict line.** Replace "`blocking` = ≥1 Critical or ≥2 Important" with "`blocking` = ≥1 Critical". +- [ ] **Step 5: Verify.** + Run: `rg -n '2 Important' wp/agents/plan-adversary.md; rg -n 'A gap is Critical|uncovered part is a Critical|only in part.*Critical' wp/agents/plan-adversary.md; rg -c 'is an Important finding' wp/agents/plan-adversary.md; rg -n 'cheaper alternative' wp/agents/plan-adversary.md` + Expected: the first prints nothing; the second prints three lines (a wrapped sentence may need `-U`); the count equals the count on `develop` minus two (`git show develop:plugins/working-process/agents/plan-adversary.md | rg -c 'is an Important finding'`); the last prints one line. +- [ ] **Step 6: Commit** — `git commit -m "feat(working-process): plan-adversary blocks on Critical only and grades undelivered requirements Critical"` + +### Task 4: Workflow rule — definition, triage hold, brief, dispatch record size + +**Files:** +- Modify: `wp/rules/workflow.md` (step 1; *Dispatching a verdict agent* bullets on the dispatch record, the relay header and the decision count; *The review loop* triage paragraph; *Re-dispatch briefs*) + +**Realizes:** D2, D4, D5, D8, D11 + +- [ ] **Step 1: Step 1 of the flow (D8).** After the consult-persona sentences, add: while drafting a design spec, before its first review, the session asks the developer for a size target, what is dropped, what native behaviour already covers and which risks are accepted, and writes the answers into the spec's non-goals and constraints — no separate brief file. +- [ ] **Step 2: Triage (D4, D5).** After the paragraph opening "Triage decides each finding by its license", add the definition (verbatim, Global Constraints) and: a fix that adds a mechanism is held whatever its severity and whether or not a license exists; not held again when it carries out a `ruling:`, nor when it is a propagation-gate hit's fix; held when the session cannot tell. Its `options:` recommend the smaller option where it meets the requirements and always include "accept as a documented limitation". +- [ ] **Step 3: Decision count (D4).** In the bullet "The header's count of decisions is the findings for which the session can cite no license", add the fixes the cost hold catches, so the count still matches the round's `held` lines. +- [ ] **Step 4: Dispatch record (D11).** In the bullet that says "under a four-line header — the date, the agent, the model self-report, and the subject", list the fields instead of counting them and add `size: ` where a document was reviewed: the body's line count without the `## Review rounds` section, from `sed '1,/^---$/d' | awk '/^## Review rounds/{s=1;next} /^## /{s=0} !s' | wc -l`. +- [ ] **Step 5: Relay header (D11).** In the bullet "The relay opens with one header line", add the size and the change since the previous record of the same document and agent; no size without a reviewed document; no change when no earlier record carries a `size:` line; the relay judges nothing. +- [ ] **Step 6: Re-dispatch briefs (D2).** After "directs the reviewer to attack the previous wave's fixes first", add: including whether a fix added a mechanism its finding did not need. +- [ ] **Step 7: Verify.** + Run: `rg -n 'four-line' wp/rules/workflow.md; rg -c 'A fix adds a mechanism when' wp/rules/workflow.md; rg -n 'size: ' wp/rules/workflow.md; rg -n 'documented limitation' wp/rules/workflow.md; rg -n -i 'size target' wp/rules/workflow.md` + Expected: the first prints nothing; count `1`; each of the others at least one line. +- [ ] **Step 8: Verify the size command** on the spec: `sed '1,/^---$/d' docs/specs/2026-11-13-cost-discipline-spec.md | awk '/^## Review rounds/{s=1;next} /^## /{s=0} !s' | wc -l` prints a number below `wc -l` of the file, and `rg -c '^## Review rounds' docs/specs/2026-11-13-cost-discipline-spec.md` prints `1`. +- [ ] **Step 9: Commit** — `git commit -m "feat(working-process): cost hold in triage, size in relays, brief while drafting"` + +### Task 5: Glossary — relay header and dispatch record + +**Files:** +- Modify: `docs/domain/glossary.md` (*Relay* and *Dispatch record* entries) + +**Realizes:** D11 + +- [ ] **Step 1:** *Relay* — the header also carries the document's size and its change where a document was reviewed. +- [ ] **Step 2:** *Dispatch record* — replace "a four-line header (date, agent, model self-report, subject)" with the field list plus "size, where a document was reviewed". +- [ ] **Step 3: Verify.** Run: `rg -n 'four-line' docs/domain/glossary.md` — Expected: nothing. No *Mechanism* entry is added (spec, *A mechanism*). +- [ ] **Step 4: Commit** — `git commit -m "docs: glossary relay and dispatch record carry size"` + +### Task 6: Changelog, validation, dogfood version and dogfood + +**Files:** +- Modify: `wp/CHANGELOG.md`, `wp/.claude-plugin/plugin.json`, `.claude/working-process/release-queue.md` (local, not committed) + +**Realizes:** none + +- [ ] **Step 1: Changelog.** Add `## Unreleased` at the top with one bullet per user-visible change: Critical-only `blocking` in both cards; undelivered requirements Critical in the plan-adversary; the architect's Critical covers unmet requirements, data loss and security; cheaper alternatives in findings; the cost hold in triage; size in relays and dispatch records; the drafting question. +- [ ] **Step 2: Dogfood version.** Set `"version": "0.20.0-dev.5.cost-discipline"` (the highest on `develop` is `-dev.4.`). +- [ ] **Step 3: Validate.** Run: `claude plugin validate . && claude plugin validate plugins/working-process` — Expected: both pass. Run: `rg -n -U 'two\s+Important|≥2 Important' plugins/` — Expected: nothing. +- [ ] **Step 4: Commit** — `git commit -m "chore(working-process): changelog and dogfooding version for cost discipline"` +- [ ] **Step 5: Dogfood, plan-adversary.** With the plugin loaded from this checkout and its rules synced, dispatch the plan-adversary on the ai-devcontainer v2 plan as it stood at its first round (in the developer's ai-devcontainer checkout). Expected: no `blocking` verdict; every finding whose fix adds a mechanism names a cheaper alternative and, where a requirement forces it, the requirement. Record the result in `.claude/working-process/2026-11-13-cost-discipline-spec/dogfood.md`. +- [ ] **Step 6: Dogfood, loop.** On a scratch spec seeded with (a) a Minor whose natural fix adds a task and (b) a design-level security defect, run one architect round and triage it. Expected: (a) is held with the smaller option recommended; (b) is Critical and the verdict `blocking`; the relay header shows the size. Record in the same file. +- [ ] **Step 7: Release queue.** Mark 2b-core implemented with the commit range in `.claude/working-process/release-queue.md`. diff --git a/docs/plans/2026-11-16-plan-quality-plan.md b/docs/plans/2026-11-16-plan-quality-plan.md new file mode 100644 index 0000000..643d8cd --- /dev/null +++ b/docs/plans/2026-11-16-plan-quality-plan.md @@ -0,0 +1,886 @@ +--- +ticket: none +date: 2026-11-16 +status: implemented +spec: ../specs/2026-11-16-plan-quality-spec.md +branch: feature/plan-quality +base: develop +adversary: concerns (resolved 2026-11-16) +--- + +# Plan Quality Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ship `wp-phrase-check`, the `plan-authoring.md` rule and the +two reads that put that rule in front of a plan's author and its +reviewer. + +**Architecture:** A Python script in the plugin's `scripts/` counts a +phrase over normalised text and verifies the count against the number +its side expects. A bash launcher in the plugin's new `bin/` finds a +Python 3.9 or later and runs the script, so a plan calls the command by +name. One path-scoped rule holds the defect classes, the failing-test +rule and the check-writing rules; the plan-adversary card and +`workflow.md` step 4 each gain a read of it. + +**Tech Stack:** Python 3.9+ standard library (`argparse`, `re`), +`unittest`, bash, Markdown. + +**Spec:** `docs/specs/2026-11-16-plan-quality-spec.md` + +## Global Constraints + +- Every command runs from the repository root, on the topic branch + `feature/plan-quality`. +- The script uses the standard library only and runs on Python 3.9: + it opens with `from __future__ import annotations`. +- Committed text is English and carries no path under a home + directory, no client name and no project name. The rule describes + its evidence generically. +- Commit messages are one line, conventional-commit form, no body and + no trailer. A commit step runs only where the developer has + authorized commits for this plan's execution. +- No step predicts what a failing run prints. A red step says: run it + with the change absent and record what it prints in the report. A + run that does not fail with the change absent stops the task: report + `BLOCKED` under superpowers:subagent-driven-development, or stop and + report to the developer when executing inline. +- Per task, run only that task's new test file. The whole suite runs + once, in Task 6. +- From Task 3 on, every verification check over text is a + `wp-phrase-check` call by its checkout path, + `plugins/working-process/bin/wp-phrase-check`: the installed plugin + does not carry the command yet. A check on a file present on both + sides runs on each side of its step, the two calls identical but for + `--side`. A file the step creates runs the after side only. +- Every expected count below was computed against the state the + previous task leaves, with develop at `8449fc7`. Steps find their + place by text, never by line number. +- New and edited Markdown under `plugins/` gets the + `elements-of-style:writing-clearly-and-concisely` pass when that + skill is available. The pass binds wording, never a decision; the + blocks this plan gives verbatim have had theirs. +- Glossary terms bind: **Verification check** and **Vacuous check** as + `docs/domain/glossary.md` defines them; never "sanity check", + "no-op check" or "dead check". + +## Review Focus + +Known limit (session's provisional decision, 2026-11-16): `--phrase` is normalised like the text, so a phrase that itself opens with a list or quote marker loses it; the helper prints the normalised phrase, which the author reads. + +Inputs the spec implies and its *Verification* list does not name. +Each has its test in the task that owns the code. + +1. A file with CRLF line endings: a phrase wrapped across a CRLF + counts like any other (Task 1, `test_crlf_wrap_counts`). +2. A file opening with a UTF-8 byte-order mark: a phrase at the very + start still counts (Task 1, `test_bom_does_not_hide_first_word`). +3. A phrase that starts with a hyphen, such as the name of one of the + command's own arguments: written `--phrase=`, it counts + (Task 1, `test_phrase_starting_with_hyphen`). +4. A path containing a space: the launcher passes it through whole + (Task 2, `test_path_with_space_survives_launcher`). +5. An empty file: it was read, holds zero lines and counts zero, so a + removal check over it passes and says `lines 0` (Task 1, + `test_empty_file_is_read`). + +## File Structure + +| File | Change | Responsibility | +|---|---|---| +| `plugins/working-process/scripts/phrase-check.py` | create | normalise, count, verify, print, exit | +| `plugins/working-process/bin/wp-phrase-check` | create | find Python 3.9+, run the script | +| `tests/working-process/test_phrase_check.py` | create | the script's behaviour | +| `tests/working-process/test_wp_phrase_check_launcher.py` | create | the launcher's fallbacks | +| `plugins/working-process/rules/plan-authoring.md` | create | the rule | +| `plugins/working-process/agents/plan-adversary.md` | modify | read the rule at FIRST ACTION | +| `plugins/working-process/rules/workflow.md` | modify | step 4 reads the rule before plan-writing | +| `plugins/working-process/README.md` | modify | component, requirements, rule count, permission entry | +| `plugins/working-process/CHANGELOG.md` | modify | `## Unreleased` entries | +| `plugins/working-process/.claude-plugin/plugin.json` | modify | description, dogfood version | +| `.claude-plugin/marketplace.json`, `README.md` | modify | description names the command | + +--- + +### Task 1: The phrase-check script + +**Files:** +- Create: `plugins/working-process/scripts/phrase-check.py` +- Test: `tests/working-process/test_phrase_check.py` + +**Interfaces:** +- Produces, for Task 2 and every later check — the command line: + + phrase-check.py [...] --phrase --before --after --side before|after [--unchanged] + + Exit `0` pass; `1` check failure (a path problem, no path named, a + count mismatch, a vacuous pair); `2` usage error, which `argparse` + raises by itself. +- Produces — functions, so the tests and the script agree on names: + `normalise(text: str) -> str`, + `count_phrase(text: str, phrase: str) -> int`, + `read_text(path: str) -> str` (raises `Unreadable`, whose message is + the reason), `main(argv: list[str] | None = None) -> int`. + +**Realizes:** D2, D3, D4 + +**The contract the tests pin** + +*Normalisation* (`normalise`), in this order: + +1. Split into lines with `str.splitlines()`. +2. From each line drop leading whitespace, then every leading marker, + repeatedly: `>` with any whitespace after it; `-`, `*` or `+` + followed by whitespace or the line's end; digits followed by `.` or + `)` and then whitespace or the line's end. As one pattern: + `^\s*(?:(?:>\s*|(?:[-*+]|\d+[.)])(?:\s+|$)))*`. +3. Join the lines with one space, collapse every run matching `\s+` to + one space, strip both ends, apply `str.casefold()`. + +Nothing else is stripped: headings (`#`), table pipes, task-list boxes +(`[ ]`), emphasis and code markers stay, so `---` and `**bold**` are +untouched. `--phrase` goes through the same function. A phrase empty +after normalising is a usage error (exit `2`). + +*Counting* (`count_phrase`): `normalise(text).count(normalise(phrase))` +per file, summed over the files named. `str.count` does not overlap, +and counting per file never spans two files. A path named twice counts +twice. + +*Reading* (`read_text`): a path is a file. The shell expands globs; +the script expands nothing and refuses a directory. Open in binary and +decode as `utf-8-sig`. The reasons, verbatim: `no such file`, +`not a file`, `cannot be read ()`, `not valid UTF-8`. +"Read no file" means no path reached the script. + +*Arguments*: `--before` and `--after` are required non-negative +integers (a negative is a usage error); `--side` is required; +`--unchanged` declares that the step leaves the count as it is. +`expected` is the number of the side named. + +*Output*, one shape, all on stdout: + + wp-phrase-check: PASS + phrase: "" + side: after + expected: 1 (before 0, after 1) + actual: 1 + read: files 1, lines 79 + : lines 79, matches 1 + +A failing run prints `wp-phrase-check: FAIL` on the first line and +appends one `fail:` line per reason, in this fixed order: + + fail: : + fail: read no file + fail: count mismatch: expected on side , found + fail: vacuous: before and after are both ; pass --unchanged if the step leaves the phrase as it is + +With a path problem or no path, `actual:` reads `not counted`, the +`read:` block lists the files that were read, and neither count line +is evaluated. Otherwise the mismatch line and the vacuity line are +evaluated independently, so a run can print both, mismatch first. The +vacuity line fires on either side whenever `--before` equals `--after` +without `--unchanged`. + +The helper does not know whether a file exists on the other side. A +step that creates or deletes a file runs only the side where the file +exists, with `0` as the absent side's number; the rule of Task 3 says +so, and the script needs nothing for it (spec round 2 ruling: "the +helper unchanged"). + +- [ ] **Step 1: Write the tests** + +`tests/working-process/test_phrase_check.py`, one `unittest.TestCase`. +Follow `test_decision_coverage.py`: `REPO = Path(__file__).resolve().parents[2]`, +`SCRIPT` under `plugins/working-process/scripts/`, each test in a +`tempfile.TemporaryDirectory`, the script run with +`subprocess.run([sys.executable, SCRIPT, *args], capture_output=True, text=True)`. +Two helpers: `write(name, content) -> str` (bytes when given bytes) +and `run(*args)`. Below, `B/A/S` abbreviates +`--before B --after A --side S`; "→ 0" is the exit code; quoted text +must appear in stdout. + +| Test | File content | Call | Asserts | +|---|---|---|---| +| `test_wrapped_phrase_counts` | `alpha beta\ngamma delta\n` | phrase `beta gamma`, 0/1/after | → 0, `actual: 1` | +| `test_capital_after_wrap` | `the quick\nBrown fox\n` | `quick brown`, 0/1/after | → 0, `actual: 1` | +| `test_doubled_whitespace` | `alpha \t beta\n` | `alpha beta`, then `alpha beta`, each 0/1/after | both → 0, `actual: 1` | +| `test_crlf_wrap_counts` | bytes `alpha\r\nbeta\r\n` | `alpha beta`, 0/1/after | → 0, `actual: 1` | +| `test_bom_does_not_hide_first_word` | bytes `\xef\xbb\xbfalpha beta\n` | `alpha beta`, 0/1/after | → 0, `actual: 1` | +| `test_list_and_quote_markers_dropped` | `- alpha\n beta\n> gamma\n> delta\n1. one\n two\n2) three\n* four\n+ five\n` | `alpha beta`; `gamma delta`; `one two three four five`; each 0/1/after | each → 0, `actual: 1` | +| `test_nested_markers_dropped` | `> - alpha\n> beta\n` | `alpha beta`, 0/1/after | → 0, `actual: 1` | +| `test_inline_markup_untouched` | `**alpha** beta\n---\n-dash\n# head\n` | `alpha beta`, 1/0/after; then `**alpha** beta --- -dash # head`, 0/1/after | both → 0; `actual: 0`, then `actual: 1` | +| `test_phrase_normalised_like_text` | `alpha beta\n` | `--phrase=- Alpha\n BETA` (a real newline), 0/1/after | → 0, `actual: 1` | +| `test_phrase_starting_with_hyphen` | `use --side here\n` | `--phrase=--side`, 0/1/after | → 0, `actual: 1` | +| `test_no_match_across_files` | `a.md`: `alpha\n`; `b.md`: `beta\n` | both paths, `alpha beta`, 1/0/after | → 0, `actual: 0` | +| `test_matches_do_not_overlap` | `aa aa aa\n`; then `ab ab ab ab\n` | `aa aa`, 0/1/after; `ab ab`, 0/2/after | → 0 `actual: 1`; → 0 `actual: 2` | +| `test_total_over_files_and_what_was_read` | `a.md`: `x\nalpha\n`; `b.md`: `alpha\nalpha\ny\n` | both paths, `alpha`, 0/3/after | → 0; first line `wp-phrase-check: PASS`; `expected: 3 (before 0, after 3)`; `actual: 3`; `read: files 2, lines 5`; a line ending `a.md: lines 2, matches 1`; one ending `b.md: lines 3, matches 2` | +| `test_same_path_twice_counts_twice` | `alpha\n` | the path twice, `alpha`, 0/2/after | → 0, `read: files 2, lines 2` | +| `test_empty_file_is_read` | empty | `alpha`, 1/0/after | → 0, `read: files 1, lines 0`, `actual: 0` | +| `test_side_selects_the_number` | `alpha\n` | `alpha`, 1/0/before; then 1/0/after | → 0; then → 1 with `fail: count mismatch: expected 0 on side after, found 1` | +| `test_mismatch_fails` | `alpha\n` | `alpha`, 0/2/after | → 1; first line `wp-phrase-check: FAIL`; `fail: count mismatch: expected 2 on side after, found 1` | +| `test_equal_counts_fail_unless_declared` | `alpha\n` | `alpha`, 1/1/before; 1/1/after; 1/1/after with `--unchanged` | → 1 with `fail: vacuous`; → 1 with `fail: vacuous`; → 0 with no `fail:` | +| `test_mismatch_reported_before_vacuity` | `alpha\n` | `alpha`, 2/2/after | → 1; stdout holds both `fail: count mismatch` and `fail: vacuous`, the first at the lower index | +| `test_missing_path_fails` | none | a path that does not exist, `alpha`, 1/0/after | → 1; `actual: not counted`; a `fail:` line ending `no such file`; no `fail: count mismatch` | +| `test_directory_fails` | none | the temporary directory itself, `alpha`, 1/0/after | → 1; a `fail:` line ending `not a file` | +| `test_invalid_utf8_fails` | bytes `\xff\xfe alpha\n` | `alpha`, 0/1/after | → 1; a `fail:` line ending `not valid UTF-8` | +| `test_unopenable_file_fails` | `alpha\n`, then `os.chmod(path, 0)` | `alpha`, 0/1/after | → 1; `fail:` line containing `cannot be read`. Skip when `os.name == "nt"` or `os.geteuid() == 0` | +| `test_one_bad_path_fails_the_run` | `a.md`: `alpha\n` | `a.md` and a missing path, `alpha`, 0/1/after | → 1; `actual: not counted`; `read: files 1, lines 1` | +| `test_no_path_fails` | none | no path, `alpha`, 1/0/after | → 1; `fail: read no file` | +| `test_blank_phrase_is_usage_error` | `alpha\n` | `--phrase= `, 0/1/after | → 2 | +| `test_negative_count_is_usage_error` | `alpha\n` | `alpha`, `--before=-1 --after 0 --side after` | → 2 | + +A missing or non-numeric `--before`, `--after` or `--side` gets no +test: `argparse` rejects it before the script's own code runs (spec +ledger, the dismissed gate line before round 2). + +- [ ] **Step 2: Observe the tests with the script absent** + +Run: `python3 -m unittest discover -s tests/working-process -p 'test_phrase_check.py'` + +Record in the report the summary line it prints and the first failure +or error in full. If the run ends `OK`, stop: `BLOCKED`. A file-level +failure here shows only that the tests reach for the script; Step 4 is +what shows each test can fail. + +- [ ] **Step 3: Write `plugins/working-process/scripts/phrase-check.py`** + +Shebang `#!/usr/bin/env python3`, a module docstring carrying the +usage line and the exit codes, the four functions of **Interfaces**, +`TOOL = "wp-phrase-check"` for the output's first line, and +`if __name__ == "__main__": sys.exit(main())`. Declare the paths as +`nargs="*"` so that no path reaches the script's own "read no file" +failure instead of an `argparse` error. The `--help` text says that a +phrase starting with a hyphen is written `--phrase=`. +`chmod +x` the file. + +- [ ] **Step 4: Run the tests, then show two of them can fail** + +Run: `python3 -m unittest discover -s tests/working-process -p 'test_phrase_check.py'` +Passes when the last line is `OK`. + +Then, twice, weaken the script and re-run the same command, recording +which tests fail each time, and restore the script after each: +(a) delete the marker pattern from `normalise`; (b) make the vacuity +reason never fire. If either weakening leaves the run `OK`, stop: +`BLOCKED`. Run the command once more after restoring; it ends `OK`. + +- [ ] **Step 5: Commit** + +```bash +git add plugins/working-process/scripts/phrase-check.py tests/working-process/test_phrase_check.py +git ls-files -s plugins/working-process/scripts/phrase-check.py +``` + +The second command's line starts `100755`. If it starts `100644`, run +`git update-index --chmod=+x plugins/working-process/scripts/phrase-check.py` +and check again. + +```bash +git commit -m "feat(working-process): phrase-check script for plan verification checks" +``` + +--- + +### Task 2: The launcher + +**Files:** +- Create: `plugins/working-process/bin/wp-phrase-check` +- Test: `tests/working-process/test_wp_phrase_check_launcher.py` + +**Interfaces:** +- Consumes: `scripts/phrase-check.py` and its command line (Task 1). +- Produces: the command `wp-phrase-check`, taking the script's + arguments unchanged and returning its exit code. With no usable + Python it exits `2` and prints one line on stderr: + + wp-phrase-check: no Python 3.9 or later found; tried: python3 (), python (), py -3 () + + where `` is `not found` or `rejected`. + +**Realizes:** D1, D5 + +**The contract the tests pin** + +- `#!/usr/bin/env bash`. The launcher resolves its own path from + `${BASH_SOURCE[0]}`, following symbolic links in a loop with + `readlink` and joining a relative target to the link's directory — + no `readlink -f` and no `realpath`, which stock macOS lacks. + Directory names come from parameter expansion and `cd … && pwd`, so + `readlink` is the only external command it calls. The script is + `/../scripts/phrase-check.py`; + `CLAUDE_PLUGIN_ROOT` is not read. +- Candidates, in order: `python3`, `python`, `py -3`. A candidate + whose first word `command -v` does not find is `not found`. One that + is found runs + `-c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)'` + with stdout and stderr discarded; a non-zero exit is `rejected`. + That one line is valid in Python 2, so an old interpreter answers + and is rejected, never run. +- The first accepted candidate is run with + `exec "${candidate[@]}" "$script" "$@"`, the candidate held as an + array so `py -3` stays two words. + +- [ ] **Step 1: Write the tests** + +`tests/working-process/test_wp_phrase_check_launcher.py`, one +`unittest.TestCase`, skipped whole when `os.name == "nt"`. Each test +builds a directory of stubs and runs +`subprocess.run([BASH, LAUNCHER, *args], env={"PATH": stub_dir}, capture_output=True, text=True)` +with `BASH = shutil.which("bash")`. The stub directory always holds a +symbolic link to the real `readlink` (`shutil.which("readlink")`) and +nothing else from the system, so no real interpreter is reachable. +Stubs are executable files starting `#!`: + +- *good*: `exec "$@"`; +- *old*: `if [ "$1" = "-c" ]; then exit 1; fi; echo WRONG-INTERPRETER; exit 0`; +- *good py*: `[ "$1" = "-3" ] || exit 9; shift; exec "$@"`. + +`PASSING` names the arguments of a run that passes: a temporary file +holding `alpha\n`, `--phrase alpha --before 0 --after 1 --side after`. + +| Test | Stubs | Call | Asserts | +|---|---|---|---| +| `test_python3_runs` | `python3` good | `PASSING` | → 0; stdout starts `wp-phrase-check: PASS` | +| `test_old_python3_is_skipped_for_python` | `python3` old, `python` good | `PASSING` | → 0; stdout starts `wp-phrase-check: PASS`; `WRONG-INTERPRETER` nowhere in stdout | +| `test_py_launcher_is_last_resort` | `py` good py | `PASSING` | → 0; stdout starts `wp-phrase-check: PASS` | +| `test_no_python_names_what_it_tried` | `python3` old | `PASSING` | → 2; stdout empty; stderr holds `python3 (rejected)`, `python (not found)` and `py -3 (not found)` | +| `test_exit_code_passes_through` | `python3` good | the same file, `--phrase alpha --before 0 --after 2 --side after` | → 1; stdout starts `wp-phrase-check: FAIL` | +| `test_symlinked_launcher_finds_script` | `python3` good | the launcher run through a symbolic link made in a second temporary directory, `PASSING` | → 0; stdout starts `wp-phrase-check: PASS` | +| `test_path_with_space_survives_launcher` | `python3` good | the file named `two words.md`, otherwise `PASSING` | → 0; a stdout line ending `two words.md: lines 1, matches 1` | + +- [ ] **Step 2: Observe the tests with the launcher absent** + +Run: `python3 -m unittest discover -s tests/working-process -p 'test_wp_phrase_check_launcher.py'` + +Record the summary line and the first failure or error in full. If the +run ends `OK`, stop: `BLOCKED`. + +- [ ] **Step 3: Write `plugins/working-process/bin/wp-phrase-check`** + +To the contract above; `chmod +x` it. Keep it short: resolve, try the +three candidates collecting each ``, `exec` the first accepted, +otherwise print the stderr line and `exit 2`. + +- [ ] **Step 4: Run the tests, then show the version test can fail** + +Run: `python3 -m unittest discover -s tests/working-process -p 'test_wp_phrase_check_launcher.py'` +Passes when the last line is `OK`. + +Then make the launcher accept every found candidate without the +version test, re-run, record which tests fail, and restore it. If the +run stays `OK`, stop: `BLOCKED`. Re-run after restoring; it ends `OK`. + +- [ ] **Step 5: Run the command by its checkout path** + +Run: `plugins/working-process/bin/wp-phrase-check README.md --phrase "Missing Bits" --before 2 --after 2 --unchanged --side after` + +Passes when it exits `0` and prints `wp-phrase-check: PASS` and +`actual: 2`. This is the first real run on this host; later tasks +depend on it. + +- [ ] **Step 6: Commit** + +```bash +git add plugins/working-process/bin/wp-phrase-check tests/working-process/test_wp_phrase_check_launcher.py +git ls-files -s plugins/working-process/bin/wp-phrase-check +``` + +The second command's line starts `100755`; otherwise run +`git update-index --chmod=+x plugins/working-process/bin/wp-phrase-check` +and check again. + +```bash +git commit -m "feat(working-process): wp-phrase-check launcher in the plugin bin" +``` + +--- + +### Task 3: The plan-authoring rule + +**Files:** +- Create: `plugins/working-process/rules/plan-authoring.md` + +**Realizes:** D6, D7, D9 + +- [ ] **Step 1: Write the rule** + +The file's whole content, verbatim. The `paths:` values are quoted +scalars; `claude plugin validate` does not read `rules/`, so read the +frontmatter by eye once written. + +`````markdown +--- +paths: + - "docs/plans/**" + - "docs/**/*-plan.md" +--- + +# Plan authoring — recurring defect classes + +A plan's verification steps keep failing in the same few ways. Read +this before the plan's first line is written, and ask each class's +question of every task before handing the plan on. The plan-adversary +agent, when available, reads the same text. + +## Seven classes + +1. **A check or test that cannot fail.** It passes whether or not the + step did its work: a test green without the change, a count equal + before and after, a search over a path that holds nothing. *What + does this print with the step undone?* +2. **An expected value fitted to the author's view.** The value was + read off the tree the author had open, while the check runs on the + tree the previous task leaves. *Did I compute it on that tree?* +3. **An anchor by line number.** A line number goes stale with the + first edit above it, an earlier task of the same plan included. + *Does the step find its place by text that will still be there?* +4. **A defect born of a repair.** A fix written between review rounds + gets less care than the first draft, and most late findings come + from one. *Have I re-run every check the fix touches?* +5. **A check of an artifact the consumer does not load.** The step + verifies the source while the consumer reads an installed, built or + cached copy. *Which file does the consumer open?* +6. **Fixes in one wave that undo each other.** One fix restores the + phrase another fix's check counts, or two rewrite one sentence. + *Does any fix in this wave change what another relies on?* +7. **The same discipline one site away.** A finding marks one site, + and its neighbours usually share the defect: the next task, the + sibling file, the other side of a pair. *Where else does the rule + I just applied hold?* + +## A failing test is observed, never predicted + +A plan never states the message a failing test will print. It +prescribes the observation: run the test with the change absent — +before the change is written, or with it reverted — record what the +run prints in the implementer's report, and restore the change where +it was reverted. The plan stays as approved. A test that passes with +the change absent proves nothing, and the task stops as blocked: an +implementer reports its execution skill's blocked status (`BLOCKED` in +superpowers' subagent-driven-development skill, when available), and a +session executing the plan itself stops and reports to the developer. + +## Writing a verification check + +When the `wp-phrase-check` command is available — the working-process +plugin puts it on the Bash tool's `PATH` while enabled — every +verification check over text takes its form: + + wp-phrase-check ... --phrase "" --before --after --side before|after + +It joins lines, collapses whitespace, ignores case and drops a line's +leading list or quote marker, and it prints the expected count, the +actual count and what it read. Without the command, normalise by hand +— `tr -s '[:space:]' ' '`, then a case-insensitive count — and state +both numbers beside the check. + +The command cannot enforce the rest: + +- Run the check on each side of its step, the two calls identical but + for `--side`. +- Give a file the step creates or deletes a check of its own, run only + on the side where the file exists; the absent side's number is `0`. +- State the change the step makes, as the before/after pair, never a + total fitted to the file as the author found it. +- Write a check that correct text can satisfy. When satisfying a check + forces an odd edit, the check is the defect. +- Pass `--unchanged` only to state that the step leaves the phrase as + it is; equal numbers without it fail. + +Classes 2 and 3 bind every check as well and are stated once, above. +````` + +What the text settles, for the reviewer of this plan: + +- The seven classes are D9's, in D9's order, each with its question. +- Classes 2 and 3 are also two of the spec's five check-writing + items. Each is stated once, as a class; the check-writing list + carries the other three and points back. +- "Blocked" is `BLOCKED` in superpowers:subagent-driven-development + and, inline, a stop reported to the developer. +- The command is named conditionally. Without it the author + normalises by hand and states both numbers. +- The created-or-deleted-file case of D4 lives here, in the second + check-writing item; the command takes no argument for it. + +- [ ] **Step 2: Verify the rule, after side only (the step created the file)** + +```bash +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "Plan authoring — recurring defect classes" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "docs/**/*-plan.md" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "never states the message" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "stops as blocked" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "wp-phrase-check" --before 0 --after 2 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "absent side's number" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/plan-authoring.md --phrase "checklist" --before 0 --after 0 --unchanged --side after +``` + +Each exits `0`. The last one states D8's ban on the word in this rule: +the count stays zero by declaration. Then the seven class names, one +call each, every one expecting `--before 0 --after 1 --side after` on +the same file: `cannot fail`, `fitted to the author's view`, +`anchor by line number`, `born of a repair`, +`the consumer does not load`, `undo each other`, `one site away`. + +Run: `wc -l < plugins/working-process/rules/plan-authoring.md` +Passes when it prints `79`; the spec's size target is under 80. + +Run: `sh plugins/working-process/scripts/ruleset-hash.sh --list plugins/working-process/rules | grep -c 'plan-authoring.md'` +Passes when it prints `1`: the listing is what `sync-rules` installs +from. Before this task the same command printed `0`. + +- [ ] **Step 3: Commit** + +```bash +git add plugins/working-process/rules/plan-authoring.md +git commit -m "feat(working-process): plan-authoring rule with the recurring defect classes" +``` + +--- + +### Task 4: The two reads — adversary card and workflow step 4 + +**Files:** +- Modify: `plugins/working-process/agents/plan-adversary.md` (the + FIRST ACTION paragraph) +- Modify: `plugins/working-process/rules/workflow.md` (step 4, the + paragraph beginning `Then write the`) + +**Realizes:** D8, D10 + +- [ ] **Step 1: Run the before side** + +```bash +plugins/working-process/bin/wp-phrase-check plugins/working-process/agents/plan-adversary.md --phrase "rules/plan-authoring.md" --before 0 --after 1 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/agents/plan-adversary.md --phrase "(evidence = that file)." --before 1 --after 1 --unchanged --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/workflow.md --phrase "plan-authoring rule" --before 0 --after 2 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/workflow.md --phrase "requires reading it before the plan is written" --before 1 --after 0 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/workflow.md --phrase "superpowers:writing-plans when available" --before 1 --after 1 --unchanged --side before +``` + +Each exits `0`. A non-zero exit here means the tree is not the one +this plan was written against: stop and report. + +- [ ] **Step 2: Edit the card** + +In `plugins/working-process/agents/plan-adversary.md`, the FIRST +ACTION paragraph ends `(evidence = that file).` Leave it as it is and +add, after one blank line, this paragraph: + +```markdown +Then read `${CLAUDE_PLUGIN_ROOT}/rules/plan-authoring.md`, "Plan +authoring — recurring defect classes": the text the plan's author +wrote from. A step that shows one of its seven classes, predicts the +message a failing test prints, or breaks one of its check-writing +rules is a finding (evidence = the plan quote and that rule's +heading). +``` + +The card's `description:` stays as it is; no severity is assigned, so +the card's generic scale grades the finding. + +- [ ] **Step 3: Edit `workflow.md` step 4** + +Replace the paragraph of step 4 that begins `Then write the` and ends +`context cannot count on it loading.` with this one, keeping the +three-space indent of the step's other paragraphs: + +```markdown + Before the plan's first line is written, whoever writes it — the + session or a separate context — reads the plan-authoring rule, + installed beside this one: a path-scoped rule loads only when a + matching file is read, and a new plan has none yet. Then write the + implementation plan with superpowers:writing-plans when available; + plans live in `docs/plans/` (or the ticket directory, below). A + brief that delegates plan-writing to a separate context names the + spec-plan-lifecycle rule and the plan-authoring rule and requires + reading both before the plan is written: the first carries the + annotations a plan owes a registered design spec, the second the + recurring defect classes and the check-writing rules, and a + separate context cannot count on either loading. +``` + +The lifecycle rule's sentence "as the workflow rule's step 4 says" +stays true and is not edited. + +- [ ] **Step 4: Run the after side** + +```bash +plugins/working-process/bin/wp-phrase-check plugins/working-process/agents/plan-adversary.md --phrase "rules/plan-authoring.md" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/agents/plan-adversary.md --phrase "(evidence = that file)." --before 1 --after 1 --unchanged --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/workflow.md --phrase "plan-authoring rule" --before 0 --after 2 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/workflow.md --phrase "requires reading it before the plan is written" --before 1 --after 0 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/rules/workflow.md --phrase "superpowers:writing-plans when available" --before 1 --after 1 --unchanged --side after +``` + +Each exits `0`. + +Run: `claude plugin validate plugins/working-process` +Passes when it reports the plugin valid; the card's frontmatter was +not touched, and this shows it still parses. + +- [ ] **Step 5: Commit** + +```bash +git add plugins/working-process/agents/plan-adversary.md plugins/working-process/rules/workflow.md +git commit -m "feat(working-process): plan-writing and the plan-adversary read the plan-authoring rule" +``` + +--- + +### Task 5: README, identity surfaces, changelog, dogfood version + +**Files:** +- Modify: `plugins/working-process/README.md` +- Modify: `plugins/working-process/CHANGELOG.md` +- Modify: `plugins/working-process/.claude-plugin/plugin.json` +- Modify: `.claude-plugin/marketplace.json` +- Modify: `README.md` + +**Realizes:** D11 + +- [ ] **Step 1: Derive the dogfood counter from develop** + +```bash +git log develop -p --format= -- plugins/working-process/.claude-plugin/plugin.json | grep -o '^+.*-dev\.[0-9]*\.' | grep -o '[0-9]*\.$' | sort -n | tail -1 +``` + +Written against a develop on which this prints `9.`, so the version is +`0.20.0-dev.10.plan-quality`: one above the highest counter in +develop's history, on the version develop already carries above the +released `0.19.0`, with the branch short-name as discriminator. If it +prints another number, use that number plus one in Step 3 and in both +runs of the version check, and say so in the report. + +- [ ] **Step 2: Run the before side** + +```bash +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "wp-phrase-check" --before 0 --after 2 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "eight rule files" --before 1 --after 0 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "nine rule files" --before 0 --after 1 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "plan-authoring.md" --before 0 --after 1 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "claude.ai or Cowork" --before 0 --after 1 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "for the propagation auditor's coverage duty." --before 1 --after 0 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/CHANGELOG.md --phrase "wp-phrase-check" --before 0 --after 1 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/CHANGELOG.md --phrase "plan-authoring.md" --before 0 --after 1 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/.claude-plugin/plugin.json .claude-plugin/marketplace.json README.md --phrase "wp-phrase-check" --before 0 --after 3 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/.claude-plugin/plugin.json --phrase "0.20.0-dev.9.process-context" --before 1 --after 0 --side before +plugins/working-process/bin/wp-phrase-check plugins/working-process/.claude-plugin/plugin.json --phrase "0.20.0-dev.10.plan-quality" --before 0 --after 1 --side before +``` + +Each exits `0`; a non-zero exit means the tree differs from the one +this plan was written against: stop and report. + +- [ ] **Step 3: Edit the plugin README** + +Four edits in `plugins/working-process/README.md`. + +(a) *Components*: after the `sync-rules` skill's bullet, which ends +`"Process rules" section.`, add: + +```markdown +- **`wp-phrase-check` command** — a plan's verification check over + text. It counts a phrase after joining lines, collapsing whitespace, + ignoring case and dropping list and quote markers, verifies the count + against the number its side expects, and fails a check that could + not show its step did anything. It ships in `bin/`, which Claude + Code puts on the Bash tool's `PATH` while the plugin is enabled. +``` + +(b) *Requirements*: after the first bullet, which ends +`alone work on ≥ 2.1.143).`, add: + +```markdown +- Claude Code itself, not claude.ai or Cowork: the plugin ships a + top-level `bin/`, and a plugin that has one does not install there. +``` + +and replace the bullet that ends +`for the propagation auditor's coverage duty.` with: + +```markdown +- Python 3.9 or later, standard library only. `wp-phrase-check` finds + it as `python3`, `python` or `py -3`, in that order, and confirms + each by its version; the propagation auditor's coverage duty calls + `python3`. +``` + +(c) *Process rules*: `eight rule files` becomes `nine rule files`, +and the clause ending `plan or domain document is open), and the` +becomes `plan or domain document is open), the recurring defect +classes a plan's author reads (`plan-authoring.md`, loaded while a +plan is open), and the` — re-wrap the paragraph as the file wraps. + +(d) *Reducing permission prompts* stays as it is: the helper runs +under the user's permission mode, as superpowers' scripts do (spec, +non-goals; developer's ruling 2026-11-16). + +- [ ] **Step 4: Edit the changelog, the identity surfaces and the version** + +`plugins/working-process/CHANGELOG.md`: append to the `## Unreleased` +section, directly before the `## 0.19.0 — 2026-11-13` heading: + +```markdown +- `wp-phrase-check`, a command the plugin puts on the Bash tool's + `PATH`: a plan's verification check over text, counting a phrase + whatever the file's wrapping, case or whitespace. Each run names its + side, prints the expected count, the actual count and what it read, + and fails on a mismatch, a missing or unreadable path, a run that + read no file, or equal before and after counts not declared + unchanged. A bash launcher finds Python 3.9 or later as `python3`, + `python` or `py -3`. +- A new rule, `plan-authoring.md`, loaded while a plan is open: seven + recurring defect classes, the rule that a plan prescribes observing + a failing test and never predicts its message, and the check-writing + rules. Plan-writing reads it before the plan's first line, and the + plan-adversary reads the shipped copy. +- The plugin now needs Claude Code itself: with a top-level `bin/` it + does not install on claude.ai or in Cowork. +``` + +The three descriptions gain the command, in one commit, each after the +words `integrity-auditor audit agents,`: + +- `plugins/working-process/.claude-plugin/plugin.json`: + `…audit agents, the wp-phrase-check command for a plan's + verification checks over text, and process rules distributed as a + Rules payload; …` — and `"version"` becomes + `"0.20.0-dev.10.plan-quality"`. +- `.claude-plugin/marketplace.json`: + `…audit agents, the wp-phrase-check command, plus distributed + process rules`. +- `README.md`, the `working-process` row: + ``…audit agents, the `wp-phrase-check` command, distributed process + rules``. + +Each JSON description stays one line. + +- [ ] **Step 5: Run the after side** + +```bash +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "wp-phrase-check" --before 0 --after 2 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "eight rule files" --before 1 --after 0 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "nine rule files" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "plan-authoring.md" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "claude.ai or Cowork" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/README.md --phrase "for the propagation auditor's coverage duty." --before 1 --after 0 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/CHANGELOG.md --phrase "wp-phrase-check" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/CHANGELOG.md --phrase "plan-authoring.md" --before 0 --after 1 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/.claude-plugin/plugin.json .claude-plugin/marketplace.json README.md --phrase "wp-phrase-check" --before 0 --after 3 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/.claude-plugin/plugin.json --phrase "0.20.0-dev.9.process-context" --before 1 --after 0 --side after +plugins/working-process/bin/wp-phrase-check plugins/working-process/.claude-plugin/plugin.json --phrase "0.20.0-dev.10.plan-quality" --before 0 --after 1 --side after +``` + +Each exits `0`. + +Run: `ls plugins/working-process/rules/*.md | wc -l` +Passes when it prints `9`, the number the README now states. + +Run: `python3 -c "import json; json.load(open('plugins/working-process/.claude-plugin/plugin.json')); json.load(open('.claude-plugin/marketplace.json')); print('ok')"` +Passes when it prints `ok`. + +- [ ] **Step 6: Commit** + +```bash +git add plugins/working-process/README.md plugins/working-process/CHANGELOG.md plugins/working-process/.claude-plugin/plugin.json .claude-plugin/marketplace.json README.md +git commit -m "docs(working-process): wp-phrase-check and plan-authoring in README, catalog and changelog" +``` + +--- + +### Task 6: Final verification + +**Files:** none changed. A defect found here goes back to the task +that owns the file. + +**Realizes:** D1, D7 + +- [ ] **Step 1: The whole suite, once** + +Run: `python3 -m unittest discover -s tests/working-process` +Passes when the last line is `OK`. The count is the 77 tests develop +carries plus the 27 of Task 1 and the 7 of Task 2: `Ran 111 tests`. +Another count means a test was added, dropped or not collected: find +which before going on. + +- [ ] **Step 2: Validate** + +Run: `claude plugin validate .` +Run: `claude plugin validate plugins/working-process` +Each passes when it reports no error. + +- [ ] **Step 3: Hygiene over the new files, by the command itself** + +```bash +plugins/working-process/bin/wp-phrase-check plugins/working-process/bin/wp-phrase-check plugins/working-process/scripts/phrase-check.py plugins/working-process/rules/plan-authoring.md tests/working-process/test_phrase_check.py tests/working-process/test_wp_phrase_check_launcher.py --phrase "/home/" --before 0 --after 0 --unchanged --side after +``` + +Passes when it exits `0` and its `read:` line says `files 5`. + +- [ ] **Step 4: Both files carry the executable bit in git** + +Run: `git ls-files -s plugins/working-process/bin/wp-phrase-check plugins/working-process/scripts/phrase-check.py` +Passes when both lines start `100755`. + +- [ ] **Step 5: A live session and a subagent run the command by name** + +Executor: the controlling session, with the developer's go-ahead — +the step disables the installed `working-process` plugin while it +runs, so the checkout's copy loads without a name collision. Never +leave it disabled. + +First observe the absent state: in a shell where the checkout's `bin/` +is not on `PATH`, run `wp-phrase-check --help` and record what it +prints. + +```bash +claude plugin disable working-process +claude -p "Run this exact command with the Bash tool and print its output verbatim under the label SESSION: wp-phrase-check README.md --phrase wp-phrase-check --before 0 --after 1 --side after. Then dispatch one general-purpose subagent, tell it to run the same command with its Bash tool and return the output verbatim, and print what it returns under the label SUBAGENT." --plugin-dir plugins/working-process --allowedTools "Bash(wp-phrase-check *)" "Agent" "Task" +claude plugin enable working-process +``` + +Passes when the output holds `wp-phrase-check: PASS` and `actual: 1` +under both labels. A `command not found`, or a subagent that could not +run the command, fails the step: report it with the output, since D1 +rests on this. Run `claude plugin list` afterwards and confirm +`working-process` is enabled. + +- [ ] **Step 6: The rule installs — developer step, STOP** + +Once the dogfood version is installed on the developer's host, the +developer runs the `working-process:sync-rules` skill and confirms +that `plan-authoring.md` lands in the rules target. The session does +not write to the user-level rules directory unasked. Until then the +`ruleset-hash.sh --list` result of Task 3 is the evidence that the +payload carries the file. + +- [ ] **Step 7: Report** + +The closing report carries: every recorded red observation (Tasks 1 +and 2, and Step 5's absent state), the two weakening runs of Task 1 +and the one of Task 2, the derived dogfood counter, the live check's +two outputs, and what was not checked — the Windows store placeholder +(an accepted risk of the spec) and any Claude Code version floor for a +plugin's `bin/`. + +## Review rounds + +Gate lines from the pre-round propagation episode, 2026-11-16 (haiku). The episode held hits, so they stay here, before the first round heading. + +- hit fixed 2026-11-16 — Task 5 Step 5 expected `wp-phrase-check` 4 times in the plugin README after the edit; dropping the permission entry left 2; now 2 +- hit fixed 2026-11-16 — "the dismissed hit" put a Hit in view of the plan's bare "check"; now "the dismissed gate line" + +Both fixes change one value and one word; the episode was not re-dispatched over them, and the first adversary round reads the whole plan. + +### 2026-11-16 — plan-adversary, opus 5.5, concerns (round 1, full-document) + +Record: `.claude/working-process/2026-11-16-plan-quality-plan/plan-adversary-round-1.md`. + +- fixed 2026-11-16 — [Minor] Task 5 Steps 2 and 5 carried different `--after` values for one check after the gate fix touched Step 5 only; license: Global Constraints, "the two calls identical but for `--side`"; Step 2 now `--after 2` +- fixed 2026-11-16 — [Minor] a phrase opening with a list or quote marker loses it under normalisation; provisional: 2026-11-16 (stand-in session); accepted as a documented limitation under *Review Focus*, no script option +- signal 2026-11-16 — both findings Minor with one-line fixes; another round would not earn its cost + +The round was full-document, so it closes the loop: `concerns` is resolved by the two fixes above under the developer's standing instruction of 2026-11-16 to carry the work through implementation without asking unless a decision is genuinely theirs. diff --git a/docs/plans/2026-11-16-process-context-plan.md b/docs/plans/2026-11-16-process-context-plan.md new file mode 100644 index 0000000..5a8afb9 --- /dev/null +++ b/docs/plans/2026-11-16-process-context-plan.md @@ -0,0 +1,908 @@ +--- +ticket: none +date: 2026-11-16 +status: implemented +spec: ../specs/2026-11-16-process-context-spec.md +branch: feature/process-context +base: develop +adversary: concerns (resolved 2026-11-16) +--- + +# Process Context Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Move the dispatcher's procedure, the disposition ledger, the +Unfinished-work list and the per-round commit convention out of the two +large rules into skill reference files, and leave pointers behind. + +**Architecture:** Each moved text is extracted verbatim from the +merge base into a reference file, checked with a whitespace-normalised `diff`, and only +then has its pointers rewritten, so the rewrite is the whole visible +change. The sources are cut afterwards, one rule per task, and every +pointer into moved text is rewritten from the inventory below. + +**Tech Stack:** Markdown, `bash`, `git`, `sed`, `grep`, `diff`, `wc`, +Python `unittest`, the `claude` CLI. + +**Spec:** `docs/specs/2026-11-16-process-context-spec.md` + +## Global Constraints + +- **Realizes:** D1 — every moved text lands in the home its reader + needs: always loaded (`workflow.md`), with a document class + (`spec-plan-lifecycle.md`), or read when an activity starts (a skill). + No task puts text in a fourth place. +- **Realizes:** D9 — text read when an activity starts lives in a skill + directory under `plugins/working-process/skills/`. No file is added to + or removed from `plugins/working-process/rules/`. +- **Realizes:** D11 — in an installed rule, a pointer to skill text + names the skill and its reference, conditionally, and never a path or + a file name: "the `review-loop` skill's procedure reference, when that + skill is available", "its ledger reference", "the `process-status` + skill's Unfinished-work reference". +- **Realizes:** D12 — text that moves whole moves unchanged but for the + pointer rewrites this plan lists. Each extraction is checked with an + empty `diff` before any rewrite; a difference this plan does not list + is a defect. +- **Realizes:** D13 — `## Ticket directories` and `### Moving a document + into a ticket directory` stay in `spec-plan-lifecycle.md`, untouched. +- No rule text changes meaning. A cut sentence moves to a named home or + repeats text that stays; nothing leaves with its decision. +- No loader, hook or settings key is added. `sync-rules` is not edited. +- Pointer forms outside installed rules: `SKILL.md` and agent cards use + `${CLAUDE_PLUGIN_ROOT}/skills//.md`; a reference file + names a sibling as "`LEDGER.md`, beside this file" and another skill's + reference by skill and file name, since `${CLAUDE_PLUGIN_ROOT}` is + substituted in skill and agent content, not in a file a session reads + later; the registry keeps its `plugins/`-relative path. +- A mention is not a pointer. "The provisional batch", "a `hit held` + line", "an Unfinished-work entry" name things and stay as written; a + pointer says where a text lives ("the workflow rule defines", "below", + "above") and is rewritten. +- Glossary bans bind: no unqualified "probe" (write "measurement"), no + bare "pair" where a pair offer is in view (write "audit pair" or "pair + offer"). +- English only, no machine paths, no company names. Commit messages are + one-line conventional commits with no body and no trailer; commit only + where the developer has authorized commits for this execution. +- No agent creates `evals/trigger-evals.json`. +- Run every command with `bash` from the repository root: `rg` is not on + this plan's assumed path, and an interactive shell may alias `grep`. +- Every size is reported beside its estimate. A miss is reported, never + a failure. + +## Review Focus + +- A session with the new plugin and unsynced old rules holds both + copies; the skill's description must trigger alone. Task 1 pins the + four read moments in the description. +- A session with the new rules and no plugin meets pointers to a skill + it lacks; every pointer must be conditional. Tasks 2 and 3 grep for + the conditional on each pointer line. +- After a compaction only `SKILL.md` returns; it must tell the session + to invoke the skill again and re-read the references. Task 1 pins the + sentence. +- A reviewer dispatched on a document with `## Review rounds` no longer + receives the ledger grammar; the brief must carry the reference's + path. Task 1 pins the sentence in `SKILL.md`. +- `process-status` must still fail loudly when it cannot read its list. + Task 4 keeps the skill's failure rule and checks the heading it keys + on. + +## Settled questions + +1. **Steps cut.** Step 3 loses its gate sentence and its "definition + below" clause (Task 2, Step 3). Step 4 loses its sequencing, which + moves; its two sentences repeating the lifecycle rule stay, since + that rule is not loaded when the offer is accepted. Steps 1, 2, 5 + and 7 lose nothing: none of their sentences has a named home or a + repeat in kept text. The projected `workflow.md` is about 19,500 + characters against the 15,000 estimate; the developer accepted the + miss on 2026-11-16, and it is reported, not closed. +2. **Step 4.** The offer is base lines 45–113 and 131–137. The + sequencing is base lines 115–130 and moves to `PROCEDURE.md`. The + delegated plan-writer sentence (133–137) stays in step 4, so the + lifecycle rule's "as the workflow rule's step 4 says" resolves + unedited. +3. **Reference names.** `skills/review-loop/PROCEDURE.md`, + `skills/review-loop/LEDGER.md`, + `skills/process-status/UNFINISHED-WORK.md` — upper case, beside + `SKILL.md`, as `grilling-session` names its own. Step 4's sequencing, + the per-round commit convention and the relay-then-stamp sentence all + go to `PROCEDURE.md`. +4. **Per-round convention.** It is lifecycle base lines 987–1045, from + "Asking whether the loop may commit per round" to "where no sha + exists." Afterwards the lifecycle rule cites neither + `review.per-round-commit` nor `docs-branch.merge`, and the registry + names `PROCEDURE.md` for both and for `review.autonomy`. +5. **Routing.** Verdict dispatch: both references. Consumption gate: + both. `status` move: `PROCEDURE.md`. Ledger line: `LEDGER.md`. +6. **"Both audits offered above…"** stays in `workflow.md`; its reader + may dispatch an audit outside the four moments. Its pointer is + rewritten. +7. **Pointer forms.** See Global Constraints. +8. **The heading.** `UNFINISHED-WORK.md` keeps `## Unfinished-work + list`, and `process-status` still keys on it. The sentence "the + heading and the skill move together or not at all" moves with the + section, unchanged and still true. Nothing replaces it in the + lifecycle rule. +9. **Pointer sentences.** One per skill. `workflow.md` gets one for + `review-loop` and one for the Unfinished-work reference. +10. **"Edited together."** Written once, as the closing sentence of + `review-loop/SKILL.md`. +11. **Live checks.** Task 7, Step 5, after the developer installs the + dogfood version and syncs the rules: one context measurement per + document class, one `process-status` run, one `review-loop` trigger + check. A miss is reported, never a failure. + +## Pointer inventory + +Line numbers are at the merge base +(`BASE=$(git merge-base HEAD develop)`). Each task anchors its edit on +the quoted text, since earlier tasks shift lines. Every bash block +assumes `BASE`, `W` and `L` as Task 1 Step 1 sets them; a fresh shell +sets all three again first. Rows match by the listed line, not by +text alone: W783 carries the same words as the W508 row and stays. + +`plugins/working-process/rules/workflow.md`, kept text: + +| Line | Pointer | Becomes | +|---|---|---| +| 37 | "the verdict-agent dispatch subsection below" | Task 2, Step 3 | +| 39–44 | "the dispatch subsection below defines the gate"; "the definition below" | cut, Task 2, Step 3 | +| 53–57 | "the verdict-agent dispatch subsection defines" | procedure reference | +| 129 | "the propagation gate below" | moves with 115–130 | +| 140–141 | "the verdict-agent dispatch subsection below" | procedure reference | +| 150–151 | "*The stand-in and the provisional batch* below" | procedure reference | +| 155–156 | "the dispatch-record store's `.gitignore` guard" | stated inline | +| 184–185 | "the verdict-agent dispatch subsection already defines" | procedure reference | +| 230–232 | "the two the verdict-agent dispatch subsection defines" | stated inline | +| 300–301 | "which the spec-plan-lifecycle rule names" | procedure reference | + +Examined and left: 10, 133 and 200 ("below", kept targets); 52, 134, +178, 203 and 210 (lifecycle text that stays); 158, 281–283 (mentions). + +`plugins/working-process/rules/spec-plan-lifecycle.md`, kept text: + +| Line | Pointer | Becomes | +|---|---|---| +| 54 | "the provisional batch the workflow rule defines" | procedure reference | +| 167 | "the list below" | "the Unfinished-work list" | + +Examined and left: 92 and 452 (workflow text that stays); 65–66, 83, +151, 189, 357, 360, 466, 930, 943–946 (mentions). + +Other files: + +| File and line | Pointer | Action | +|---|---|---| +| `skills/process-status/SKILL.md:8–11, 15–19` | the lifecycle rule's section | Task 4 | +| `skills/grilling-session/SKILL.md:60` | "the lifecycle rule's Unfinished-work list" | Task 5 | +| `README.md:93` (plugin) | "the lifecycle rule publishes" | Task 5 | +| `README.md:162` (plugin) | "section of the lifecycle rule" | Task 5 | +| `README.md:214–217` (plugin) | "relay-then-stamp sequence … in the workflow rule" | Task 5 | +| `SETTINGS_REGISTRY.md:106, 122, 130` | `read-by:` | Tasks 2 and 3 | +| `docs/domain/glossary.md:451` | "section of the spec-plan-lifecycle rule" | Task 5 | + +Examined and left: `PERSONA_COMMON.md:87, 123` and both consult cards +(the consultation paragraphs stay); `README.md:74, 206, 288–290` +(plugin); `agents/plan-adversary.md:53`, `agents/integrity-auditor.md:64`, +`agents/propagation-auditor.md:153, 189–191` (mentions, or +*Decision register* and *Plan annotations*, which stay); +`rules/review-reports.md:42`, `rules/ticket-frontmatter.md:58` +(*Branch naming* stays); `rules/technical-design.md:34` (resolves +through the lifecycle rule's kept bullet and its new pointer paragraph); +`scripts/decision-coverage.py:6`; the glossary's **Disposition ledger**, +**Round heading**, **Gate line** and **Document branch** entries, which +name no home. + +Pointers inside moved text are listed in the task that moves it. + +--- + +### Task 1: The `review-loop` skill + +**Files:** +- Create: `plugins/working-process/skills/review-loop/SKILL.md` +- Create: `plugins/working-process/skills/review-loop/PROCEDURE.md` +- Create: `plugins/working-process/skills/review-loop/LEDGER.md` + +**Interfaces:** +- Produces: the skill name `review-loop`; the reference names + `PROCEDURE.md` and `LEDGER.md`; the `PROCEDURE.md` headings + `### The audit pair at the consumption gate` and + `### Per-round commits on a document branch`. + +**Realizes:** D3, D4, D6, D10 + +- [ ] **Step 1: Confirm the anchors** + +```bash +BASE=$(git merge-base HEAD develop) +W=plugins/working-process/rules/workflow.md +L=plugins/working-process/rules/spec-plan-lifecycle.md +git show $BASE:$W | sed -n '115p;130p;322p;868p' | cut -c1-40 +git show $BASE:$L | sed -n '470p;807p;914p;925p;987p;1045p' | cut -c1-40 +``` + +Expected, in order: ` Where the technical-design offer is accep`, +` has passed, leaving no confirmed hit, w`, +`## Dispatching a verdict agent`, +`` The `## Dispatching a verdict agent` secti``, +`## The disposition ledger`, +`State prevents relitigation, not the rev`, +`close, resolved entries sweep to the arc`, `full-document round.`, +`Asking whether the loop may commit per r`, `path, where no sha exists.` +A mismatch stops the task: the base moved. + +- [ ] **Step 2: Extract the two references** + +```bash +D=plugins/working-process/skills/review-loop; mkdir -p $D +{ printf '# review-loop — the dispatcher'\''s procedure\n\n' + git show $BASE:$W | sed -n '322,867p' + git show $BASE:$L | sed -n '914,925p' | sed '1s/^.*archive\. //' + printf '\n### The audit pair at the consumption gate\n\n' + git show $BASE:$W | sed -n '115,130p' | sed 's/^ //' + printf '\n### Per-round commits on a document branch\n\n' + git show $BASE:$L | sed -n '987,1045p' +} > $D/PROCEDURE.md +{ printf '# review-loop — the ledger grammar\n\n' + git show $BASE:$L | sed -n '470,807p' +} > $D/LEDGER.md +``` + +- [ ] **Step 3: Verify the extraction is verbatim** + +```bash +norm() { tr -s '[:space:]' '\n' | sed '/^$/d'; } +diff <(grep -v -e '^# review-loop' -e '^### The audit pair at' -e '^### Per-round commits on' $D/PROCEDURE.md | norm) \ + <({ git show $BASE:$W | sed -n '322,867p'; git show $BASE:$L | sed -n '914,925p' | sed '1s/^.*archive\. //' + git show $BASE:$W | sed -n '115,130p'; git show $BASE:$L | sed -n '987,1045p'; } | norm) +diff <(sed '1,2d' $D/LEDGER.md | norm) <(git show $BASE:$L | sed -n '470,807p' | norm) +``` + +Expected: no output from either `diff`. Commit here where authorized +(`feat(working-process): review-loop references, extracted verbatim`), +so the next step's diff shows the rewrites alone. + +- [ ] **Step 4: Rewrite the pointers in `PROCEDURE.md`** + +Each row is one edit. Find the quoted phrase at the listed line by its +words: it may wrap onto the next line, and the same words elsewhere are +not this row's. + +| Base line | Text | Becomes | +|---|---|---| +| W451 | "the round record the lifecycle rule defines" | "the round record `LEDGER.md`, beside this file, defines" | +| W490 | "the lifecycle rule's per-round commits" | "the per-round commits defined under *Per-round commits on a document branch* below" | +| W508, 533, 661, 670, 708, 740, 829 | "the spec-plan-lifecycle rule defines" | "`LEDGER.md` defines" | +| W644–645 | "The spec-plan-lifecycle rule defines" (wraps after "The") | "`LEDGER.md` defines" | +| W790 | "the spec-plan-lifecycle rule owns it" | "`LEDGER.md` owns it" | +| W592 | "step 6 describes" | "the workflow rule's step 6 describes" | +| W797–799 | "the drop-or-wait question above" | "the drop-or-wait question the workflow rule's model selection asks" | +| L916–918 | "this sentence and the workflow rule's verdict-agent dispatch subsection state the same relay-before-stamp ordering and are edited together when that changes" | "this sentence and the bullet list under *Dispatching a verdict agent* above state the same relay-before-stamp ordering" | +| L919 | "The subsection sequences" | "That list sequences" | +| L922–923 | "defined in that subsection" | "defined under *What a diff-scoped LGTM certifies* above" | +| W129 | "the propagation gate below" | "the propagation gate above" | +| L987 | "is not that suggestion" | "is not the lifecycle rule's commit suggestion" | +| L988–989 | "The suggestion above says" | "That suggestion says" | +| L991–992 | "exactly as this paragraph describes it" | "exactly as that rule describes it" | +| L996 | "as the workflow rule's review loop says" | "as *The review loop* above says" | +| L998 | "One shape of that sooner call" | "One shape of the sooner commit the lifecycle rule leaves to the developer" | + +W783 ("the resolution annotation the spec-plan-lifecycle rule defines"), +W332 and W343 stay: their targets stay in the lifecycle rule. Base lines +868–873, the promise to edit two homes together, are not carried: the +spec ends that promise (*The dispatcher's procedure*), and the moved +sentence takes the paragraph's place. + +- [ ] **Step 5: Rewrite the pointers in `LEDGER.md`** + +| Base line | Text | Becomes | +|---|---|---| +| L580 | "the case the workflow rule names" | "the case `PROCEDURE.md`, beside this file, names" | +| L588 | "the resolution annotation above already owes" | "the resolution annotation the spec-plan-lifecycle rule already owes" | +| L661 | "the Chain debt entry's owner leg" | "the owner leg of the Chain debt entry, in the `process-status` skill's `UNFINISHED-WORK.md`," | +| L691 | "The workflow rule owns the ask" | "`PROCEDURE.md` owns the ask" | +| L708 | "the one exception the workflow rule makes" | "the one exception `PROCEDURE.md` makes" | +| L769 | "bound in the workflow rule" | "bound in `PROCEDURE.md`" | +| L773 | "the workflow rule's report" | "the report `PROCEDURE.md` prescribes" | + +- [ ] **Step 6: Verify the rewrites** + +```bash +grep -c 'subsection' $D/PROCEDURE.md # 0 +grep -c 'workflow rule' $D/PROCEDURE.md # 2 (step 6, model selection) +grep -c 'spec-plan-lifecycle rule' $D/PROCEDURE.md # 1 (resolution annotation) +grep -c 'LEDGER.md' $D/PROCEDURE.md # 10 or more +grep -c 'workflow rule' $D/LEDGER.md # 0 +grep -c 'annotation above' $D/LEDGER.md # 0 +grep -c 'edited together' $D/PROCEDURE.md # 0 +diff <(git show $BASE:$W | sed -n '322,867p') <(sed -n '/^## Dispatching a verdict agent/,$p' $D/PROCEDURE.md | sed '/^### The audit pair at/,$d') # every hunk is a row above; works whether or not Step 3 was committed +``` + +- [ ] **Step 7: Write `SKILL.md`** + +Author it with the `skill-creator` discipline for the description only; +create no eval file. The content, verbatim: + +```markdown +--- +name: review-loop +description: "The dispatcher's procedure for the working process's review loop, and the grammar of the disposition ledger. Invoke before dispatching a verdict agent (architect, plan-adversary), at a consumption gate (before plan-writing or implementation), before a status move on a design spec, technical design or plan, and before writing a ledger line under a document's Review rounds section — the first time in a conversation, and again after a compaction. Instructions only: it dispatches no agent and runs no round." +--- + +# review-loop — the dispatcher's procedure and the ledger + +This skill carries instructions and nothing else. It dispatches no +agent and runs no round. Read the reference your moment needs, whole, +before you act: + +| You are about to… | Read | +|---|---| +| dispatch a verdict agent | `PROCEDURE.md`, then `LEDGER.md` | +| pass a consumption gate | `PROCEDURE.md`, then `LEDGER.md` | +| move a `status` | `PROCEDURE.md` | +| write a ledger line | `LEDGER.md` | + +- `${CLAUDE_PLUGIN_ROOT}/skills/review-loop/PROCEDURE.md` — dispatching + a verdict agent, the review loop, the stand-in and the provisional + batch, the propagation gate, re-dispatch briefs, the terminators, what + a diff-scoped LGTM certifies, the audit pair at the consumption gate, + and per-round commits on a document branch. +- `${CLAUDE_PLUGIN_ROOT}/skills/review-loop/LEDGER.md` — the disposition + ledger under `## Review rounds`: round headings, disposition lines, + gate lines. + +After a compaction this body returns and the references do not. Invoke +the skill again at the next of the four moments and re-read what it +routes to. + +A reviewer or an auditor no longer receives the ledger grammar with the +document it reads. When you dispatch any agent on a document that +carries a `## Review rounds` section, give its brief the absolute path +of `LEDGER.md` and ask it to read that file first. + +The four moments are listed in three places — the workflow rule's +pointer sentence, this skill's description, and the table above — and +the three are edited together. +``` + +- [ ] **Step 8: Verify the skill** + +```bash +S=$D/SKILL.md +grep -c 'again after a compaction' $S # 1 +grep -c 'absolute path' $S # 1 +grep -c 'edited together' $S # 1 +for m in 'verdict agent' 'consumption gate' 'status move' 'ledger line'; do + sed -n '3p' $S | grep -c "$m"; done # 1 four times +claude plugin validate plugins/working-process # passes +python3 -m unittest discover -s tests/working-process 2>&1 | tail -1 # OK +``` + +- [ ] **Step 9: Commit** — `feat(working-process): review-loop skill` + +### Task 2: Cut `workflow.md` + +**Files:** +- Modify: `plugins/working-process/rules/workflow.md` +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md:122, 130` + +**Interfaces:** +- Consumes: the skill and reference names from Task 1. + +**Realizes:** D2, D3 + +- [ ] **Step 1: Delete the moved procedure and write the pointer** + +Delete from the line after `## Dispatching a verdict agent` to the end +of the file. Keep the heading. Under it write, verbatim: + +```markdown +When the `review-loop` skill is available, invoke it — the first time +in a conversation, and again after a compaction — before dispatching a +verdict agent (`architect`, `plan-adversary`), at a consumption gate, +before a `status` move, and before writing a ledger line. Its procedure +reference holds the dispatch procedure, the review loop, the stand-in +and the provisional batch, the propagation gate, re-dispatch briefs, +the terminators and what a diff-scoped LGTM certifies; its ledger +reference holds the disposition ledger and its gate lines. + +When the `process-status` skill is available, its Unfinished-work +reference holds the Unfinished-work list; the skill reads it when the +developer asks what the process left unfinished. +``` + +- [ ] **Step 2: Move step 4's sequencing out** + +Replace base lines 115–130 ("Where the technical-design offer is +accepted, the audit waits: the" through "has passed, leaving no +confirmed hit, when that agent is available.") with, at the step's +three-space indent: + +```markdown +Where the technical-design offer is accepted, the audit waits until +the design exists and its review dispositions are applied; the audit +pair's sequencing at this gate is in the `review-loop` skill's +procedure reference, when that skill is available. +``` + +The first clause repeats the lifecycle rule's *Lifecycle offers* +("writing the design and applying its review dispositions precedes the +joint integrity audit"). "Then write the implementation plan…" through +"…cannot count on it loading." stays as written. + +- [ ] **Step 3: Shorten steps 3 and 4** + +Step 3 becomes, verbatim: + +```markdown +3. **Grilled spec → architect review.** Offer a dispatch of the + working-process `architect` agent (when available), on the most + capable available model, named explicitly; dispatch, stamping and + the propagation gate before each round follow the `review-loop` + skill's procedure reference, when that skill is available. When the + `propagation-auditor` agent is available, offer a propagation audit + at authoring time as well, after any multi-site edit; that offer + stands outside the loop. +``` + +The cut sentence — the audit gates that dispatch and every later +round — repeats *The propagation gate* in `PROCEDURE.md`. + +In step 4, keep the sentence opening "It writes both ends" (102–105) +and the sentence opening "The plan written afterwards carries" +(109–113). They repeat the lifecycle rule's `technical-design:` bullet, +but that rule is not loaded when the offer is accepted (developer's +ruling, 2026-11-16). + +Steps 1, 2, 5 and 7 lose no sentence. + +- [ ] **Step 4: Rewrite the remaining pointers** + +| Base line | Text | Becomes | +|---|---|---| +| 53–55 | "the pair-offer form the verdict-agent dispatch subsection defines" | "the pair-offer form the `review-loop` skill's procedure reference defines, when that skill is available" | +| 140–141 | "dispatch and stamping follow the verdict-agent dispatch subsection below" | "dispatch and stamping follow the `review-loop` skill's procedure reference, when that skill is available" | +| 150–151 | "a provisional decision, defined under *The stand-in and the provisional batch* below" | "a provisional decision, which the `review-loop` skill's procedure reference defines under *The stand-in and the provisional batch*, when that skill is available" | +| 155–156 | "under the dispatch-record store's `.gitignore` guard" | "in a store kept out of git by a `.gitignore` containing exactly `*`" | +| 184–185 | "running on the relay machinery the verdict-agent dispatch subsection already defines" | "running on the relay machinery the `review-loop` skill's procedure reference defines, when that skill is available" | +| 230–232 | "taking the timestamp shape of the two the verdict-agent dispatch subsection defines:" | "named `.claude/working-process//--.md` — `` the subject, kebab-cased and capped at sixty characters, and a second record in the same second taking the lowest free counter suffix, `-2` then `-3` — in a store at the repo root kept out of git by a `.gitignore` containing exactly `*`:" | +| 300–301 | "which the spec-plan-lifecycle rule names" | "which the `review-loop` skill's procedure reference names, when that skill is available," | + +- [ ] **Step 5: Update the registry** + +`SETTINGS_REGISTRY.md`: under `## review.autonomy`, +`read-by: working-process/skills/review-loop/PROCEDURE.md`; under +`## review.per-round-commit`, +`read-by: working-process/skills/review-loop/PROCEDURE.md, working-process/rules/spec-plan-lifecycle.md` +(Task 3 drops the second file). + +- [ ] **Step 6: Verify** + +```bash +W=plugins/working-process/rules/workflow.md +grep -c '^### ' $W # 0 +grep -c '^## Dispatching a verdict agent$' $W # 1 +grep -c 'subsection' $W # 0 +grep -c 'subsection below\|gate below\|batch\* below\|definition below' $W # 0 +grep -c 'Oscillation tripwire\|round cap' $W # 0 +grep -c 'review\.autonomy\|review\.per-round-commit' $W # 0 +grep -n -A1 'review-loop' $W # read: every pointer sentence carries "when that skill is available" +grep -c '^1\. \|^2\. \|^3\. \|^4\. \|^5\. \|^6\. \|^7\. ' $W # 7 +grep -c 'consult.personas\|design.technical-design-offer\|dispatch.propagation-auditor-tier\|ticket.root' $W # 4 or more +wc -m < $W # report; estimate 15,000, projection about 19,500 +python3 -m unittest discover -s tests/working-process 2>&1 | tail -1 # OK +``` + +Read the shortened steps 3 and 4 against the base text and confirm no +decision left without a home (the first anti-goal). + +- [ ] **Step 7: Commit** — `refactor(working-process): workflow rule keeps the offers, the procedure moves to review-loop` + +### Task 3: Cut the ledger and the loop's text from the lifecycle rule + +**Files:** +- Modify: `plugins/working-process/rules/spec-plan-lifecycle.md` +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md:106, 130` + +**Interfaces:** +- Consumes: the skill and reference names from Task 1. + +**Realizes:** D4, D6 + +- [ ] **Step 1: Delete the ledger** + +Delete from `## The disposition ledger` through "State prevents +relitigation, not the reviewer's memory." and its blank line (base +470–808). `## Unfinished-work list` now follows *Finding what revises a +document*; Task 4 moves it. + +- [ ] **Step 2: Delete the relay-then-stamp sentence** + +In *Lifecycle offers*, delete from "After any" (mid-line, base 914) +through "…waits for the confirming full-document round." (925). The +paragraph ends "…resolved entries sweep to the archive." + +- [ ] **Step 3: Delete the per-round commit convention** + +Delete from "Asking whether the loop may commit per round" through +"…the default path, where no sha exists." (base 987–1045). To the +paragraph before it, which ends "committing itself stays with the +developer.", append: + +```markdown +One shape of that sooner commit, per-round commits on a document +branch, has a convention: when the `review-loop` skill is available, +its procedure reference holds it, with the document branch's merge at +this gate. +``` + +- [ ] **Step 4: Rewrite the kept pointer and add the closing pointer** + +Base 54: "the provisional batch the workflow rule defines" becomes "the +provisional batch the `review-loop` skill's procedure reference +defines, when that skill is available,". + +Before the last paragraph ("Ticket value format, sourcing order…"), +add: + +```markdown +The disposition ledger — the round headings, disposition lines and gate +lines a document carries under `## Review rounds` — is defined in the +`review-loop` skill's ledger reference, when that skill is available. +``` + +- [ ] **Step 5: Update the registry** + +Under `## docs-branch.merge` and under `## review.per-round-commit`: +`read-by: working-process/skills/review-loop/PROCEDURE.md`. + +- [ ] **Step 6: Verify** + +```bash +L=plugins/working-process/rules/spec-plan-lifecycle.md +grep -c '^## The disposition ledger\|^### Gate lines' $L # 0 +grep -c 'State prevents relitigation\|hit dismissed' $L # 0 +grep -c 'relay-before-stamp\|subsection' $L # 0 +grep -c 'docs-branch\.merge\|review\.per-round-commit\|\.docs' $L # 0 +grep -c 'workflow rule' $L # 2 (model selection, step 4) +grep -c '^## Ticket directories$\|^### Moving a document into a ticket directory$' $L # 2 +diff <(git show $BASE:$L | sed -n '204,292p') <(sed -n '/^## Ticket directories$/,/^## Decision register$/p' $L | sed '$d') # empty +grep -n -A1 'review-loop' $L # read: every pointer sentence carries "when that skill is available" +grep -l 'review.per-round-commit' plugins/working-process/rules plugins/working-process/skills -r # PROCEDURE.md only +grep -l 'docs-branch.merge' plugins/working-process/rules plugins/working-process/skills plugins/working-process/agents -r # PROCEDURE.md and rules/process-settings.md (a fenced example there, no reader) +python3 -m unittest discover -s tests/working-process 2>&1 | tail -1 # OK +``` + +If either `grep -l` lists another file that cites the key in backticks +outside a fence, add it to that key's `read-by:` line. + +- [ ] **Step 7: Commit** — `refactor(working-process): disposition ledger and per-round commits move to review-loop` + +### Task 4: The Unfinished-work list joins `process-status` + +**Files:** +- Create: `plugins/working-process/skills/process-status/UNFINISHED-WORK.md` +- Modify: `plugins/working-process/skills/process-status/SKILL.md:8-19` +- Modify: `plugins/working-process/rules/spec-plan-lifecycle.md` + +**Interfaces:** +- Produces: `UNFINISHED-WORK.md`, whose `## Unfinished-work list` + heading the skill keys on. + +**Realizes:** D6 + +- [ ] **Step 1: Extract and verify** + +```bash +U=plugins/working-process/skills/process-status/UNFINISHED-WORK.md +{ printf '# process-status — the Unfinished-work list\n\n' + git show $BASE:$L | sed -n '809,900p'; } > $U +diff <(sed '1,2d' $U) <(git show $BASE:$L | sed -n '809,900p') # empty +``` + +- [ ] **Step 2: Rewrite its pointers** + +"the resolution annotation above" (base 835–836) becomes "the resolution +annotation the spec-plan-lifecycle rule defines". "the list below" does +not occur here. Nothing else changes: "This section is the list" and +"the heading and the skill move together or not at all" stay, and are +still true. + +- [ ] **Step 3: Delete the section from the lifecycle rule** + +Delete `## Unfinished-work list` through "Either way the anchor stops +matching." and its blank line (base 809–901). At base 167, "so they +never match the list below" becomes "so they never match the +Unfinished-work list". Extend the closing pointer paragraph from Task 3 +with a second sentence: + +```markdown +The Unfinished-work list is the `process-status` skill's +Unfinished-work reference, when that skill is available. +``` + +- [ ] **Step 4: Point the skill at its reference** + +In `process-status/SKILL.md`: lines 8–11 become "Runs the +Unfinished-work list its reference file publishes and reports what it +finds. The list owns which classes exist; this skill owns nothing but +running them, confirming their hits, and reporting. A class this skill +has never heard of works the moment the list publishes it." Step 1's +first paragraph becomes "Read the `## Unfinished-work list` section of +`${CLAUDE_PLUGIN_ROOT}/skills/process-status/UNFINISHED-WORK.md`, the +reference file shipped beside this skill." The failure rule (lines +26–30) stays as written. + +- [ ] **Step 5: Verify** + +```bash +grep -c '^## Unfinished-work list$' $U # 1 +grep -c '^- \*\*' $U # 6 (the six classes) +grep -c 'annotation above' $U # 0 +grep -c '^## Unfinished-work list' $L # 0 +grep -c 'Misplaced stamp\|the list below' $L # 0 +grep -c 'rules/spec-plan-lifecycle.md\|lifecycle rule' plugins/working-process/skills/process-status/SKILL.md # 0 +grep -c 'skills/process-status/UNFINISHED-WORK.md' plugins/working-process/skills/process-status/SKILL.md # 1 +wc -m < $L # report; estimate 32,000 +claude plugin validate plugins/working-process # passes +``` + +- [ ] **Step 6: Commit** — `refactor(working-process): Unfinished-work list becomes a process-status reference` + +### Task 5: Pointers in other files + +**Files:** +- Modify: `plugins/working-process/README.md:93, 162, 214-217` +- Modify: `plugins/working-process/skills/grilling-session/SKILL.md:60` +- Modify: `docs/domain/glossary.md:450-460` + +**Realizes:** D14 + +- [ ] **Step 1: Plugin README** + +Line 93: "the lifecycle rule publishes" becomes "its reference file +publishes". Line 162: "section of the lifecycle rule" becomes "section +of the `process-status` skill's `UNFINISHED-WORK.md`". Lines 214–217: +the relay-then-stamp sequence is attributed to the `review-loop` skill, +and the two audit offers stay with the workflow rule; read the +paragraph to its end and keep the re-sync advice true. + +- [ ] **Step 2: `grilling-session`** + +Line 60: "the Grilling pending class of the lifecycle rule's +Unfinished-work list" becomes "the Grilling pending class of the +Unfinished-work list, a reference of the `process-status` skill". + +- [ ] **Step 3: Glossary** + +The **Unfinished-work list** entry opens "The reference file of the +`process-status` skill, `UNFINISHED-WORK.md`, holding one entry per +class of unfinished process work"; "costs one edit in the rule" becomes +"costs one edit in the list". The rest of the entry and its `_Avoid_` +line stay. Run the elements-of-style pass over the changed sentences. + +- [ ] **Step 4: Verify** + +```bash +grep -rn 'lifecycle rule.*Unfinished-work\|Unfinished-work.*lifecycle rule\|Unfinished-work list. section of the lifecycle' \ + plugins/working-process README.md docs/domain | wc -l # 0 +grep -c 'section of the spec-plan-lifecycle rule holding' docs/domain/glossary.md # 0 +grep -c 'UNFINISHED-WORK.md' docs/domain/glossary.md plugins/working-process/README.md # 1 or more each +``` + +- [ ] **Step 5: Commit** — `docs(working-process): pointers follow the moved text` + +### Task 6: Identity surfaces, changelog, version + +**Files:** +- Modify: `plugins/working-process/.claude-plugin/plugin.json` +- Modify: `.claude-plugin/marketplace.json:10` +- Modify: `README.md:19` +- Modify: `plugins/working-process/README.md:88-95` +- Modify: `plugins/working-process/CHANGELOG.md` + +**Realizes:** D15 + +- [ ] **Step 1: Name the skill in all three identity surfaces** + +In each description's skill list, write "process-status, process-setup, +review-loop and sync-rules skills". `plugin.json` is canonical; the +catalog entry and the README row carry the same list. + +- [ ] **Step 2: Plugin README** + +After the `process-status` bullet add a `review-loop` bullet: what it +holds (the dispatcher's procedure and the ledger grammar, as two +reference files), its four read moments, and that it dispatches +nothing. + +- [ ] **Step 3: Changelog** + +Under the existing `## Unreleased` heading add: + +```markdown +- The dispatcher's procedure — verdict dispatch, the review loop, the + stand-in, the propagation gate, re-dispatch briefs, the terminators, + the diff-scoped LGTM, per-round commits — leaves the workflow rule, + and the disposition ledger leaves the lifecycle rule, for a new + `review-loop` skill. Invoke it before a verdict dispatch, at a + consumption gate, before a `status` move and before writing a ledger + line. No decision changes. +- The Unfinished-work list is now a reference file of `process-status`. +- A brief for any agent dispatched on a document with a + `## Review rounds` section carries the ledger reference's path. +- Run `sync-rules` after updating: both rules shrink. +``` + +- [ ] **Step 4: Dogfood version** + +```bash +git log develop --format=%H -- plugins/working-process/.claude-plugin/plugin.json | + while read c; do git show "$c:plugins/working-process/.claude-plugin/plugin.json"; done | + grep -o 'dev\.[0-9]*\.' | sort -t. -k2 -n | tail -1 +``` + +Expected today: `dev.8.` Set `"version": "0.20.0-dev.9.process-context"`. +If the command prints a higher number, take the next one. + +- [ ] **Step 5: Verify** + +```bash +grep -c 'review-loop' plugins/working-process/.claude-plugin/plugin.json .claude-plugin/marketplace.json README.md +# 1 each +grep -c '"version": "0.20.0-dev.9.process-context"' plugins/working-process/.claude-plugin/plugin.json # 1 +claude plugin validate . && claude plugin validate plugins/working-process # both pass +``` + +- [ ] **Step 6: Commit** — `chore(working-process): review-loop identity surfaces, changelog, dogfood version` + +### Task 7: Final verification + +**Files:** +- Test: `tests/working-process/test_settings_registry.py` + +**Realizes:** none + +- [ ] **Step 1: Tests and validation** + +```bash +python3 -m unittest discover -s tests/working-process 2>&1 | tail -3 # Ran 77 tests … OK +claude plugin validate . && claude plugin validate plugins/working-process +git diff --name-status $BASE -- plugins/working-process/rules | grep -c '^[AD]' # 0: no rule file added or removed +git diff $BASE --stat -- plugins/working-process/hooks plugins/working-process/scripts | wc -l # 0 +``` + +- [ ] **Step 2: Every moved heading is gone from its old home and present in its new one** + +```bash +P=plugins/working-process +for h in 'The review loop' 'The stand-in and the provisional batch' 'The propagation gate' \ + 'Re-dispatch briefs' 'Terminators' 'What a diff-scoped LGTM certifies'; do + echo "$h: $(grep -c "^### $h\$" $P/rules/workflow.md) $(grep -c "^### $h\$" $P/skills/review-loop/PROCEDURE.md)" +done # 0 1 on every line +echo "$(grep -c '^### Gate lines$' $P/rules/spec-plan-lifecycle.md) $(grep -c '^### Gate lines$' $P/skills/review-loop/LEDGER.md)" # 0 1 +``` + +- [ ] **Step 3: Pointer sweep** + +```bash +grep -rn 'dispatch subsection\|propagation gate below\|provisional batch the workflow\|relay-before-stamp ordering and are edited' \ + plugins README.md docs/domain | wc -l # 0 +grep -rn 'workflow rule' plugins/working-process docs/domain README.md +``` + +Read every line the second command prints and confirm its target still +stands in `workflow.md`: model selection, the tier table, step 4, step +6, *Branch naming*, the consultation paragraphs. Report any other. + +- [ ] **Step 4: Sizes** + +```bash +wc -m plugins/working-process/rules/workflow.md plugins/working-process/rules/spec-plan-lifecycle.md \ + plugins/working-process/skills/review-loop/*.md plugins/working-process/skills/process-status/*.md +wc -l plugins/working-process/skills/review-loop/SKILL.md # under 500 +``` + +Report each rule beside its estimate: about 15,000 and about 32,000. + +- [ ] **Step 5: Live checks, on the checkout's plugin** + +The marketplace tracks `develop` on GitHub, so the topic branch's +version cannot be installed through it before the merge. The checks use +the live-session recipe instead, on the real configuration (a scratch +`CLAUDE_CONFIG_DIR` cannot authenticate a live session). Setup, the +developer's act, since it changes their environment: + +1. `claude plugin disable working-process`, so the checkout's copy does + not collide with the installed one; +2. `sync-rules` with the checkout's `plugins/working-process/rules` as a + developer-named source, so the user-level rules are the new ones; +3. every `claude -p` below carries `--plugin-dir plugins/working-process` + (an absolute path where it runs outside the repository). + +Confirm first: + +```bash +grep -c 'State prevents relitigation' ~/.claude/rules/working-process/spec-plan-lifecycle.md # 0 +``` + +Every run below adds `--output-format stream-json --verbose`, so its +output carries the token usage and the tool calls the checks read. + +1. **Context measurement, one per document class.** In a scratch + directory outside the repository, create `docs/specs/x-spec.md`, + `docs/technical-designs/x-technical-design.md` and + `docs/plans/x-plan.md`, each with frontmatter carrying `status:`. + From that directory, for each document, run + `claude -p --model haiku "Read the first twenty lines of . Then list the rule files injected into your context."`. + Expected: `spec-plan-lifecycle.md` among the injected files in all + three runs; the precondition's grep already shows the ledger text is + gone from that rule. Report the files and each run's + token count beside the 97,000-token figure in the spec. +2. **`process-status`.** In this repository, run + `claude -p "/working-process:process-status"`. Expected: the report + names all six Unfinished-work classes, and its output shows + `UNFINISHED-WORK.md` read from the checkout's + `plugins/working-process/skills/process-status/`. +3. **`review-loop` trigger.** In this repository, run + `claude -p "Dispatch the plan-adversary on docs/plans/2026-11-16-process-context-plan.md; stop before dispatching and say what you read first."`. + Expected: the transcript shows the `review-loop` skill invoked + before any dispatch. One run is a signal, not proof for every + session. + +A miss in any of the three is reported, never a failure. + +Teardown, the developer's act: `claude plugin enable working-process`, +then `sync-rules` from the installed plugin. Its rules are older than the +checkout's, so the Rules engine's direction gate asks before writing; +confirm it. + +- [ ] **Step 6: Closing report** + +Report the sizes, the measurement, the `workflow.md` shortfall, and +every provisional decision taken. + +## Review rounds + +### 2026-11-16 — plan-adversary, opus 5.5, concerns (round 1, full-document) + +Record: `.claude/working-process/2026-11-16-process-context-plan/plan-adversary-round-1.md`. The gate lines below come from the pre-round propagation episode (haiku, one re-dispatch, clean). + +- hit fixed 2026-11-16 — Task 1 Step 3's first `diff` printed a stray empty line: the stripped title left its blank line; `norm` now drops empty lines +- hit fixed 2026-11-16 — Task 2 Step 6's grep for `half-written` cannot reach 0 once step 4's kept sentence stays; the alternative is dropped +- hit fixed 2026-11-16 — Task 3 Step 6 expected `docs-branch.merge` in `PROCEDURE.md` only; `rules/process-settings.md` carries it in a fenced example, no reader; expectation corrected +- hit fixed 2026-11-16 — `PROCEDURE.md` keeps "the drop-or-wait question above", whose referent stays in `workflow.md`; Task 1 Step 4 gains the W797–799 row +- hit dismissed 2026-11-16 — `PROCEDURE.md`, `LEDGER.md`, `UNFINISHED-WORK.md` are names no source defines; counter: the spec names the references by role and leaves their file names to the plan, and D11 forbids paths, not names +- hit fixed 2026-11-16 — (auditor's judgment note) the inline consultation record name dropped the sixty-character stem cap and the collision counter; the Task 2 row now carries both +- fixed 2026-11-16 — [Important] Task 7 Step 5's context measurement ran under the developer's old user-level rules and would report a false miss; ruling: 2026-11-16; it runs after the developer installs the dogfood version and syncs the rules, on the real configuration, since a scratch `CLAUDE_CONFIG_DIR` cannot authenticate a live session +- fixed 2026-11-16 — [Important] Task 4 Step 5 invoked `process-status` before the dogfood version existed; ruling: 2026-11-16; the invocation moves to Task 7 Step 5, after the dogfood install, and checks the new cache directory +- fixed 2026-11-16 — [Minor] the skill's trigger was checked by grep only; ruling: 2026-11-16; Task 7 Step 5 adds one `claude -p` run asked to dispatch a plan-adversary, whose transcript must show `review-loop` invoked +- fixed 2026-11-16 — [Minor] the moved per-round section opens with "is not that suggestion", whose antecedent stays in the lifecycle rule; license: spec D12, pointers rewritten; Task 1 Step 4 gains an L987 row and L988 shortens to "That suggestion says" +- fixed 2026-11-16 — [Minor] Task 1 Step 6 expected `workflow rule` once in `PROCEDURE.md`, while the W797–799 gate fix adds a second; license: the gate line above; expectation now 2 +- fixed 2026-11-16 — [Minor] Task 7 Step 1's `git status` check is vacuous once tasks are committed; license: spec *Verification*, no rule file added or removed; now `git diff --name-status $BASE`, no new command +- fixed 2026-11-16 — [Minor] the inline consultation record name lost "at the repo root"; license: spec anti-goal 1, no moved sentence changes meaning; the row 230–232 replacement now says it +- signal 2026-11-16 — a diff-scoped round on this wave would not earn its cost; the confirming full-document round owed by the plan will read these fixes +- hit fixed 2026-11-16 — the Task 1 Step 4 "owns it" pair turned W790 into "the spec-plan-lifecycle rule `LEDGER.md` owns it"; the row splits and W790 rewrites the whole phrase +- hit fixed 2026-11-16 — W645 reads "The" (capital, wrapped) and missed the lowercase anchor, while a text match would wrongly catch W783; W644–645 has its own row and rows match by line +- hit fixed 2026-11-16 — `$BASE` and `$L` are used in Task 3, 4 and 7 blocks that never set them; the method paragraph says every block assumes Task 1 Step 1's variables and a fresh shell sets them again +- hit fixed 2026-11-16 — the Architecture line said "byte-for-byte" while the check normalises whitespace; now "verbatim" and "whitespace-normalised", as the spec's *Verification* says +- hit fixed 2026-11-16 — Task 1 Step 4's "match it by its words, not by one line" contradicted the method paragraph's "rows match by the listed line"; Step 4 now says to find the phrase at the listed line by its words + +### 2026-11-16 — plan-adversary, opus 5.5, concerns (round 2, full-document) + +Record: `.claude/working-process/2026-11-16-process-context-plan/plan-adversary-round-2.md`. The confirming round. + +- declined 2026-11-16 — [Minor] the relay-then-stamp sentence would merge into the preceding paragraph; ruling: 2026-11-16; base W866 is "document again." and W867 is the blank line, so the extraction already ends with the paragraph break +- fixed 2026-11-16 — [Minor] Task 1 Step 6's `git diff --stat` passes vacuously when Step 3's optional commit did not happen; license: Global Constraints, commits only where authorized; now a `diff` of the base range against `PROCEDURE.md`, no new command +- fixed 2026-11-16 — [Minor] Tasks 2 and 3 Step 6 expected `grep -vc 'available'` to print 0 while the prescribed pointer text wraps; license: the plan's own verbatim replacement texts; now `grep -n -A1` read by eye +- fixed 2026-11-16 — [Minor] Task 7 Step 5's measurement prompt contained the phrase it asked about; license: the precondition's grep already proves the ledger text is gone; the phrase question is dropped +- fixed 2026-11-16 — [Minor] the live checks' plain `claude -p` output carried neither the token count nor the tool calls; ruling: 2026-11-16; every run adds `--output-format stream-json --verbose` +- fixed 2026-11-16 — [Minor] `claude plugin update` cannot deliver the topic's version, since the marketplace tracks `develop`; ruling: 2026-11-16; Task 7 Step 5 uses the live-session recipe — the installed plugin disabled, `sync-rules` from the checkout, `--plugin-dir` on every run — with a teardown +- signal 2026-11-16 — no further round earns its cost: all five findings are Minor and none changes moved text or a pointer target + +Round 2's `concerns` is resolved without a further round: the developer answered the three held findings on 2026-11-16 and closed the loop on the reviewer's stop signal, since every finding was Minor and none touched moved text or a pointer target. diff --git a/docs/plans/2026-11-17-document-check-plan.md b/docs/plans/2026-11-17-document-check-plan.md new file mode 100644 index 0000000..9788e89 --- /dev/null +++ b/docs/plans/2026-11-17-document-check-plan.md @@ -0,0 +1,314 @@ +--- +ticket: none +date: 2026-11-17 +status: implemented +adversary: blocking (adjudicated 2026-11-17) +spec: ../specs/2026-11-17-document-check-spec.md +branch: feature/document-check +base: develop +--- + +# Document check Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ship `wp-document-check` and `wp-decision-coverage` behind one launcher, and make the dispatcher run them before the propagation auditor at every gate. + +**Architecture:** One bash launcher, copied per command, picks `scripts/.py` by its own file name and the first Python 3.9+. A new standard-library script runs two Document checks on every design spec, technical design and plan, and table closure on a technical design. The gate procedure, the auditor's card and every shipped sentence describing the old arrangement change to put the scripts in the dispatcher's hands. + +**Tech Stack:** Python 3.9+ standard library, bash, `unittest`; Markdown rules, agent cards and skill references. + +**Spec:** `docs/specs/2026-11-17-document-check-spec.md` (approved, `integrity:` d31a3a4). Read it whole before Task 1; this plan cites its decisions and does not restate their arguments. + +## Global Constraints + +- Python 3.9+, standard library only; no third-party import anywhere. +- Every hit line has the shape ` — — check: `, `` one of `references`, `citations`, `table-closure`. +- Exit codes of `document-check.py`: 0 when the Document checks ran, hits or not; 1 when the document cannot be read; 2 on a usage error. +- **Realizes:** D2 — A hit only where the parse settles the defect; every unsettled form is counted on a `not checked` summary line. +- **Realizes:** D15 — Under `## Review rounds` the Document checks read only the lines below the last `### ` round heading. +- Committed text is English, no machine paths, no client names (repo-hygiene rule). +- Verification checks over text take the `wp-phrase-check` form the plan-authoring rule gives, run on each side of their step; where the command is not on `PATH`, run `python3 plugins/working-process/scripts/phrase-check.py` with the same arguments. +- Commits: one line, conventional-commit prefix, no body, no trailer. +- The plugin version becomes `0.20.0-dev.11.document-check` (Task 7). + +**Deviation from the spec, recorded here:** *Settled for the plan* says the launcher reads its name "before resolving symlinks". The shipped test `test_symlinked_launcher_finds_script` invokes the launcher through a link named `link`, which that reading would break. The launcher reads its name from the resolved file instead, so a link of any name works and each copy in `bin/` still names its own script. The call was the session's; it changes nothing D4 decides. + +## Review Focus + +1. A document with no frontmatter, or one whose frontmatter never closes — the script must still run and type it as a design spec, never crash. +2. A `path:line` whose file exists but is binary or not UTF-8 — read with `errors="replace"`, never a traceback. +3. CRLF line endings — headings and table rows must parse as with LF. +4. A Windows checkout of `bin/` — copies must stay byte-identical and executable; a test pins both. +5. A technical design whose Parts table is absent — `table-closure` prints `not applicable`-style counts (0 relations), never a hit for a missing table. + +--- + +### Task 1: One launcher for every Python script + +**Files:** +- Modify: `plugins/working-process/bin/wp-phrase-check` +- Create: `plugins/working-process/bin/wp-decision-coverage` +- Create: `tests/working-process/test_wp_launcher.py` +- Delete: `tests/working-process/test_wp_phrase_check_launcher.py` (its tests move into the new file unchanged) + +**Interfaces:** +- Produces: `bin/wp-` runs `scripts/.py`; `` is the resolved file name without its `wp-` prefix. The no-Python message reads `wp-: no Python 3.9 or later found; tried: …` and exits 2. + +**Realizes:** D4, D5 + +- [ ] **Step 1: Move the launcher tests and add three.** Create `test_wp_launcher.py` holding every test of the old file, with `LAUNCHER` kept as the phrase-check launcher, plus: + - `test_bin_copies_are_identical` — every file in `bin/` has the same bytes and the executable bit (`os.access(p, os.X_OK)`). + - `test_each_launcher_has_its_script` — for every `bin/wp-`, `scripts/.py` exists. + - `test_decision_coverage_launcher_runs` — with the `GOOD` python3 stub, `bin/wp-decision-coverage ` exits 0 and prints a line starting `decision-coverage:`. + Delete the old file. + +- [ ] **Step 2: Observe the change absent.** Run `cd tests/working-process && python3 -m unittest test_wp_launcher` before Step 3 and record what it prints. `test_decision_coverage_launcher_runs` must fail; if it passes, stop as blocked. The two structural tests pass on today's one-file `bin/` — they guard copies, not this change — so prove them after Step 3 instead: flip one byte of `bin/wp-decision-coverage`, and separately rename `scripts/decision-coverage.py`, run them, record that each fails, and restore both. + +- [ ] **Step 3: Generalise `bin/wp-phrase-check`.** After the symlink loop resolves `self`, set `name="${self##*/}"; name="${name#wp-}"`; the script path becomes `"$dir/../scripts/$name.py"`, the error message's prefix `wp-$name`, and the header comment names `scripts/.py`. Copy the file to `bin/wp-decision-coverage` byte for byte, mode 100755 (`git update-index --chmod=+x` if the filesystem loses it). + +- [ ] **Step 4: Run the launcher tests and the whole suite** — all pass, including the moved symlink test. + +- [ ] **Step 5: Commit** — `feat(working-process): one launcher serves every Python script` + +### Task 2: `document-check.py` — skeleton, document type, internal references + +**Files:** +- Create: `plugins/working-process/scripts/document-check.py` +- Create: `plugins/working-process/bin/wp-document-check` (copy of the Task 1 launcher) +- Create: `tests/working-process/test_document_check.py` + +**Interfaces:** +- Consumes: the Task 1 launcher. +- Produces: `main(argv: list[str]) -> int`; `doc_type(path: str, frontmatter: dict[str, str]) -> str` returning `"technical-design"`, `"plan"` or `"spec"`; `body_lines(text: str) -> list[tuple[int, str]]` — 1-based line numbers of lines outside fenced blocks, below the frontmatter, and under `## Review rounds` only below its last `### ` heading (D15) — with no `### ` heading yet, the whole section; a frontmatter that never closes is treated as absent, the body starting at line 1; `Report` holding hits and per-check `checked`/`not checked` counters, printed hits first, then exactly three summary lines in the order `references`, `citations`, `table-closure`. + +**Realizes:** D1, D3 + +- [ ] **Step 1: Write the failing tests** in `test_document_check.py`, each a temporary repo (`git init` in a temp dir) and a document written into it: + - `test_type_by_path_then_frontmatter` — `docs/technical-designs/x.md` with `spec:` → `technical-design`; `docs/tickets/A-1-x/A-1-x-technical-design.md` → `technical-design`; `docs/plans/p.md` with `spec:` → `plan`; a file without `spec:` → `spec`; a file without frontmatter → `spec`. + - `test_named_section_wrong_side_is_hit` — `*Gamma* below` where `## Gamma` sits above → one hit, `check: references`. + - `test_named_section_right_side_is_clean` — the clean twin. + - `test_unknown_name_is_not_checked` — `*Nowhere* below` → no hit, `references` not-checked count 1. + - `test_plan_task_reference` — a plan citing `Task 3` with only `### Task 1` and `### Task 2` → one hit; adding `### Task 3:` → none. + - `test_bare_below_and_step_are_not_checked` — "see below", "Step 2", "§4" → no hit, three not checked. + - `test_ledger_reads_last_round_only` — a citation-free wrong-side reference under an earlier `### ` round heading → no hit; the same under the last heading → one hit; the same in a `## Review rounds` with no `### ` heading → one hit. + - `test_fenced_block_ignored` and `test_crlf_document` (Review Focus 3). + - `test_no_frontmatter_and_unclosed_frontmatter` (Review Focus 1) — exit 0, three summary lines; with an unclosed `---`, a wrong-side reference after it → one hit. + - `test_exit_codes` — missing file → 1; no argument → 2. + - `test_summary_lines_shape` — stdout ends with three lines matching `^document-check: (references|citations|table-closure) `. + Matching: a name and a heading compare after `wp-phrase-check`'s normalisation (load `normalise` from `scripts/phrase-check.py` with `importlib.util.spec_from_file_location`; no test imports it today, they run it by subprocess), at any heading level, ignoring a leading section number (`3.2 `); "beside" means the name and `below`/`above` sit in one sentence. Name the side by heading line versus citing line; a name matching more than one heading is not checked (add `test_duplicate_heading_not_checked`). + +- [ ] **Step 2: Observe them fail** with the script absent; record what each prints. Stop as blocked if any passes. + +- [ ] **Step 3: Implement** the functions above; `citations` and `table-closure` report zero counts for now (`table-closure` prints `not applicable` on a non-technical design). Copy the launcher to `bin/wp-document-check` (byte-identical, 100755), and add `test_document_check_launcher_runs` to `test_wp_launcher.py`: with the `GOOD` stub, `bin/wp-document-check ` exits 0 and prints three `document-check:` summary lines. + +- [ ] **Step 4: Run** `test_document_check.py` and `test_wp_launcher.py` — pass. + +- [ ] **Step 5: Commit** — `feat(working-process): wp-document-check with the internal-references check` + +### Task 3: Citations and link targets + +**Files:** +- Modify: `plugins/working-process/scripts/document-check.py` +- Modify: `tests/working-process/test_document_check.py` + +**Interfaces:** +- Consumes: `body_lines`, `Report`, `doc_type` from Task 2. +- Produces: `check_citations(path: str, lines: list[tuple[int, str]], report: Report, root: str, created: set[str]) -> None`. + +**Realizes:** D9 + +- [ ] **Step 1: Write the failing tests**, each with its clean twin: + - `test_path_line_outside_file` — `` `sub/a.md:9` `` against a 3-line `sub/a.md` → hit; `:3` → none; `:2-3` → none; `:2-4` → hit. + - `test_symbol_on_cited_line` — `` `alpha` (sub/a.md:2) `` where line 2 lacks `alpha` → hit; holds it → none. + - `test_missing_file_rule` — `sub/missing.md:1` with `sub/` present → hit; `nodir/missing.md:1` → not checked; bare `missing.md:1` → not checked; in a plan, `` - Create: `sub/missing.md` `` above → not checked. + - `test_link_target` — `[x](sub/missing.md)` with `sub/` present → hit; `[x](https://e.org)`, `[x](#anchor)` and `[x](sub/a.md#sec)` → not checked; an existing target → checked, no hit. + - `test_backticked_path_without_line_never_hits` — `` `sub/missing.md` `` → not checked, on spec, plan and technical design alike. + - `test_git_ignored_path_resolves` — a file listed in `.gitignore` that exists → checked, no hit. + - `test_license_quote` — `license: "foo bar" sub/a.md:2` where line 2 reads `Foo\nbar` across a wrap within the window lines 2–4 → none; a quote absent from the file → hit; a quote with no location → not checked; the same three cases with `ruling:` in place of `license:` → the same results; a quote followed by an `*italic*` naming no heading of the document → not checked. The check reads both `license:` and `ruling:` clauses. Location precedence: first `path:line`, path, or `*italic heading*` after the quote; a `path:line` is searched in lines `line` to `line+2`, a path in the whole file, a heading in its section. + - `test_binary_target` (Review Focus 2) — a non-UTF-8 file cited by `path:line` → no traceback, counted. + Paths resolve against the document's directory, then the repository root (`git rev-parse --show-toplevel`, falling back to the current directory). + +- [ ] **Step 2: Observe them fail**; record the output. Stop as blocked if any passes. + +- [ ] **Step 3: Implement** `check_citations`; read cited files with `encoding="utf-8", errors="replace"`. + +- [ ] **Step 4: Run** the test file — pass. + +- [ ] **Step 5: Commit** — `feat(working-process): document-check citations and link targets` + +### Task 4: Table closure + +**Files:** +- Modify: `plugins/working-process/scripts/document-check.py` +- Modify: `tests/working-process/test_document_check.py` + +**Interfaces:** +- Consumes: `body_lines`, `Report`, `doc_type`. +- Produces: `declared_relations(rule_path: str) -> list[tuple[str, str, bool, str, str]]` — (table, column, each_side, target table, target column) parsed from the rule's `## Declared table relations` table; `check_tables(path: str, lines: list[tuple[int, str]], report: Report, relations: list[tuple[str, str, bool, str, str]]) -> None`. The rule path is `