From e0e912c9116e501b680de3eb098f88bc0021b248 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:56:46 +0100 Subject: [PATCH 01/59] docs(working-process): cost-discipline spec and plan --- docs/plans/2026-11-13-cost-discipline-plan.md | 148 +++++++ docs/specs/2026-11-13-cost-discipline-spec.md | 410 ++++++++++++++++++ 2 files changed, 558 insertions(+) create mode 100644 docs/plans/2026-11-13-cost-discipline-plan.md create mode 100644 docs/specs/2026-11-13-cost-discipline-spec.md 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..e4d2d7b --- /dev/null +++ b/docs/plans/2026-11-13-cost-discipline-plan.md @@ -0,0 +1,148 @@ +--- +ticket: none +date: 2026-11-13 +status: approved +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/specs/2026-11-13-cost-discipline-spec.md b/docs/specs/2026-11-13-cost-discipline-spec.md new file mode 100644 index 0000000..e645993 --- /dev/null +++ b/docs/specs/2026-11-13-cost-discipline-spec.md @@ -0,0 +1,410 @@ +--- +ticket: none +date: 2026-11-13 +status: approved +decisions: registered +architect: concerns (resolved 2026-11-13) +branch: feature/cost-discipline +base: develop +--- + +# Cost discipline — reviews that ask whether a mechanism is worth having + +Every review the working process runs asks how a document breaks. None +asks whether what it adds is worth having. This spec makes the +reviewers and the session's triage ask that question, and leaves the +decision to cut scope with the developer. It is package 2b-core of the +release queue: cost discipline without process weights. + +## Problem + +In ai-devcontainer v1, every review wave grew its plan and none shortened +one: four plans reached 6,714 lines. A search of every architect, +plan-adversary, integrity and Codex record from that work for +*over-engineer*, *YAGNI*, *KISS*, *simplif* and *scope creep* returns no +hits. Four mechanics made the documents grow: + +- **A finding was fixed by adding a mechanism.** A Minor about + `--ssh-retarget` became the new task `profile:ssh-retarget`, marked + "(Recommended)" and accepted; sixteen minutes later the developer asked + why it existed. An override validator grew to 629 lines because each + bypass a reviewer found widened it; nobody proposed narrowing the input + it accepted. +- **Recommendations favoured completeness.** The developer accepts the + session's recommendation almost every time, so a recommendation acts + as the decision. Nothing asked it to prefer the smaller option. +- **The verdict threshold kept code-dense plans blocked.** + `blocking` = ≥1 Critical or ≥2 Important. v1 ran 17 plan-adversary + rounds and reached LGTM in none. In v2, a 575-line KISS plan went + `blocking` three times with no Critical finding, though every fix was + licensed or a one-line ruling. +- **A requirement licensed unlimited mechanism.** One plan's rollback + engine followed from three requirements in the design spec. Three + `blocking` rounds in a row found defects in rollback logic the + previous round's fixes had added. No step asked whether the + requirement should be cut. + +v2 worked because the developer did the cutting by hand. The reviewer +brief carried "block only on data loss, privacy or security, a broken +requirement; do not propose new mechanisms", and the architect returned +LGTM with ten one-line Minors. + +Sources: the ai-devcontainer phase A and B analyses and the Codex +over-engineering review, kept in the developer's local process records. + +## Goals, non-goals, anti-goals + +Goals: + +- A reviewer that proposes a fix adding a mechanism also names a cheaper + way out. +- A fix that adds a mechanism reaches the developer before it lands, with + the smaller option recommended where it meets the requirements. +- Only a Critical finding blocks; an Important is `concerns`. +- A mechanism the developer dropped does not come back without new + evidence. +- The developer sees, every round, how much the document grew. + +Non-goals: + +- Process weights: the `process.weight` key, the `process-weight:` field, + a `light` mode. They are package 2b-weight, held until this package's + dogfood shows a need. +- A settings key for the verdict threshold. It waits for a project that + wants the stricter threshold back. +- Growth thresholds or tripwires. The evidence calibrates none. +- A reviewer pass asking whether native behaviour covers a requirement + at the spec stage. The question D8 adds while drafting is the only + spec-stage change. +- Rules for an outside co-reviewer such as Codex. +- Asking the consultation question on every path; it returns to the + errata package. + +Anti-goals — the change fails, even if it works, when: + +- it adds more mechanism to the process than it removes from documents; +- a data-loss, security or broken-requirement defect passes without + `blocking`, outside a domain checklist's own grading (see *Verdict + threshold*); +- the developer is interrupted over findings that carry no decision. + +## Decisions + +- **D1** — Where a finding's suggested fix adds a mechanism, the + architect and the plan-adversary name at least one cheaper + alternative beside it, within the same finding; the plan-adversary + also names the requirement that forces the mechanism. Argued in + *Reviewers*. +- **D2** — A diff-scoped round attacks the previous wave's fixes for + added mechanism as well as for defects. Argued in *Reviewers*. +- **D3** — The architect reports a requirement whose realization forces + mechanism out of proportion to its value as a finding that suggests + relaxing the requirement. Argued in *Reviewers*. withdrawn the + mechanism a requirement forces appears in the plan, so the duty moves + to the plan-adversary's D1 alternatives, and the architect's + over-engineering lens covers the design side, ruling: 2026-11-13; + replaced by D1 +- **D4** — Triage holds every fix that adds a mechanism, whatever the + finding's severity and whether or not a license exists. Argued in + *Triage*. +- **D5** — A held finding's recommendation prefers the smaller option + where it meets the requirements; "accept as a documented limitation" + is always among the options. Argued in *Triage*. +- **D6** — `blocking` means at least one Critical finding, in both + cards; two Important findings no longer block. Argued in *Verdict + threshold*. +- **D7** — In the plan-adversary's scale, a requirement the plan does + not deliver is Critical: a "done when" no phase delivers, a `new`, + `changed` or `retired` part of a technical design no task covers, and + a registered decision realized only in part. Argued in *Verdict + threshold*. +- **D8** — 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; the + answers land in the spec's non-goals and constraints. Argued in + *Before drafting*. +- **D9** — A mechanism the developer drops is recorded as a non-goal in + the design spec or as a `ruling:` line in the ledger; both reviewers + treat the spec's non-goals as settled and re-raise one only with new + evidence; a re-raised non-goal is held, the non-goal quoted in + `counter:`. Argued in *Dropped stays dropped*. +- **D10** — A `declined` line for a finding the developer deferred ends + with `; backlog`. Argued in *Backlog*. withdrawn it answers no goal, + and a `declined` line's own clause can say "deferred", ruling: + 2026-11-13 +- **D11** — The relay header carries the reviewed document's size, + without its ledger, and the change since the previous round. The + dispatch record's header gains a size line to make the change + derivable. Argued in *Net growth*. +- **D12** — The architect's Critical also covers a stated requirement + the design does not meet and a data-loss or security defect. Argued + in *Verdict threshold*. + +## A mechanism + +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, +since that is how v1's validator reached 629 lines: each fix closed a +bypass by adding a check. 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. This is the definition D1, D2 +and D4 share. Two files carry it: `PERSONA_COMMON.md`, which both cards +read before reviewing (the architect through its persona file), and the workflow rule, for the session's triage. The +glossary gets no entry: "mechanism" has ordinary uses in bound text, and +the defined phrase is "a fix adds a mechanism". + +## Reviewers + +The architect's persona already carries an over-engineering lens, but it +reads the design as a whole. A fix that adds a mechanism usually arrives +as the answer to one finding, and diff-scoped rounds then attack only +whether the fix is correct, so the lens never meets it. + +D1 puts the cost question inside the finding that would cause the +mechanism. Beside a fix that adds one, the reviewer names at least one +cheaper alternative: narrowing the input, relying on the tool's native +behaviour, accepting the gap as a documented limitation, or deferring +it. The alternative sits in the same finding, so no separate list, grade +or section appears. The plan-adversary gets the same duty, since in v1 +most mechanism-breeding findings were its own. It also names the +requirement that forces the mechanism, with `origin: design-spec`: the +mechanism a requirement forces first appears in the plan, where the +rollback engine of *Problem* did. Naming stays inside the card's +boundary, under which a finding whose origin names a judged document +"proposes no change to that document"; the workflow rule holds such a +finding, and the developer decides whether to relax the requirement. + +D2 adds one question to the diff-scoped brief's "attack the previous +wave's fixes first": did a fix add a mechanism the finding did not need? + +D3 first gave the architect this duty. The architect reads the design +spec, where a requirement's mechanism is not yet written, and its +persona's over-engineering lens already asks the design-side question, +so D3 was withdrawn in favour of the plan-adversary's alternative above. + +## Triage + +The workflow rule's triage decides by license: a fix the session can +cite a written decision for is self-fixable. A requirement licenses any +amount of mechanism that enforces it, which is how v1 grew. + +D4 adds one hold that a license does not lift: a fix that adds a +mechanism is held for the developer, whatever its severity. Most such +fixes would reach the developer anyway; the hold closes the path where +a licensed Minor became a task. + +D5 sets the default of the held line's `options:`. The session +recommends the smaller option where it meets the requirements, and +"accept as a documented limitation" is always offered. The +recommendation still names the mechanism when nothing smaller meets the +requirement. + +Two kinds of fix stay outside D4. A fix that carries out a `ruling:` +is not held again, because the developer has already decided it. A +propagation-gate hit is not held either, because its derivation +licenses its fix: a coverage hit that writes a missing task realizes a +decision the spec already registered. Where the session cannot tell +whether a fix adds a mechanism, it holds the fix, as the workflow rule +already prescribes for any doubtful case. + +The held set grows by exactly the fixes D4 catches, and the round's one +batch carries them, so each round still interrupts the developer at most +once. A loop interrupts more often, by design: a round whose only +mechanism-adding fixes were licensed used to continue unasked, and now +stops for the developer. The relay header's count of decisions follows: +the workflow rule derives it from the findings with no license, and it +gains the fixes D4 holds, so the count and the round's `held` lines +still agree. + +## Verdict threshold + +Both cards define `blocking` as at least one Critical or two Important +findings (`plan-adversary.md`, `architect.md`). D6 drops the second leg +in both, so an Important finding gives `concerns`. `concerns` is the +autonomy zone, so a plan with Important findings and no Critical stays +inside the loop instead of suspending it. + +The two scales differ. The architect's Critical covers "the design +cannot deliver its stated purpose" but names neither a single unmet +requirement nor a data-loss or security defect; both would be +Important, "a boundary or choice that forces rework if built as +designed". D12 adds both to its +Critical. Its requirement leg stays open on purpose: any single unmet +requirement blocks, as v2's brief asked, where D7 bounds the +plan-adversary to three enumerated cases. The plan-adversary's Critical names data loss, security, +a production outage and a broken deploy, and grades three undelivered +requirements as Important: a "done when" no phase delivers (dimension +1), an uncovered part of a technical design (dimension 5), and a +registered decision realized only in part (dimension 6). D7 adds the +undelivered requirement to its Critical and regrades those three, so +dropping the second leg lets no broken requirement through. The other +Important findings in those dimensions — a missing `technical-design:` +entry, an unknown `change` value, a redefined contract — describe a +defect in the documents rather than an undelivered requirement, and stay +Important. + +One path stays open, as a documented limitation. A domain checklist's +severity wins over the generic scale, and the Salesforce plan-review +checklist grades three security-model defects Important — a missing +org-wide default or FLS, `without sharing` without a justification, a +capability on a profile. Today any two of them in one plan block it; after D6 they give +`concerns`. The loop still triages them, and a domain plugin that wants +one to block regrades it in its own checklist. + +## Before drafting + +v2's brief carried size targets, a list of what v1 dropped, accepted +risks and expectations for first use, and the documents written from it +stayed short. D8 makes the session ask for those answers while it +drafts the design spec, at step 1 of the workflow rule, before the +spec's first review. The answers go into the spec's non-goals and +constraints, never into a separate brief file, so every reviewer reads +them, D9 protects them, and no stamp goes stale. Asking later, at the +consumption gate, would edit a spec that a verdict and an `integrity:` +stamp already certify. + +## Dropped stays dropped + +The ledger already settles a line carrying `ruling:`: a later round may +re-raise it only with new evidence. A drop agreed in conversation but +never written down has no such protection. D9 requires the drop to be +written, either as a non-goal in the design spec or as a `ruling:` line, +and adds one sentence to `PERSONA_COMMON.md`, which both cards read +before reviewing: +the spec's non-goals are settled, +and a finding that would reintroduce one says what new evidence it +brings. + +A non-goal carries no date, so a re-raise cannot be folded against it +the way the lifecycle rule folds a re-raise of a `ruling:` line. The +session holds it instead, quoting the non-goal in `counter:`; that +follows from the workflow rule as it stands, which holds a finding the +session believes is wrong with its counter-evidence, so no new sentence +ships for it. `PERSONA_COMMON.md` carries only the reviewer's half, +beside the definition: non-goals are settled, and evidence counts as +new against the spec's own text. + +## Backlog + +D10 proposed a `; backlog` ending on `declined` lines for deferred +findings. It answered no goal, and two glossary entries ban the word ("backlog item", "backlog"), so +it was withdrawn: a `declined` line's own clause can say the finding is +deferred, and D5's "accept as a documented limitation" stays. + +## Net growth + +v1's plans grew 30–94 % across their reviews, and nobody saw the numbers +until the retrospective. D11 shows them at every relay: the reviewed +document's line count, counted from the end of the frontmatter and +excluding the `## Review rounds` section, and the change since the +previous round's dispatch record of the same document and agent. The +dispatch record's header gains a fifth line, `size: `, which is +where the previous count comes from. The relay reports the number and +judges nothing. A dispatch with no reviewed document carries no size +line, and a round with no earlier record carrying one reports the size +without a change. Every live rule and glossary entry that calls the +header "four-line" lists its fields instead, size "where a document was +reviewed", so no line count goes false; documents already `implemented` +keep their wording. + +## Verification + +- Both cards carry the new threshold, and no file in `plugins/` still + says "two Important" or "≥2 Important". +- A dogfood replays the plan-adversary on the v2 plan as it stood at its + first round. Expected: no `blocking` verdict, and every finding whose + fix adds a mechanism names a cheaper alternative. +- A dogfood of one review loop on a scratch spec seeded with a Minor whose + natural fix adds a task. Expected: the fix is held, its recommendation + is the smaller option, and the relay header shows size and change. +- The same dogfood seeds a design-level security defect into the + scratch spec — a requirement or decision that itself exposes data, not + a failure the architect would have to hunt for. + Expected: the architect grades it Critical, and the verdict is + `blocking`. + +## Out of scope + +- Weights, a threshold setting and growth tripwires (see *Goals, non-goals, anti-goals*). +- Reviewing the rules themselves for size; this package governs + documents the process reviews. + +## Changes by file + +- `PERSONA_COMMON.md` — the definition in *A mechanism*; D9's settled + non-goals, with evidence new against the spec's text; its self-description by counts ("the + two duties", "All four sections") follows the new content. +- `agents/architect.md` — D1, D6, D12. +- `agents/plan-adversary.md` — D1 with the named requirement, D6, D7. +- `docs/domain/glossary.md` — D11 in the *Relay* entry's header and the + *Dispatch record* entry's four-line header. +- `rules/workflow.md` — D2 in *Re-dispatch briefs*; D4 and D5 in *The + review loop*; D4 in the relay header's count of decisions; D8 in step + 1; D11 in the dispatch record and relay bullets; the definition in *A + mechanism*. +- `CHANGELOG.md` of working-process. +- `.claude/working-process/release-queue.md` (local) — 2b-core status. + +## Calls made by the author + +- The definition of a mechanism lists six kinds plus widening an + existing part; deleting, narrowing, tests and verification steps add + none. +- D11 reads the previous count from the dispatch record rather than + adding a field to the round heading, whose grammar is closed. +- The plan-adversary gets D1 too, not only the architect, because most + mechanism-breeding findings in v1 were its own. +- D4 exempts fixes carrying out a `ruling:` and propagation-gate hits; + a doubtful case is held. +- D11 omits the size line without a document and the change without an + earlier record. +- D2 lives in the workflow rule's brief composition only; the cards are + unchanged by it. + +## Review rounds + +### 2026-11-13 — architect, fable 5.2, blocking (round 1, full-document) + +- hit fixed 2026-11-13 — the glossary's *Dispatch record* entry calls the header four-line and *Changes by file* did not list it; added to *Changes by file* +- hit fixed 2026-11-13 — the glossary's *Relay* entry restates the relay header D11 changes; added to *Changes by file* +- hit fixed 2026-11-13 — *A mechanism* named rules and cards as the definition's consumers while *Changes by file* put it in workflow.md only; both cards now carry it +- hit fixed 2026-11-13 — the glossary had no entry for the minted term; *Changes by file* adds a *Mechanism* entry +- hit fixed 2026-11-13 — the lifecycle sentence "Two additions extend those shapes" gains D10's ending and the spec gave no new wording; *Backlog* now says it becomes three +- hit fixed 2026-11-13 — the "four-line" sweep reached implemented documents; *Net growth* limits it to live rules and glossary entries +- hit fixed 2026-11-13 — *Out of scope* cited a *Non-goals* heading that does not exist; it now cites *Goals, non-goals, anti-goals* +- hit dismissed 2026-11-13 — D9's non-goal protection needs a workflow.md brief edit; counter: D9 puts the protection in both cards, which every round reads, and the brief's ledger clause covers ledger lines a reviewer cannot otherwise see as settled (the architect agreed in round 1) +- hit fixed 2026-11-13 — the non-goals called D8 "the brief question"; reworded to the question D8 adds while drafting +- hit fixed 2026-11-13 — the "defer to backlog" option on held lines had no *Changes by file* entry; added under workflow.md with D5 +- fixed 2026-11-13 — [Important] F1: anti-goal 2 is not secured: the architect's Critical names no requirement, data-loss or security leg, and domain checklists grade security defects Important, which D6 turns into `concerns`; ruling: 2026-11-13; D12 adds unmet requirements, data loss and security to the architect's Critical, *Verdict threshold* records checklist-graded Importants as a documented limitation, *Verification* seeds a security defect +- fixed 2026-11-13 — [Important] F2: the mechanism definition misses widening an existing part (the 629-line validator) and is unclear on tests and steps; ruling: 2026-11-13; *A mechanism* counts widening an existing part and excludes tests and verification steps +- fixed 2026-11-13 — [Important] F3: D3 sits on the architect, who never sees the mechanism a requirement forces; the plan-adversary does; ruling: 2026-11-13; D1 gives the plan-adversary the requirement-relaxing alternative, D3 withdrawn and replaced by D1 +- fixed 2026-11-13 — [Minor] F4+F5: D10 answers no goal and mints "backlog", a word the glossary bans twice; ruling: 2026-11-13; D10 withdrawn, *Backlog* records why, the lifecycle rule leaves *Changes by file* +- fixed 2026-11-13 — [Minor] F7: a re-raised non-goal has no fold and no base for new evidence; ruling: 2026-11-13; D9 and *Dropped stays dropped* hold a re-raised non-goal with the non-goal quoted in `counter:` +- fixed 2026-11-13 — [Minor] F8: three copies of the definition where PERSONA_COMMON.md, read by both cards, would make two, and a glossary term collides with ordinary uses of "mechanism"; ruling: 2026-11-13; the definition moves to PERSONA_COMMON.md and the workflow rule, the glossary entry is dropped +- fixed 2026-11-13 — [Minor] F6: D4 changes the relay header's decision count and the per-loop interruption count; license: D4; *Triage* states both consequences, *Changes by file* lists the relay-count bullet +- fixed 2026-11-13 — [Minor] F9: "says five" is false for a dispatch without a document; license: D11 (no size line without a document); *Net growth* lists fields instead of a count +- fixed 2026-11-13 — the *Verification* dogfood had "not now" write `; backlog`, against *Backlog*; license: *Backlog* and *Calls made by the author*; reworded to "defer to backlog" +- signal 2026-11-13 — one more diff-scoped round earns its cost, attacking the F1 and F2 fixes; Minors only expected after it +- hit dismissed 2026-11-13 — *A mechanism* says two files carry the definition while neither does yet; counter: a design spec states the target state, *Changes by file* prescribes the edit, and F8's "moves" records the spec's change, not a shipped one +- hit dismissed 2026-11-13 — two earlier gate lines and the *Verification* fix line name D10's backlog ending, now withdrawn; counter: ledger lines record what each wave did at the time, and the F4+F5 line records the withdrawal +- hit fixed 2026-11-13 — *Verdict threshold* said "two of them block" of per-finding grades; reworded to "any two of them in one plan block it" +- hit fixed 2026-11-13 — *Verdict threshold* misquoted the architect's Important; now quotes the card in full +- hit fixed 2026-11-13 — *A mechanism* and *Dropped stays dropped* said both cards read PERSONA_COMMON.md first, while the architect reaches it through its persona file; reworded to "read before reviewing" +- hit fixed 2026-11-13 — the non-goal sends the consult question to the errata package while the local release queue still listed it under 2b-core; the queue now moves it to package 5, the spec stands +- hit fixed 2026-11-13 — *Backlog* said the glossary bans "backlog" twice, while one entry bans "backlog item"; reworded to name both entries +- hit fixed 2026-11-13 — the local release queue's 2b-core scope still carried the withdrawn `; backlog` ending; the queue now records it as dropped, its 2b-weight and 2b+ designs left as written + +### 2026-11-13 — architect, fable 5.2, concerns (round 2, diff-scoped) + +- fixed 2026-11-13 — [Important] R2-1: the F2 definition counted the validator's fixes both as widening and as narrowing; license: the F2 ruling and *Problem*'s validator example; *A mechanism* keys on a new check, branch or case, replaces "narrowing" with removing an input, option or case, and exempts a test or verification step only when it brings no new command or script +- fixed 2026-11-13 — [Minor] R2-2: anti-goal 2 still names the path the F1 limitation accepts; license: the F1 ruling; anti-goal 2 now excepts a domain checklist's own grading +- fixed 2026-11-13 — [Minor] R2-3: D12's "a stated requirement the design does not meet" is open-ended, so a single unmet goal now blocks on the architect where D7 bounds the adversary to three cases; ruling: 2026-11-13; the leg stays open, *Verdict threshold* states that any single unmet requirement blocks +- fixed 2026-11-13 — [Minor] R2-4: D1's requirement-relaxing alternative breaks the plan-adversary's boundary ("proposes no change to that document"); license: plan-adversary.md, *Judged documents: decline*; D1 and *Reviewers* now have the adversary name the requirement, the developer decides whether to relax it +- fixed 2026-11-13 — [Minor] R2-5: the held re-raise of a non-goal sits in PERSONA_COMMON.md, whose readers never triage, while the workflow rule already holds a disputed finding with `counter:`; ruling: 2026-11-13; folding the F7 line; *Dropped stays dropped* derives the hold from the workflow rule, PERSONA_COMMON.md keeps the reviewer half, *Changes by file* follows +- fixed 2026-11-13 — [Minor] R2-6: the seeded security defect tests grading only if the architect hunts for it, which its persona disclaims; license: ARCHITECT_PERSONA.md's own duty; *Verification* seeds a design-level defect +- fixed 2026-11-13 — PERSONA_COMMON.md describes itself by counts the move makes false; license: its own text; *Changes by file* has the counts follow the new content +- signal 2026-11-13 — another architect round does not earn its cost; the leftovers are worth one batch to the developer + +Resolved 2026-11-13 without a fresh round: the developer accepted the round-2 recommendations and closed the loop on the reviewer's stop signal; every round-2 finding is `fixed` above. From f75d16a08ee80f78710a7170f77ece25535af004 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:57:27 +0100 Subject: [PATCH 02/59] feat(working-process): cost-discipline section in the shared persona file --- plugins/working-process/PERSONA_COMMON.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/plugins/working-process/PERSONA_COMMON.md b/plugins/working-process/PERSONA_COMMON.md index c60e9a3..373ee20 100644 --- a/plugins/working-process/PERSONA_COMMON.md +++ b/plugins/working-process/PERSONA_COMMON.md @@ -1,9 +1,10 @@ # Working-process personas — standing duties Every working-process persona carries the two duties below alongside its -own, respects the boundary between the personas, and — when dispatched in +own, respects the boundary between the personas, keeps the cost +discipline when it issues findings, and — when dispatched in consultation — is governed by the consultation contract that closes this -file. All four sections are defined only here, so they can never drift +file. All five sections are defined only here, so they can never drift between their consumers. `plan-adversary` carries the same two duties without being a persona: it @@ -61,6 +62,21 @@ no decomposition at all earns exactly that observation from the architect, and a shape that looks wrong earns one line from the designer — not a verdict on it. +## Cost discipline + +This section binds a reviewer that issues findings — the `architect` +agent and `plan-adversary`. 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. Each +card says what a finding owes when its fix adds a mechanism. + +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. + ## The consultation contract This section binds `*-consult` dispatches and their dispatcher only. The From 86cd8fa0b8f8d84af9590709bafc0ade955c494f Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:57:54 +0100 Subject: [PATCH 03/59] feat(working-process): architect blocks on Critical only and names cheaper alternatives --- plugins/working-process/agents/architect.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/plugins/working-process/agents/architect.md b/plugins/working-process/agents/architect.md index 80e498d..2a564b3 100644 --- a/plugins/working-process/agents/architect.md +++ b/plugins/working-process/agents/architect.md @@ -39,14 +39,19 @@ stamping. 2. **Findings** — one per issue: severity, section, a one-sentence claim, evidence (`file:line`, a quote from the subject, a documentation URL, or a glossary/ADR entry), and a suggestion. No filler, no style nits, - no claims without a citation. + no claims without a citation. Where the suggestion adds a mechanism + (defined in `PERSONA_COMMON.md`, *Cost discipline*), name at least + one cheaper alternative beside it, in the same finding: narrowing the + input, the tool's native behaviour, accepting the gap as a documented + limitation, or deferring it. 3. **Verdict** — `LGTM | concerns | blocking`; `blocking` = at least one - Critical or two Important findings. + Critical finding. 4. A few sentences of overall architectural opinion. Severity is measured in design terms: `Critical` — the design cannot -deliver its stated purpose, or overrides a recorded decision without -naming and superseding it; `Important` — a boundary or choice that forces +deliver its stated purpose or meet one of its stated requirements, +carries a data-loss or security defect, or overrides a recorded decision +without naming and superseding it; `Important` — a boundary or choice that forces rework if built as designed; `Minor` — naming, clarity, convention. ## Stamping From acbdf5761df480fbd70f7277da3015ca300857d9 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:58:25 +0100 Subject: [PATCH 04/59] feat(working-process): plan-adversary blocks on Critical only and grades undelivered requirements Critical --- .../working-process/agents/plan-adversary.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/plugins/working-process/agents/plan-adversary.md b/plugins/working-process/agents/plan-adversary.md index 0a61f7a..291f2dc 100644 --- a/plugins/working-process/agents/plan-adversary.md +++ b/plugins/working-process/agents/plan-adversary.md @@ -24,11 +24,19 @@ contradicting a glossary term or a recorded ADR is a finding - Every finding cites evidence: `file:line`, a quote from the plan, a skill/reference path, or a domain `ruleId`. - Severity `Critical | Important | Minor`. Generic scale: Critical = data - loss, security, production outage, broken deploy; Important = breaks a + loss, security, production outage, broken deploy, a requirement the + plan does not deliver; Important = breaks a mandatory standard with no immediate runtime failure; Minor = style, naming, docs. When a domain checklist assigns a severity to its rule, that severity wins — never re-grade it. - One finding per issue. No filler. No claims without a citation. +- Where a finding's suggested fix adds a mechanism (defined in + `PERSONA_COMMON.md`, *Cost discipline*), name at least one cheaper + alternative beside it, in the same finding: narrowing the input, the + tool's native behaviour, accepting the gap as a documented limitation, + or deferring it. Where a requirement of a design spec forces the + mechanism, name that requirement with `origin` naming the design spec, + and propose no change to it (see *Judged documents: decline*). - Never read a credential's value — `gh auth token`, a token or key file, a keyring — or write one into a command. Report a check that needs authentication the dispatch did not provide as not checked. @@ -65,7 +73,7 @@ licenses the edit. - Does every phase advance some "done when"? A phase mapped to none is scope creep. -- Is every "done when" delivered by some phase? A gap is Important. +- Is every "done when" delivered by some phase? A gap is Critical. - Refactors or future-proofing beyond the task → Minor, unless they widen the blast radius. @@ -103,7 +111,7 @@ pointer. A missing or extra entry is itself an Important finding whose `origin` names `implementation-plan`. The plan must cover every part marked `new`, `changed` or `retired`; one part may span several tasks and one task several parts, and a part carried as `unchanged` context -needs none. An uncovered part is an Important finding whose `origin` +needs none. An uncovered part is a Critical finding whose `origin` names `implementation-plan`. A `change` value outside `new | changed | retired | unchanged` is an Important finding whose `origin` names `technical-design`: the set is closed, and an unknown @@ -126,7 +134,7 @@ not you. Judge each decision, never each site: one decision may span several tasks and Global Constraints entries, so ask whether all the sites citing it realize it in full together, and whether a cited constraint actually binds the work it constrains. A decision realized -only in part — six rows of eight — is an Important finding whose +only in part — six rows of eight — is a Critical finding whose `origin` names `implementation-plan`. A deferral the developer ruled on a `**Defers:**` line is not judged; a task that quietly depends on the deferred decision anyway is a finding. Decisions inherited through a @@ -157,7 +165,7 @@ decision settles it, the finding says the question is the developer's. ] } -`blocking` = ≥1 Critical or ≥2 Important — revise before building. +`blocking` = ≥1 Critical — revise before building. `concerns` = worth surfacing, not blocking. `LGTM` = no findings. ## Stamping From 28dae4ce9edc0a956194608d3e7d0cdc43d0f8b7 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:58:40 +0100 Subject: [PATCH 05/59] fix(working-process): plan-adversary names the requirement with origin design-spec --- plugins/working-process/agents/plan-adversary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/working-process/agents/plan-adversary.md b/plugins/working-process/agents/plan-adversary.md index 291f2dc..8880fb3 100644 --- a/plugins/working-process/agents/plan-adversary.md +++ b/plugins/working-process/agents/plan-adversary.md @@ -35,7 +35,7 @@ contradicting a glossary term or a recorded ADR is a finding alternative beside it, in the same finding: narrowing the input, the tool's native behaviour, accepting the gap as a documented limitation, or deferring it. Where a requirement of a design spec forces the - mechanism, name that requirement with `origin` naming the design spec, + mechanism, name that requirement with `origin` `design-spec`, and propose no change to it (see *Judged documents: decline*). - Never read a credential's value — `gh auth token`, a token or key file, a keyring — or write one into a command. Report a check that From ed2318f182817a522ea0200b5c5285964c564d23 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:59:15 +0100 Subject: [PATCH 06/59] feat(working-process): cost hold in triage, size in relays, brief while drafting --- plugins/working-process/rules/workflow.md | 40 +++++++++++++++++++---- 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 149f9de..0099a4a 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -24,7 +24,11 @@ disables its suggestion — never the work itself. guess; a recorded key is simply read again. On a genuinely ambiguous ask — in-thread dialogue or a fresh-context consultation? — ask one short question rather than silently picking a - surface. + surface. While drafting a design spec, before its first review, ask + the developer for a size target, what is dropped, what native + behaviour already covers, and which risks are accepted; write the + answers into the spec's non-goals and constraints, never into a + separate brief file, so every reviewer reads them. 2. **Spec → grilling.** Once a spec exists, offer a grilling-session (when the working-process plugin is installed) to stress-test its language against the project's domain terms. @@ -308,8 +312,12 @@ available: loop. The order has one named exception, defined under *What a diff-scoped LGTM certifies* below: a plan's diff-scoped LGTM. - The dispatch record is written before the relay. The dispatcher - saves what the agent returned, verbatim, under a four-line header — - the date, the agent, the model self-report, and the subject — with + saves what the agent returned, verbatim, under a header of the date, + the agent, the model self-report, the subject, and — where a + document was reviewed — its size, `size: `: 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` + — with no frontmatter and no `ticket`, since the record is evidence rather than a process artefact. It goes to `.claude/working-process/` at the repo root (`git rev-parse --show-toplevel`). A record survives @@ -349,7 +357,11 @@ available: takes the lowest free counter suffix instead: `-2`, then `-3`. - The relay opens with one header line, then one line per finding. The header carries the verdict, the model self-report, the finding count - by severity, and how many decisions await the developer. Each + by severity, and how many decisions await the developer, and — where + a document was reviewed — its size and the change since the previous + record of the same document and agent; with no earlier record + carrying a `size:` line it shows the size alone. The relay reports + the number and judges nothing. Each finding takes one line — severity, origin, claim — except where the reviewer emits no origin: the `architect` reads one document and every finding it returns originates there, so an architect relay's @@ -363,7 +375,8 @@ available: quotation rather than a reconstruction — so the relay names that record's path, and the developer can open what was condensed. - The header's count of decisions is the findings for which the - session can cite no license, derived at relay time from the report + session can cite no license, plus those whose suggested fix adds a + mechanism (the hold under *The review loop*), derived at relay time from the report and the decisions already written down — before any ledger line exists, since `open` is written at stamp time and triage follows the stamp. The `held` lines the same round later writes are that count's @@ -470,6 +483,20 @@ decision. Consequences the loop states outright: clause the spec-plan-lifecycle rule defines — which also leaves the design spec's `integrity:` stamp stale, as any body edit to either document of an audit pair does. +- A fix that adds a mechanism is held whatever its severity, and a + license does not lift the hold. 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. Two fixes stay outside the hold: one carrying out + a line with `ruling:`, which the developer already decided, and a + propagation-gate hit's fix, which its derivation licenses. A fix the + session cannot place either way is held. The held line's `options:` + recommend the smaller option where it meets the requirements and + always include "accept as a documented limitation". A fix wave that deviates from a reviewer's suggestion records the deviation and its rationale beside the text they concern — not only in @@ -568,7 +595,8 @@ agent installed, every dispatch proceeds as it did before. The first round reads the whole document; every later round is diff-scoped. Its brief names what changed since the round it follows, -directs the reviewer to attack the previous wave's fixes first, and +directs the reviewer to attack the previous wave's fixes first — +including whether a fix added a mechanism its finding did not need — and forbids re-reviewing the rest — repair-born defects are the dominant late-round class, and diff-scoping also ends stale-read findings. From 1bb70636bf10125d6c25e6ae437c32c7bf81f476 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:59:22 +0100 Subject: [PATCH 07/59] docs: glossary relay and dispatch record carry size --- docs/domain/glossary.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index f19d51e..6e90b35 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -608,7 +608,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,8 +619,8 @@ _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//`, +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: From 1bbaf87ec88bb22d04e0349ae9bffa238857d817 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 17:59:33 +0100 Subject: [PATCH 08/59] chore(working-process): changelog and dogfooding version for cost discipline --- .../.claude-plugin/plugin.json | 2 +- plugins/working-process/CHANGELOG.md | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index bbb9e25..99d4514 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.19.0", + "version": "0.20.0-dev.5.cost-discipline", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 04cea26..e89f119 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -2,6 +2,26 @@ Released versions of this plugin, newest first. +## Unreleased + +- The architect and the plan-adversary return `blocking` only on a + Critical finding; two Important findings now give `concerns`. +- The plan-adversary grades an undelivered requirement Critical: a + "done when" no phase delivers, an uncovered technical-design part, a + decision realized only in part. +- The architect's Critical also covers an unmet stated requirement and + a data-loss or security defect. +- A finding whose fix adds a mechanism names a cheaper alternative; the + plan-adversary also names the requirement that forces it. The + definition of a mechanism lives in `PERSONA_COMMON.md`, beside the + rule that a design spec's non-goals are settled. +- Triage holds every fix that adds a mechanism, licensed or not, and + recommends the smaller option. +- Dispatch records and relays carry the reviewed document's size and + its change since the previous round. +- While drafting a design spec, the session asks for a size target, + what is dropped, what native behaviour covers and the accepted risks. + ## 0.19.0 — 2026-11-13 - New design specs, technical designs and plans are named From 94111d3d835335fae4e392b46f1ccb95d8700670 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 18:03:46 +0100 Subject: [PATCH 09/59] fix(working-process): final-review minors for cost discipline --- docs/domain/glossary.md | 13 +++++---- plugins/working-process/ARCHITECT_PERSONA.md | 3 +- plugins/working-process/PERSONA_COMMON.md | 17 +++++------ plugins/working-process/README.md | 4 +-- plugins/working-process/agents/architect.md | 5 ++-- .../working-process/agents/plan-adversary.md | 14 +++++----- plugins/working-process/rules/workflow.md | 28 ++++++++++--------- 7 files changed, 45 insertions(+), 39 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 6e90b35..63430f9 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -620,12 +620,13 @@ _Avoid_: report back, forward (as the term) The file a dispatcher writes before relaying a background agent's result — one dispatch, one file, holding what the agent returned 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. +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/plugins/working-process/ARCHITECT_PERSONA.md b/plugins/working-process/ARCHITECT_PERSONA.md index 0777dc1..30c5522 100644 --- a/plugins/working-process/ARCHITECT_PERSONA.md +++ b/plugins/working-process/ARCHITECT_PERSONA.md @@ -4,7 +4,8 @@ Adopt the role of a seasoned software architect. One own duty, below, plus what every working-process persona carries: read `PERSONA_COMMON.md` in this plugin's root and adopt it too — domain expertise, the glossary/ADR duty that comes before any judgement, and the boundary with the system -designer; a consult dispatch is additionally governed by the consultation +designer; the `architect` agent also keeps the cost discipline there +when it issues findings; a consult dispatch is additionally governed by the consultation contract there. ## Own duty — design quality diff --git a/plugins/working-process/PERSONA_COMMON.md b/plugins/working-process/PERSONA_COMMON.md index 373ee20..42c3bb0 100644 --- a/plugins/working-process/PERSONA_COMMON.md +++ b/plugins/working-process/PERSONA_COMMON.md @@ -1,15 +1,16 @@ # Working-process personas — standing duties Every working-process persona carries the two duties below alongside its -own, respects the boundary between the personas, keeps the cost -discipline when it issues findings, and — when dispatched in +own, respects the boundary between the personas, and — when dispatched in consultation — is governed by the consultation contract that closes this -file. All five sections are defined only here, so they can never drift -between their consumers. - -`plan-adversary` carries the same two duties without being a persona: it -holds its role inline rather than in a persona file, and neither the -boundary section nor the consultation contract binds it — its own charter +file. The cost-discipline section binds only the reviewers that issue +findings, which it names. All five sections are defined only here, so +they can never drift between their consumers. + +`plan-adversary` carries the same two duties and the cost discipline +without being a persona: it holds its role inline rather than in a +persona file, and neither the boundary section nor the consultation +contract binds it — its own charter is the one the persona files state, failure hunting on plan mechanics. ## Domain expertise diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index c60972f..c280ad1 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -105,8 +105,8 @@ verdict dispatch and the integrity audit itself. Each persona is single-sourced in its file at the plugin root — [ARCHITECT_PERSONA.md](./ARCHITECT_PERSONA.md) and [SYSTEM_DESIGNER_PERSONA.md](./SYSTEM_DESIGNER_PERSONA.md) — with the -shared duties, the persona boundary, and the consultation contract held -once in [PERSONA_COMMON.md](./PERSONA_COMMON.md). `plan-adversary` +shared duties, the persona boundary, the reviewers' cost discipline and +the consultation contract held once in [PERSONA_COMMON.md](./PERSONA_COMMON.md). `plan-adversary` sources its standing duties from the same shared file without being a persona; the two `*-auditor` agents inherit neither persona nor standing duties and carry what they need in their own files. Every component diff --git a/plugins/working-process/agents/architect.md b/plugins/working-process/agents/architect.md index 2a564b3..3357d56 100644 --- a/plugins/working-process/agents/architect.md +++ b/plugins/working-process/agents/architect.md @@ -51,8 +51,9 @@ stamping. Severity is measured in design terms: `Critical` — the design cannot deliver its stated purpose or meet one of its stated requirements, carries a data-loss or security defect, or overrides a recorded decision -without naming and superseding it; `Important` — a boundary or choice that forces -rework if built as designed; `Minor` — naming, clarity, convention. +without naming and superseding it; `Important` — a boundary or choice +that forces rework if built as designed; `Minor` — naming, clarity, +convention. ## Stamping diff --git a/plugins/working-process/agents/plan-adversary.md b/plugins/working-process/agents/plan-adversary.md index 8880fb3..a596ed3 100644 --- a/plugins/working-process/agents/plan-adversary.md +++ b/plugins/working-process/agents/plan-adversary.md @@ -10,13 +10,13 @@ mis-scopes, or breaks without anyone noticing. Do not rewrite it. Do not soften it. FIRST ACTION: read `${CLAUDE_PLUGIN_ROOT}/PERSONA_COMMON.md` and adopt -its standing duties — domain expertise and the glossary/ADR duty; the -boundary section and the consultation contract there carve you out by -name. Then, per that glossary duty, read `docs/domain/glossary.md` and -`docs/domain/adr/` — resolved from the repo root, as the duty -specifies — when they exist. Canonical terms bind your wording, -and — re-tightening the shared file's "called out" floor — a plan -contradicting a glossary term or a recorded ADR is a finding +its standing duties — domain expertise, the glossary/ADR duty and the +cost discipline; the boundary section and the consultation contract +there carve you out by name. Then, per that glossary duty, read +`docs/domain/glossary.md` and `docs/domain/adr/` — resolved from the +repo root, as the duty specifies — when they exist. Canonical terms bind +your wording, and — re-tightening the shared file's "called out" floor — +a plan contradicting a glossary term or a recorded ADR is a finding (evidence = that file). ## Ground rules diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 0099a4a..9ed18b5 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -316,9 +316,9 @@ available: the agent, the model self-report, the subject, and — where a document was reviewed — its size, `size: `: 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` - — with - no frontmatter and no `ticket`, since the record is evidence rather + `sed '1,/^---$/d' | awk '/^## Review rounds/{s=1;next} /^## /{s=0} !s' | wc -l`, + or with the `sed` stage dropped for a document without frontmatter — + with no frontmatter and no `ticket`, since the record is evidence rather than a process artefact. It goes to `.claude/working-process/` at the repo root (`git rev-parse --show-toplevel`). A record survives compaction, the session's end and a branch switch, and no more; that @@ -357,8 +357,8 @@ available: takes the lowest free counter suffix instead: `-2`, then `-3`. - The relay opens with one header line, then one line per finding. The header carries the verdict, the model self-report, the finding count - by severity, and how many decisions await the developer, and — where - a document was reviewed — its size and the change since the previous + by severity, how many decisions await the developer, and — where a + document was reviewed — its size and the change since the previous record of the same document and agent; with no earlier record carrying a `size:` line it shows the size alone. The relay reports the number and judges nothing. Each @@ -376,14 +376,16 @@ available: record's path, and the developer can open what was condensed. - The header's count of decisions is the findings for which the session can cite no license, plus those whose suggested fix adds a - mechanism (the hold under *The review loop*), derived at relay time from the report - and the decisions already written down — before any ledger line - exists, since `open` is written at stamp time and triage follows the - stamp. The `held` lines the same round later writes are that count's - check: they come to the same number, and a divergence means triage - found a license the relay missed, triage lost one the relay claimed, - or the oscillation tripwire held a finding that does carry a - license. The third is lawful, so the check reports the number rather + mechanism and carries out no `ruling:` (the hold under *The review + loop*), derived at relay time from the report and the decisions + already written down — before any ledger line exists, since `open` + is written at stamp time and triage follows the stamp. The `held` + lines the same round later writes are that count's check: they come + to the same number, and a divergence means triage found a license + the relay missed, triage lost one the relay claimed, triage placed a + fix on the other side of the mechanism line than the relay did, or + the oscillation tripwire held a finding that does carry a license. + The last is lawful, so the check reports the number rather than asserting a fault. Verdicts that suspend autonomy — `blocking`, the spent round cap, the all-Minor signal — stay out of the count: they decide whether the loop continues rather than what a document From 1c521d1cf2d7373216ae9baa85fcc182b484a2d6 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 19:47:31 +0100 Subject: [PATCH 10/59] docs(working-process): cost discipline spec and plan implemented --- docs/plans/2026-11-13-cost-discipline-plan.md | 2 +- docs/specs/2026-11-13-cost-discipline-spec.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plans/2026-11-13-cost-discipline-plan.md b/docs/plans/2026-11-13-cost-discipline-plan.md index e4d2d7b..1ef6857 100644 --- a/docs/plans/2026-11-13-cost-discipline-plan.md +++ b/docs/plans/2026-11-13-cost-discipline-plan.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-13 -status: approved +status: implemented spec: ../specs/2026-11-13-cost-discipline-spec.md branch: feature/cost-discipline base: develop diff --git a/docs/specs/2026-11-13-cost-discipline-spec.md b/docs/specs/2026-11-13-cost-discipline-spec.md index e645993..e22babf 100644 --- a/docs/specs/2026-11-13-cost-discipline-spec.md +++ b/docs/specs/2026-11-13-cost-discipline-spec.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-13 -status: approved +status: implemented decisions: registered architect: concerns (resolved 2026-11-13) branch: feature/cost-discipline From 189ededfbb33d4460fb9000001ca70edaa5ae62c Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 16:22:27 +0100 Subject: [PATCH 11/59] docs(working-process): delegation boundaries spec --- .../2026-11-14-delegation-boundaries-spec.md | 375 ++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 docs/specs/2026-11-14-delegation-boundaries-spec.md diff --git a/docs/specs/2026-11-14-delegation-boundaries-spec.md b/docs/specs/2026-11-14-delegation-boundaries-spec.md new file mode 100644 index 0000000..11dfc51 --- /dev/null +++ b/docs/specs/2026-11-14-delegation-boundaries-spec.md @@ -0,0 +1,375 @@ +--- +ticket: none +date: 2026-11-14 +status: approved +decisions: registered +architect: blocking (adjudicated 2026-11-14) +integrity: 2026-11-14 (sha: 4d685b3) +branch: feature/delegation-boundaries +base: develop +--- + +# Delegation boundaries — provisional decisions and asks that only read + +A session decides many things the developer never sees: a stand-in's +answer, a ruling sent to an implementer, a status move. Some of those +decisions turn out to be the developer's. A session also acts on a +question as if it were an order. This spec lets delegated decisions take +effect at once without asking, records them as provisional, and hands +them to the developer in one batch at the document's next status move, +or for a design document at its consumption gate. +It also limits a question or a stated fact to reading. It is package 2c +of the release queue, narrowed by a history analysis. + +## Problem + +A history analysis read four sources of Claude Code sessions (about 160 +sessions, 2026-08-18 to 2026-11-14); a second pass re-derived each +report's claims from the transcripts and kept only what held. The +records stay local, in `.claude/working-process/history-analysis-2026-11-14/`. +Four findings bear on this spec: + +- **A stand-in's calls were reversed.** In one project the developer + let Codex stand in for them on document reviews. Of the session's eight + provisional calls they later read, they reversed three; at least one of + the three came from the stand-in (the time-zone field), and probably a + second (tab switching on a page). The session also closed a `blocking` plan + verdict on a stand-in consent given before that round ran. In another + project, pasted Codex text was kept as `ruling:` lines after the + developer called it a suggestion. +- **A session's own answer was wider than needed.** An implementer asked + a security question no document settled; the session sent back its own + ruling, which the developer narrowed two minutes later at the cost of + one more implement-and-review cycle. +- **A session moved a status and skipped a step on its own.** One + session set a design to `implemented` without the code-review step, + "according to the recommendation". +- **A question became an action, in all four sources.** A question + about validation rules led to edits and a deploy; a stated fact led + to a record update in a shared org; a pasted audit led to an executor + and two commits; "commit mise.html and push" pushed a different, + guessed file; "merge" led to a version mint and a release push. + +The developer's answer to the first finding sets the shape: a stand-in +exists so the developer is not asked again and again, so its decisions +take effect, and the developer reads them together at the end. + +## Goals, non-goals, anti-goals + +Goals: + +- A delegated decision takes effect without asking, and the record says + who made it. +- The developer reads every delegated decision once, in one batch, + before the document they approve moves on. +- A question or a stated fact never changes state, and a request + changes only what it names. + +Non-goals: + +- A goal or Stop hook treated as consent. None of the four sources + shows it since ai-devcontainer v1. +- A separate rule that an author never reviews its own text. D1 and D4 + cover the cases the analysis found. +- A settings key or a file that records a delegation. The delegation is + given in conversation and lives for that session. +- The model self-report check, which the analysis also found wanting. + It is package 5's. +- Implementation-time records in a ledger. A plan's implementation has + no ledger, and D5 keeps it that way. + +Anti-goals — the change fails, even if it works, when: + +- the developer is asked more often than before; +- a provisional decision reads like a developer's ruling in any record; +- reading for an answer becomes harder: a session hesitates to dispatch + an agent that only gathers information. + +## Decisions + +- **D1** — A *provisional decision* is a decision no written decision + licenses, taken by someone other than the developer: a stand-in's + answer, or a session's answer to an implementer. It takes effect at + once. In a review loop, its disposition line carries the authorizer + `provisional: ()` wherever the developer's answer + would have carried `ruling:`. Argued in + *Provisional decisions*. +- **D2** — The developer names a *stand-in* in conversation, for that + session. The stand-in answers the held findings the loop would put to + the developer, and each answer is a provisional decision. + An answer covers only the question put to it; a later event needs a + new question. Every other act stays the developer's: loop control + (round orders, cap and all-Minor escalations, a round after + `blocking`), held gate hits, a fix the mechanism hold stops, + adjudicating a `blocking` verdict, withdrawing or + deferring a registered decision, and moving a `status`. A stand-in's + answer is not developer contact; it may answer a `blocking` round's + held findings, whose fixes land while the loop stays stopped. A session + that loses the delegation on compaction asks again rather than guess. + Argued in *The stand-in*. +- **D3** — Provisional decisions reach the developer as one batch, + delivered with the request for the document's next status move, and + for a design spec or a technical design no later than its consumption + gate. The developer confirms or reverses each. Confirmed, the line's + `provisional:` becomes `ruling: `. Reversed, the session applies + the developer's answer at once and rewrites the line to the terminal + state that answer gives — a reversed `fixed` may become `declined` or + stay `fixed` with narrower text, a reversed `declined` becomes + `fixed` — carrying `ruling: `, the date of the developer's + answer. A line a plan review writes into an already-consumed judged + document travels in the plan's batch, and one answer settles both + lines. A move made on the developer's word leaves no `provisional:` + line, and an approval given before the request still gets the batch + first. Argued in *The batch*. +- **D4** — A document's `status` moves only on the developer's word, or + under a note in the project's instructions that names that move. Under + such a note the batch goes into the report that + announces the move, and reversals still land before the next work + starts. Argued in *Status moves*. +- **D5** — At implementation time, a provisional decision is written + when it is taken to `.claude/working-process//provisional.md`, + where `` is the plan's basename, or the design spec's where no + plan exists — one line per decision: date, question, answer and + author, `session` or `stand-in `. The session that took them + relays the list in its closing report; an answer there settles an + item and is appended to its line, and the batch at the `implemented` + move carries only what is still unanswered. No ledger line is + written. An execution skill's + own list, such as "Rulings I made", is relayed as provisional + decisions. Argued in *Implementation*. +- **D6** — An ask licenses only what it asks for. A question or a stated + fact asks for an answer: it licenses reading, with any tool, agents + included, and never a change of state — an edit, a commit, an agent + that writes, a push, a deploy, a write to a remote system, a release. + A request licenses the change it names, on the object it names, and + no further act with its own effect; an ambiguous object is asked + about. Any other change needs a request for it, or a consent that + covers it — given in this session, as a Standing answer, or by + project instruction; where one looks needed, the session proposes it + and waits. Records the rules owe — ledger lines, dispatch records, + D5's file — are no change an ask must name. Argued in *Asks that only read*. +- **D7** — A line carrying `provisional:` is not settled. A reviewer may + re-raise its finding like any `license:` line, and the oscillation + tripwire does not apply to it. Until confirmed, neither the line nor + the text its fix wrote licenses a later fix. Argued in *Provisional + decisions*. + +## Provisional decisions + +The ledger already says who decided each fix: `license:` when the +session cited a written decision, `ruling:` when the developer decided. +A stand-in's answer is neither, and writing it as `ruling:` is the +error the analysis found — the record then claims the developer decided +what Codex proposed. A third authorizer keeps the record true and +keeps "every terminal line carries exactly one authorizer". + +The author in the clause names who decided. In a ledger it is always +`stand-in `, since triage gives a session no unlicensed decision +to take; `session` appears only in D5's file. A batch is then a query, +not a memory: every line under the +document's `## Review rounds` whose authorizer is `provisional:`. + +A provisional line is not settled (D7). Settled lines are protected +because they record the developer's decision; this one records nobody's +yet. It sits with `license:` lines, which re-dispatch briefs already +leave open to attack. The oscillation tripwire guards against two +readings of one license; a provisional answer cites none, so a re-raise +against it goes through ordinary triage, and an unlicensed fix is held +or put to the stand-in as before. + +Nor does a provisional answer license anything. Triage cites written +decisions, and a stand-in's fix writes one into the document; a later +fix citing that text would rest on an answer the developer has not read, +and the batch query would not find it. The text stays uncitable until +confirmed, so a dependent fix is held, answered and listed in its turn. + +## The stand-in + +The developer wants a stand-in to stand in: to answer what the developer +would answer, so the loop does not stop for them on a held question. +Those questions concern what the document says, and each answer leaves +a ledger line the batch reads back and the developer can reverse. + +Every other act stays with the developer, each for its own reason. A +round order, a cap or all-Minor escalation and a round after +`blocking` spend rounds; a spent round cannot be confirmed or reversed, +and the cap resets only on a message from the developer. Adjudicating a +`blocking` verdict and moving a status each close what the batch exists +to reopen; the analysis found exactly that, a `blocking` verdict closed +on a stand-in's consent. Withdrawing or deferring a registered decision +changes what the spec decides, and its grammar carries `ruling:` alone; +a held gate hit is such a missing decision, so it stays with the +developer too. A fix the mechanism hold stops is a cost decision, the +one the hold exists to put to the developer. + +A stand-in's answer covers the question it was asked. The closed +`blocking` verdict rested on a consent given before the round that +produced it; no answer about a round can cover that round's outcome. + +The delegation lives in conversation, like the loop's autonomy consent +when it is not recorded. A session that loses it on compaction asks +again rather than guess, as the consult consent already does. + +## The batch + +The developer chose one handover at the end of a document's review +loop, and the end the rules already give them is the status move they +make. A spec or a plan moves to `approved` when they approve it, so the +batch rides on that request: they read the decisions before they approve +what they shaped. + +A design spec or a technical design is consumed before its approval can +matter: a plan written from a provisional line is rewritten when the +line is reversed. Its batch therefore falls due no later than its +consumption gate. + +The terminators still end the rounds, and a loop can end well before +the developer approves; the batch waits for the next status move, or +for a design document's consumption gate, whichever comes first. At +that gate the batch is settled before the integrity audit, since a +reversal edits the audited body and, like any fix wave, runs the +propagation gate. + +Each item is confirmed or reversed. A reversal is the developer's +ruling, so the session applies it at once and rewrites the line in +place: the token says what became of the document under the developer's +answer, and the authorizer is now theirs. Confirming converts the +authorizer alone. A rewrite in place keeps one home per finding, as the +held gate line's terminal rewrites already do. +On a move made on the developer's word, no `provisional:` survives, +and a document that moved with one still carrying it moved without its +batch. A move made under D4's project instruction carries its batch in +its report, and the lines stay `provisional:` until the developer +answers it; converting or rewriting them on an `implemented` document +is a process record, which the frozen body excepts. + +A line a plan review writes into an already-consumed design spec, by +the lifecycle rule's cross-document clause, would find no later +consumption gate there. It travels in the plan's batch instead, and the +developer's one answer converts or rewrites both lines. + +## Status moves + +The lifecycle rule already treats approval as the developer's — "the +developer has approved the plan (the `status` flip to `approved`)" — +but says nothing of who may move a status to `implemented`. The +analysis found a session that did so on its own recommendation, with +the code review skipped. D4 states the owner for every move. + +Some projects hand a move to the session. In one, a manager session +merges a verified package and closes its plan. A note in the project's +instructions that names the move keeps that working — no settings key +records a status move — and the batch then reaches the developer in the +merge report, and a reversal there is work before the next +package rather than a blocked merge. + +## Implementation + +During implementation an implementer asks questions no document +settles, and a session that answers each one alone takes a provisional +decision every time. Holding each for the developer would interrupt them +constantly, which the stand-in decision rejected. So the session +answers, records the answer as provisional, and the batch at the +`implemented` move carries it. + +An implementation has no ledger, and its batch may fall due sessions +later, so the record cannot be the session's memory. The session writes +each decision when it takes it to a file in the dispatch-record store, +which survives compaction. The store belongs to one checkout, and the +`implemented` move may happen in another, so the session that took the +decisions relays the list in its closing report; the file is only the +net under its own compaction. An execution skill may +keep its own list — superpowers' inline executor ends with "Rulings I +made" — and the relay calls those items provisional, since the +developer made none of them. + +A skipped process step is no provisional decision. Every step is an +offer the developer declines, and D4 keeps the `implemented` move +theirs, which is what the analysis found missing. + +## Asks that only read + +Every case in the fourth finding has one shape: the developer asked for +an answer, stated a fact or requested one change, and the session +changed something more. The +reversals all followed a change of state — an org write, a deploy, a +commit, a push, a release — and never a read. + +So the line runs by effect, not by tool. Reading is always allowed: a +session that needs an agent to gather data or analyse a corpus may +dispatch one on a question. A change of state needs a request for that +change, and a request reaches no further than its object: "merge" asks +for a merge, not a release. A consent the developer gave — in this +session, as a Standing answer, or by project instruction — such as the +loop's per-round commits, is such a request and keeps working. + +An ambiguous request names the change but not its object — "commit +mise.html and push" when no such file is tracked. The session asks which +object is meant; a guess acted on is a change nobody requested. + +## Parts touched + +- `plugins/working-process/rules/workflow.md` — D2 and D3 in the review + loop, D3's batch named *the provisional batch* to keep it apart from + the per-round held batch; D7 in *Re-dispatch briefs*' protection list + and the oscillation tripwire, and its no-license clause in triage's + list of what licenses a fix; D5 under step 6; D6 as a section beside + *Credentials*. +- `plugins/working-process/rules/spec-plan-lifecycle.md` — the + `provisional:` clause in the clause table under *The disposition + ledger* and the terminal-line definitions (D1, D3); the status-move + owner (D4), in one place for every move; D7 beside the re-raise + protection; the consumption gate's backstop sentence gains + `provisional:` lines beside `held` and `hit held` for a judged + document only, never a plan's passage to implementation (D3). +- `docs/domain/glossary.md` — **Provisional decision** and **Stand-in**; + **Ruling** gains a pointer to its provisional counterpart. +- `plugins/working-process/CHANGELOG.md` — an `## Unreleased` entry. + +## Out of scope + +- How a stand-in is reached (Codex CLI, a pasted reply). The developer's + own instructions cover the mechanics. +- A check that a status moved with no `provisional:` line left. The + process-status skill could report it later; nothing here requires it. +- The harness's own guidance on irreversible actions. D6 narrows the + cases the analysis found — a question, a fact, a request exceeded — + and does not restate the rest. + +## Review rounds + +### 2026-11-14 — architect, fable 5.2, blocking (round 1, full-document) + +- hit fixed 2026-11-14 — *Parts touched* named an "authorizer table" the lifecycle rule does not have; it now names the clause table under *The disposition ledger* +- hit fixed 2026-11-14 — *Problem* said two of the three reversals came from the stand-in while the verification confirms one; it now says at least one, probably two +- fixed 2026-11-14 — [Important] F1: D2 hands the stand-in round orders and cap and all-Minor escalations, which have no ledger line, cannot be reversed, never reach the batch and lift every spend bound; ruling: 2026-11-14; D2 and *The stand-in* narrow the stand-in to held findings and held hits, loop control stays the developer's, a stand-in answer is not developer contact +- fixed 2026-11-14 — [Important] F2: a stand-in answer to a held hit can withdraw or defer a registered decision, whose grammars (`withdrawn …, ruling:`, `**Defers:** …; ruling:`) and `decision-coverage.py` know only `ruling:`; ruling: 2026-11-14; D2 keeps withdrawing and deferring a registered decision with the developer +- fixed 2026-11-14 — [Important] F3: D1's "a session's choice to skip a process step" lets a session skip any gate provisionally, reverses "every step is an offer … let the developer decline", and has no record outside implementation; ruling: 2026-11-14; D1 drops the skipped step, *Implementation* says why +- fixed 2026-11-14 — [Important] F4: no rule says when a judged document moves to `approved`, the consumption gate passes on `provisional:` lines, and D3's list omits the technical design and a spec's `implemented` move; ruling: 2026-11-14; D3 names the next status move and, for a judged document, no later than its consumption gate; *The batch* argues it +- fixed 2026-11-14 — [Important] F5: D5 keeps implementation-time decisions in the session's account, a memory across compaction, under a heading "Rulings I made"; ruling: 2026-11-14; D5 writes each decision when taken to `.claude/working-process//provisional.md`, a skill's own list is relayed as provisional +- fixed 2026-11-14 — [Important] F6: "standing consent" collides with glossary **Standing answer** (a settings line) and names no home; ruling: 2026-11-14; D4, D6, *Status moves* and *Asks that only read* say Standing answer or project instruction, no new term +- fixed 2026-11-14 — [Minor] F8: nothing says a `provisional:` line, or text its fix wrote, licenses no later fix; ruling: 2026-11-14; D7 and *Provisional decisions* add that neither the line nor its text licenses a fix until confirmed +- fixed 2026-11-14 — [Minor] F9: two cases in finding 4 are requests exceeded, not questions, and the ambiguous-object rule has no register entry; ruling: 2026-11-14; D6 opens with an ask licensing only what it asks for, a request reaches no further than its object +- fixed 2026-11-14 — [Minor] F7: *The batch*'s "no `provisional:` survives the status move" is false under D4's report; license: D4; *The batch* scopes the invariant to moves made on the developer's word +- fixed 2026-11-14 — [Minor] F10: D3's fixed↔declined rewrite reads as binary while finding 2 was a narrowing; license: D3 ("the terminal state that answer gives"); D3's two cases are now examples, including a narrowing +- signal 2026-11-14 — another round only after the developer rules on F1–F6, a diff-scoped one over the rewritten D1–D3; the Minors are worth a sentence each and no round +- hit fixed 2026-11-14 — the intro still named a skipped step among the decisions a session takes unseen, after F3 dropped it; it now names a status move +- hit fixed 2026-11-14 — D4, *The batch* and *Status moves* let a Standing answer name a status move, while a Standing answer is a settings line and no registered key records one; they now name a project instruction alone, D6 and *Asks that only read* keep Standing answer, which the per-round commits exemplify +- hit fixed 2026-11-14 — the F10 rewrite dropped D3's reversed-`declined` case; D3 carries it again beside the narrowing +- hit dismissed 2026-11-14 — the `provisional:` chain names no reading surface; counter: the reader is the session gathering the batch at the status-move request, which D3 puts into workflow.md's review loop, and *Out of scope* defers a process-status check by design +- hit dismissed 2026-11-14 — the round-1 signal says "rewritten D1–D3" while the wave touched D1–D7; counter: a signal records what the reviewer judged at the time, and the reviewer foresaw D1–D3 as the rewrite +- hit dismissed 2026-11-14 — D5 puts `provisional.md`, not a dispatch record, into the dispatch-record store; counter: the record naming grammar governs records only, the store is the per-checkout git-ignored home that survives compaction, and D5 mints the file by name +- hit fixed 2026-11-14 — a gate line placed the per-round commits example in D6, where only *Asks that only read* carries it; the line now names both +- hit fixed 2026-11-14 — *Problem* called the second reversal "the settings tabs" while the records name tab switching on a page; relabelled + +### 2026-11-14 — architect, fable 5.2, blocking (round 2, diff-scoped) + +- fixed 2026-11-14 — [Important] F11: D5's file lives in a per-checkout store, so a batch is lost silently when the `implemented` move happens in another checkout, as in the manager case *Status moves* names (re-raises F5 with new evidence); ruling: 2026-11-14; D5 and *Implementation* make the deciding session relay the list in its closing report, the file only the compaction net +- fixed 2026-11-14 — [Important] F12: *The batch*'s "the lines convert once the developer has read it" writes `ruling:` without the developer's word; license: D3 and the second anti-goal; *The batch* converts the lines on the developer's answer +- fixed 2026-11-14 — [Minor] F13: D6's "Standing answer" excludes an unrecorded session consent the old "standing consent" covered; license: the workflow rule's session-scoped answers; D6 and *Asks that only read* name a consent given in this session, as a Standing answer or by project instruction +- fixed 2026-11-14 — [Minor] F14: D6's "nothing past it" is unqualified, and *Out of scope* still describes the old D6; license: *Problem* finding 4; D6 forbids a further act with its own effect, *Out of scope* describes the new D6 +- fixed 2026-11-14 — [Minor] F15: D7's reversal clause names `license:` lines the prohibition beside it makes impossible (re-raises F8 with new evidence); ruling: 2026-11-14; the reversal clause is cut from D7 and *Provisional decisions* +- fixed 2026-11-14 — [Minor] F16: D3's consumption-gate clause has no site in *Parts touched*; license: D3; *Parts touched* adds the lifecycle backstop sentence, which gains `provisional:` lines +- signal 2026-11-14 — no further round earns its cost unless F11 takes the main-checkout mechanism; the Minors are a sentence each, the integrity-class items go to the consumption-gate audit +- hit fixed 2026-11-14 — F13's clause said *Asks that only read* names the three consent sources while only D6 did; the section now names them +- hit dismissed 2026-11-14 — the glossary has no **Stand-in** or **Provisional decision** entry; counter: *Parts touched* prescribes both entries and the **Ruling** pointer, which land with the implementation From d5ba154934f3053484a8d24258f8293204c5461c Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 16:23:47 +0100 Subject: [PATCH 12/59] feat(working-process): stand-in, provisional decisions and asks that only read --- docs/domain/glossary.md | 21 ++++- plugins/working-process/CHANGELOG.md | 14 ++++ .../rules/spec-plan-lifecycle.md | 21 ++++- plugins/working-process/rules/workflow.md | 78 ++++++++++++++++++- 4 files changed, 127 insertions(+), 7 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 63430f9..cfbd1d9 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -389,9 +389,28 @@ 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 with `provisional: ()` +on its disposition line or in 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. 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 diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index e89f119..ddbc09d 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -21,6 +21,20 @@ Released versions of this plugin, newest first. its change since the previous round. - While drafting a design spec, the session asks for a size target, what is dropped, what native behaviour covers and the accepted risks. +- The developer may name a stand-in for the session. It answers held + findings, its answers take effect at once as provisional decisions + (`provisional: (stand-in )`), and the developer confirms + or reverses them in one provisional batch at the document's next + status move, or at a design document's consumption gate. Loop + control, held gate hits, mechanism holds, adjudication, withdrawals, + deferrals and status moves stay the developer's. +- Implementation-time answers no document settles are provisional too: + written to `.claude/working-process//provisional.md` and + relayed in the closing report. +- Every `status` move is the developer's, or a project instruction's + that names the move. +- A question or a stated fact licenses reading only; a request licenses + the change it names and no further act with its own effect. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 2e84f36..f61407e 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -49,6 +49,13 @@ base: master # optional: branch the topic branch was cut from - `status` is linear and moves forward only. Review rounds are iterative and live in their own fields; `grilled`, `architect`, and `adversary` appear only once the corresponding step has run. +- Every `status` move is the developer's: it happens on their word, or + under a note in the project's instructions that names that move. + Under such a note the provisional batch the workflow rule defines + goes into the report announcing the move, and its lines stay + `provisional:` until the developer answers; converting or rewriting + them on an `implemented` document is a process record, which the + frozen body below excepts. - An `implemented` document records what shipped at its release, and the surfaces it named are the current truth. Never build from one without diffing it against those surfaces first — the document is the archive, @@ -519,9 +526,11 @@ annotates a verdict, while `resolved ` annotated a finding. tripwire's named flip is that evidence. - `fixed ` — the document changed on account of this finding. Its authorizer says who decided: `license:` where the session cited a - written decision, `ruling:` where the developer did. + written decision, `ruling:` where the developer did, `provisional:` + where a stand-in did. - `declined ` — the document stands. It always carries `ruling:`, - because declining is a decision and triage gives a session no license + or `provisional:` where a stand-in declined it, because declining is + a decision and triage gives a session no license to decide. Each disposition line is written before the edit it describes, or with @@ -539,6 +548,7 @@ The leading token is a queryable state. Clauses are payload. |---|---|---| | `license: ` | the written decision the session acted on | `fixed` | | `ruling: ` | the developer authorized it; on a fold, the prior ruling's date followed by `folding
` naming what it folds against | `fixed`, `declined` | +| `provisional: (stand-in )` | a stand-in the developer named decided it; it licenses nothing until the developer confirms it in the provisional batch, when it becomes `ruling:` | `fixed`, `declined` | | `question:` | the question, phrased so one short answer resolves it | `held` | | `options:` | the options and the session's recommendation | `held` | | `counter:` | the session's evidence where the finding is disputed or contested | `held` | @@ -777,6 +787,10 @@ A pre-design settled line carries no authorizer clause and is settled by its token alone; a fold against one cites the date on that token, which is when the developer decided. +A line carrying `provisional:` is not settled: it records nobody's +decision yet, so a re-raise against it is ordinary triage, as against a +`license:` line, and nothing here folds it. + State prevents relitigation, not the reviewer's memory. ## Unfinished-work list @@ -915,7 +929,8 @@ so the `integrity:` stamp sits on the design spec and names both. A document's consumption gate is the backstop for its ledger: no judged document passes to plan-writing, nor a plan to implementation, while -`held` lines or `hit held` gate lines stay open — an LGTM can leave the +`held` lines or `hit held` gate lines stay open, nor a judged document +while its `provisional:` lines do — an LGTM can leave the frontmatter clean while a decision question still pends, so the gate asks those questions at the latest. A `hit held` line blocks until the gate has re-run and rewritten it to a terminal shape, since declining diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 9ed18b5..733e823 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -144,7 +144,21 @@ disables its suggestion — never the work itself. family below for small mechanical ones — named explicitly. 6. **Implementation.** Test-driven when superpowers:test-driven-development is available; bugs go through - superpowers:systematic-debugging when available. + superpowers:systematic-debugging when available. A question no + document settles — an implementer's, or the session's own while it + executes a plan — is answered by the session, and the answer is a + provisional decision, defined under *The stand-in and the + provisional batch* below. It is written when taken to + `.claude/working-process//provisional.md`, `` being the + plan's basename or, where no plan exists, the design spec's: one + line per decision — date, question, answer, author (`session` or + `stand-in `) — under the dispatch-record store's `.gitignore` + guard, and no ledger line is written. The session that took them + relays the list in its closing report; an answer there settles an + item and is appended to its line, and the provisional batch at the + `implemented` move carries what is still unanswered. An execution + skill's own list, such as superpowers' "Rulings I made", is relayed + as provisional decisions too. 7. **Implementation → code review.** When a `*-code-review` skill is installed for a domain the change touches, offer a review of the work's diff — once implementation is complete and before the plan's @@ -244,6 +258,22 @@ Never read a credential's value — `gh auth token`, a token or key file, a keyring — or write one into a command. Report a check that needs authentication the developer did not provide as not checked. +## Asks and their reach + +An ask licenses only what it asks for. A question or a stated fact asks +for an answer: it licenses reading, with any tool, agents included, and +never a change of state — an edit, a commit, an agent that writes, a +push, a deploy, a write to a remote system, a release. A request +licenses the change it names, on the object it names, and no further +act with its own effect: "merge" asks for a merge, not a release. Where +the object is ambiguous — a named file that does not exist — ask which +is meant; a guess acted on is a change nobody requested. Any other +change needs a request for it, or a consent that covers it — given in +this session, as a Standing answer, or by project instruction, such as +the review loop's per-round commits; where one looks needed, propose it +and wait. Records these rules owe — ledger lines, dispatch records, the +implementation's provisional list — are no change an ask must name. + ## Branch naming Feature work happens on a topic branch named @@ -474,7 +504,9 @@ decision. Consequences the loop states outright: recorded developer decision. - Only written decisions license fixes. A decision settled in conversation becomes citable by being written into the document, - which the fix itself accomplishes. + which the fix itself accomplishes. A line carrying `provisional:` + licenses nothing until the developer confirms it, and neither does + the text its fix wrote. - A finding whose `origin` names a judged document — a design spec or a technical design — is held unless a written decision licenses the edit, since changing either from inside a plan review is design work. @@ -521,6 +553,41 @@ Once the licensed fixes land, the loop either continues or yields: One batch per round is the contract: the developer is interrupted once per round, and only over a decision that is genuinely theirs. +### The stand-in and the provisional batch + +The developer may name a *stand-in* in conversation — another agent or +tool that answers for them — for the rest of the Claude Code session; a +session that loses the delegation on compaction asks again rather than +guess. The stand-in answers the held findings a round would put to the +developer, and each answer is a *provisional decision*: it takes effect +at once, and its disposition line carries +`provisional: (stand-in )` where the developer's answer +would carry `ruling:`. An answer covers only the question put to it; a +later event needs a new question. A stand-in may answer a `blocking` +round's held findings, whose fixes land while the loop stays stopped. +Every other act stays the developer's: round orders, cap and all-Minor +escalations, a round after `blocking`, held gate hits, a fix the +mechanism hold stops, adjudicating a `blocking` verdict, withdrawing or +deferring a registered decision, and moving a `status`. A stand-in's +answer is not developer contact, so it resets no cap. + +Provisional decisions reach the developer as one *provisional batch*: +every line under the document's `## Review rounds` whose authorizer is +`provisional:`. It is delivered with the request for the document's +next status move, and for a design spec or a technical design no later +than its consumption gate, settled there before the integrity audit +since a reversal edits the audited body. An approval given before the +request still gets the batch first. A line a plan review writes into an +already-consumed judged document travels in the plan's batch, and one +answer settles both lines. The developer confirms or reverses each +item. Confirmed, `provisional:` becomes `ruling: `, the date of +the answer. Reversed, the session applies the answer at once and +rewrites the line in place to the terminal state the answer gives — a +reversed `fixed` may become `declined` or stay `fixed` with narrower +text, a reversed `declined` becomes `fixed` — carrying `ruling:`, and +runs the propagation gate over the change as after any fix wave. A move +made on the developer's word leaves no `provisional:` line behind. + ### The propagation gate When the `propagation-auditor` agent is available, a passing propagation @@ -626,6 +693,9 @@ context, never as a review target, and what that protects is narrow: footing; - `held` lines carry questions already put, so a round does not duplicate one; +- lines carrying `provisional:` record nobody's decision yet, so they + are not settled and a reviewer may re-raise them like `license:` + lines; - `fixed` lines carrying `license:` get no protection at all — the previous round's are the diff and are named as the first thing to attack, and older ones are simply unprotected, since a reviewer told @@ -696,7 +766,9 @@ evidence to attack, never a defence to protect. `license:` is never re-fixed autonomously. Two readings of one license are a contested reading, so it escalates as held, the flip named. A re-raise against a line carrying `ruling:` is the relitigation case - instead, and the spec-plan-lifecycle rule owns it. + instead, and the spec-plan-lifecycle rule owns it. A line carrying + `provisional:` cites no license, so a re-raise against it goes + through ordinary triage and the tripwire does not apply. The cap guards spend and the signal guards sense; both escalate, and neither is a wall. Relay stays the developer's standing veto — every From 5f15cc280c4d71c3d7e719bf9808d9577134841d Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 16:25:54 +0100 Subject: [PATCH 13/59] fix(working-process): final-review fixes for delegation boundaries --- docs/domain/glossary.md | 8 +++++--- plugins/working-process/CHANGELOG.md | 3 ++- plugins/working-process/rules/spec-plan-lifecycle.md | 2 +- plugins/working-process/rules/workflow.md | 11 ++++++++--- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index cfbd1d9..dce3f45 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -397,8 +397,9 @@ _Avoid_: developer decision (as the name), developer fix 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 with `provisional: ()` -on its disposition line or in the implementation's provisional list, +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 @@ -406,7 +407,8 @@ _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. It never takes loop control, a held +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 diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index ddbc09d..2707078 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -25,7 +25,8 @@ Released versions of this plugin, newest first. findings, its answers take effect at once as provisional decisions (`provisional: (stand-in )`), and the developer confirms or reverses them in one provisional batch at the document's next - status move, or at a design document's consumption gate. Loop + status move, or at a design spec's or technical design's consumption + gate. Loop control, held gate hits, mechanism holds, adjudication, withdrawals, deferrals and status moves stay the developer's. - Implementation-time answers no document settles are provisional too: diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index f61407e..e0f37d1 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -548,7 +548,7 @@ The leading token is a queryable state. Clauses are payload. |---|---|---| | `license: ` | the written decision the session acted on | `fixed` | | `ruling: ` | the developer authorized it; on a fold, the prior ruling's date followed by `folding
` naming what it folds against | `fixed`, `declined` | -| `provisional: (stand-in )` | a stand-in the developer named decided it; it licenses nothing until the developer confirms it in the provisional batch, when it becomes `ruling:` | `fixed`, `declined` | +| `provisional: (stand-in )` | a stand-in the developer named decided it, on that date; it licenses nothing until the developer confirms it in the provisional batch, when it becomes `ruling:` | `fixed`, `declined` | | `question:` | the question, phrased so one short answer resolves it | `held` | | `options:` | the options and the session's recommendation | `held` | | `counter:` | the session's evidence where the finding is disputed or contested | `held` | diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 733e823..b71c610 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -548,7 +548,10 @@ Once the licensed fixes land, the loop either continues or yields: awaiting the developer, since a round over known-open decisions re-reports them at the loop's most expensive tier for no information. The developer may still order a round on the partial - document — every step is an offer. + document — every step is an offer. Where a stand-in is named, the + held findings go to it instead, and once its answers land the loop + continues as with the held set empty: a `provisional:` line awaits + only the provisional batch, never the next round. One batch per round is the contract: the developer is interrupted once per round, and only over a decision that is genuinely theirs. @@ -569,11 +572,13 @@ Every other act stays the developer's: round orders, cap and all-Minor escalations, a round after `blocking`, held gate hits, a fix the mechanism hold stops, adjudicating a `blocking` verdict, withdrawing or deferring a registered decision, and moving a `status`. A stand-in's -answer is not developer contact, so it resets no cap. +answer is not developer contact, so it resets no cap. During +implementation it may also answer the questions step 6 describes. Provisional decisions reach the developer as one *provisional batch*: every line under the document's `## Review rounds` whose authorizer is -`provisional:`. It is delivered with the request for the document's +`provisional:`, and at a plan's `implemented` move the unanswered items +of its provisional list. It is delivered with the request for the document's next status move, and for a design spec or a technical design no later than its consumption gate, settled there before the integrity audit since a reversal edits the audited body. An approval given before the From 3d697ef4b23eef10c995e8f9f74db6dcd9c86499 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 16:32:47 +0100 Subject: [PATCH 14/59] docs(working-process): delegation boundaries spec implemented --- docs/specs/2026-11-14-delegation-boundaries-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/2026-11-14-delegation-boundaries-spec.md b/docs/specs/2026-11-14-delegation-boundaries-spec.md index 11dfc51..d7bb757 100644 --- a/docs/specs/2026-11-14-delegation-boundaries-spec.md +++ b/docs/specs/2026-11-14-delegation-boundaries-spec.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-14 -status: approved +status: implemented decisions: registered architect: blocking (adjudicated 2026-11-14) integrity: 2026-11-14 (sha: 4d685b3) From 014191cdbed9f5b030741d8d7e0c4840dbc89996 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 16:34:25 +0100 Subject: [PATCH 15/59] chore(working-process): dogfooding version for delegation boundaries --- plugins/working-process/.claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index 99d4514..3e9daf2 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.20.0-dev.5.cost-discipline", + "version": "0.20.0-dev.6.delegation-boundaries", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], From 8decb9511a296d4fe1a0aee9b71257b63db8b561 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 17:12:36 +0100 Subject: [PATCH 16/59] fix(working-process): transcript model check, extracted dispatch records, designer-session trigger --- plugins/working-process/.claude-plugin/plugin.json | 2 +- plugins/working-process/CHANGELOG.md | 7 +++++++ .../working-process/rules/spec-plan-lifecycle.md | 9 ++++++++- plugins/working-process/rules/workflow.md | 13 +++++++++++-- .../skills/system-designer-session/SKILL.md | 2 +- 5 files changed, 28 insertions(+), 5 deletions(-) diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index 3e9daf2..f98493a 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.20.0-dev.6.delegation-boundaries", + "version": "0.20.0-dev.7.dispatch-errata", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 2707078..7105633 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -36,6 +36,13 @@ Released versions of this plugin, newest first. that names the move. - A question or a stated fact licenses reading only; a request licenses the change it names and no further act with its own effect. +- The dispatcher checks a verdict or audit run's model against the + model the agent's transcript records, not only its self-report; with + no readable transcript the check is reported as unchecked. +- A dispatch record is extracted from the agent's transcript with a + published `jq` command instead of being retyped. +- `system-designer-session` also opens when the workflow's + technical-design step routes to it, not only on an explicit ask. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index e0f37d1..a51e20c 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -152,7 +152,14 @@ base: master # optional: branch the topic branch was cut from - Verdict agents self-report the model they ran on (family plus version); the dispatcher compares it against the dispatched and prescribed tiers before stamping, and each round's verdict, model, and date are - recorded in the document body. Committed examples of the bare fallback form use + recorded in the document body. A self-report cannot reveal a + substituted model — thirteen runs dispatched on one family ran on + another while reporting the dispatched one — so where the agent's + transcript is readable (in Claude Code, the task's output file) the + model the API recorded decides the comparison: + `jq -r 'select(.type=="assistant") | .message.model' | sort -u`. + Without a readable transcript, or where the command prints nothing, + the comparison is reported as unchecked, never as a match. Committed examples of the bare fallback form use placeholders (as above) so they never match the list below. - `branch` and `base` appear once the topic branch exists — never guessed up front, omitted entirely when there is no topic branch. diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index b71c610..b80495f 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -199,7 +199,8 @@ on the most capable available, each named explicitly; the key's value is a tier, never a model name, and Claude Code resolves it through the table below this paragraph. Both reports open with a model self-report the dispatcher compares against the dispatched -and the prescribed rung before relying on the result — a mismatched +and the prescribed rung before relying on the result, the transcript's +model deciding where the lifecycle rule says it does — a mismatched propagation run earns no reliance, and a below-tier integrity run gets no stamp. When a dispatch is refused because the dispatched model's cap is hit — and only then; any other failure is an ordinary @@ -342,7 +343,15 @@ available: loop. The order has one named exception, defined under *What a diff-scoped LGTM certifies* below: a plan's diff-scoped LGTM. - The dispatch record is written before the relay. The dispatcher - saves what the agent returned, verbatim, under a header of the date, + saves what the agent returned, verbatim — extracted from the agent's + transcript, never retyped, since a retyped record once shared none of + its 23 lines with the report it claimed to hold. In Claude Code the + task's output file is that transcript, and the report is the + hand-back call's message: + `jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="SubagentHandback") | .input.message' `. + Where that prints nothing, the agent's final assistant text is the + report; where no transcript is readable, the record says it was + copied from the relay. It goes under a header of the date, the agent, the model self-report, the subject, and — where a document was reviewed — its size, `size: `: the body's line count without the `## Review rounds` section, from diff --git a/plugins/working-process/skills/system-designer-session/SKILL.md b/plugins/working-process/skills/system-designer-session/SKILL.md index a9cfe28..bc45afa 100644 --- a/plugins/working-process/skills/system-designer-session/SKILL.md +++ b/plugins/working-process/skills/system-designer-session/SKILL.md @@ -1,6 +1,6 @@ --- name: system-designer-session -description: "In-session consultation with the system designer persona — interactive work on what a design is made of: parts, contracts, state, behaviour under load, observability, technology choice. Use ONLY when the developer explicitly asks to talk to the system designer (\"ask the designer\", \"system designer session\"); generic design questions belong to brainstorming. For a second opinion from a fresh context unshaped by this conversation, dispatch the system-designer-consult agent instead — this skill can assemble its briefing." +description: "In-session consultation with the system designer persona — interactive work on what a design is made of: parts, contracts, state, behaviour under load, observability, technology choice. Use when the developer explicitly asks to talk to the system designer (\"ask the designer\", \"system designer session\"), or when the workflow's technical-design step opens it; generic design questions belong to brainstorming. For a second opinion from a fresh context unshaped by this conversation, dispatch the system-designer-consult agent instead — this skill can assemble its briefing." --- Consultation surface of the system designer persona — the interactive From 1bd665af0c12b0e6a6938331b871905bd2275722 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sat, 14 Nov 2026 17:14:48 +0100 Subject: [PATCH 17/59] fix(working-process): review fixes for dispatch errata --- plugins/working-process/CHANGELOG.md | 4 ++-- plugins/working-process/rules/spec-plan-lifecycle.md | 10 +++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 7105633..86d2f81 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -39,8 +39,8 @@ Released versions of this plugin, newest first. - The dispatcher checks a verdict or audit run's model against the model the agent's transcript records, not only its self-report; with no readable transcript the check is reported as unchecked. -- A dispatch record is extracted from the agent's transcript with a - published `jq` command instead of being retyped. +- A verdict agent's dispatch record is extracted from the agent's + transcript with a published `jq` command instead of being retyped. - `system-designer-session` also opens when the workflow's technical-design step routes to it, not only on an explicit ask. diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index a51e20c..56559ee 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -156,10 +156,14 @@ base: master # optional: branch the topic branch was cut from substituted model — thirteen runs dispatched on one family ran on another while reporting the dispatched one — so where the agent's transcript is readable (in Claude Code, the task's output file) the - model the API recorded decides the comparison: + model the API recorded, read as its family, decides the comparison: `jq -r 'select(.type=="assistant") | .message.model' | sort -u`. - Without a readable transcript, or where the command prints nothing, - the comparison is reported as unchecked, never as a match. Committed examples of the bare fallback form use + Where it differs from the self-report, the record, the round heading + and the relay carry the transcript's model, the self-report beside it + in parentheses. Without a readable transcript, or where the command + prints nothing, the self-report comparison runs as before and the + relay calls it unchecked, never a match. Committed examples of the + bare fallback form use placeholders (as above) so they never match the list below. - `branch` and `base` appear once the topic branch exists — never guessed up front, omitted entirely when there is no topic branch. From 28448044f744cb25273c201b98118b43ca722246 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sun, 15 Nov 2026 00:25:28 +0100 Subject: [PATCH 18/59] fix(working-process): consultation briefing without a recommendation, measured numbers, model self-report --- plugins/working-process/CHANGELOG.md | 6 ++++++ plugins/working-process/PERSONA_COMMON.md | 8 ++++++++ plugins/working-process/agents/architect-consult.md | 3 +++ plugins/working-process/agents/system-designer-consult.md | 3 +++ plugins/working-process/rules/workflow.md | 4 +++- 5 files changed, 23 insertions(+), 1 deletion(-) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 86d2f81..e344873 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -43,6 +43,12 @@ Released versions of this plugin, newest first. transcript with a published `jq` command instead of being retyped. - `system-designer-session` also opens when the workflow's technical-design step routes to it, not only on an explicit ask. +- A consultation's briefing leaves out the dispatcher's own + recommendation. +- A consultation reply opens with a model self-report, backs a number + that carries a recommendation with a measurement or marks it + `assumed`, and mentions an absent glossary or ADR directory only + where a judgement depended on it. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/PERSONA_COMMON.md b/plugins/working-process/PERSONA_COMMON.md index 42c3bb0..c6be8af 100644 --- a/plugins/working-process/PERSONA_COMMON.md +++ b/plugins/working-process/PERSONA_COMMON.md @@ -101,6 +101,8 @@ The briefing — the dispatcher's obligations: leaves the persona guessing from the dispatch's working directory; - point, don't paste: name files and areas rather than inviting exploration — what a consultation reads is what it costs; +- put the question without the dispatcher's own recommendation: a + persona handed an answer tends to return it; - when both personas are consulted on one subject: one canonical briefing text given to both, each with its own focusing question appended, and no cross-persona content — neither is told what the other said. A @@ -120,6 +122,12 @@ from it is stamped into frontmatter: per focusing question — or one per briefing, where none was appended — and the path to the record; the workflow rule defines that record and names it; +- a number that carries a recommendation — a row count, a volume, a + latency — is measured in the subject's own data, with the command + shown, or marked `assumed`; a recommendation resting on an assumed + number names the measurement that would overturn it; +- an absent glossary or ADR directory is mentioned only where a + judgement depended on it, never as a standing opening; - disagreement between the personas is presented as a disagreement, with both positions — the choice is the developer's; the relaying thread may add its own opinion, marked as its own; diff --git a/plugins/working-process/agents/architect-consult.md b/plugins/working-process/agents/architect-consult.md index 38e24aa..ab96019 100644 --- a/plugins/working-process/agents/architect-consult.md +++ b/plugins/working-process/agents/architect-consult.md @@ -33,6 +33,9 @@ than from any summary. Treat a settled decision as settled unless it contradicts a recorded ADR, which the glossary duty tells you how to handle. +Open the reply with a one-line **model self-report** — the model this +consultation actually ran on, as family plus version (e.g. "opus 4.8"). + Work the dimensions of your own duty. Where the briefing carries no decomposition at all, say so and point at the system designer instead of filling the gap. End with the questions you would need answered next, and diff --git a/plugins/working-process/agents/system-designer-consult.md b/plugins/working-process/agents/system-designer-consult.md index 131a26d..568076d 100644 --- a/plugins/working-process/agents/system-designer-consult.md +++ b/plugins/working-process/agents/system-designer-consult.md @@ -31,6 +31,9 @@ than from any summary. Treat a settled decision as settled unless it contradicts a recorded ADR, which the glossary duty tells you how to handle. +Open the reply with a one-line **model self-report** — the model this +consultation actually ran on, as family plus version (e.g. "opus 4.8"). + Work the dimensions of your own duty and dismiss by name the ones that do not apply. End with the questions you would need answered next, and name plainly anywhere the briefing left you guessing — a briefing gap is worth diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index b80495f..b658099 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -219,7 +219,9 @@ Dispatching a consultation, when the consult agents are available: one dispatch, briefed once. The briefing names the subject and where it lives (the repo root at minimum), the constraints that bind it, and settled decisions separated from open questions — pointing at files -rather than pasting them. A follow-up is a fresh cross-check dispatch, +rather than pasting them. It puts the question without the session's +own recommendation, since a persona handed an answer tends to return +it. A follow-up is a fresh cross-check dispatch, never a resumption. When both personas are consulted on one subject, give both the same canonical briefing, each with its own focusing question appended, and tell neither what the other said. Dispatch as a From 9d1c3902d8b141c6fd03fb20a90f42deea1a564e Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sun, 15 Nov 2026 00:25:29 +0100 Subject: [PATCH 19/59] fix(working-process): plan-adversary walks domain checklists in diff-scoped rounds --- plugins/working-process/CHANGELOG.md | 2 ++ plugins/working-process/agents/plan-adversary.md | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index e344873..b1ce0fc 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -49,6 +49,8 @@ Released versions of this plugin, newest first. that carries a recommendation with a measurement or marks it `assumed`, and mentions an absent glossary or ADR directory only where a judgement depended on it. +- The plan-adversary walks the domain checklists in diff-scoped rounds + too. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/agents/plan-adversary.md b/plugins/working-process/agents/plan-adversary.md index a596ed3..a1879d5 100644 --- a/plugins/working-process/agents/plan-adversary.md +++ b/plugins/working-process/agents/plan-adversary.md @@ -50,7 +50,8 @@ plan touches — judged from its content and the repo's markers (e.g. its dimensions with the same rigor as the generic ones below. Domains without a checklist get the generic dimensions only, with the duty's remaining sources (other skills, then verified model knowledge) covering -the expertise. +the expertise. A diff-scoped round loads the same checklists and walks +them over the diff. ## Judged documents: decline From 8c2b37f4116dc04d551c7bb91bf7470604cafd58 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sun, 15 Nov 2026 00:25:29 +0100 Subject: [PATCH 20/59] fix(working-process): integrity stamp is read at the consumption gate alone --- plugins/working-process/CHANGELOG.md | 2 ++ plugins/working-process/rules/spec-plan-lifecycle.md | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index b1ce0fc..0b9e22b 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -51,6 +51,8 @@ Released versions of this plugin, newest first. where a judgement depended on it. - The plan-adversary walks the domain checklists in diff-scoped rounds too. +- The `integrity:` stamp is read at the consumption gate alone; one + gone stale after the plan was written owes no new audit. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 56559ee..dea967e 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -597,7 +597,9 @@ It carries no ordinal and no verdict, which keeps it out of the round cap's derivation and out of the Unfinished-work commands that anchor a round heading: it records a fix, not a round. Two stamps go stale as on any body edit — the `integrity:` hash stops matching, and the verdict -stops certifying the words that changed. The same heading serves a +stops certifying the words that changed. The `integrity:` stamp is +read at the consumption gate alone: one gone stale after the plan was +written is expected and owes no new audit. The same heading serves a register edit that a plan's held gate line licensed, on a design spec whose loop has closed at whatever verdict: the heading then names the plan whose gate held the hit, and that plan's terminal gate line names From e8a48f7ab39ea2e0bf817c7c8e13e0ddbf3ea088 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sun, 15 Nov 2026 00:25:29 +0100 Subject: [PATCH 21/59] fix(working-process): route a single-claim verification by its kind --- plugins/working-process/CHANGELOG.md | 2 ++ plugins/working-process/rules/workflow.md | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 0b9e22b..855f7d9 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -53,6 +53,8 @@ Released versions of this plugin, newest first. too. - The `integrity:` stamp is read at the consumption gate alone; one gone stale after the plan was written owes no new audit. +- A request to verify one claim goes to the propagation-auditor, a + scripted measurement or a consultation, never to a verdict agent. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index b658099..55bc769 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -243,6 +243,11 @@ disagreement with both positions, because a disagreement is the one thing in a contribution the developer must decide and the digest exists to raise decisions rather than bury them. +A request to verify one claim goes by the claim's kind: a mechanical +check to the `propagation-auditor`, an empirical one to a scripted +measurement, a judgment to a consultation. A verdict agent reviews a +document and is never dispatched to verify a single claim. + When `docs/domain/glossary.md` exists in the project, its canonical terms and `_Avoid_` bans bind design specs, technical designs, plans, code identifiers, and reviews. From 8ec3fbbb5022f286aa2840f1f256cb2e7345e8bd Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sun, 15 Nov 2026 00:25:29 +0100 Subject: [PATCH 22/59] docs(working-process): confirming-round wording in the workflow rule and glossary --- docs/domain/glossary.md | 5 +++-- plugins/working-process/CHANGELOG.md | 2 ++ plugins/working-process/rules/workflow.md | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index dce3f45..1676a54 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -580,8 +580,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 diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 855f7d9..50f4ec5 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -55,6 +55,8 @@ Released versions of this plugin, newest first. gone stale after the plan was written owes no new audit. - A request to verify one claim goes to the propagation-auditor, a scripted measurement or a consultation, never to a verdict agent. +- Wording: a full-document round "owes no confirming round", and a + plan's loop closes on its latest round heading. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 55bc769..3674520 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -830,11 +830,11 @@ diff-scoped LGTM heading, in the shape the spec-plan-lifecycle rule defines, and that annotation defeats the gate's re-ask. The other two paths write the same token. -For a plan the loop closes only when the latest verdict round was -full-document: whatever ends its rounds while the latest round heading +For a plan the loop closes only when the latest round heading is +full-document: whatever ends its rounds while that heading is diff-scoped, one confirming full-document round follows, and that round's verdict is the one stamped. A round already full-document owes -no successor — it is the close. The confirming round inherits the gating +no confirming round — it is the close. The confirming round inherits the gating of whatever ended the rounds. Where autonomy still stands — a diff-scoped `LGTM`, or a `concerns` inside the cap — the rules mandate the round, so it is no decision of the developer's and spends none of From 069258ba409f46d7710fb7e1b2a595989f906c74 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Sun, 15 Nov 2026 00:43:02 +0100 Subject: [PATCH 23/59] chore(working-process): dogfooding version for consult errata --- plugins/working-process/.claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index f98493a..3eebbca 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.20.0-dev.7.dispatch-errata", + "version": "0.20.0-dev.8.consult-errata", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], From dc34d0658596109b62cb96f45947e66c40cd4141 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 10:39:41 +0100 Subject: [PATCH 24/59] chore: record working-process settings and drop the CLAUDE.md declaration --- .working-process/.gitignore | 1 + .working-process/settings.md | 19 +++++++++++++++++++ CLAUDE.md | 9 --------- 3 files changed, 20 insertions(+), 9 deletions(-) create mode 100644 .working-process/.gitignore create mode 100644 .working-process/settings.md 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` From a50dbe875dc32b053caeb83f5661c682d0caccb8 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:12:11 +0100 Subject: [PATCH 25/59] docs(working-process): process context spec and plan --- docs/plans/2026-11-16-process-context-plan.md | 908 ++++++++++++++++++ docs/specs/2026-11-16-process-context-spec.md | 404 ++++++++ 2 files changed, 1312 insertions(+) create mode 100644 docs/plans/2026-11-16-process-context-plan.md create mode 100644 docs/specs/2026-11-16-process-context-spec.md 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..035bcd6 --- /dev/null +++ b/docs/plans/2026-11-16-process-context-plan.md @@ -0,0 +1,908 @@ +--- +ticket: none +date: 2026-11-16 +status: approved +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/specs/2026-11-16-process-context-spec.md b/docs/specs/2026-11-16-process-context-spec.md new file mode 100644 index 0000000..7cb6489 --- /dev/null +++ b/docs/specs/2026-11-16-process-context-spec.md @@ -0,0 +1,404 @@ +--- +ticket: none +date: 2026-11-16 +status: approved +grilled: 2026-11-16 +architect: concerns (resolved 2026-11-16) +integrity: 2026-11-16 (sha: a74a36c) +decisions: registered +branch: feature/process-context +base: develop +--- + +# Process context — load a rule where its reader needs it + +The working process ships two large rules. One loads into every session +of every project; the other loads whenever anyone, a background agent +included, reads a process document. Most of both is read by nobody at +the moment it loads. This spec moves text to the place and the moment +its reader needs it and changes no decision the text carries. It is +package 7 of the release queue. + +## Problem + +Measured on `develop`, 2026-11-15, in characters, rounded: + +| Rule | Loads | Size | +|---|---|---| +| `workflow.md` | every session, every agent | about 52,000 | +| `spec-plan-lifecycle.md` | any read of a design spec, technical design or plan | about 60,000 | + +`workflow.md` spends about 33,000 of its characters on `## Dispatching +a verdict agent` and its six subsections. Only a session that is about +to dispatch a review needs them; a session writing code in an unrelated +project pays for them anyway. + +`spec-plan-lifecycle.md` spends about 18,700 characters on the +disposition ledger and its gate lines, which matter only while a +round's findings are disposed, and about 5,600 on the Unfinished-work +list, which one skill reads by path. A background agent that reads a design spec receives the +whole rule, though it stamps nothing and disposes nothing. + +A measurement on 2026-11-15 shows the cost in one number: a Haiku agent that +read twenty lines of a design spec had four rules injected, and the run +used about 97,000 tokens. + +## Goals, non-goals, anti-goals + +Goals: + +- The always-loaded part of `workflow.md` is as small as the offers + allow — estimated at about 15,000 characters, from about 52,000. +- A read of a process document no longer loads the disposition ledger, + the Unfinished-work list or the per-round commit convention — + estimated at about 32,000 characters, from about 60,000. +- Text that serves one activity loads when that activity starts. + +Every figure in this spec is an estimate that sizes the change. None is +an acceptance threshold: no gate, audit or review re-derives one as a +count or fails the change on it. + +Non-goals: + +- Rules of other plugins. They are path-scoped already. +- A per-file size limit as a design constraint. The Claude Code + documentation describes one for path-scoped rules (40,000 characters + on a 200K context window); the agent measured above received a 59,541-character + rule whole, so the limit is not observed here and sets no target. +- Any change to what the process decides, offers or records, beyond + telling a moved text's reader where it now lives (D10). + +Anti-goals — the change fails, even if it works, when: + +- a moved sentence changes meaning, or a rule that bound a session + before no longer reaches it at the moment it applies, beyond what the + accepted risks below name; +- a pointer in a rule, card, skill, script or the glossary names a + section that no longer exists where it points; +- the change adds a loader, a hook or a settings key. + +Accepted risks, by the developer's decision (2026-11-16): + +- A session may skip reading an on-demand text and act from memory. + One sentence in the always-loaded rule names each read moment; no + mechanism enforces it. A brief written from memory may likewise omit + the ledger reference's path that D10 asks it to carry. Moments + outside the four that also lean on moved text — naming a stand-in + mid-session, reading a propagation report while authoring, a + completion notification after a compaction — rest on the same + pointer sentence. +- A verdict dispatch with no document, such as an architect asked a + bare question, rests on that sentence alone. +- A session that loads the installed rules without the plugin, or with + an older plugin that lacks the skill, cannot reach the moved text. + Every pointer sentence is conditional — "when the `review-loop` skill + is available" — as this repository's plugin-authoring convention + requires of rule text naming a skill. + +## Decisions + +- **D1** — Every piece of rule text has one of three homes, chosen by + who reads it and when: always loaded, loaded with a document class, + or read when an activity starts. Argued in *Three homes*. +- **D2** — The always-loaded `workflow.md` keeps the seven steps and the + cross-cutting text *The always-loaded rule* lists, and one sentence + per on-demand text naming its read moment. A step cut to its offer + loses no decision: a cut sentence moves to a named home or repeats + text that stays. Step 6 is no offer and stays whole but for its + pointers. Argued in *The always-loaded rule*. +- **D3** — The verdict-dispatch procedure, with the review loop, the + stand-in, the propagation gate, re-dispatch briefs, the terminators + and the diff-scoped LGTM, leaves `workflow.md` for a new skill, + `review-loop`, which a session invokes before it dispatches a verdict + agent, at a consumption gate, before a `status` move, and before it + writes a ledger line. Its `SKILL.md` is short and routes each moment + to the reference files it needs; the procedure is one reference. Its + description names the four moments. Argued in + *The dispatcher's procedure*. +- **D4** — The disposition ledger and its gate lines leave + `spec-plan-lifecycle.md` for a reference file of that skill. Argued + in *The dispatcher's procedure*. +- **D5** — The lifecycle rule splits by document class: a shared part + for all three classes, and one part each for what only a design spec, + only a technical design's audit pair, and only a plan needs. withdrawn + the gain after D4 and D6 does not repay three more rule files, + ruling: 2026-11-16 +- **D6** — More text leaves the path-scoped rule for the one activity + that uses it: the Unfinished-work list becomes a reference file of + the `process-status` skill; the per-round commit convention and the + relay-then-stamp sentence of *Lifecycle offers* join the + `review-loop` skill. Argued in *What leaves the lifecycle rule*. +- **D7** — The consultation paragraphs in `workflow.md` shrink to the + offer and a pointer; the contract in `PERSONA_COMMON.md` stays the + single text. Argued in *The always-loaded rule*. withdrawn an + installed rule cannot point at `PERSONA_COMMON.md` (D11), and about + 2,000 characters do not repay a pointer nobody can follow, ruling: + 2026-11-16 +- **D8** — Text moves verbatim; nothing is redrafted, the steps of + `workflow.md` included. A move is verified by diffing the moved text + against its source, and every pointer by resolving it. Argued in + *Verification*. withdrawn D2 shortens the steps, so text no longer + moves verbatim everywhere, ruling: 2026-11-16 +- **D9** — The home for text read when an activity starts is a skill, + never a file among the installed rules. Argued in *Three homes*. +- **D10** — The brief of any agent dispatched on a document carrying a + `## Review rounds` section — a reviewer or an auditor — gives it the + path of the ledger reference and asks it to read it, since it no longer + receives the ledger grammar with the document. Argued in *The + dispatcher's procedure*. +- **D11** — A pointer in an installed rule to text that lives in a + skill names the skill and its reference file, conditionally ("when + the skill is available"), never by path: an installed rule cannot know the + plugin's versioned directory. Only a session that invoked the skill + knows the absolute path, and it passes that path on where a brief + needs it (D10). Argued in *Three homes*. +- **D12** — Text that moves whole (D3, D4, D6) moves unchanged but for + its pointers, and is diffed against its source. Argued in + *Verification*. +- **D13** — Ticket directories, with the procedure for moving a + document into one, stay in the lifecycle rule. Argued in *What leaves + the lifecycle rule*. +- **D14** — The implementation rewrites the glossary's **Unfinished-work + list** entry to name its new home. Argued in *What leaves the + lifecycle rule*. +- **D15** — The plugin's identity surfaces name the new skill: + `plugin.json`, the marketplace catalog entry and the repo README row. + Argued in *Verification*. + +## Three homes + +| Home | Reader | Mechanism | +|---|---|---| +| Always loaded | every session | a rule without `paths:` | +| With a document class | whoever reads that document | a rule with `paths:` | +| When an activity starts | the session doing it | a skill, invoked on a pointer | + +The test for a piece of text: *who needs this, and what are they doing +when they need it?* A background agent reading a design spec needs the +frontmatter contract and nothing about dispatching. A session about to +dispatch needs the whole procedure and has no reason to hold it before. + +The second home uses `paths:`, which Claude Code loads on a read of a +matching file. The patterns are the lifecycle rule's own, the brace +pattern `docs/**/*-{spec,technical-design,plan}.md` included, so +documents in a ticket directory match. + +The third home is a skill, by the developer's decision (2026-11-16). +Claude Code's own guidance for task-specific instructions that need not +sit in context is a skill, loaded when invoked. A skill ships and +updates with the plugin, so it cannot go stale the way an installed +rule copy does until the next `sync-rules`; and a file among the +installed rules would need a `paths:` matching nothing to stay +unloaded. The price is one skill description, always in context. + +A pointer to the third home names the skill and the reference file — +"when the `review-loop` skill is available, its ledger reference" — and +never a path. Rules +install under the home directory while a skill lives in the plugin's +versioned cache directory, so a written path goes stale at the next +release. A session that invoked the skill has its base directory and +can pass the absolute path to an agent's brief. + +## The always-loaded rule + +`workflow.md` keeps: + +- the seven numbered steps, each but step 6 cut to its offer: what is offered, + when, and which tool makes it available; +- model selection and the tier table; +- Credentials, Asks and their reach, Branch naming; +- the glossary and elements-of-style paragraphs, the ticket-directory + paragraph, and the verify-routing sentence; +- one pointer sentence per on-demand text. + +A step cut to its offer loses no decision. Each cut sentence either +moves to a named home or repeats text that stays; it never leaves with +the decision it carries. + +Step 4 is the largest step, at about 5,900 characters: it carries the +technical-design offer's declaration rules and the audit pair's +sequencing. The offer stays. The sequencing moves to the `review-loop` +skill, whose reader is the session at the consumption gate — one of +its read moments — and not every reader of a document. + +Step 6 is no offer. It is the only home of the provisional list: its +path, its line shape and the duty to relay it. It stays whole; only its +pointers into moved text are rewritten. Its pointer to the record +store's `.gitignore` guard gives way to the guard itself, stated inline +— a `.gitignore` containing exactly `*` — so writing the provisional +list needs no read of the skill. + +The two consultation paragraphs stay as they are. They are the +dispatcher-facing copy of the contract in `PERSONA_COMMON.md`, and the +two are edited together. An installed rule cannot name that file's +path, and the paragraphs cost about 2,000 characters. One pointer in +them changes: the record name they borrow from the dispatch +subsection is stated inline — `--.md`, under a +`.gitignore` containing exactly `*` — since dispatching a consultation +is none of the read moments. + +## The dispatcher's procedure + +`## Dispatching a verdict agent` and everything under it, with the +disposition ledger and its gate lines, form one text with one reader: +the session running a review loop. They become the `review-loop` skill. +Its `SKILL.md` is short: for each read moment it names the reference +file to read. Two reference files sit beside it — the dispatch +procedure and the ledger grammar. A single body would run to about +9,000 tokens, while Claude Code advises keeping `SKILL.md` under 500 +lines and, after a compaction, re-attaches only the first 5,000 tokens +of each invoked skill; the terminators would drop silently. A short +body survives a compaction whole and tells the session to invoke the +skill again, which re-reads the references it routes to; a ledger-line +write reads the grammar without the procedure. The skill's description names the four read moments, +since where the rules were never synced it is the only trigger. The session invokes it at four moments, the first in a +conversation and again after a compaction: before it dispatches a +verdict agent, at a consumption gate, before a `status` move, and before +it writes a ledger line. The last three can come with no round in +sight — the pair offer lives in the procedure and its +`, debt discharged` annotation in the ledger grammar, so a consumption +gate reads both references; a `status` move delivers the provisional batch, and an +answer to a held batch, given in a later session, is written as a +`ruling:` line before anything is dispatched. The skill carries +instructions and nothing else — it dispatches no agent and runs no +round. + +The four read moments are listed in three places: the always-loaded +pointer sentence, the skill's description and its `SKILL.md`. The three +are edited together. + +The two rules today promise to keep the relay-then-stamp ordering in +step: the dispatch subsection of `workflow.md` and one sentence of +*Lifecycle offers*, with the plan's diff-scoped LGTM exception. That +sentence is the dispatcher's procedure too, so it joins the skill +(D6), and with both halves in one home the promise to edit them together ends. + +Background agents stop receiving this text. Reviewers and auditors read +the documents they judge; none dispatches. One reader still needs the +ledger grammar: a reviewer or auditor whose document carries a `## Review rounds` +section — a diff-scoped round, a plan's confirming round, a pair +offer's round arm, a new loop after a close — reads the ledger and must +tell a settled `ruling:` line from a `provisional:` or `license:` one. +Its brief gives the path of the skill's ledger reference and asks the +reviewer to read it. + +## What leaves the lifecycle rule + +The lifecycle rule stays one rule for all three document classes. Besides +the ledger (D4), three pieces of text have one reader each and leave it: + +- the Unfinished-work list, which the `process-status` skill reads by + path today, becomes that skill's reference file; +- per-round commits on a document branch belong to the loop and join + the `review-loop` skill; +- the relay-then-stamp sentence of *Lifecycle offers*, with its + exception for a plan's diff-scoped LGTM, joins the same skill (see + *The dispatcher's procedure*). + +The glossary's **Unfinished-work list** defines the list as a section +of the lifecycle rule. The implementation rewrites that definition when +the list moves; the glossary describes what shipped, so the grilling +leaves it alone. + +Ticket directories, with the procedure for moving a document into one, +stay in the lifecycle rule. `workflow.md` already tells a session to read +that text before it creates a ticket directory, since no file exists +yet to load it, and that pointer keeps working. + +## Verification + +- Text that moves unchanged (D3, D4, D6) is compared with its source + after whitespace normalisation, and any difference other than a + pointer rewrite is reported. A shortened step (D2) is checked by + review against the first anti-goal. +- Every pointer into moved text is rewritten to the text's new home + (D11), or deleted with its sentence where D2 shortens a step. A + pointer names the text in many ways: by heading, by a phrase such as + "the verdict-agent dispatch subsection below" or "the provisional + batch the workflow rule defines", or by naming the rule that holds + it — `workflow.md`'s *Branch naming* does so for per-round commits, + and the `read-by:` lines of `SETTINGS_REGISTRY.md` do so for + `review.autonomy`, `review.per-round-commit` and + `docs-branch.merge`, which then name the `review-loop` skill's + procedure reference — the file that cites the keys, as the registry + test requires — in the registry's own repo-path form — the registry is no installed rule, so D11 does not + bind it. Each rewritten pointer is then resolved against its new + home. The + plan enumerates every such pointer, in rules, skills, cards, the + README, the registry and the glossary; no single search is complete, + so the plan reads the kept text of both rules whole and searches the + other files for each moved heading and its phrases. +- The shipped files are measured with `wc -m`, and the sizes are + reported beside the estimates in *Goals*. A miss is reported, never a + failure. +- One context measurement per document class: an agent reads a document of that class + and reports which rule files were injected. +- `sync-rules` needs no change: no rule file is added or removed, and + the two rules it installs only shrink. +- The plugin's identity surfaces name the new skill: `plugin.json`, + the marketplace catalog entry and the repo README row. + +## Out of scope + +- Rewording for brevity outside steps 1–7 of `workflow.md`, beyond + what a move forces. +- Splitting the lifecycle rule by document class (D5, withdrawn). +- The installed rule copies in a developer's home directory; they + follow at the next `sync-rules`. + +## Calls made by the author + +- **Ticket directories stay path-scoped.** They have one reader, like + the sections D6 moves, but no skill of their own and an always-loaded + pointer that already works. Keeping them costs about 4,700 characters + on every document read. +- **The skill is named `review-loop`.** It names the activity its + reader is in, as the other skills of this plugin do. + +## Review rounds + +### 2026-11-16 — architect, fable 5.2, blocking (round 1, full-document) + +The verdict follows the card installed at dispatch, 0.19.0-dev.4 +(two Important = `blocking`); +the card on `develop` requires a Critical, which would make it +`concerns`. Record: +`.claude/working-process/2026-11-16-process-context-spec/architect-round-1.md`. +The developer ruled on 2026-11-16 to read it under the current card: +the field carries `concerns`. + +- hit fixed 2026-11-16 — *Branch naming* in `workflow.md` names the lifecycle rule as the home of per-round commits, which D6 moves; *Verification* now names it +- hit fixed 2026-11-16 — the registry's `read-by:` lines for `docs-branch.merge` and `review.per-round-commit` go stale under D6; *Verification* now names them +- hit fixed 2026-11-16 — *Verification*'s two searches missed `per-round`, `docs-branch`, `relay-then-stamp`, `stand-in`, `diff-scoped` and excluded `workflow.md`; replaced +- hit dismissed 2026-11-16 — "read moment", "always-loaded", "path-scoped", "identity surface", "provisional batch", "ledger reference" have no glossary entry; counter: the grilling ruled no new terms, they are this spec's plain prose, and the provisional batch is defined in `workflow.md` +- hit fixed 2026-11-16 — the search missed pointers worded "verdict-agent dispatch subsection", "propagation gate below", "provisional batch"; the bullet drops its completeness claim and the plan reads the kept text whole +- hit fixed 2026-11-16 — the `read-by:` lines were only checked to resolve; the bullet now rewrites them to the skill +- hit dismissed 2026-11-16 — individual stays-text pointers are not listed in the spec; counter: the spec assigns their enumeration to the plan, and the bullet names every class they fall in +- hit fixed 2026-11-16 — rewritten `read-by:` lines conflicted with D11; D11 scoped to installed rules, the registry keeps its repo-path form (not re-audited: the episode's re-dispatch bound was reached) +- hit fixed 2026-11-16 — D2 said "the seven offers" and *The always-loaded rule* cut every step to its offer, while step 6 is no offer; both now except step 6 +- hit fixed 2026-11-16 — the round 1 note named "the installed card" for a two-Important rule the card now installed lacks; the note names the card installed at dispatch, 0.19.0-dev.4 +- hit dismissed 2026-11-16 — the round 1 record's `size: 283` re-derives as 284 on commit 751dc40; counter: the record measured the text as dispatched, before the stamp added the blank line ahead of `## Review rounds` +- hit dismissed 2026-11-16 — glossary gaps for the spec's prose terms, re-raised; counter: the dismissal above stands — the grilling ruled no new terms, and the hit brings no new evidence +- fixed 2026-11-16 — [Important] D2 cuts all seven steps to their offer but names a home for cut text only in step 4; step 6 is no offer; ruling: 2026-11-16; D2 and *The always-loaded rule* now say a cut sentence moves to a named home or repeats kept text, and step 6 stays whole with its pointers rewritten +- fixed 2026-11-16 — [Important] a session with the installed rules but without the plugin, or with an older one, finds pointers to a skill that does not exist; ruling: 2026-11-16; every pointer sentence is conditional (D11, *Three homes*), and a third accepted risk names this reader +- fixed 2026-11-16 — [Important] a single skill body of about 9,000 tokens loses its terminators when compaction keeps the first 5,000; ruling: 2026-11-16; D3 and *The dispatcher's procedure* now give a short `SKILL.md` routing each read moment to one of two reference files, the procedure and the ledger grammar +- fixed 2026-11-16 — [Minor] step 4's audit-pair sequencing was moving to the path-scoped lifecycle rule, whose reader is every document read; ruling: 2026-11-16; it moves to `review-loop`, read at the consumption gate +- fixed 2026-11-16 — [Minor] D10 handed the ledger reference to diff-scoped rounds only; ruling: 2026-11-16; D10 now covers any round on a document carrying `## Review rounds` +- fixed 2026-11-16 — [Minor] the spec did not say the skill's description carries the read moments, the only trigger where rules were never synced; ruling: 2026-11-16; D3 and *The dispatcher's procedure* say it names the four moments, the name stays + +### 2026-11-16 — architect, fable 5.2, concerns (round 2, diff-scoped) + +Record: `.claude/working-process/2026-11-16-process-context-spec/architect-round-2.md`. + +- fixed 2026-11-16 — [Minor] the registry bullet named `SKILL.md` as the reader of three keys, but the short router will not cite them; license: `tests/working-process/test_settings_registry.py:116-120` requires every `read-by:` file to cite its key, and `SETTINGS_REGISTRY.md:13` defines `read-by:` as the files that read it; the bullet now names the skill's procedure reference +- fixed 2026-11-16 — [Minor] step 6 stays whole with its pointers rewritten, yet taking a provisional decision is none of the four read moments; ruling: 2026-11-16; *The always-loaded rule* now has step 6 state the record store's guard inline, a `.gitignore` containing exactly `*` +- declined 2026-11-16 — [Minor] the reviewer's card could read the ledger reference through `${CLAUDE_PLUGIN_ROOT}` instead of the dispatcher carrying its path; ruling: 2026-11-16; D10 stands, and the first accepted risk now names a brief that omits the path +- fixed 2026-11-16 — the four read moments live in three places with no statement that they move together; ruling: 2026-11-16; *The dispatcher's procedure* now says the three are edited together +- signal 2026-11-16 — a third round does not earn its cost: the round is all-Minor, the leftovers are one correction and two short answers, and the integrity audit at the consumption gate reads the whole document +- hit fixed 2026-11-16 — the spec used the bare word "probe" three times, which the glossary bans (`_Avoid_: … probe (unqualified)`); now "measurement" +- hit fixed 2026-11-16 — bare "pair" for the relay-then-stamp sentences, with a pair offer in view in the same section (`_Avoid_: pair (bare, where a pair offer is also in view)`); now "the promise to edit them together" + +Round 2's `concerns` is resolved without a fresh round: the developer +answered both held findings on 2026-11-16 and chose the integrity audit +at the consumption gate over a third round, as the reviewer's stop +signal advised. From 8f930a891e0522e66166a9c0298da3ab037c6a24 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:14:41 +0100 Subject: [PATCH 26/59] feat(working-process): review-loop references, extracted verbatim --- .../skills/review-loop/LEDGER.md | 340 ++++++++++ .../skills/review-loop/PROCEDURE.md | 641 ++++++++++++++++++ 2 files changed, 981 insertions(+) create mode 100644 plugins/working-process/skills/review-loop/LEDGER.md create mode 100644 plugins/working-process/skills/review-loop/PROCEDURE.md diff --git a/plugins/working-process/skills/review-loop/LEDGER.md b/plugins/working-process/skills/review-loop/LEDGER.md new file mode 100644 index 0000000..f4583ba --- /dev/null +++ b/plugins/working-process/skills/review-loop/LEDGER.md @@ -0,0 +1,340 @@ +# review-loop — the ledger grammar + +## The disposition ledger + +The body record a `concerns` or `blocking` round owes has a canonical +shape, not an improvised one — practice produced three competing +conventions across six documents before it was written down. The rounds +live under one section, `## Review rounds`, and each round opens with a +heading: + + ### — , , (round N[, ]) + +The scope token admits two values, `diff-scoped` and `full-document`, +and is omitted only on a round predating the distinction. A recovery +reading keys on the absence of `full-document`, so a full-document round +always says so. + +The latest round heading is the one carrying the highest ordinal, +wherever it sits in the section: no order is prescribed for the blocks +and live ledgers run both ways. Ordinals run per document and per field, +and continue across loops — a later loop opens at the next number rather +than at one, which is what the round cap's derivation from the headings +already assumed. + +Under the heading each finding takes one line, its disposition the +leading token: + + - open — [] + - held — [] ; question: ; options: + - fixed — [] ; ; + - declined — [] ; ; + +The severity bracket is omitted on a line whose sole authorizer is +`ruling:` **and** which no reviewer graded — both legs, never one: + + - fixed — ; ruling: ; + +`open` and `held` are the non-terminal states, and the only two +disposition states the Unfinished-work list anchors; the one gate line +it anchors, `hit held`, is defined under *Gate lines* below. `fixed` +and `declined` are terminal and say what became of the document: it +changed, or it stands. + +The two dates on a terminal line record different events and are both +written even when they coincide. The leading date is when the line +reached its terminal state; `ruling:` is when the decision it cites was +taken. On an ordinary developer-authorized line the two are the same day +and say so; on a fold they differ, and that divergence is the point of +carrying both. + +The severity slot is a reviewer's grade, so it is omitted exactly where +there is none: a change the developer directed mid-round is not a +finding, and inventing a grade for it would be the same manufacture the +authorizer rule forbids. This adds no fourth severity value; the +glossary's three stand. + +`fixed` and `resolved` merge because they were never two states. Both +mean the document changed on account of this finding, and they differed +only in who authorized it, which is now a clause. Merging also frees a +word the rules used for two objects — `concerns (resolved )` +annotates a verdict, while `resolved ` annotated a finding. + +- `open` — written at stamp time, before the findings are triaged. An + `open` line surviving a session means the remediation never ran, and + the document's next touch re-offers it. +- `held` — the finding needs the developer. The line carries the + concrete question and the options with the session's recommendation; + where the finding is disputed or contested, `counter:` carries the + evidence the developer needs in order to answer, and the oscillation + tripwire's named flip is that evidence. +- `fixed ` — the document changed on account of this finding. Its + authorizer says who decided: `license:` where the session cited a + written decision, `ruling:` where the developer did, `provisional:` + where a stand-in did. +- `declined ` — the document stands. It always carries `ruling:`, + or `provisional:` where a stand-in declined it, because declining is + a decision and triage gives a session no license + to decide. + +Each disposition line is written before the edit it describes, or with +it — never batched at the end of a wave. The dangerous failure is not a +session dying mid-round but a fix wave half-applied with no lines +written: the body has changed, nothing says which change belongs to +which finding, and the next round's brief reads a diff source that is +silently wrong. Writing contemporaneously makes a partial wave +self-evident, since `open` and `fixed` lines mixed under one heading say +exactly where the session stopped. + +The leading token is a queryable state. Clauses are payload. + +| clause | carries | on | +|---|---|---| +| `license: ` | the written decision the session acted on | `fixed` | +| `ruling: ` | the developer authorized it; on a fold, the prior ruling's date followed by `folding
` naming what it folds against | `fixed`, `declined` | +| `provisional: (stand-in )` | a stand-in the developer named decided it, on that date; it licenses nothing until the developer confirms it in the provisional batch, when it becomes `ruling:` | `fixed`, `declined` | +| `question:` | the question, phrased so one short answer resolves it | `held` | +| `options:` | the options and the session's recommendation | `held` | +| `counter:` | the session's evidence where the finding is disputed or contested | `held` | +| `deviation:
` | where the rationale for departing from a reviewer's suggestion lives | `fixed` | + +`question:` and `options:` are both required on a `held` line: the batch +that relays them is a transcript, and a session that dies between the +relay and the answer leaves the next session to re-derive the options, +possibly differently, so the developer answers a question that silently +changed. `counter:` and `deviation:` are conditional, written whenever +their condition holds. + +Every terminal line carries exactly one authorizer. + +A fix one review licenses can land in a document other than the +reviewed one — a plan review's finding whose `origin` names a judged +document is the +case the workflow rule names. The disposition line then lands in the +ledger of the document that changed, and the reviewed document's line +points at it in its `` clause, naming that document and +the heading the line sits under: one authorizer, two documents, two +lines, and the invariant above holds on each. The pointer needs no +clause of its own — `` already belongs to the `fixed` +line's shape, so the clause table stays closed. In the changed +document the line goes under its latest round heading, or with the +body note the resolution annotation above already owes, where that +document is stamped and no fresh round ran. A document whose loop +closed at `LGTM` has neither — the annotation is defined for `concerns` +and for a `blocking` verdict closed by adjudication, never for `LGTM` — +so the fix opens a heading of its own: + + ### — fix from + +It carries no ordinal and no verdict, which keeps it out of the round +cap's derivation and out of the Unfinished-work commands that anchor a +round heading: it records a fix, not a round. Two stamps go stale as on +any body edit — the `integrity:` hash stops matching, and the verdict +stops certifying the words that changed. The `integrity:` stamp is +read at the consumption gate alone: one gone stale after the plan was +written is expected and owes no new audit. The same heading serves a +register edit that a plan's held gate line licensed, on a design spec +whose loop has closed at whatever verdict: the heading then names the +plan whose gate held the hit, and that plan's terminal gate line names +the heading and the line under it. Unlike a review-licensed fix, such an +edit never joins a resolution note, even on a `concerns (resolved)` +spec: that note records what resolved the verdict, and this edit +resolves none. + +Payload costs nothing structurally. An Unfinished-work command under the +list's default scope guard is held to the frontmatter block, so no body +line reaches it at all; an entry publishing its own scope anchors a +leading disposition token or a round heading, and an indented +continuation matches neither. Payload under a line is therefore invisible +to every published command, and where it runs long it belongs in +indented sub-bullets rather than in a longer line. + +Two additions extend those shapes, and nothing else does: the +annotation here, and the cross-document fix heading above. A +diff-scoped `LGTM` heading gains `, debt discharged ` once the +chain debt it carries is discharged, and its presence defeats the +consumption gate's re-ask, as `, waived ` defeats the re-review +offer: + + ### — architect, , LGTM (round 3, diff-scoped), debt discharged + +The token goes after the closing parenthesis rather than inside it. A +parenthesised token qualifies a value — `concerns (resolved )` +changes what the verdict means — while a comma-appended token adds a +later event to a finished record, and this annotation is written later, +by a different actor, about a different event. + +Three paths discharge the debt, all three write the same token, and the +dispatcher writes it in every case: the developer declining the gate's +pair offer, written in the decline turn before the work that decline +licenses begins, and written for every document that offer named — a +declined offer over an audit pair discharges the chain debt of both. +What a decline never does is stand in for the audit itself: it writes +no `integrity:` stamp, leaves every other open finding open, and closes +no `blocking` verdict. "Do not run the audit" is a release from the +chain debt the offer named and from nothing else; an integrity audit, +written once its dispositions are +applied and before the `integrity:` stamp — and where that audit read an +audit pair, it discharges the debt of both documents it read, annotating +each document's own unannotated diff-scoped `LGTM` headings; and any +later full-document +round, at its stamping turn, whatever its verdict — the debt is +discharged by the reading, not by the grade. A full-document round reads +the whole document, so it annotates every unannotated diff-scoped `LGTM` +heading above it rather than only the one it follows. + +The token carries a date and nothing else. Each path leaves its own +trace — an `integrity:` stamp, a later full-document heading, or +neither — and no consumer reads the path, so recording it would give one +fact a second home. Where a session discharges the debt and dies before +annotating, the annotation's own derivation licenses a later session to +write it; on a document still in flight only the decline path has +nothing to derive from, and there the debt correctly re-surfaces and the +developer declines again. On a document already `implemented` the +Chain debt entry's owner leg makes even that derivable, from the +standing decision it cites. + +Ledger lines written before this merge stay as written, as the `scope` +token's introduction already established. The shapes they use are kept +here as described historical forms rather than deleted: + + - resolved — [] ; landed in
+ - resolved (declined) — [] ; + +A reader must still parse pre-merge documents, and a fold against a +pre-design settled line cites a date off a token the live grammar no +longer produces. These two shapes are described, never minted: no +session writes a new line in either form. + +Narrative prose between the lines of a `## Review rounds` section is +lawful and expected. This grammar governs headings, lines, and their +indented payload; a paragraph explaining why a wave went the way it did +belongs there too. A lint over the section reads the anchored lines and +ignores the prose. + +A reviewer's stop signal takes a line of its own, under the heading of +the round that gave it: + + - signal — + +It carries the leading token `signal`, no severity — a judgment about +the next round's marginal value is not a finding — and no authorizer, +since nobody licensed it. It joins no anchor: a stop signal owes nobody +a next move, so it is closed the moment it is written, as a gate line +is. The workflow rule owns the ask that produces it. + +### Gate lines + +The propagation gate, when that agent is available, writes gate lines of +its own: the two ordinary shapes here, and the held shape and its three +terminal rewrites below. Each carries its own leading token and never a +severity, because a hit is a located detection the dispatcher confirms +or dismisses, never a graded finding: + + - hit fixed — ; + - hit dismissed — ; counter: + +Neither carries a license either, because a hit's fix is licensed by its +own derivation. + +A hit of the coverage duty whose fix needs a decision no derivation +settles is held for the developer — the one exception the workflow rule +makes to hits never waiting. It takes a third shape, rewritten in place +to one of three terminal shapes, so its state always has one home: + + - hit held — ; question: ; options: + - hit fixed — ; ; ruling: + - hit deferred — ; ruling: ; Defers: + - hit withdrawn — ; ruling: ; # + +The rewrite happens once the gate has re-run over the changed document +and whatever depends on it, never on the developer's answer alone. +`hit fixed … ruling:` records that the document now carries the +decision the developer settled — a plan that realizes it, or a register +the ruling repaired; `hit deferred` records an approved `**Defers:**` +line in the plan, and `hit withdrawn` a register entry now a tombstone. +Each is written only where it names what happened, and none is +`hit dismissed`, because the gap was real when the hit fired. The +ordinary `hit fixed` shape, without `ruling:`, stays for every hit +whose fix its derivation licensed. `ruling:` on a gate line means what +it means on a disposition line, and a diff-scoped round treats the line +as settled. + +A `hit held` line lives in the ledger of the document whose gate raised +it — the audited plan, or the design spec audited alone. Its leading +date is the gate's, and the terminal rewrite replaces it with the date +the line reached its terminal state. A held hit ends its gate episode +and blocks the dispatch the gate guards; the re-run after the +developer's answer is a fresh episode. A register edit the answer +causes is recorded in the spec's own ledger — under its latest round +heading while its loop is open, and under the fix heading above once +its loop has closed. A spec already `implemented` takes the edit by +revision instead, and the held hit waits for it. + +Each is written at gate time, under the last round's heading. The `hit` +token tells a gate line apart from that round's own findings; the date +does not, since a gate episode and the round it precedes commonly share +one. A gate still never mints a heading of its own, on the separate +ground that the round heading's grammar is closed and a gate is not a +round. The fix heading above is no counter-example: a gate's lines can +wait for the round that is coming, while a fix landing on a document +whose loop closed at `LGTM` waits for nothing. Writing at gate +time is what the lines are for: a dismissal must exist while the episode +is still re-dispatching, or the gate cannot terminate, and the next +diff-scoped brief is composed before its own round is stamped. A gate +before a document's first round has no heading to write under; its lines +wait for that round and are written at its stamp, the one case where +they do — unless the episode holds a hit, since the round its lines +would wait for cannot start. A pre-round episode holding at least one +hit writes every one of its lines, the `hit held` line and its siblings +alike, in the `## Review rounds` section before the first round +heading, and they stay there, rewrites included: no round produced +them, and one episode keeps one home. Once such lines stand there, +every later pre-round episode writes there too, holding or not, so the +document's pre-round gate history keeps one place. A document with no +`## Review rounds` section gains one, at its end, with its first gate +line. + +A gate episode always lands somewhere: its lines are the reason a later +reader need not re-derive what the session already settled. + +No gate-line shape covers a hit left outstanding when the re-dispatch +bound in the workflow rule stops an episode. That state owes the +developer a decision, so neither `hit fixed` nor `hit dismissed` can +honestly carry it, and `hit held` is scoped to the coverage duty's +hits; no anchor surfaces it today — a stated gap, not an oversight. +Until a shape exists, the workflow rule's report is its only record. + +A `hit fixed` line puts the gate's ordinary work where the next +diff-scoped brief already looks, beside the round's `fixed` lines. A +`hit dismissed` line records a decision the developer was never asked to +make, so a later round cites it instead of re-deriving it and a session +that would dismiss the same hit differently argues against written words +rather than silence. Neither joins the unfinished-work anchors: both are +closed when written and owe nobody a next move. A `hit held` line owes +the developer an answer, so it joins them until its terminal rewrite. + +A line carrying `ruling:` is a recorded developer decision, and what a +later round may do with it depends on what that round brings: + +- re-raised without new evidence — folded and cited, never asked again; + the fold produces `declined ` carrying `ruling:` with the prior + ruling's date and a `folding` citation of the line it folds against, + so the authorizer is cited rather than manufactured; +- re-raised with new evidence — `held`, its `counter:` citing the prior + ruling, because a session that folded this alone would arbitrate + between a reviewer and a recorded developer decision. + +Evidence is new relative to what the folded line records — its claim and +the reasoning its clauses carry — not relative to the reviewer's +wording. A session that cannot tell holds rather than folds. + +A pre-design settled line carries no authorizer clause and is settled by +its token alone; a fold against one cites the date on that token, which +is when the developer decided. + +A line carrying `provisional:` is not settled: it records nobody's +decision yet, so a re-raise against it is ordinary triage, as against a +`license:` line, and nothing here folds it. + +State prevents relitigation, not the reviewer's memory. diff --git a/plugins/working-process/skills/review-loop/PROCEDURE.md b/plugins/working-process/skills/review-loop/PROCEDURE.md new file mode 100644 index 0000000..153bcd3 --- /dev/null +++ b/plugins/working-process/skills/review-loop/PROCEDURE.md @@ -0,0 +1,641 @@ +# review-loop — the dispatcher's procedure + +## Dispatching a verdict agent + +Dispatching a verdict agent (`architect`, `plan-adversary`), when +available: + +- From an interactive session the dispatch always runs in the + background — a review never blocks the session, mirroring the + review-reports rule's precedent. A run with no interactive + dispatcher cannot relay, so it never stamps; on a document whose + field is still unstamped, the next interactive touch re-offers the + round through the lifecycle rule's offer loop. A round lost on an + already-stamped document leaves no signal and is accepted as lost — + never corruption, only a missing re-run. +- Before dispatch, resolve any undecided Process directory + (`docs/specs/`, `docs/technical-designs/`, `docs/plans/`) so the + first-create question cannot interrupt the stamp turn. +- At dispatch, tell the developer the round is running in the + background and its result will arrive as a task notification, with + progress visible in the session's task list. +- On the completion notification, in one turn and in this order: + verify the agent's model self-report (the comparison the lifecycle + rule defines), write the dispatch record defined below, relay the + report to the developer, check every citation the report supplies + against what it names, then stamp the verdict (`LGTM` | `concerns` | + `blocking`) into the reviewed document's `architect:` / + `adversary:` frontmatter field. The citation check follows the relay + rather than preceding it, because a wrong citation in conversation + costs a correction while a wrong one in the record outlives the + loop. The order has one named exception, defined under *What a + diff-scoped LGTM certifies* below: a plan's diff-scoped LGTM. +- The dispatch record is written before the relay. The dispatcher + saves what the agent returned, verbatim — extracted from the agent's + transcript, never retyped, since a retyped record once shared none of + its 23 lines with the report it claimed to hold. In Claude Code the + task's output file is that transcript, and the report is the + hand-back call's message: + `jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="SubagentHandback") | .input.message' `. + Where that prints nothing, the agent's final assistant text is the + report; where no transcript is readable, the record says it was + copied from the relay. It goes under a header of the date, + the agent, the model self-report, the subject, and — where a + document was reviewed — its size, `size: `: 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`, + or with the `sed` stage dropped for a document without frontmatter — + with no frontmatter and no `ticket`, since the record is evidence rather + than a process artefact. It goes to `.claude/working-process/` at + the repo root (`git rev-parse --show-toplevel`). A record survives + compaction, the session's end and a branch switch, and no more; that + bound is what the relay's condensation below leans on. Audits write + none — a propagation gate's hits land in the ledger and an integrity + audit's dispositions land as the edits it causes plus the + `integrity:` stamp, so a record would give one fact a second home. +- The store is git-ignored by a `.gitignore` containing exactly `*`. + Before writing a record the dispatcher ensures that file holds + exactly that, rather than writing it once: the guard repairs a store + directory made by hand, a file someone truncated, and a `git clean` + that took the file and left the directory. A project already + ignoring `.claude/` still gets the file, since the store may not + depend on another file's contents. +- The record's name carries its agent and one discriminator: + + .claude/working-process//-round-.md + .claude/working-process//--.md + + `` is the reviewed document's basename without its extension, + one directory per subject. A verdict agent takes the round ordinal, + derived the way the heading will derive it — the highest ordinal the + document's rounds carry, plus one, ordinals continuing across + loops — because the record is written before that heading exists. A + dispatch that reviews no document takes its subject as the stem, + kebab-cased and capped at sixty characters, and the timestamp shape, + having no ledger to draw an ordinal from; an `architect` dispatch on + a bare question is one such, and the test is whether a document + exists rather than which agent ran. Where a round-ordinal name is + already taken, the new file appends the timestamp to it — + `-round---.md` — which settles the + superseded round two sessions can produce on one ordinal without + asking either to judge which report is stale. A timestamp name + collides only when a second record lands in the same second, where + appending the same timestamp would reproduce the taken name, so it + takes the lowest free counter suffix instead: `-2`, then `-3`. +- The relay opens with one header line, then one line per finding. The + header carries the verdict, the model self-report, the finding count + by severity, how many decisions await the developer, and — where a + document was reviewed — its size and the change since the previous + record of the same document and agent; with no earlier record + carrying a `size:` line it shows the size alone. The relay reports + the number and judges nothing. Each + finding takes one line — severity, origin, claim — except where the + reviewer emits no origin: the `architect` reads one document and + every finding it returns originates there, so an architect relay's + line carries severity and claim alone. +- Condensation reaches narrative prose alone, whatever a session's + output style prescribes. The finding list is never condensed, and no + finding or its severity is ever dropped: the relay is the + developer's standing veto, so a finding nobody printed is a finding + nobody could overrule. Narrative is safe to condense because the + dispatch record holds the full text, which makes an expansion a + quotation rather than a reconstruction — so the relay names that + record's path, and the developer can open what was condensed. +- The header's count of decisions is the findings for which the + session can cite no license, plus those whose suggested fix adds a + mechanism and carries out no `ruling:` (the hold under *The review + loop*), derived at relay time from the report and the decisions + already written down — before any ledger line exists, since `open` + is written at stamp time and triage follows the stamp. The `held` + lines the same round later writes are that count's check: they come + to the same number, and a divergence means triage found a license + the relay missed, triage lost one the relay claimed, triage placed a + fix on the other side of the mechanism line than the relay did, or + the oscillation tripwire held a finding that does carry a license. + The last is lawful, so the check reports the number rather + than asserting a fault. Verdicts that suspend autonomy — `blocking`, + the spent round cap, the all-Minor signal — stay out of the count: + they decide whether the loop continues rather than what a document + says, and the relay reports them in its own right. +- A citation the report supplies — a file and line, an identifier, a + count — is checked against what it names before it is written into + the document or acted on by a fix. A precise citation reads like + verification and is not one, and the dispatcher who copies it into + the ledger launders a reviewer's evidence into the project's record. + The check is cheap and its absence is measured: one cycle relayed a + line number off by one and an identifier that did not exist, both + quoted with exact positions, both caught later by a propagation + audit rather than at the relay. This is the citation's analogue of + the model self-report comparison above — the same duty, on the other + thing a report asserts about the world. +- The stamp — the field, any fallback record, and the round record + the lifecycle rule defines — lands as one edit, body record first + where edit granularity forces separate writes, and goes to the + document named in the report, never to "the most recent dispatch". + The same exception splits that one edit: on a plan's diff-scoped + LGTM the round record lands while the frontmatter stamp waits for + the confirming round. +- The sequence ends the delivery, not the loop: after relay and stamp + the session may fix the document and dispatch a fresh round, or put + its questions to the developer first. +- At most one live round per document per field within the session; + superseding a running round stops it when the platform offers a + stop, otherwise the stale result is relayed as stale and never + stamped. A parallel round from another session is accepted as + undetectable and stays benign: both rounds record in the body and the + field holds the later stamp. One consequence postdates that decision — + a diff-scoped LGTM certifies a chain, so an interleave punches a hole + no round ever read. The discharge paths are the mitigation, since an + audit and a full-document round each read the whole document, and a + heading-derived cap over-counts under interleave, which escalates + early. +- When the reviewed document changed after dispatch — known only + conversationally; an out-of-session edit is accepted as + undetectable — the relay says so and the stamp waits for the + developer's call. +- When compaction leaves an in-flight dispatch unclear, check the task + list rather than guess, and never fabricate a pending result. +- An agent that dies or returns nothing is an ordinary error: relay + the failure and offer a fresh dispatch on the same tier. +- A consultation (`*-consult`) produces no verdict and nothing to + record. + +### The review loop + +Rounds after the first form a loop, and the loop is the offered unit — +no single re-dispatch is offered on its own. At the session's first +verdict dispatch, ask once whether the loop may run autonomously — yes +/ not now / not in this session — state the round cap with the +question, and honour the answer for the rest of the Claude Code session +without asking again. The same question carries a second clause wherever +the lifecycle rule's per-round commits are available: whether the loop +may commit the reviewed document once per round. One question, two +answers, asked once. Each clause has a settings key, `review.autonomy` +and `review.per-round-commit`, read as the process-settings rule says: +a set key answers its clause unasked, and only an unset clause is +asked. A yes or no may be given "and record" per clause — "yes, and +record; commits: not now" records the first clause alone — which +writes that clause's key through the loader's `--set` where a settings +block names the loader; "not now" and "not in this session" are never +recorded. Without consent every round +behaves as it did before: relay, stamp, and every proposal waits for +the developer. + +Triage decides each finding by its license, never by its grade. A +finding is self-fixable when the session can cite the decision that +licenses the fix — a statement in the document itself, a glossary term +or `_Avoid_` ban, a recorded ADR, or a line carrying `ruling:` — and +the citation goes on the finding's line in the disposition +ledger the spec-plan-lifecycle rule defines. Everything else is held +for the developer, and a finding that could go either way is a +decision. Consequences the loop states outright: + +- Severity is not the line. A Minor finding can be a naming call the + developer already ruled on; a Critical can be a contradiction with a + recorded ADR, which the ADR itself licenses the session to fix. +- A contradiction between two decision-bearing statements is held: + fixing for consistency would pick a winner silently. +- A finding the session believes is wrong is held with the session's + counter-evidence attached — never fixed silently, never dropped + silently. The session never arbitrates between a reviewer and a + recorded developer decision. +- Only written decisions license fixes. A decision settled in + conversation becomes citable by being written into the document, + which the fix itself accomplishes. A line carrying `provisional:` + licenses nothing until the developer confirms it, and neither does + the text its fix wrote. +- A finding whose `origin` names a judged document — a design spec or a + technical design — is held unless a written decision licenses the + edit, since changing either from inside a plan review is design work. + `origin` is a list, so a finding naming more than one holds the same + way, and its `held` line names in `options:` which named document is + fixable at once. A licensed fix lands in the ledger of the document + that changed, and the plan's line points at it, by the cross-document + clause the spec-plan-lifecycle rule defines — which also leaves the + design spec's `integrity:` stamp stale, as any body edit to either + document of an audit pair does. +- A fix that adds a mechanism is held whatever its severity, and a + license does not lift the hold. 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. Two fixes stay outside the hold: one carrying out + a line with `ruling:`, which the developer already decided, and a + propagation-gate hit's fix, which its derivation licenses. A fix the + session cannot place either way is held. The held line's `options:` + recommend the smaller option where it meets the requirements and + always include "accept as a documented limitation". + +A fix wave that deviates from a reviewer's suggestion records the +deviation and its rationale beside the text they concern — not only in +the ledger — so the next reviewer trips over the reason exactly where +the disagreement lives. + +Once the licensed fixes land, the loop either continues or yields: + +- Held set empty — dispatch the next round without asking, within the + cap. +- Held set non-empty — batch the held questions into one message at the + relay turn (per item: the claim in one line, why it is held, the + question, and the options with the session's recommendation), then + wait. A fresh round dispatches only on a document with nothing + awaiting the developer, since a round over known-open decisions + re-reports them at the loop's most expensive tier for no + information. The developer may still order a round on the partial + document — every step is an offer. Where a stand-in is named, the + held findings go to it instead, and once its answers land the loop + continues as with the held set empty: a `provisional:` line awaits + only the provisional batch, never the next round. + +One batch per round is the contract: the developer is interrupted once +per round, and only over a decision that is genuinely theirs. + +### The stand-in and the provisional batch + +The developer may name a *stand-in* in conversation — another agent or +tool that answers for them — for the rest of the Claude Code session; a +session that loses the delegation on compaction asks again rather than +guess. The stand-in answers the held findings a round would put to the +developer, and each answer is a *provisional decision*: it takes effect +at once, and its disposition line carries +`provisional: (stand-in )` where the developer's answer +would carry `ruling:`. An answer covers only the question put to it; a +later event needs a new question. A stand-in may answer a `blocking` +round's held findings, whose fixes land while the loop stays stopped. +Every other act stays the developer's: round orders, cap and all-Minor +escalations, a round after `blocking`, held gate hits, a fix the +mechanism hold stops, adjudicating a `blocking` verdict, withdrawing or +deferring a registered decision, and moving a `status`. A stand-in's +answer is not developer contact, so it resets no cap. During +implementation it may also answer the questions step 6 describes. + +Provisional decisions reach the developer as one *provisional batch*: +every line under the document's `## Review rounds` whose authorizer is +`provisional:`, and at a plan's `implemented` move the unanswered items +of its provisional list. It is delivered with the request for the document's +next status move, and for a design spec or a technical design no later +than its consumption gate, settled there before the integrity audit +since a reversal edits the audited body. An approval given before the +request still gets the batch first. A line a plan review writes into an +already-consumed judged document travels in the plan's batch, and one +answer settles both lines. The developer confirms or reverses each +item. Confirmed, `provisional:` becomes `ruling: `, the date of +the answer. Reversed, the session applies the answer at once and +rewrites the line in place to the terminal state the answer gives — a +reversed `fixed` may become `declined` or stay `fixed` with narrower +text, a reversed `declined` becomes `fixed` — carrying `ruling:`, and +runs the propagation gate over the change as after any fix wave. A move +made on the developer's word leaves no `provisional:` line behind. + +### The propagation gate + +When the `propagation-auditor` agent is available, a passing propagation +gate is the precondition for the dispatches it gates: the session +dispatches the audit over the document, fixes its hits, and repeats +until no confirmed hit remains, so an expensive reader only ever meets +a mechanically consistent document. The gate fires before every +verdict-agent dispatch, first rounds included — authoring errors exist +before any repair; after a fix wave, before the next round; and before +an integrity audit. A hit's fix is licensed by its own derivation — a +recounted counter and an enumerated missed call site decide +themselves — so hits never wait for the developer, with one named +exception, for the coverage duty's hits alone. + +The two coverage hits — a registered decision no task cites, and a task +lacking its `**Realizes:**` line — are triaged by license. Where a task +already does the work and lacks only its annotation, the task's text +licenses adding the identifier. Where no task realizes the decision and +the decision's text settles every choice the missing task requires, the +decision licenses writing it, and the next round's brief names it among +the previous wave's fixes. Where writing the task needs a choice the +decision does not make, the hit is held: its question is that missing +decision, not the gap, which is already established. Any other hit of +the coverage duty is fixed where its derivation settles the fix and held +where it does not, as when breaking a `replaced by` cycle means choosing +which entry stands. No other duty's hit is ever held. + +A held hit ends its gate episode and blocks the dispatch the gate +guards, as a held finding blocks a fresh round, and the session puts its +question to the developer. The answer lands where the decision belongs — +in the spec's register, or as the plan's `**Defers:**` line — and the +gate re-runs over the changed document and whatever depends on it, as a +fresh episode; the dispatch goes out once that episode passes. The +spec-plan-lifecycle rule defines the `hit held` line and its terminal +shapes. + +A report's body governs, never its closing token. Where a report lists +located hits and also carries `CLEAN`, the hits are the report and the +gate has not passed. It has happened more than once on the cheapest +family, and once under a brief that ruled the combination out in as +many words — so emphasis on the writing side is spent, and the guard +belongs to the dispatcher who reads. The rule is stated here rather +than generalised, because `CLEAN` is this agent's token and no other +report carries one. A `decision-coverage:` or `table-closure:` line is +neither a hit nor a breach of the token's position: the card writes +those lines on every run, clean ones included, between the hits and the +token. + +A hit the session believes is wrong is dismissed, never silently: the +session writes the `dismissed` line the spec-plan-lifecycle rule +defines and reports the dismissal in the next report it relays to the +developer. A dismissed hit is a report, not a question, so it never +enters the held batch and never spends the round's one interruption — +the developer reads the dismissal and keeps their standing veto over it. +The written line is what makes the gate terminate: a dismissed hit +recurs on every re-dispatch, so a gate waiting on a hitless audit would +wait forever, and a dismissal nobody wrote down would be re-derived +from nothing every round. Both dispositions take the gate lines the +spec-plan-lifecycle rule defines. + +Two re-dispatches bound one gate episode — the run before a single +dispatch, never the document's lifetime, so every round gets its own +gate. A third is not attempted. The session reports the hits still +outstanding, with the standing of a dismissal, and holds the dispatch +the gate was guarding: a gate that cannot come clean has not done the +one job the expensive reader depends on. The report names what keeps +recurring, since fixes breeding fresh hits is the failure this bound +exists to catch. It stays a report — the developer may order the +dispatch anyway, as they may order any step — so it never becomes a +second question in a round that already spent its one. Without the +agent installed, every dispatch proceeds as it did before. + +### Re-dispatch briefs + +The first round reads the whole document; every later round is +diff-scoped. Its brief names what changed since the round it follows, +directs the reviewer to attack the previous wave's fixes first — +including whether a fix added a mechanism its finding did not need — and +forbids re-reviewing the rest — repair-born defects are the dominant +late-round class, and diff-scoping also ends stale-read findings. + +The ledger supplies what changed. The previous round's `fixed` lines and +their `` clauses, together with any gate lines under the +same heading, are the record of that wave, so the brief cites them and +needs no snapshot, commit, or hash. Where the loop is not committing per +round, the ledger is the only durable account of the diff; where it is, +the commit carries the lines and the ledger still carries the intent. The +brief cites the ledger either way. + +Diff-scoping forbids re-reviewing the document beyond the diff, and the +ledger is part of the document — so without a clause the reviewer is cut +off from the one section recording what the developer already decided. +The ledger is therefore always in scope for a diff-scoped round as +context, never as a review target, and what that protects is narrow: + +- settled lines may be re-raised only with new evidence — new against + what the folded line records, the base the spec-plan-lifecycle rule + defines — which routes to `held` rather than to a fold. A line + carrying `ruling:` is settled by that clause; a historical line + written before this design, `resolved (declined)` included, + carries no authorizer clause and is settled by its token alone. Both + are the developer's decisions, and both are protected on the same + footing; +- `held` lines carry questions already put, so a round does not + duplicate one; +- lines carrying `provisional:` record nobody's decision yet, so they + are not settled and a reviewer may re-raise them like `license:` + lines; +- `fixed` lines carrying `license:` get no protection at all — the + previous round's are the diff and are named as the first thing to + attack, and older ones are simply unprotected, since a reviewer told + not to re-raise a fix would lose the property diff-scoping was + adopted for. + +The reviewer learns what it may not reopen, never what it may not find. +Naming the section rather than copying its lines keeps the brief from +growing with the round count. + +Every brief states the loop's terminators outright — the cap and the +all-Minor signal below — rather than improvising them late, and asks +the reviewer for its own stop signal: judge whether another round earns +its cost, and say what the round's leftovers are worth. The ask stands +every round, whatever grades the findings carry — a round can leave one +Important behind and still not repay a re-read. That judgment concerns +the next round's marginal value, never whether the document is good +enough, and it informs the developer's decision rather than replacing +it. The signal is recorded where a later session can cite it: one line +under the heading of the round that gave it, in the shape the +spec-plan-lifecycle rule defines. A signal surviving only in a relay +dies with the next compaction, and practice has needed it twice — once +to justify overriding one, once to close a loop on one. Where the ledger +records a deviation from a reviewer's suggestion, +the brief invites refutation of the recorded rationale — a rationale is +evidence to attack, never a defence to protect. + +### Terminators + +- `LGTM` ends the loop — on a plan, only a full-document round's LGTM + does. +- `blocking` suspends autonomy entirely: relay, stamp, stop — no further + round without the developer. It licenses no separate fix prohibition, + because triage already holds what the prohibition was reaching for: a + design reshape has no citable license by construction, so it is held + whatever the verdict's grade. `concerns` is the autonomy zone. +- Round cap: three autonomous rounds per document per field without + developer contact, counting only rounds that returned a verdict. + Hitting the cap escalates in one batch — what was fixed, what remains, + why — rather than halting silently, and any developer contact resets + the count. Developer contact is a message from the developer: not a + relay they read, not an escalation the session sent, not an unanswered + batch. The count is derived from the round headings and the reset + event is recorded nowhere, so the cap is best-effort by construction; + a session that cannot count its own rounds escalates rather than + assuming, since resetting to zero would let a long session grant + itself three fresh rounds after every compaction. A plan's confirming + full-document round counts like any other: the count folds round + headings, and excluding one kind would mean classifying them — a + second fragile derivation in the one place the rules already concede + the cap is best-effort. A plan whose loop spent its three rounds + therefore escalates once before its confirming round, which is the + most expensive shape a round takes and the one a cap guarding spend + should guard first. A run of `blocking` verdicts is unbounded by the + cap, for the reason the cap is stated in: it counts autonomous rounds, + and `blocking` suspends autonomy, so every continuation after one is + the developer's own decision rather than a round the cap governs. + Consenting to three rounds consents to three autonomous ones. +- All-Minor signal: two consecutive rounds whose findings are all Minor + end the unattended run. Triage the round as always — by license, never + by grade — and escalate with an offer of a fresh round instead of + dispatching one. The escalation is a question, so the loop stays open + until the developer answers it: the resolution annotation the + spec-plan-lifecycle rule defines records their close — on a plan, once + the confirming round has run — and no session writes it without their + answer. +- Oscillation tripwire: a finding re-raised against a line carrying + `license:` is never re-fixed autonomously. Two readings of one license + are a contested reading, so it escalates as held, the flip named. A + re-raise against a line carrying `ruling:` is the relitigation case + instead, and the spec-plan-lifecycle rule owns it. A line carrying + `provisional:` cites no license, so a re-raise against it goes + through ordinary triage and the tripwire does not apply. + +The cap guards spend and the signal guards sense; both escalate, and +neither is a wall. Relay stays the developer's standing veto — every +report reaches them before the session acts on it — and a model-cap +refusal mid-loop forces developer contact: the drop-or-wait +question above is never answered autonomously. + +### What a diff-scoped LGTM certifies + +A diff-scoped LGTM certifies a chain rather than a fresh whole-document +read: round 1 read the whole document, and every later wave was +reviewed by the round that followed it. What that chain still owes +differs by document. + +For a judged document, the consumption gate before plan-writing makes +the pair offer as one question — an integrity audit or a full-document +round — and never an offer followed by a re-offer of the option just +declined. When the `integrity-auditor` agent is absent the offer +carries the full-document round alone. For an audit pair the gate makes +one pair offer for both documents: its audit arm reads the two +together, while choosing its round arm dispatches one full-document +architect round on each document that carries the debt, and +plan-writing waits until every verdict so dispatched is settled under +the rules any verdict follows; the joint integrity audit stays a check +of its own. The two arms cost differently and the +offer says so: an audit returns material for the dispatcher to dispose +of and leaves the verdict alone, while a full-document round on a +judged document is a new loop's first round, since that document's +LGTM already closed its loop — it mints its own verdict and stamps it, +so a `concerns` there flips the field back while plan-writing waits. +The full-document-round arm therefore blocks plan-writing; the audit +arm does not, and plan-writing follows its dispositions. + +Declining is the developer discharging the chain debt by release rather +than by performance, and the discharge is recorded rather than +remembered: the dispatcher appends `, debt discharged ` to the +diff-scoped LGTM heading, in the shape the spec-plan-lifecycle rule +defines, and that annotation defeats the gate's re-ask. The other two +paths write the same token. + +For a plan the loop closes only when the latest round heading is +full-document: whatever ends its rounds while that heading +is diff-scoped, one confirming full-document round follows, and that +round's verdict is the one stamped. A round already full-document owes +no confirming round — it is the close. The confirming round inherits the gating +of whatever ended the rounds. Where autonomy still stands — +a diff-scoped `LGTM`, or a `concerns` inside the cap — the rules mandate +the round, so it is no decision of the developer's and spends none of +the round's one interruption. After `blocking`, the round cap or the +all-Minor signal it is the developer's to order, because each of those +suspends autonomy by its own terminator, and a round the rules mandate +cannot outrank a terminator that stopped the loop. + +A session never judges that the rounds are ending. The terminators do, +as does the developer closing the loop. While none has fired and the +held set is empty, the next round is diff-scoped and the loop simply +continues; the confirming round is owed the moment one fires, which is +the moment a session would otherwise write the resolution annotation. + +The plan case carries the single named exception to the relay-then-stamp +order above — a plan's diff-scoped LGTM is relayed and its round record +written, and only the frontmatter stamp waits for the confirming round. +Recovery therefore reads the ledger rather than the stamp. A plan whose +latest round heading is a diff-scoped `LGTM` that no later full-document +round follows is re-offered its confirming round at the document's next +touch, whatever the frontmatter says, since that heading is itself an +end. A latest heading of any other verdict is not an end, so there the +round is re-offered when something tries to end the rounds — an +annotation, an adjudication, a `status` move — or when a terminator that +suspends autonomy has fired. + +Scoping never spans a close. An annotation close ends the loop, and a +later round on the same document opens a new one, reading the whole +document again. + +After any +review round, relay the report to the developer, then stamp the +verdict into the document's field — 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. +The subsection sequences further checks inside its own turn — the model +self-report before the relay, the report's citations after it — which +this sentence deliberately does not restate, so gaining one does not +make it stale. The order has one named exception, defined in that +subsection: a plan's diff-scoped LGTM is relayed and its round record +written, while only the frontmatter stamp waits for the confirming +full-document round. + +### The audit pair at the consumption gate + +Where the technical-design offer is accepted, the audit waits: the +design is the last producer of changes to its design spec, and the +two are then audited as one target — an audit pair. The gate makes +one offer for that audit pair rather than one per document, and the +offer +names both documents, so declining it releases the chain debt of the +two it named and nothing besides. Where the audit runs instead, it +discharges that debt for both documents it read. The other arm stays +per-document: choosing it dispatches one full-document architect +round on each document that carries chain debt, each discharging the +debt of the one it read, and plan-writing waits for every verdict so +dispatched. The brief +confirms the auditor's two preconditions: every edit from the +conversation is written to disk, since one unsaved decision +manufactures a run of false defects; and the propagation gate below +has passed, leaving no confirmed hit, when that agent is available. + +### Per-round commits on a document branch + +Asking whether the loop may commit per round is not that suggestion, and +the difference is the speech act rather than the timing. The suggestion +above says a moment to commit has arrived; the consent question asks +once, before any round runs, for standing authorization to use a +mechanism — and a "no" leaves the authoring phase exactly as this +paragraph describes it. That is why it may be asked during authoring +while the suggestion may not. A set `review.per-round-commit`, read as +the process-settings rule says, is that standing authorization already +given or withheld, and the clause is not asked; unset, it is asked as +the workflow rule's review loop says, "and record" among its answers. + +One shape of that sooner call has a convention, because practice kept +reaching for it: **per-round commits on a document branch.** When the +developer authorizes it, the loop commits the reviewed document once per +round, as the round's last act. That boundary matches the ledger's own +unit — a round mutates the document several times (the stamp, the +triage, the fix wave, any gate episodes), and one commit after the wave +records what the round found together with what the session did about +it. + +The commits go to a local branch named `.docs`, never to the +topic branch itself. Git refuses a ref nested under an existing branch, +so `feature/-/docs` cannot exist while its parent +does; the +suffix takes a dot because the branch convention already spends hyphens +on name parts, where `-docs` would read as a topic about documenting. + +The loop runs on that branch for the whole authoring phase — the design +spec's rounds, the technical design's and the plan's alike — and the +topic branch takes it at the implementation-ready gate: by fast-forward +where the history is wanted whole, by squash where it is not. That +choice belongs to the project rather than the session, so the settings +key `docs-branch.merge` — `squash` or `fast-forward`, read as the +process-settings rule says — records it where it binds. Until a project +migrates to the key, a `CLAUDE.md` note — at the repo root or beside the +documents — declares it too, the key winning where the two disagree and +the session saying so. A session with neither asks at the gate, and the +answers include "squash, and record" and "fast-forward, and record", +which write the key through the loader's `--set` where a settings block +names the loader. Either way the document branch survives the merge, +which keeps loop churn off any published branch until somebody pushes it +and leaves the surviving ref marking where authoring ended. + +Both halves of "local" are worth knowing before relying on it. Churn +stays private, and the history dies with the working copy: a teammate +cannot see it, and a lost machine takes it. That is still more than the +alternative, where the same rounds live only in a transcript, but it +means "return the document to the state round three read" is a promise +about one clone rather than about the repository. + +What per-round commits never do is replace the ledger. Git says which +lines changed; the ledger says with what intent and on whose license, +and a diff carries neither "narrowed the claim" nor a cited ADR. A +`` clause may thin to a sentence where the commit carries +the detail; it does not go. Nor does a sha stand in for a hash: a round +heading that one day carried its commit's sha would name that round, +and it never stands in for the `integrity:` hash, which is computed from +the body and must work on a document nobody committed — the default +path, where no sha exists. From dbf9315312d70d2d6f9dee5ebd6b938d91f10ca0 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:21:21 +0100 Subject: [PATCH 27/59] feat(working-process): review-loop skill --- .../skills/review-loop/LEDGER.md | 17 +++--- .../skills/review-loop/PROCEDURE.md | 58 +++++++------------ .../skills/review-loop/SKILL.md | 39 +++++++++++++ 3 files changed, 68 insertions(+), 46 deletions(-) create mode 100644 plugins/working-process/skills/review-loop/SKILL.md diff --git a/plugins/working-process/skills/review-loop/LEDGER.md b/plugins/working-process/skills/review-loop/LEDGER.md index f4583ba..f3dc180 100644 --- a/plugins/working-process/skills/review-loop/LEDGER.md +++ b/plugins/working-process/skills/review-loop/LEDGER.md @@ -109,8 +109,7 @@ Every terminal line carries exactly one authorizer. A fix one review licenses can land in a document other than the reviewed one — a plan review's finding whose `origin` names a judged -document is the -case the workflow rule names. The disposition line then lands in the +document is the case `PROCEDURE.md`, beside this file, names. The disposition line then lands in the ledger of the document that changed, and the reviewed document's line points at it in its `` clause, naming that document and the heading the line sits under: one authorizer, two documents, two @@ -118,7 +117,7 @@ lines, and the invariant above holds on each. The pointer needs no clause of its own — `` already belongs to the `fixed` line's shape, so the clause table stays closed. In the changed document the line goes under its latest round heading, or with the -body note the resolution annotation above already owes, where that +body note the resolution annotation the spec-plan-lifecycle rule already owes, where that document is stamped and no fresh round ran. A document whose loop closed at `LGTM` has neither — the annotation is defined for `concerns` and for a `blocking` verdict closed by adjudication, never for `LGTM` — @@ -190,8 +189,7 @@ fact a second home. Where a session discharges the debt and dies before annotating, the annotation's own derivation licenses a later session to write it; on a document still in flight only the decline path has nothing to derive from, and there the debt correctly re-surfaces and the -developer declines again. On a document already `implemented` the -Chain debt entry's owner leg makes even that derivable, from the +developer declines again. On a document already `implemented` the owner leg of the Chain debt entry, in the `process-status` skill's `UNFINISHED-WORK.md`, makes even that derivable, from the standing decision it cites. Ledger lines written before this merge stay as written, as the `scope` @@ -221,7 +219,7 @@ It carries the leading token `signal`, no severity — a judgment about the next round's marginal value is not a finding — and no authorizer, since nobody licensed it. It joins no anchor: a stop signal owes nobody a next move, so it is closed the moment it is written, as a gate line -is. The workflow rule owns the ask that produces it. +is. `PROCEDURE.md` owns the ask that produces it. ### Gate lines @@ -238,8 +236,7 @@ Neither carries a license either, because a hit's fix is licensed by its own derivation. A hit of the coverage duty whose fix needs a decision no derivation -settles is held for the developer — the one exception the workflow rule -makes to hits never waiting. It takes a third shape, rewritten in place +settles is held for the developer — the one exception `PROCEDURE.md` makes to hits never waiting. It takes a third shape, rewritten in place to one of three terminal shapes, so its state always has one home: - hit held — ; question: ; options: @@ -299,11 +296,11 @@ A gate episode always lands somewhere: its lines are the reason a later reader need not re-derive what the session already settled. No gate-line shape covers a hit left outstanding when the re-dispatch -bound in the workflow rule stops an episode. That state owes the +bound in `PROCEDURE.md` stops an episode. That state owes the developer a decision, so neither `hit fixed` nor `hit dismissed` can honestly carry it, and `hit held` is scoped to the coverage duty's hits; no anchor surfaces it today — a stated gap, not an oversight. -Until a shape exists, the workflow rule's report is its only record. +Until a shape exists, the report `PROCEDURE.md` prescribes is its only record. A `hit fixed` line puts the gate's ordinary work where the next diff-scoped brief already looks, beside the round's `fixed` lines. A diff --git a/plugins/working-process/skills/review-loop/PROCEDURE.md b/plugins/working-process/skills/review-loop/PROCEDURE.md index 153bcd3..b5f88af 100644 --- a/plugins/working-process/skills/review-loop/PROCEDURE.md +++ b/plugins/working-process/skills/review-loop/PROCEDURE.md @@ -128,8 +128,7 @@ available: audit rather than at the relay. This is the citation's analogue of the model self-report comparison above — the same duty, on the other thing a report asserts about the world. -- The stamp — the field, any fallback record, and the round record - the lifecycle rule defines — lands as one edit, body record first +- The stamp — the field, any fallback record, and the round record `LEDGER.md`, beside this file, defines — lands as one edit, body record first where edit granularity forces separate writes, and goes to the document named in the report, never to "the most recent dispatch". The same exception splits that one edit: on a plan's diff-scoped @@ -168,7 +167,7 @@ verdict dispatch, ask once whether the loop may run autonomously — yes / not now / not in this session — state the round cap with the question, and honour the answer for the rest of the Claude Code session without asking again. The same question carries a second clause wherever -the lifecycle rule's per-round commits are available: whether the loop +the per-round commits defined under *Per-round commits on a document branch* below are available: whether the loop may commit the reviewed document once per round. One question, two answers, asked once. Each clause has a settings key, `review.autonomy` and `review.per-round-commit`, read as the process-settings rule says: @@ -186,7 +185,7 @@ finding is self-fixable when the session can cite the decision that licenses the fix — a statement in the document itself, a glossary term or `_Avoid_` ban, a recorded ADR, or a line carrying `ruling:` — and the citation goes on the finding's line in the disposition -ledger the spec-plan-lifecycle rule defines. Everything else is held +ledger `LEDGER.md` defines. Everything else is held for the developer, and a finding that could go either way is a decision. Consequences the loop states outright: @@ -211,7 +210,7 @@ decision. Consequences the loop states outright: way, and its `held` line names in `options:` which named document is fixable at once. A licensed fix lands in the ledger of the document that changed, and the plan's line points at it, by the cross-document - clause the spec-plan-lifecycle rule defines — which also leaves the + clause `LEDGER.md` defines — which also leaves the design spec's `integrity:` stamp stale, as any body edit to either document of an audit pair does. - A fix that adds a mechanism is held whatever its severity, and a @@ -270,7 +269,7 @@ escalations, a round after `blocking`, held gate hits, a fix the mechanism hold stops, adjudicating a `blocking` verdict, withdrawing or deferring a registered decision, and moving a `status`. A stand-in's answer is not developer contact, so it resets no cap. During -implementation it may also answer the questions step 6 describes. +implementation it may also answer the questions the workflow rule's step 6 describes. Provisional decisions reach the developer as one *provisional batch*: every line under the document's `## Review rounds` whose authorizer is @@ -322,8 +321,7 @@ guards, as a held finding blocks a fresh round, and the session puts its question to the developer. The answer lands where the decision belongs — in the spec's register, or as the plan's `**Defers:**` line — and the gate re-runs over the changed document and whatever depends on it, as a -fresh episode; the dispatch goes out once that episode passes. The -spec-plan-lifecycle rule defines the `hit held` line and its terminal +fresh episode; the dispatch goes out once that episode passes. `LEDGER.md` defines the `hit held` line and its terminal shapes. A report's body governs, never its closing token. Where a report lists @@ -339,16 +337,14 @@ those lines on every run, clean ones included, between the hits and the token. A hit the session believes is wrong is dismissed, never silently: the -session writes the `dismissed` line the spec-plan-lifecycle rule -defines and reports the dismissal in the next report it relays to the +session writes the `dismissed` line `LEDGER.md` defines and reports the dismissal in the next report it relays to the developer. A dismissed hit is a report, not a question, so it never enters the held batch and never spends the round's one interruption — the developer reads the dismissal and keeps their standing veto over it. The written line is what makes the gate terminate: a dismissed hit recurs on every re-dispatch, so a gate waiting on a hitless audit would wait forever, and a dismissal nobody wrote down would be re-derived -from nothing every round. Both dispositions take the gate lines the -spec-plan-lifecycle rule defines. +from nothing every round. Both dispositions take the gate lines `LEDGER.md` defines. Two re-dispatches bound one gate episode — the run before a single dispatch, never the document's lifetime, so every round gets its own @@ -386,8 +382,7 @@ The ledger is therefore always in scope for a diff-scoped round as context, never as a review target, and what that protects is narrow: - settled lines may be re-raised only with new evidence — new against - what the folded line records, the base the spec-plan-lifecycle rule - defines — which routes to `held` rather than to a fold. A line + what the folded line records, the base `LEDGER.md` defines — which routes to `held` rather than to a fold. A line carrying `ruling:` is settled by that clause; a historical line written before this design, `resolved (declined)` included, carries no authorizer clause and is settled by its token alone. Both @@ -417,8 +412,7 @@ Important behind and still not repay a re-read. That judgment concerns the next round's marginal value, never whether the document is good enough, and it informs the developer's decision rather than replacing it. The signal is recorded where a later session can cite it: one line -under the heading of the round that gave it, in the shape the -spec-plan-lifecycle rule defines. A signal surviving only in a relay +under the heading of the round that gave it, in the shape `LEDGER.md` defines. A signal surviving only in a relay dies with the next compaction, and practice has needed it twice — once to justify overriding one, once to close a loop on one. Where the ledger records a deviation from a reviewer's suggestion, @@ -468,15 +462,14 @@ evidence to attack, never a defence to protect. `license:` is never re-fixed autonomously. Two readings of one license are a contested reading, so it escalates as held, the flip named. A re-raise against a line carrying `ruling:` is the relitigation case - instead, and the spec-plan-lifecycle rule owns it. A line carrying + instead, and `LEDGER.md` owns it. A line carrying `provisional:` cites no license, so a re-raise against it goes through ordinary triage and the tripwire does not apply. The cap guards spend and the signal guards sense; both escalate, and neither is a wall. Relay stays the developer's standing veto — every report reaches them before the session acts on it — and a model-cap -refusal mid-loop forces developer contact: the drop-or-wait -question above is never answered autonomously. +refusal mid-loop forces developer contact: the drop-or-wait question the workflow rule's model selection asks is never answered autonomously. ### What a diff-scoped LGTM certifies @@ -507,8 +500,7 @@ arm does not, and plan-writing follows its dispositions. Declining is the developer discharging the chain debt by release rather than by performance, and the discharge is recorded rather than remembered: the dispatcher appends `, debt discharged ` to the -diff-scoped LGTM heading, in the shape the spec-plan-lifecycle rule -defines, and that annotation defeats the gate's re-ask. The other two +diff-scoped LGTM heading, in the shape `LEDGER.md` defines, and that annotation defeats the gate's re-ask. The other two paths write the same token. For a plan the loop closes only when the latest round heading is @@ -548,14 +540,11 @@ document again. After any review round, relay the report to the developer, then stamp the -verdict into the document's field — 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. -The subsection sequences further checks inside its own turn — the model +verdict into the document's field — this sentence and the bullet list under *Dispatching a verdict agent* above state the same relay-before-stamp ordering. +That list sequences further checks inside its own turn — the model self-report before the relay, the report's citations after it — which this sentence deliberately does not restate, so gaining one does not -make it stale. The order has one named exception, defined in that -subsection: a plan's diff-scoped LGTM is relayed and its round record +make it stale. The order has one named exception, defined under *What a diff-scoped LGTM certifies* above: a plan's diff-scoped LGTM is relayed and its round record written, while only the frontmatter stamp waits for the confirming full-document round. @@ -575,23 +564,20 @@ debt of the one it read, and plan-writing waits for every verdict so dispatched. The brief confirms the auditor's two preconditions: every edit from the conversation is written to disk, since one unsaved decision -manufactures a run of false defects; and the propagation gate below +manufactures a run of false defects; and the propagation gate above has passed, leaving no confirmed hit, when that agent is available. ### Per-round commits on a document branch -Asking whether the loop may commit per round is not that suggestion, and -the difference is the speech act rather than the timing. The suggestion -above says a moment to commit has arrived; the consent question asks +Asking whether the loop may commit per round is not the lifecycle rule's commit suggestion, and +the difference is the speech act rather than the timing. That suggestion says a moment to commit has arrived; the consent question asks once, before any round runs, for standing authorization to use a -mechanism — and a "no" leaves the authoring phase exactly as this -paragraph describes it. That is why it may be asked during authoring +mechanism — and a "no" leaves the authoring phase exactly as that rule describes it. That is why it may be asked during authoring while the suggestion may not. A set `review.per-round-commit`, read as the process-settings rule says, is that standing authorization already -given or withheld, and the clause is not asked; unset, it is asked as -the workflow rule's review loop says, "and record" among its answers. +given or withheld, and the clause is not asked; unset, it is asked as *The review loop* above says, "and record" among its answers. -One shape of that sooner call has a convention, because practice kept +One shape of the sooner commit the lifecycle rule leaves to the developer has a convention, because practice kept reaching for it: **per-round commits on a document branch.** When the developer authorizes it, the loop commits the reviewed document once per round, as the round's last act. That boundary matches the ledger's own diff --git a/plugins/working-process/skills/review-loop/SKILL.md b/plugins/working-process/skills/review-loop/SKILL.md new file mode 100644 index 0000000..a0ee8fa --- /dev/null +++ b/plugins/working-process/skills/review-loop/SKILL.md @@ -0,0 +1,39 @@ +--- +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. From 7701c47d81d71e1d13875603abe6a9648b132f04 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:30:26 +0100 Subject: [PATCH 28/59] refactor(working-process): workflow rule keeps the offers, the procedure moves to review-loop --- plugins/working-process/SETTINGS_REGISTRY.md | 4 +- plugins/working-process/rules/workflow.md | 628 ++----------------- 2 files changed, 43 insertions(+), 589 deletions(-) diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index c0a214d..8682ae8 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -119,7 +119,7 @@ question: May the architect and system-designer personas be consulted as a desig scope: personal values: yes | no default: unset -read-by: working-process/rules/workflow.md +read-by: working-process/skills/review-loop/PROCEDURE.md question: May the review loop run autonomously, within the round cap? ## review.per-round-commit @@ -127,7 +127,7 @@ question: May the review loop run autonomously, within the round cap? scope: personal values: yes | no default: unset -read-by: working-process/rules/workflow.md, working-process/rules/spec-plan-lifecycle.md +read-by: working-process/skills/review-loop/PROCEDURE.md, working-process/rules/spec-plan-lifecycle.md question: May the review loop commit the reviewed document once per round? ## ticket.root diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 3674520..9806370 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -33,15 +33,13 @@ disables its suggestion — never the work itself. (when the working-process plugin is installed) to stress-test its language against the project's domain terms. 3. **Grilled spec → architect review.** Offer a dispatch of the - working-process `architect` agent (when available); dispatch and - stamping follow the verdict-agent dispatch subsection below. - Dispatch it on the most capable available model, named explicitly. - When the `propagation-auditor` agent is available, a propagation - audit gates that dispatch and every later round — the dispatch - subsection below defines the gate and its dispatch points. Offer the - same audit at authoring time as well, after any multi-site edit; - that offer stands outside the loop, so the definition below does not - carry it. + 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. 4. **Spec → plan.** At the spec's consumption gate, before the plan is written, offer an integrity audit when the `integrity-auditor` agent is available: a fresh-context read of the whole design spec, and of @@ -51,8 +49,8 @@ disables its suggestion — never the work itself. every document the stamp names — a match means the standing stamp satisfies the gate, and the spec-plan-lifecycle rule owns that comparison. For a judged document whose LGTM came from a diff-scoped - chain the offer takes the pair-offer form the verdict-agent dispatch - subsection defines — one pair offer for an audit pair, never one per + chain the offer takes the pair-offer form the `review-loop` skill's procedure reference + defines, when that skill is available — one pair offer for an audit pair, never one per document — and narrows as that definition says when the auditor is absent. @@ -112,22 +110,11 @@ disables its suggestion — never the work itself. relative to the plan's own directory — so the plan-adversary always has each design to read. - Where the technical-design offer is accepted, the audit waits: the - design is the last producer of changes to its design spec, and the - two are then audited as one target — an audit pair. The gate makes - one offer for that audit pair rather than one per document, and the - offer - names both documents, so declining it releases the chain debt of the - two it named and nothing besides. Where the audit runs instead, it - discharges that debt for both documents it read. The other arm stays - per-document: choosing it dispatches one full-document architect - round on each document that carries chain debt, each discharging the - debt of the one it read, and plan-writing waits for every verdict so - dispatched. The brief - confirms the auditor's two preconditions: every edit from the - conversation is written to disk, since one unsaved decision - manufactures a run of false defects; and the propagation gate below - has passed, leaving no confirmed hit, when that agent is available. + 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. + 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 @@ -137,8 +124,8 @@ disables its suggestion — never the work itself. context cannot count on it loading. 5. **Plan → adversary review.** Before implementing a non-trivial plan, offer a working-process plan-adversary agent dispatch (when - available); dispatch and stamping follow the verdict-agent dispatch - subsection below. + available); dispatch and stamping follow the `review-loop` skill's + procedure reference, when that skill is available. Dispatch it on a model scaled to the plan's size, complexity, and risk — the most capable available for complex or risky plans, one family below for small mechanical ones — named explicitly. @@ -147,13 +134,14 @@ disables its suggestion — never the work itself. superpowers:systematic-debugging when available. A question no document settles — an implementer's, or the session's own while it executes a plan — is answered by the session, and the answer is a - provisional decision, defined under *The stand-in and the - provisional batch* below. It is written when taken to + provisional decision, which the `review-loop` skill's procedure reference + defines under *The stand-in and the provisional batch*, when that skill is + available. It is written when taken to `.claude/working-process//provisional.md`, `` being the plan's basename or, where no plan exists, the design spec's: one line per decision — date, question, answer, author (`session` or - `stand-in `) — under the dispatch-record store's `.gitignore` - guard, and no ledger line is written. The session that took them + `stand-in `) — in a store kept out of git by a `.gitignore` containing + exactly `*`, and no ledger line is written. The session that took them relays the list in its closing report; an answer there settles an item and is appended to its line, and the provisional batch at the `implemented` move carries what is still unanswered. An execution @@ -182,7 +170,8 @@ a path-scoped rule has not loaded before the first file is written. Both audits offered above run in the background, so a gated dispatch waits for its audit's task notification before it is issued — a sequencing rule rather than a blocking call, running on the relay -machinery the verdict-agent dispatch subsection already defines. +machinery the `review-loop` skill's procedure reference defines, when that +skill is available. Model selection for these dispatches: always name the model explicitly — an omitted model inherits the session's model, defeating the heuristic @@ -228,8 +217,10 @@ question appended, and tell neither what the other said. Dispatch as a named background agent, so the transcript stays inspectable. A contribution is written to its dispatch record before it is relayed, -taking the timestamp shape of the two the verdict-agent dispatch -subsection defines: a consultation mints no round heading, so it has +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 `*`: a consultation mints no round heading, so it has no ordinal to derive, and several consultations of one persona on one subject in one day are expected. The floor is met in that file — attributed and substantially verbatim, compression allowed and merging @@ -298,7 +289,8 @@ name and this convention does not govern it. The work's design spec, technical design and plan record the result in their `branch:` field — the topic branch, not the `.docs` branch a review loop's per-round commits use, which the -spec-plan-lifecycle rule names and which is a sibling of it rather than +`review-loop` skill's procedure reference names, when that skill is available, +and which is a sibling of it rather than a second topic branch. The ticket rule's sourcing order reads the current branch name first when a new document needs a ticket. @@ -321,553 +313,15 @@ recorded, and a fresh session or a compaction may ask again. ## Dispatching a verdict agent -Dispatching a verdict agent (`architect`, `plan-adversary`), when -available: - -- From an interactive session the dispatch always runs in the - background — a review never blocks the session, mirroring the - review-reports rule's precedent. A run with no interactive - dispatcher cannot relay, so it never stamps; on a document whose - field is still unstamped, the next interactive touch re-offers the - round through the lifecycle rule's offer loop. A round lost on an - already-stamped document leaves no signal and is accepted as lost — - never corruption, only a missing re-run. -- Before dispatch, resolve any undecided Process directory - (`docs/specs/`, `docs/technical-designs/`, `docs/plans/`) so the - first-create question cannot interrupt the stamp turn. -- At dispatch, tell the developer the round is running in the - background and its result will arrive as a task notification, with - progress visible in the session's task list. -- On the completion notification, in one turn and in this order: - verify the agent's model self-report (the comparison the lifecycle - rule defines), write the dispatch record defined below, relay the - report to the developer, check every citation the report supplies - against what it names, then stamp the verdict (`LGTM` | `concerns` | - `blocking`) into the reviewed document's `architect:` / - `adversary:` frontmatter field. The citation check follows the relay - rather than preceding it, because a wrong citation in conversation - costs a correction while a wrong one in the record outlives the - loop. The order has one named exception, defined under *What a - diff-scoped LGTM certifies* below: a plan's diff-scoped LGTM. -- The dispatch record is written before the relay. The dispatcher - saves what the agent returned, verbatim — extracted from the agent's - transcript, never retyped, since a retyped record once shared none of - its 23 lines with the report it claimed to hold. In Claude Code the - task's output file is that transcript, and the report is the - hand-back call's message: - `jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="SubagentHandback") | .input.message' `. - Where that prints nothing, the agent's final assistant text is the - report; where no transcript is readable, the record says it was - copied from the relay. It goes under a header of the date, - the agent, the model self-report, the subject, and — where a - document was reviewed — its size, `size: `: 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`, - or with the `sed` stage dropped for a document without frontmatter — - with no frontmatter and no `ticket`, since the record is evidence rather - than a process artefact. It goes to `.claude/working-process/` at - the repo root (`git rev-parse --show-toplevel`). A record survives - compaction, the session's end and a branch switch, and no more; that - bound is what the relay's condensation below leans on. Audits write - none — a propagation gate's hits land in the ledger and an integrity - audit's dispositions land as the edits it causes plus the - `integrity:` stamp, so a record would give one fact a second home. -- The store is git-ignored by a `.gitignore` containing exactly `*`. - Before writing a record the dispatcher ensures that file holds - exactly that, rather than writing it once: the guard repairs a store - directory made by hand, a file someone truncated, and a `git clean` - that took the file and left the directory. A project already - ignoring `.claude/` still gets the file, since the store may not - depend on another file's contents. -- The record's name carries its agent and one discriminator: - - .claude/working-process//-round-.md - .claude/working-process//--.md - - `` is the reviewed document's basename without its extension, - one directory per subject. A verdict agent takes the round ordinal, - derived the way the heading will derive it — the highest ordinal the - document's rounds carry, plus one, ordinals continuing across - loops — because the record is written before that heading exists. A - dispatch that reviews no document takes its subject as the stem, - kebab-cased and capped at sixty characters, and the timestamp shape, - having no ledger to draw an ordinal from; an `architect` dispatch on - a bare question is one such, and the test is whether a document - exists rather than which agent ran. Where a round-ordinal name is - already taken, the new file appends the timestamp to it — - `-round---.md` — which settles the - superseded round two sessions can produce on one ordinal without - asking either to judge which report is stale. A timestamp name - collides only when a second record lands in the same second, where - appending the same timestamp would reproduce the taken name, so it - takes the lowest free counter suffix instead: `-2`, then `-3`. -- The relay opens with one header line, then one line per finding. The - header carries the verdict, the model self-report, the finding count - by severity, how many decisions await the developer, and — where a - document was reviewed — its size and the change since the previous - record of the same document and agent; with no earlier record - carrying a `size:` line it shows the size alone. The relay reports - the number and judges nothing. Each - finding takes one line — severity, origin, claim — except where the - reviewer emits no origin: the `architect` reads one document and - every finding it returns originates there, so an architect relay's - line carries severity and claim alone. -- Condensation reaches narrative prose alone, whatever a session's - output style prescribes. The finding list is never condensed, and no - finding or its severity is ever dropped: the relay is the - developer's standing veto, so a finding nobody printed is a finding - nobody could overrule. Narrative is safe to condense because the - dispatch record holds the full text, which makes an expansion a - quotation rather than a reconstruction — so the relay names that - record's path, and the developer can open what was condensed. -- The header's count of decisions is the findings for which the - session can cite no license, plus those whose suggested fix adds a - mechanism and carries out no `ruling:` (the hold under *The review - loop*), derived at relay time from the report and the decisions - already written down — before any ledger line exists, since `open` - is written at stamp time and triage follows the stamp. The `held` - lines the same round later writes are that count's check: they come - to the same number, and a divergence means triage found a license - the relay missed, triage lost one the relay claimed, triage placed a - fix on the other side of the mechanism line than the relay did, or - the oscillation tripwire held a finding that does carry a license. - The last is lawful, so the check reports the number rather - than asserting a fault. Verdicts that suspend autonomy — `blocking`, - the spent round cap, the all-Minor signal — stay out of the count: - they decide whether the loop continues rather than what a document - says, and the relay reports them in its own right. -- A citation the report supplies — a file and line, an identifier, a - count — is checked against what it names before it is written into - the document or acted on by a fix. A precise citation reads like - verification and is not one, and the dispatcher who copies it into - the ledger launders a reviewer's evidence into the project's record. - The check is cheap and its absence is measured: one cycle relayed a - line number off by one and an identifier that did not exist, both - quoted with exact positions, both caught later by a propagation - audit rather than at the relay. This is the citation's analogue of - the model self-report comparison above — the same duty, on the other - thing a report asserts about the world. -- The stamp — the field, any fallback record, and the round record - the lifecycle rule defines — lands as one edit, body record first - where edit granularity forces separate writes, and goes to the - document named in the report, never to "the most recent dispatch". - The same exception splits that one edit: on a plan's diff-scoped - LGTM the round record lands while the frontmatter stamp waits for - the confirming round. -- The sequence ends the delivery, not the loop: after relay and stamp - the session may fix the document and dispatch a fresh round, or put - its questions to the developer first. -- At most one live round per document per field within the session; - superseding a running round stops it when the platform offers a - stop, otherwise the stale result is relayed as stale and never - stamped. A parallel round from another session is accepted as - undetectable and stays benign: both rounds record in the body and the - field holds the later stamp. One consequence postdates that decision — - a diff-scoped LGTM certifies a chain, so an interleave punches a hole - no round ever read. The discharge paths are the mitigation, since an - audit and a full-document round each read the whole document, and a - heading-derived cap over-counts under interleave, which escalates - early. -- When the reviewed document changed after dispatch — known only - conversationally; an out-of-session edit is accepted as - undetectable — the relay says so and the stamp waits for the - developer's call. -- When compaction leaves an in-flight dispatch unclear, check the task - list rather than guess, and never fabricate a pending result. -- An agent that dies or returns nothing is an ordinary error: relay - the failure and offer a fresh dispatch on the same tier. -- A consultation (`*-consult`) produces no verdict and nothing to - record. - -### The review loop - -Rounds after the first form a loop, and the loop is the offered unit — -no single re-dispatch is offered on its own. At the session's first -verdict dispatch, ask once whether the loop may run autonomously — yes -/ not now / not in this session — state the round cap with the -question, and honour the answer for the rest of the Claude Code session -without asking again. The same question carries a second clause wherever -the lifecycle rule's per-round commits are available: whether the loop -may commit the reviewed document once per round. One question, two -answers, asked once. Each clause has a settings key, `review.autonomy` -and `review.per-round-commit`, read as the process-settings rule says: -a set key answers its clause unasked, and only an unset clause is -asked. A yes or no may be given "and record" per clause — "yes, and -record; commits: not now" records the first clause alone — which -writes that clause's key through the loader's `--set` where a settings -block names the loader; "not now" and "not in this session" are never -recorded. Without consent every round -behaves as it did before: relay, stamp, and every proposal waits for -the developer. - -Triage decides each finding by its license, never by its grade. A -finding is self-fixable when the session can cite the decision that -licenses the fix — a statement in the document itself, a glossary term -or `_Avoid_` ban, a recorded ADR, or a line carrying `ruling:` — and -the citation goes on the finding's line in the disposition -ledger the spec-plan-lifecycle rule defines. Everything else is held -for the developer, and a finding that could go either way is a -decision. Consequences the loop states outright: - -- Severity is not the line. A Minor finding can be a naming call the - developer already ruled on; a Critical can be a contradiction with a - recorded ADR, which the ADR itself licenses the session to fix. -- A contradiction between two decision-bearing statements is held: - fixing for consistency would pick a winner silently. -- A finding the session believes is wrong is held with the session's - counter-evidence attached — never fixed silently, never dropped - silently. The session never arbitrates between a reviewer and a - recorded developer decision. -- Only written decisions license fixes. A decision settled in - conversation becomes citable by being written into the document, - which the fix itself accomplishes. A line carrying `provisional:` - licenses nothing until the developer confirms it, and neither does - the text its fix wrote. -- A finding whose `origin` names a judged document — a design spec or a - technical design — is held unless a written decision licenses the - edit, since changing either from inside a plan review is design work. - `origin` is a list, so a finding naming more than one holds the same - way, and its `held` line names in `options:` which named document is - fixable at once. A licensed fix lands in the ledger of the document - that changed, and the plan's line points at it, by the cross-document - clause the spec-plan-lifecycle rule defines — which also leaves the - design spec's `integrity:` stamp stale, as any body edit to either - document of an audit pair does. -- A fix that adds a mechanism is held whatever its severity, and a - license does not lift the hold. 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. Two fixes stay outside the hold: one carrying out - a line with `ruling:`, which the developer already decided, and a - propagation-gate hit's fix, which its derivation licenses. A fix the - session cannot place either way is held. The held line's `options:` - recommend the smaller option where it meets the requirements and - always include "accept as a documented limitation". - -A fix wave that deviates from a reviewer's suggestion records the -deviation and its rationale beside the text they concern — not only in -the ledger — so the next reviewer trips over the reason exactly where -the disagreement lives. - -Once the licensed fixes land, the loop either continues or yields: - -- Held set empty — dispatch the next round without asking, within the - cap. -- Held set non-empty — batch the held questions into one message at the - relay turn (per item: the claim in one line, why it is held, the - question, and the options with the session's recommendation), then - wait. A fresh round dispatches only on a document with nothing - awaiting the developer, since a round over known-open decisions - re-reports them at the loop's most expensive tier for no - information. The developer may still order a round on the partial - document — every step is an offer. Where a stand-in is named, the - held findings go to it instead, and once its answers land the loop - continues as with the held set empty: a `provisional:` line awaits - only the provisional batch, never the next round. - -One batch per round is the contract: the developer is interrupted once -per round, and only over a decision that is genuinely theirs. - -### The stand-in and the provisional batch - -The developer may name a *stand-in* in conversation — another agent or -tool that answers for them — for the rest of the Claude Code session; a -session that loses the delegation on compaction asks again rather than -guess. The stand-in answers the held findings a round would put to the -developer, and each answer is a *provisional decision*: it takes effect -at once, and its disposition line carries -`provisional: (stand-in )` where the developer's answer -would carry `ruling:`. An answer covers only the question put to it; a -later event needs a new question. A stand-in may answer a `blocking` -round's held findings, whose fixes land while the loop stays stopped. -Every other act stays the developer's: round orders, cap and all-Minor -escalations, a round after `blocking`, held gate hits, a fix the -mechanism hold stops, adjudicating a `blocking` verdict, withdrawing or -deferring a registered decision, and moving a `status`. A stand-in's -answer is not developer contact, so it resets no cap. During -implementation it may also answer the questions step 6 describes. - -Provisional decisions reach the developer as one *provisional batch*: -every line under the document's `## Review rounds` whose authorizer is -`provisional:`, and at a plan's `implemented` move the unanswered items -of its provisional list. It is delivered with the request for the document's -next status move, and for a design spec or a technical design no later -than its consumption gate, settled there before the integrity audit -since a reversal edits the audited body. An approval given before the -request still gets the batch first. A line a plan review writes into an -already-consumed judged document travels in the plan's batch, and one -answer settles both lines. The developer confirms or reverses each -item. Confirmed, `provisional:` becomes `ruling: `, the date of -the answer. Reversed, the session applies the answer at once and -rewrites the line in place to the terminal state the answer gives — a -reversed `fixed` may become `declined` or stay `fixed` with narrower -text, a reversed `declined` becomes `fixed` — carrying `ruling:`, and -runs the propagation gate over the change as after any fix wave. A move -made on the developer's word leaves no `provisional:` line behind. - -### The propagation gate - -When the `propagation-auditor` agent is available, a passing propagation -gate is the precondition for the dispatches it gates: the session -dispatches the audit over the document, fixes its hits, and repeats -until no confirmed hit remains, so an expensive reader only ever meets -a mechanically consistent document. The gate fires before every -verdict-agent dispatch, first rounds included — authoring errors exist -before any repair; after a fix wave, before the next round; and before -an integrity audit. A hit's fix is licensed by its own derivation — a -recounted counter and an enumerated missed call site decide -themselves — so hits never wait for the developer, with one named -exception, for the coverage duty's hits alone. - -The two coverage hits — a registered decision no task cites, and a task -lacking its `**Realizes:**` line — are triaged by license. Where a task -already does the work and lacks only its annotation, the task's text -licenses adding the identifier. Where no task realizes the decision and -the decision's text settles every choice the missing task requires, the -decision licenses writing it, and the next round's brief names it among -the previous wave's fixes. Where writing the task needs a choice the -decision does not make, the hit is held: its question is that missing -decision, not the gap, which is already established. Any other hit of -the coverage duty is fixed where its derivation settles the fix and held -where it does not, as when breaking a `replaced by` cycle means choosing -which entry stands. No other duty's hit is ever held. - -A held hit ends its gate episode and blocks the dispatch the gate -guards, as a held finding blocks a fresh round, and the session puts its -question to the developer. The answer lands where the decision belongs — -in the spec's register, or as the plan's `**Defers:**` line — and the -gate re-runs over the changed document and whatever depends on it, as a -fresh episode; the dispatch goes out once that episode passes. The -spec-plan-lifecycle rule defines the `hit held` line and its terminal -shapes. - -A report's body governs, never its closing token. Where a report lists -located hits and also carries `CLEAN`, the hits are the report and the -gate has not passed. It has happened more than once on the cheapest -family, and once under a brief that ruled the combination out in as -many words — so emphasis on the writing side is spent, and the guard -belongs to the dispatcher who reads. The rule is stated here rather -than generalised, because `CLEAN` is this agent's token and no other -report carries one. A `decision-coverage:` or `table-closure:` line is -neither a hit nor a breach of the token's position: the card writes -those lines on every run, clean ones included, between the hits and the -token. - -A hit the session believes is wrong is dismissed, never silently: the -session writes the `dismissed` line the spec-plan-lifecycle rule -defines and reports the dismissal in the next report it relays to the -developer. A dismissed hit is a report, not a question, so it never -enters the held batch and never spends the round's one interruption — -the developer reads the dismissal and keeps their standing veto over it. -The written line is what makes the gate terminate: a dismissed hit -recurs on every re-dispatch, so a gate waiting on a hitless audit would -wait forever, and a dismissal nobody wrote down would be re-derived -from nothing every round. Both dispositions take the gate lines the -spec-plan-lifecycle rule defines. - -Two re-dispatches bound one gate episode — the run before a single -dispatch, never the document's lifetime, so every round gets its own -gate. A third is not attempted. The session reports the hits still -outstanding, with the standing of a dismissal, and holds the dispatch -the gate was guarding: a gate that cannot come clean has not done the -one job the expensive reader depends on. The report names what keeps -recurring, since fixes breeding fresh hits is the failure this bound -exists to catch. It stays a report — the developer may order the -dispatch anyway, as they may order any step — so it never becomes a -second question in a round that already spent its one. Without the -agent installed, every dispatch proceeds as it did before. - -### Re-dispatch briefs - -The first round reads the whole document; every later round is -diff-scoped. Its brief names what changed since the round it follows, -directs the reviewer to attack the previous wave's fixes first — -including whether a fix added a mechanism its finding did not need — and -forbids re-reviewing the rest — repair-born defects are the dominant -late-round class, and diff-scoping also ends stale-read findings. - -The ledger supplies what changed. The previous round's `fixed` lines and -their `` clauses, together with any gate lines under the -same heading, are the record of that wave, so the brief cites them and -needs no snapshot, commit, or hash. Where the loop is not committing per -round, the ledger is the only durable account of the diff; where it is, -the commit carries the lines and the ledger still carries the intent. The -brief cites the ledger either way. - -Diff-scoping forbids re-reviewing the document beyond the diff, and the -ledger is part of the document — so without a clause the reviewer is cut -off from the one section recording what the developer already decided. -The ledger is therefore always in scope for a diff-scoped round as -context, never as a review target, and what that protects is narrow: - -- settled lines may be re-raised only with new evidence — new against - what the folded line records, the base the spec-plan-lifecycle rule - defines — which routes to `held` rather than to a fold. A line - carrying `ruling:` is settled by that clause; a historical line - written before this design, `resolved (declined)` included, - carries no authorizer clause and is settled by its token alone. Both - are the developer's decisions, and both are protected on the same - footing; -- `held` lines carry questions already put, so a round does not - duplicate one; -- lines carrying `provisional:` record nobody's decision yet, so they - are not settled and a reviewer may re-raise them like `license:` - lines; -- `fixed` lines carrying `license:` get no protection at all — the - previous round's are the diff and are named as the first thing to - attack, and older ones are simply unprotected, since a reviewer told - not to re-raise a fix would lose the property diff-scoping was - adopted for. - -The reviewer learns what it may not reopen, never what it may not find. -Naming the section rather than copying its lines keeps the brief from -growing with the round count. - -Every brief states the loop's terminators outright — the cap and the -all-Minor signal below — rather than improvising them late, and asks -the reviewer for its own stop signal: judge whether another round earns -its cost, and say what the round's leftovers are worth. The ask stands -every round, whatever grades the findings carry — a round can leave one -Important behind and still not repay a re-read. That judgment concerns -the next round's marginal value, never whether the document is good -enough, and it informs the developer's decision rather than replacing -it. The signal is recorded where a later session can cite it: one line -under the heading of the round that gave it, in the shape the -spec-plan-lifecycle rule defines. A signal surviving only in a relay -dies with the next compaction, and practice has needed it twice — once -to justify overriding one, once to close a loop on one. Where the ledger -records a deviation from a reviewer's suggestion, -the brief invites refutation of the recorded rationale — a rationale is -evidence to attack, never a defence to protect. - -### Terminators - -- `LGTM` ends the loop — on a plan, only a full-document round's LGTM - does. -- `blocking` suspends autonomy entirely: relay, stamp, stop — no further - round without the developer. It licenses no separate fix prohibition, - because triage already holds what the prohibition was reaching for: a - design reshape has no citable license by construction, so it is held - whatever the verdict's grade. `concerns` is the autonomy zone. -- Round cap: three autonomous rounds per document per field without - developer contact, counting only rounds that returned a verdict. - Hitting the cap escalates in one batch — what was fixed, what remains, - why — rather than halting silently, and any developer contact resets - the count. Developer contact is a message from the developer: not a - relay they read, not an escalation the session sent, not an unanswered - batch. The count is derived from the round headings and the reset - event is recorded nowhere, so the cap is best-effort by construction; - a session that cannot count its own rounds escalates rather than - assuming, since resetting to zero would let a long session grant - itself three fresh rounds after every compaction. A plan's confirming - full-document round counts like any other: the count folds round - headings, and excluding one kind would mean classifying them — a - second fragile derivation in the one place the rules already concede - the cap is best-effort. A plan whose loop spent its three rounds - therefore escalates once before its confirming round, which is the - most expensive shape a round takes and the one a cap guarding spend - should guard first. A run of `blocking` verdicts is unbounded by the - cap, for the reason the cap is stated in: it counts autonomous rounds, - and `blocking` suspends autonomy, so every continuation after one is - the developer's own decision rather than a round the cap governs. - Consenting to three rounds consents to three autonomous ones. -- All-Minor signal: two consecutive rounds whose findings are all Minor - end the unattended run. Triage the round as always — by license, never - by grade — and escalate with an offer of a fresh round instead of - dispatching one. The escalation is a question, so the loop stays open - until the developer answers it: the resolution annotation the - spec-plan-lifecycle rule defines records their close — on a plan, once - the confirming round has run — and no session writes it without their - answer. -- Oscillation tripwire: a finding re-raised against a line carrying - `license:` is never re-fixed autonomously. Two readings of one license - are a contested reading, so it escalates as held, the flip named. A - re-raise against a line carrying `ruling:` is the relitigation case - instead, and the spec-plan-lifecycle rule owns it. A line carrying - `provisional:` cites no license, so a re-raise against it goes - through ordinary triage and the tripwire does not apply. - -The cap guards spend and the signal guards sense; both escalate, and -neither is a wall. Relay stays the developer's standing veto — every -report reaches them before the session acts on it — and a model-cap -refusal mid-loop forces developer contact: the drop-or-wait -question above is never answered autonomously. - -### What a diff-scoped LGTM certifies - -A diff-scoped LGTM certifies a chain rather than a fresh whole-document -read: round 1 read the whole document, and every later wave was -reviewed by the round that followed it. What that chain still owes -differs by document. - -For a judged document, the consumption gate before plan-writing makes -the pair offer as one question — an integrity audit or a full-document -round — and never an offer followed by a re-offer of the option just -declined. When the `integrity-auditor` agent is absent the offer -carries the full-document round alone. For an audit pair the gate makes -one pair offer for both documents: its audit arm reads the two -together, while choosing its round arm dispatches one full-document -architect round on each document that carries the debt, and -plan-writing waits until every verdict so dispatched is settled under -the rules any verdict follows; the joint integrity audit stays a check -of its own. The two arms cost differently and the -offer says so: an audit returns material for the dispatcher to dispose -of and leaves the verdict alone, while a full-document round on a -judged document is a new loop's first round, since that document's -LGTM already closed its loop — it mints its own verdict and stamps it, -so a `concerns` there flips the field back while plan-writing waits. -The full-document-round arm therefore blocks plan-writing; the audit -arm does not, and plan-writing follows its dispositions. - -Declining is the developer discharging the chain debt by release rather -than by performance, and the discharge is recorded rather than -remembered: the dispatcher appends `, debt discharged ` to the -diff-scoped LGTM heading, in the shape the spec-plan-lifecycle rule -defines, and that annotation defeats the gate's re-ask. The other two -paths write the same token. - -For a plan the loop closes only when the latest round heading is -full-document: whatever ends its rounds while that heading -is diff-scoped, one confirming full-document round follows, and that -round's verdict is the one stamped. A round already full-document owes -no confirming round — it is the close. The confirming round inherits the gating -of whatever ended the rounds. Where autonomy still stands — -a diff-scoped `LGTM`, or a `concerns` inside the cap — the rules mandate -the round, so it is no decision of the developer's and spends none of -the round's one interruption. After `blocking`, the round cap or the -all-Minor signal it is the developer's to order, because each of those -suspends autonomy by its own terminator, and a round the rules mandate -cannot outrank a terminator that stopped the loop. - -A session never judges that the rounds are ending. The terminators do, -as does the developer closing the loop. While none has fired and the -held set is empty, the next round is diff-scoped and the loop simply -continues; the confirming round is owed the moment one fires, which is -the moment a session would otherwise write the resolution annotation. - -The plan case carries the single named exception to the relay-then-stamp -order above — a plan's diff-scoped LGTM is relayed and its round record -written, and only the frontmatter stamp waits for the confirming round. -Recovery therefore reads the ledger rather than the stamp. A plan whose -latest round heading is a diff-scoped `LGTM` that no later full-document -round follows is re-offered its confirming round at the document's next -touch, whatever the frontmatter says, since that heading is itself an -end. A latest heading of any other verdict is not an end, so there the -round is re-offered when something tries to end the rounds — an -annotation, an adjudication, a `status` move — or when a terminator that -suspends autonomy has fired. - -Scoping never spans a close. An annotation close ends the loop, and a -later round on the same document opens a new one, reading the whole -document again. - -The `## Dispatching a verdict agent` section above — its bullet list -and every subsection under it, this one included — and the lifecycle -rule's relay-then-stamp sentence state the same relay-before-stamp -ordering and are edited together when that changes. The other checks -this section sequences inside the dispatch turn are its own; adding one -leaves that sentence correct. +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. From 259770b29ea7797329044b4b7d8f4a0e17b95962 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:43:10 +0100 Subject: [PATCH 29/59] refactor(working-process): disposition ledger and per-round commits move to review-loop --- plugins/working-process/SETTINGS_REGISTRY.md | 4 +- .../rules/spec-plan-lifecycle.md | 423 +----------------- 2 files changed, 13 insertions(+), 414 deletions(-) diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index 8682ae8..9dad00f 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -103,7 +103,7 @@ question: Which tier runs the propagation gate — cheapest, mid or most-capable scope: team values: squash | fast-forward default: unset -read-by: working-process/rules/spec-plan-lifecycle.md +read-by: working-process/skills/review-loop/PROCEDURE.md question: How does the topic branch take the .docs branch at the implementation-ready gate — squash or fast-forward? ## consult.personas @@ -127,7 +127,7 @@ question: May the review loop run autonomously, within the round cap? scope: personal values: yes | no default: unset -read-by: working-process/skills/review-loop/PROCEDURE.md, working-process/rules/spec-plan-lifecycle.md +read-by: working-process/skills/review-loop/PROCEDURE.md question: May the review loop commit the reviewed document once per round? ## ticket.root diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index dea967e..407b12f 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -51,7 +51,8 @@ base: master # optional: branch the topic branch was cut from appear only once the corresponding step has run. - Every `status` move is the developer's: it happens on their word, or under a note in the project's instructions that names that move. - Under such a note the provisional batch the workflow rule defines + Under such a note the provisional batch the `review-loop` skill's procedure + reference defines, when that skill is available, goes into the report announcing the move, and its lines stay `provisional:` until the developer answers; converting or rewriting them on an `implemented` document is a process record, which the @@ -467,345 +468,6 @@ This is a lookup, not an Unfinished-work entry: a `revises:` pointer owes nobody a next move, and the implemented-document principle above already warns every reader of an archived document without it. -## The disposition ledger - -The body record a `concerns` or `blocking` round owes has a canonical -shape, not an improvised one — practice produced three competing -conventions across six documents before it was written down. The rounds -live under one section, `## Review rounds`, and each round opens with a -heading: - - ### — , , (round N[, ]) - -The scope token admits two values, `diff-scoped` and `full-document`, -and is omitted only on a round predating the distinction. A recovery -reading keys on the absence of `full-document`, so a full-document round -always says so. - -The latest round heading is the one carrying the highest ordinal, -wherever it sits in the section: no order is prescribed for the blocks -and live ledgers run both ways. Ordinals run per document and per field, -and continue across loops — a later loop opens at the next number rather -than at one, which is what the round cap's derivation from the headings -already assumed. - -Under the heading each finding takes one line, its disposition the -leading token: - - - open — [] - - held — [] ; question: ; options: - - fixed — [] ; ; - - declined — [] ; ; - -The severity bracket is omitted on a line whose sole authorizer is -`ruling:` **and** which no reviewer graded — both legs, never one: - - - fixed — ; ruling: ; - -`open` and `held` are the non-terminal states, and the only two -disposition states the Unfinished-work list anchors; the one gate line -it anchors, `hit held`, is defined under *Gate lines* below. `fixed` -and `declined` are terminal and say what became of the document: it -changed, or it stands. - -The two dates on a terminal line record different events and are both -written even when they coincide. The leading date is when the line -reached its terminal state; `ruling:` is when the decision it cites was -taken. On an ordinary developer-authorized line the two are the same day -and say so; on a fold they differ, and that divergence is the point of -carrying both. - -The severity slot is a reviewer's grade, so it is omitted exactly where -there is none: a change the developer directed mid-round is not a -finding, and inventing a grade for it would be the same manufacture the -authorizer rule forbids. This adds no fourth severity value; the -glossary's three stand. - -`fixed` and `resolved` merge because they were never two states. Both -mean the document changed on account of this finding, and they differed -only in who authorized it, which is now a clause. Merging also frees a -word the rules used for two objects — `concerns (resolved )` -annotates a verdict, while `resolved ` annotated a finding. - -- `open` — written at stamp time, before the findings are triaged. An - `open` line surviving a session means the remediation never ran, and - the document's next touch re-offers it. -- `held` — the finding needs the developer. The line carries the - concrete question and the options with the session's recommendation; - where the finding is disputed or contested, `counter:` carries the - evidence the developer needs in order to answer, and the oscillation - tripwire's named flip is that evidence. -- `fixed ` — the document changed on account of this finding. Its - authorizer says who decided: `license:` where the session cited a - written decision, `ruling:` where the developer did, `provisional:` - where a stand-in did. -- `declined ` — the document stands. It always carries `ruling:`, - or `provisional:` where a stand-in declined it, because declining is - a decision and triage gives a session no license - to decide. - -Each disposition line is written before the edit it describes, or with -it — never batched at the end of a wave. The dangerous failure is not a -session dying mid-round but a fix wave half-applied with no lines -written: the body has changed, nothing says which change belongs to -which finding, and the next round's brief reads a diff source that is -silently wrong. Writing contemporaneously makes a partial wave -self-evident, since `open` and `fixed` lines mixed under one heading say -exactly where the session stopped. - -The leading token is a queryable state. Clauses are payload. - -| clause | carries | on | -|---|---|---| -| `license: ` | the written decision the session acted on | `fixed` | -| `ruling: ` | the developer authorized it; on a fold, the prior ruling's date followed by `folding
` naming what it folds against | `fixed`, `declined` | -| `provisional: (stand-in )` | a stand-in the developer named decided it, on that date; it licenses nothing until the developer confirms it in the provisional batch, when it becomes `ruling:` | `fixed`, `declined` | -| `question:` | the question, phrased so one short answer resolves it | `held` | -| `options:` | the options and the session's recommendation | `held` | -| `counter:` | the session's evidence where the finding is disputed or contested | `held` | -| `deviation:
` | where the rationale for departing from a reviewer's suggestion lives | `fixed` | - -`question:` and `options:` are both required on a `held` line: the batch -that relays them is a transcript, and a session that dies between the -relay and the answer leaves the next session to re-derive the options, -possibly differently, so the developer answers a question that silently -changed. `counter:` and `deviation:` are conditional, written whenever -their condition holds. - -Every terminal line carries exactly one authorizer. - -A fix one review licenses can land in a document other than the -reviewed one — a plan review's finding whose `origin` names a judged -document is the -case the workflow rule names. The disposition line then lands in the -ledger of the document that changed, and the reviewed document's line -points at it in its `` clause, naming that document and -the heading the line sits under: one authorizer, two documents, two -lines, and the invariant above holds on each. The pointer needs no -clause of its own — `` already belongs to the `fixed` -line's shape, so the clause table stays closed. In the changed -document the line goes under its latest round heading, or with the -body note the resolution annotation above already owes, where that -document is stamped and no fresh round ran. A document whose loop -closed at `LGTM` has neither — the annotation is defined for `concerns` -and for a `blocking` verdict closed by adjudication, never for `LGTM` — -so the fix opens a heading of its own: - - ### — fix from - -It carries no ordinal and no verdict, which keeps it out of the round -cap's derivation and out of the Unfinished-work commands that anchor a -round heading: it records a fix, not a round. Two stamps go stale as on -any body edit — the `integrity:` hash stops matching, and the verdict -stops certifying the words that changed. The `integrity:` stamp is -read at the consumption gate alone: one gone stale after the plan was -written is expected and owes no new audit. The same heading serves a -register edit that a plan's held gate line licensed, on a design spec -whose loop has closed at whatever verdict: the heading then names the -plan whose gate held the hit, and that plan's terminal gate line names -the heading and the line under it. Unlike a review-licensed fix, such an -edit never joins a resolution note, even on a `concerns (resolved)` -spec: that note records what resolved the verdict, and this edit -resolves none. - -Payload costs nothing structurally. An Unfinished-work command under the -list's default scope guard is held to the frontmatter block, so no body -line reaches it at all; an entry publishing its own scope anchors a -leading disposition token or a round heading, and an indented -continuation matches neither. Payload under a line is therefore invisible -to every published command, and where it runs long it belongs in -indented sub-bullets rather than in a longer line. - -Two additions extend those shapes, and nothing else does: the -annotation here, and the cross-document fix heading above. A -diff-scoped `LGTM` heading gains `, debt discharged ` once the -chain debt it carries is discharged, and its presence defeats the -consumption gate's re-ask, as `, waived ` defeats the re-review -offer: - - ### — architect, , LGTM (round 3, diff-scoped), debt discharged - -The token goes after the closing parenthesis rather than inside it. A -parenthesised token qualifies a value — `concerns (resolved )` -changes what the verdict means — while a comma-appended token adds a -later event to a finished record, and this annotation is written later, -by a different actor, about a different event. - -Three paths discharge the debt, all three write the same token, and the -dispatcher writes it in every case: the developer declining the gate's -pair offer, written in the decline turn before the work that decline -licenses begins, and written for every document that offer named — a -declined offer over an audit pair discharges the chain debt of both. -What a decline never does is stand in for the audit itself: it writes -no `integrity:` stamp, leaves every other open finding open, and closes -no `blocking` verdict. "Do not run the audit" is a release from the -chain debt the offer named and from nothing else; an integrity audit, -written once its dispositions are -applied and before the `integrity:` stamp — and where that audit read an -audit pair, it discharges the debt of both documents it read, annotating -each document's own unannotated diff-scoped `LGTM` headings; and any -later full-document -round, at its stamping turn, whatever its verdict — the debt is -discharged by the reading, not by the grade. A full-document round reads -the whole document, so it annotates every unannotated diff-scoped `LGTM` -heading above it rather than only the one it follows. - -The token carries a date and nothing else. Each path leaves its own -trace — an `integrity:` stamp, a later full-document heading, or -neither — and no consumer reads the path, so recording it would give one -fact a second home. Where a session discharges the debt and dies before -annotating, the annotation's own derivation licenses a later session to -write it; on a document still in flight only the decline path has -nothing to derive from, and there the debt correctly re-surfaces and the -developer declines again. On a document already `implemented` the -Chain debt entry's owner leg makes even that derivable, from the -standing decision it cites. - -Ledger lines written before this merge stay as written, as the `scope` -token's introduction already established. The shapes they use are kept -here as described historical forms rather than deleted: - - - resolved — [] ; landed in
- - resolved (declined) — [] ; - -A reader must still parse pre-merge documents, and a fold against a -pre-design settled line cites a date off a token the live grammar no -longer produces. These two shapes are described, never minted: no -session writes a new line in either form. - -Narrative prose between the lines of a `## Review rounds` section is -lawful and expected. This grammar governs headings, lines, and their -indented payload; a paragraph explaining why a wave went the way it did -belongs there too. A lint over the section reads the anchored lines and -ignores the prose. - -A reviewer's stop signal takes a line of its own, under the heading of -the round that gave it: - - - signal — - -It carries the leading token `signal`, no severity — a judgment about -the next round's marginal value is not a finding — and no authorizer, -since nobody licensed it. It joins no anchor: a stop signal owes nobody -a next move, so it is closed the moment it is written, as a gate line -is. The workflow rule owns the ask that produces it. - -### Gate lines - -The propagation gate, when that agent is available, writes gate lines of -its own: the two ordinary shapes here, and the held shape and its three -terminal rewrites below. Each carries its own leading token and never a -severity, because a hit is a located detection the dispatcher confirms -or dismisses, never a graded finding: - - - hit fixed — ; - - hit dismissed — ; counter: - -Neither carries a license either, because a hit's fix is licensed by its -own derivation. - -A hit of the coverage duty whose fix needs a decision no derivation -settles is held for the developer — the one exception the workflow rule -makes to hits never waiting. It takes a third shape, rewritten in place -to one of three terminal shapes, so its state always has one home: - - - hit held — ; question: ; options: - - hit fixed — ; ; ruling: - - hit deferred — ; ruling: ; Defers: - - hit withdrawn — ; ruling: ; # - -The rewrite happens once the gate has re-run over the changed document -and whatever depends on it, never on the developer's answer alone. -`hit fixed … ruling:` records that the document now carries the -decision the developer settled — a plan that realizes it, or a register -the ruling repaired; `hit deferred` records an approved `**Defers:**` -line in the plan, and `hit withdrawn` a register entry now a tombstone. -Each is written only where it names what happened, and none is -`hit dismissed`, because the gap was real when the hit fired. The -ordinary `hit fixed` shape, without `ruling:`, stays for every hit -whose fix its derivation licensed. `ruling:` on a gate line means what -it means on a disposition line, and a diff-scoped round treats the line -as settled. - -A `hit held` line lives in the ledger of the document whose gate raised -it — the audited plan, or the design spec audited alone. Its leading -date is the gate's, and the terminal rewrite replaces it with the date -the line reached its terminal state. A held hit ends its gate episode -and blocks the dispatch the gate guards; the re-run after the -developer's answer is a fresh episode. A register edit the answer -causes is recorded in the spec's own ledger — under its latest round -heading while its loop is open, and under the fix heading above once -its loop has closed. A spec already `implemented` takes the edit by -revision instead, and the held hit waits for it. - -Each is written at gate time, under the last round's heading. The `hit` -token tells a gate line apart from that round's own findings; the date -does not, since a gate episode and the round it precedes commonly share -one. A gate still never mints a heading of its own, on the separate -ground that the round heading's grammar is closed and a gate is not a -round. The fix heading above is no counter-example: a gate's lines can -wait for the round that is coming, while a fix landing on a document -whose loop closed at `LGTM` waits for nothing. Writing at gate -time is what the lines are for: a dismissal must exist while the episode -is still re-dispatching, or the gate cannot terminate, and the next -diff-scoped brief is composed before its own round is stamped. A gate -before a document's first round has no heading to write under; its lines -wait for that round and are written at its stamp, the one case where -they do — unless the episode holds a hit, since the round its lines -would wait for cannot start. A pre-round episode holding at least one -hit writes every one of its lines, the `hit held` line and its siblings -alike, in the `## Review rounds` section before the first round -heading, and they stay there, rewrites included: no round produced -them, and one episode keeps one home. Once such lines stand there, -every later pre-round episode writes there too, holding or not, so the -document's pre-round gate history keeps one place. A document with no -`## Review rounds` section gains one, at its end, with its first gate -line. - -A gate episode always lands somewhere: its lines are the reason a later -reader need not re-derive what the session already settled. - -No gate-line shape covers a hit left outstanding when the re-dispatch -bound in the workflow rule stops an episode. That state owes the -developer a decision, so neither `hit fixed` nor `hit dismissed` can -honestly carry it, and `hit held` is scoped to the coverage duty's -hits; no anchor surfaces it today — a stated gap, not an oversight. -Until a shape exists, the workflow rule's report is its only record. - -A `hit fixed` line puts the gate's ordinary work where the next -diff-scoped brief already looks, beside the round's `fixed` lines. A -`hit dismissed` line records a decision the developer was never asked to -make, so a later round cites it instead of re-deriving it and a session -that would dismiss the same hit differently argues against written words -rather than silence. Neither joins the unfinished-work anchors: both are -closed when written and owe nobody a next move. A `hit held` line owes -the developer an answer, so it joins them until its terminal rewrite. - -A line carrying `ruling:` is a recorded developer decision, and what a -later round may do with it depends on what that round brings: - -- re-raised without new evidence — folded and cited, never asked again; - the fold produces `declined ` carrying `ruling:` with the prior - ruling's date and a `folding` citation of the line it folds against, - so the authorizer is cited rather than manufactured; -- re-raised with new evidence — `held`, its `counter:` citing the prior - ruling, because a session that folded this alone would arbitrate - between a reviewer and a recorded developer decision. - -Evidence is new relative to what the folded line records — its claim and -the reasoning its clauses carry — not relative to the reviewer's -wording. A session that cannot tell holds rather than folds. - -A pre-design settled line carries no authorizer clause and is settled by -its token alone; a fold against one cites the date on that token, which -is when the developer decided. - -A line carrying `provisional:` is not settled: it records nobody's -decision yet, so a re-raise against it is ordinary triage, as against a -`license:` line, and nothing here folds it. - -State prevents relitigation, not the reviewer's memory. - ## Unfinished-work list One entry per class of unfinished process work: the class name, its @@ -911,18 +573,7 @@ its consumption gate (fresh round at the prescribed tier); and when a judged document or plan moves to `implemented` and the memory-review-session skill is available, offer a Project memory review — released work-state notes -close, resolved entries sweep to the archive. After any -review round, relay the report to the developer, then stamp the -verdict into the document's field — 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. -The subsection sequences further checks inside its own turn — the model -self-report before the relay, the report's citations after it — which -this sentence deliberately does not restate, so gaining one does not -make it stale. The order has one named exception, defined in that -subsection: a plan's diff-scoped LGTM is relayed and its round record -written, while only the frontmatter stamp waits for the confirming -full-document round. +close, resolved entries sweep to the archive. A technical design is a judged document and takes the design spec's side of every branch in this rule: the same fields, the same @@ -983,66 +634,14 @@ sense, and the developer may commit sooner on their own call. The suggestion covers only paths git tracks or would track; deliberately ignored documents are skipped silently, and committing itself stays with the developer. - -Asking whether the loop may commit per round is not that suggestion, and -the difference is the speech act rather than the timing. The suggestion -above says a moment to commit has arrived; the consent question asks -once, before any round runs, for standing authorization to use a -mechanism — and a "no" leaves the authoring phase exactly as this -paragraph describes it. That is why it may be asked during authoring -while the suggestion may not. A set `review.per-round-commit`, read as -the process-settings rule says, is that standing authorization already -given or withheld, and the clause is not asked; unset, it is asked as -the workflow rule's review loop says, "and record" among its answers. - -One shape of that sooner call has a convention, because practice kept -reaching for it: **per-round commits on a document branch.** When the -developer authorizes it, the loop commits the reviewed document once per -round, as the round's last act. That boundary matches the ledger's own -unit — a round mutates the document several times (the stamp, the -triage, the fix wave, any gate episodes), and one commit after the wave -records what the round found together with what the session did about -it. - -The commits go to a local branch named `.docs`, never to the -topic branch itself. Git refuses a ref nested under an existing branch, -so `feature/-/docs` cannot exist while its parent -does; the -suffix takes a dot because the branch convention already spends hyphens -on name parts, where `-docs` would read as a topic about documenting. - -The loop runs on that branch for the whole authoring phase — the design -spec's rounds, the technical design's and the plan's alike — and the -topic branch takes it at the implementation-ready gate: by fast-forward -where the history is wanted whole, by squash where it is not. That -choice belongs to the project rather than the session, so the settings -key `docs-branch.merge` — `squash` or `fast-forward`, read as the -process-settings rule says — records it where it binds. Until a project -migrates to the key, a `CLAUDE.md` note — at the repo root or beside the -documents — declares it too, the key winning where the two disagree and -the session saying so. A session with neither asks at the gate, and the -answers include "squash, and record" and "fast-forward, and record", -which write the key through the loader's `--set` where a settings block -names the loader. Either way the document branch survives the merge, -which keeps loop churn off any published branch until somebody pushes it -and leaves the surviving ref marking where authoring ended. - -Both halves of "local" are worth knowing before relying on it. Churn -stays private, and the history dies with the working copy: a teammate -cannot see it, and a lost machine takes it. That is still more than the -alternative, where the same rounds live only in a transcript, but it -means "return the document to the state round three read" is a promise -about one clone rather than about the repository. - -What per-round commits never do is replace the ledger. Git says which -lines changed; the ledger says with what intent and on whose license, -and a diff carries neither "narrowed the claim" nor a cited ADR. A -`` clause may thin to a sentence where the commit carries -the detail; it does not go. Nor does a sha stand in for a hash: a round -heading that one day carried its commit's sha would name that round, -and it never stands in for the `integrity:` hash, which is computed from -the body and must work on a document nobody committed — the default -path, where no sha exists. +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. + +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. Ticket value format, sourcing order, and backfill live in the ticket-frontmatter rule. From 7f181ccab3d77ca0dde21c7d56e76892bf743376 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:45:06 +0100 Subject: [PATCH 30/59] refactor(working-process): Unfinished-work list becomes a process-status reference --- .../rules/spec-plan-lifecycle.md | 97 +------------------ .../skills/process-status/SKILL.md | 12 +-- .../skills/process-status/UNFINISHED-WORK.md | 94 ++++++++++++++++++ 3 files changed, 102 insertions(+), 101 deletions(-) create mode 100644 plugins/working-process/skills/process-status/UNFINISHED-WORK.md diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 407b12f..b3b97cb 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -165,7 +165,7 @@ base: master # optional: branch the topic branch was cut from prints nothing, the self-report comparison runs as before and the relay calls it unchecked, never a match. Committed examples of the bare fallback form use - placeholders (as above) so they never match the list below. + placeholders (as above) so they never match the Unfinished-work list. - `branch` and `base` appear once the topic branch exists — never guessed up front, omitted entirely when there is no topic branch. - `technical-design:` is optional and appears once the technical design @@ -468,99 +468,6 @@ This is a lookup, not an Unfinished-work entry: a `revises:` pointer owes nobody a next move, and the implemented-document principle above already warns every reader of an archived document without it. -## Unfinished-work list - -One entry per class of unfinished process work: the class name, its -command, and the owner of the next move, plus its own match scope where -the entry re-scopes one. This section is the list — a -command published elsewhere, such as the ticket sweep in the -ticket-frontmatter rule, is a lookup and not part of it. The -`process-status` skill, when available, runs exactly what stands here, -and this heading is the name it keys on: the heading and the skill move -together or not at all. - -A command returns hits, not Findings. A hit counts only when the -matching line sits inside the document's frontmatter block — between the -`---` on the file's first line and the `---` that closes it, never a -later pair — because a document quoting this convention in its body -describes it rather than instantiating it. That guard is the default. An -entry re-scopes it only by publishing its own match scope as a fourth -leg, and the entries below that do so say it there. - -- **Grilling pending** — a session's outcomes are recorded and not yet - applied. - `rg -l --no-ignore --crlf '^\s*grilled: grilling' docs/` - Owner: the grilling-session, when available. -- **Unresolved verdict** — a round ended in `concerns` or `blocking` - and nothing closed it. - `rg -l --no-ignore --crlf '^\s*(architect|adversary): (blocking|concerns)$' docs/` - Owner: a fresh round at the prescribed tier, or the resolution - annotation above — except on a plan whose latest round heading is - diff-scoped, whatever its verdict, where the confirming full-document - round closes the verdict and the annotation may not, since a plan's - loop closes only on a full-document round. Such a plan matches Chain - debt as well where that heading is an `LGTM`: one debt seen from two - sides, both extinguished by that round, and the duplicate is - deliberate. On a plan already at `status: implemented` the round is - discharged by recorded decline without any dispatch, as the Chain debt - leg discharges its own debt — a session derives that decline under a - `concerns` heading, while a `blocking` one waits for the developer's - adjudication, which is theirs to make. -- **Unfinished review-loop ledger** — a disposition line or a held gate - line nobody closed: an `open` line whose remediation never ran, or a - `held` or `hit held` line whose question still waits. A gate line's - date stands between its token and its dash, so the command takes an - alternative rather than a third token inside the group. - `rg -n --no-ignore --crlf '^- (open|held) —|^- hit held ' docs/` - Scope: a hit counts only inside a `## Review rounds` section — this - entry's own re-scoping of the guard above, kept for the same reason, - since a document quoting the grammar describes it rather than - instantiating it. Confirming section membership needs line positions, - which is why this command carries `-n` where the others carry `-l`. - Owner: an `open` line belongs to the document's next touch, which - re-offers the remediation; a `held` or `hit held` line belongs to the - developer. -- **Chain debt** — a diff-scoped `LGTM` heading carrying no record that - what it owed was discharged. - `rg -n --no-ignore --crlf '^### .*LGTM \(round [0-9]+, diff-scoped\)$' docs/` - Scope: a hit counts only inside a `## Review rounds` section — the - second entry to re-scope the default guard, for the reason the first - one does, and carrying `-n` for the same reason. - Owner: for a judged document, the consumption gate's pair offer; for a - plan, the - confirming full-document round. On a document already at - `status: implemented` the debt is discharged by recorded decline - without any dispatch: completed work is not re-reviewed, so the - annotation is written citing that standing decision, and a document - still in flight keeps the pair offer. -- **Pending re-review** — a verdict produced below the prescribed tier, - neither refreshed nor waived. - `rg -l --no-ignore --crlf '^\s*(architect|adversary)-fallback: [a-z0-9-]+ \((degraded|chosen) [0-9-]+\)$' docs/` - Owner: the re-review offer at the document's consumption gate. -- **Misplaced stamp** — a process field outside the top level of the - frontmatter, at any value. - `rg -l --no-ignore --crlf '^\s+(grilled|architect|adversary|architect-fallback|adversary-fallback|integrity):' docs/` - Owner: the developer; no process surface owns moving a stamp back. - The class suppresses per field: it hides any other class whose - published command would match the relocated line — at most one, and - for a field no other command names, such as `integrity`, none — - itself excluded, since its own command matches every process field. - Match semantics are the mapping, so a class published later needs no - extra rule. - -The tail anchors are exact on purpose: a `(resolved )`, -`(adjudicated )` or `, waived ` annotation defeats the -match, and that defeat is the recorded closed state. The leading -anchors are tolerant on purpose, so a relocated field is still found. -The Misplaced stamp command anchors `^\s+` instead, because there the -indentation is the defect it looks for rather than an accident to -tolerate. Those anchors sit on a frontmatter field wherever the default -guard holds. An entry publishing its own scope anchors a body line -instead — a leading disposition token or a round heading — and there the -close is a rewrite or an appended annotation: `open` or `held` becomes -`fixed ` or `declined `, and a discharged chain debt gains -`, debt discharged `. Either way the anchor stops matching. - ## Lifecycle offers Each an offer the developer may decline, and each made @@ -642,6 +549,8 @@ this gate. 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. +The Unfinished-work list is the `process-status` skill's +Unfinished-work reference, when that skill is available. Ticket value format, sourcing order, and backfill live in the ticket-frontmatter rule. diff --git a/plugins/working-process/skills/process-status/SKILL.md b/plugins/working-process/skills/process-status/SKILL.md index 653bedf..859b5b2 100644 --- a/plugins/working-process/skills/process-status/SKILL.md +++ b/plugins/working-process/skills/process-status/SKILL.md @@ -5,18 +5,16 @@ description: "Report what the working process left unfinished in this repo — a # process-status — what the process left unfinished -Runs the Unfinished-work list the lifecycle rule publishes and reports -what it finds. The rule owns which classes exist; this skill owns +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 rule publishes it. +this skill has never heard of works the moment the list publishes it. ## Step 1 — read the list Read the `## Unfinished-work list` section of -`${CLAUDE_PLUGIN_ROOT}/rules/spec-plan-lifecycle.md` — the payload copy -shipped beside this skill, never an installed copy under -`.claude/rules/`. The plugin releases skill and payload in one version, -so that copy is always in step with this skill. +`${CLAUDE_PLUGIN_ROOT}/skills/process-status/UNFINISHED-WORK.md`, the +reference file shipped beside this skill. Each entry carries three legs: the class name, one command, and the owner of the next move. Take all three. An entry may carry a fourth, its diff --git a/plugins/working-process/skills/process-status/UNFINISHED-WORK.md b/plugins/working-process/skills/process-status/UNFINISHED-WORK.md new file mode 100644 index 0000000..6300a28 --- /dev/null +++ b/plugins/working-process/skills/process-status/UNFINISHED-WORK.md @@ -0,0 +1,94 @@ +# process-status — the Unfinished-work list + +## Unfinished-work list + +One entry per class of unfinished process work: the class name, its +command, and the owner of the next move, plus its own match scope where +the entry re-scopes one. This section is the list — a +command published elsewhere, such as the ticket sweep in the +ticket-frontmatter rule, is a lookup and not part of it. The +`process-status` skill, when available, runs exactly what stands here, +and this heading is the name it keys on: the heading and the skill move +together or not at all. + +A command returns hits, not Findings. A hit counts only when the +matching line sits inside the document's frontmatter block — between the +`---` on the file's first line and the `---` that closes it, never a +later pair — because a document quoting this convention in its body +describes it rather than instantiating it. That guard is the default. An +entry re-scopes it only by publishing its own match scope as a fourth +leg, and the entries below that do so say it there. + +- **Grilling pending** — a session's outcomes are recorded and not yet + applied. + `rg -l --no-ignore --crlf '^\s*grilled: grilling' docs/` + Owner: the grilling-session, when available. +- **Unresolved verdict** — a round ended in `concerns` or `blocking` + and nothing closed it. + `rg -l --no-ignore --crlf '^\s*(architect|adversary): (blocking|concerns)$' docs/` + Owner: a fresh round at the prescribed tier, or the resolution + annotation the spec-plan-lifecycle rule defines — except on a plan whose latest round heading is + diff-scoped, whatever its verdict, where the confirming full-document + round closes the verdict and the annotation may not, since a plan's + loop closes only on a full-document round. Such a plan matches Chain + debt as well where that heading is an `LGTM`: one debt seen from two + sides, both extinguished by that round, and the duplicate is + deliberate. On a plan already at `status: implemented` the round is + discharged by recorded decline without any dispatch, as the Chain debt + leg discharges its own debt — a session derives that decline under a + `concerns` heading, while a `blocking` one waits for the developer's + adjudication, which is theirs to make. +- **Unfinished review-loop ledger** — a disposition line or a held gate + line nobody closed: an `open` line whose remediation never ran, or a + `held` or `hit held` line whose question still waits. A gate line's + date stands between its token and its dash, so the command takes an + alternative rather than a third token inside the group. + `rg -n --no-ignore --crlf '^- (open|held) —|^- hit held ' docs/` + Scope: a hit counts only inside a `## Review rounds` section — this + entry's own re-scoping of the guard above, kept for the same reason, + since a document quoting the grammar describes it rather than + instantiating it. Confirming section membership needs line positions, + which is why this command carries `-n` where the others carry `-l`. + Owner: an `open` line belongs to the document's next touch, which + re-offers the remediation; a `held` or `hit held` line belongs to the + developer. +- **Chain debt** — a diff-scoped `LGTM` heading carrying no record that + what it owed was discharged. + `rg -n --no-ignore --crlf '^### .*LGTM \(round [0-9]+, diff-scoped\)$' docs/` + Scope: a hit counts only inside a `## Review rounds` section — the + second entry to re-scope the default guard, for the reason the first + one does, and carrying `-n` for the same reason. + Owner: for a judged document, the consumption gate's pair offer; for a + plan, the + confirming full-document round. On a document already at + `status: implemented` the debt is discharged by recorded decline + without any dispatch: completed work is not re-reviewed, so the + annotation is written citing that standing decision, and a document + still in flight keeps the pair offer. +- **Pending re-review** — a verdict produced below the prescribed tier, + neither refreshed nor waived. + `rg -l --no-ignore --crlf '^\s*(architect|adversary)-fallback: [a-z0-9-]+ \((degraded|chosen) [0-9-]+\)$' docs/` + Owner: the re-review offer at the document's consumption gate. +- **Misplaced stamp** — a process field outside the top level of the + frontmatter, at any value. + `rg -l --no-ignore --crlf '^\s+(grilled|architect|adversary|architect-fallback|adversary-fallback|integrity):' docs/` + Owner: the developer; no process surface owns moving a stamp back. + The class suppresses per field: it hides any other class whose + published command would match the relocated line — at most one, and + for a field no other command names, such as `integrity`, none — + itself excluded, since its own command matches every process field. + Match semantics are the mapping, so a class published later needs no + extra rule. + +The tail anchors are exact on purpose: a `(resolved )`, +`(adjudicated )` or `, waived ` annotation defeats the +match, and that defeat is the recorded closed state. The leading +anchors are tolerant on purpose, so a relocated field is still found. +The Misplaced stamp command anchors `^\s+` instead, because there the +indentation is the defect it looks for rather than an accident to +tolerate. Those anchors sit on a frontmatter field wherever the default +guard holds. An entry publishing its own scope anchors a body line +instead — a leading disposition token or a round heading — and there the +close is a rewrite or an appended annotation: `open` or `held` becomes +`fixed ` or `declined `, and a discharged chain debt gains +`, debt discharged `. Either way the anchor stops matching. From ae440e1d9d89659331959d3011a5a42f44ad8749 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:46:42 +0100 Subject: [PATCH 31/59] docs(working-process): pointers follow the moved text --- docs/domain/glossary.md | 6 +++--- plugins/working-process/README.md | 18 ++++++++++-------- .../skills/grilling-session/SKILL.md | 4 ++-- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 1676a54..8c81c52 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -448,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 diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index c280ad1..799349e 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -90,7 +90,8 @@ verdict dispatch and the integrity audit itself. unfinished review-loop ledger (an `open` or `held` disposition line, counted only inside a `## Review rounds` section), a re-review nobody ran, a stamp outside the top level of a frontmatter block. Runs the - Unfinished-work list the lifecycle rule publishes and fires none of + Unfinished-work list its reference file + publishes and fires none of the offers those classes name. Triggers: "what is unfinished" / "process status". - **`process-setup` skill** — collects a project's standing process @@ -159,8 +160,8 @@ verdict and gain a resolution date — `concerns (resolved 2026-07-16)` — plus a body note saying what resolved them. Finding unfinished work is one command per class, published as the -`## Unfinished-work list` section of the lifecycle rule — the exact -anchors live there, and the `process-status` skill runs them. The tail +`## Unfinished-work list` section of the `process-status` skill's +`UNFINISHED-WORK.md` — the exact anchors live there, and the `process-status` skill runs them. The tail anchors are exact, so a resolved-concern annotation drops out of the match by design. @@ -211,11 +212,12 @@ out as well, and both reports open with a model self-report the dispatcher checks before relying on the run: a mismatched propagation run earns no reliance, a below-tier integrity run no stamp. -The dispatcher's half of all this lives in the plugin's Rules payload — -the verdict agents' relay-then-stamp sequence and the two audit offers -in the workflow rule, the `integrity:` stamp and its -recompute-and-compare gate in the spec-plan-lifecycle rule. After a plugin update, run a rules -re-sync so the dispatcher side matches the agents; until then the +The dispatcher's half of all this lives in the plugin's `review-loop` +skill and Rules payload — the verdict agents' relay-then-stamp sequence +in the skill, the two audit offers in the workflow rule, the +`integrity:` stamp and its recompute-and-compare gate in the +spec-plan-lifecycle rule. After a plugin update, run a rules +re-sync so the installed rules match the agents; until then the previously installed rules still carry the older record-the-verdict obligation and make neither audit offer, so no round is lost and the new gates merely stay silent. diff --git a/plugins/working-process/skills/grilling-session/SKILL.md b/plugins/working-process/skills/grilling-session/SKILL.md index fdd57a4..3f6bb34 100644 --- a/plugins/working-process/skills/grilling-session/SKILL.md +++ b/plugins/working-process/skills/grilling-session/SKILL.md @@ -57,8 +57,8 @@ applies (edit with the Edit tool): — but ONLY once every decision, glossary update, and document amendment from the session has been applied. - A session cut short leaves `grilling` in place on purpose: the - Grilling pending class of the lifecycle rule's Unfinished-work list, - which publishes the command and which `process-status` runs. + Grilling pending class of the + Unfinished-work list, a reference of the `process-status` skill. ## Grilling mechanics From ee94c514235b400204a5ef78eaa6ce08d8869cc7 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 13:48:43 +0100 Subject: [PATCH 32/59] chore(working-process): review-loop identity surfaces, changelog, dogfood version --- .claude-plugin/marketplace.json | 2 +- README.md | 2 +- plugins/working-process/.claude-plugin/plugin.json | 4 ++-- plugins/working-process/CHANGELOG.md | 11 +++++++++++ plugins/working-process/README.md | 4 ++++ 5 files changed, 19 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 944ba3b..7e5ce6e 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, plus distributed process rules" }, { "name": "python-standards", diff --git a/README.md b/README.md index 02f6e5c..ef81147 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, 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/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index 3eebbca..d4cfff9 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.20.0-dev.8.consult-errata", + "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", + "version": "0.20.0-dev.9.process-context", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 50f4ec5..a30df8d 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -57,6 +57,17 @@ Released versions of this plugin, newest first. scripted measurement or a consultation, never to a verdict agent. - Wording: a full-document round "owes no confirming round", and a plan's loop closes on its latest round heading. +- 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. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index 799349e..66f255f 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -94,6 +94,10 @@ verdict dispatch and the integrity audit itself. publishes and fires none of the offers those classes name. Triggers: "what is unfinished" / "process status". +- **`review-loop` skill** — holds the dispatcher's procedure and the + ledger grammar as two reference files. Read before a verdict dispatch, + at a consumption gate, before a `status` move and before writing a + ledger line. It dispatches nothing. - **`process-setup` skill** — collects a project's standing process answers in one sitting: shows the effective settings, asks about the unset keys, migrates `CLAUDE.md` notes and directory signals as From fc0717774f60643ca6607e30a0ad4f9a227c75fe Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 14:15:44 +0100 Subject: [PATCH 33/59] docs(working-process): process context spec and plan implemented --- docs/plans/2026-11-16-process-context-plan.md | 2 +- docs/specs/2026-11-16-process-context-spec.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plans/2026-11-16-process-context-plan.md b/docs/plans/2026-11-16-process-context-plan.md index 035bcd6..5a8afb9 100644 --- a/docs/plans/2026-11-16-process-context-plan.md +++ b/docs/plans/2026-11-16-process-context-plan.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-16 -status: approved +status: implemented spec: ../specs/2026-11-16-process-context-spec.md branch: feature/process-context base: develop diff --git a/docs/specs/2026-11-16-process-context-spec.md b/docs/specs/2026-11-16-process-context-spec.md index 7cb6489..6a4da32 100644 --- a/docs/specs/2026-11-16-process-context-spec.md +++ b/docs/specs/2026-11-16-process-context-spec.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-16 -status: approved +status: implemented grilled: 2026-11-16 architect: concerns (resolved 2026-11-16) integrity: 2026-11-16 (sha: a74a36c) From 03f37a3a5653464196d2d51ae5d84737775b781f Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:17:02 +0100 Subject: [PATCH 34/59] docs(working-process): plan quality spec and plan --- docs/domain/glossary.md | 14 + docs/plans/2026-11-16-plan-quality-plan.md | 886 +++++++++++++++++++++ docs/specs/2026-11-16-plan-quality-spec.md | 353 ++++++++ 3 files changed, 1253 insertions(+) create mode 100644 docs/plans/2026-11-16-plan-quality-plan.md create mode 100644 docs/specs/2026-11-16-plan-quality-spec.md diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 8c81c52..fcfe1be 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -514,6 +514,20 @@ 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 + **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. 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..7e45fe6 --- /dev/null +++ b/docs/plans/2026-11-16-plan-quality-plan.md @@ -0,0 +1,886 @@ +--- +ticket: none +date: 2026-11-16 +status: approved +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/specs/2026-11-16-plan-quality-spec.md b/docs/specs/2026-11-16-plan-quality-spec.md new file mode 100644 index 0000000..e0de0a3 --- /dev/null +++ b/docs/specs/2026-11-16-plan-quality-spec.md @@ -0,0 +1,353 @@ +--- +ticket: none +date: 2026-11-16 +status: approved +grilled: 2026-11-16 +architect: concerns (resolved 2026-11-16) +integrity: 2026-11-16 (sha: b40d9eb) +decisions: registered +branch: feature/plan-quality +base: develop +--- + +# Plan quality — checks that cannot be written wrong + +Implementation plans keep shipping the same classes of defect in their +verification steps, and every reviewer catches them afresh. This spec +stops them at authoring time with a helper that makes the common check +impossible to write wrong, one rule about test reds, and the defect +classes that keep recurring, written where the author meets them. It +is package 6 of the release queue. + +## Problem + +Evidence from three projects, gathered 2026-11-16 (records in the +developer's private store, not committed): + +- **This repository** — prose plans whose checks are `grep` runs. The + process-context plan passed five propagation-gate episodes, and + nearly every gate hit was a defect in a verification check: a phrase + wrapped across lines, letter case after a wrap, whitespace, a count + no correct text could reach, a shell variable no step set, a + verification check that passed with nothing to examine. Seven earlier review loops show the same classes. +- **A web-application project** — 31 findings in 18 of 31 + plan-adversary rounds concerned tests that could not fail, could not + pass, or failed for the wrong reason; 17 line or path anchors went + stale. +- **A Salesforce project** — 11 of 30 checked predictions of a failing + test's message were wrong, and one plan spent five Important findings + on them before the project switched to observing the failure instead + of predicting it. That switch at once exposed a test that could never + fail. Counts drifted in 18 or more places; 12 line citations were off + by one. + +What recurs is the class, not the instance. A rule that asks the author +to judge each site ("use a multiline match where a phrase might wrap") +keeps failing at the rate the judgment fails; what closed a class in +the past was one uniform form applied everywhere. + +## Goals, non-goals, anti-goals + +Goals: + +- A verification check over text is written in one form that already + handles wrapping, case and whitespace, and that shows its result + before and after its step. +- A plan states how to observe a failing test, never what message it + will print. +- The author of a plan reads the defect classes that keep recurring + while writing it, from one text the plan-adversary also reads. + +Non-goals: + +- Changes to `superpowers:writing-plans` or any other plugin. +- The other plan-authoring classes recorded in the developer's notes; + they stay there as background. +- A permission mechanism for the helper. It runs under the user's + permission mode, as superpowers' own scripts do. +- The propagation gate's script (release-queue package 4). It may later + reuse the helper's normalisation; nothing here prepares for that. + +Anti-goals — the package fails, even if it works, when: + +- the same classes still appear in plans written after it; +- the helper brings a defect class of its own; +- a session or an agent has to ask for permission repeatedly to run it. + +Accepted risks, by the developer's decision (2026-11-16): + +- In the default (manual) permission mode the first run in a + repository asks once. +- Whether the launcher skips the Windows store placeholder where it + comes first on `PATH` is not observed. +- A plugin with a top-level `bin/` does not install on claude.ai or in + Cowork; working-process is used in Claude Code, and the plugin's + README states the requirement. + +A throwaway spike on 2026-11-16 observed the rest: the normalised count +found a wrapped phrase grep missed (1 against 0) and a wrapped, +capitalised one (9 against 2); a plugin's `bin/` reached both a +headless session and its subagent; the default (manual) permission +mode asked, as the first accepted risk says, and auto mode ran it +without asking. On Windows, in the Claude Code CLI, the same `bin/` +reached the session and its subagent through Git Bash, and the +launcher found `python3`. + +Size target: the spec under 270 lines, revised from 200 after the +builder check and two review rounds; the helper a few hundred lines +with its tests; the rule under 80 lines. (Author's call.) + +## Decisions + +- **D1** — The working-process plugin ships `bin/wp-phrase-check`, which Claude + Code puts on the Bash tool's `PATH` while the plugin is enabled, so a + plan calls it by name in any project. Argued in *Running everywhere*. +- **D2** — `wp-phrase-check` normalises before it matches: lines joined, + whitespace collapsed, case ignored, a line's leading list or quote + marker dropped; a match never spans two files, and matches do not + overlap. A phrase is found whatever the file's wrapping. Argued in + *The helper*. +- **D3** — Every `wp-phrase-check` run prints the expected value and the + actual one and exits non-zero on a mismatch. It also prints how much + it read, and a named path that is missing or unreadable, or a run + that read no file, exits non-zero. A count mismatch is reported + before vacuity. Argued in *The helper*. +- **D4** — `wp-phrase-check` requires the count before its step and after + it, both as numbers, and fails a check whose two counts are equal + unless the author declares the step leaves it unchanged. A plan runs + the check on each side of its step, and each run verifies the actual + count against that side's number — except where a file does not + exist on one side: a step that creates a file runs the after side + only, and one that deletes it the before side only, since an absent + file counts zero by construction. A file the step creates or deletes + gets a check of its own, apart from the files present on both + sides. Argued in *The helper*. +- **D5** — `bin/wp-phrase-check` is a short bash launcher that finds + Python 3.9 or later (`python3`, then `python`, then `py -3`, each + confirmed by its version) and runs the implementation, which sits in + the plugin's `scripts/` and which the launcher finds from its own + path; with none found it prints which + commands it tried and exits non-zero. Argued in *Running everywhere*. +- **D6** — A plan never predicts the message a failing test prints. It + prescribes the observation: run the test with the change absent — + before it is written, or with it reverted — record what it prints in + the implementer's report, and restore the change where it was + reverted. A test + that does not fail stops the task as blocked. Argued in *Observing a + failure*. +- **D7** — One new rule, `plan-authoring.md`, path-scoped to plans + (`docs/plans/**`, `docs/**/*-plan.md`), holds the recurring defect + classes, the failing-test rule and the check-writing rules the helper + cannot enforce, and names `wp-phrase-check` as the form for text + checks, when the plugin is enabled. Argued in *The defect classes*. +- **D8** — The plan-adversary card reads that rule's shipped copy at + `${CLAUDE_PLUGIN_ROOT}/rules/plan-authoring.md`; the rule, titled + "Plan authoring — recurring defect classes", is the single text, and + its title does not call it a checklist, the propagation-duties rule's + word. Argued in *The defect classes*. +- **D11** — The plugin's README states that working-process needs + Claude Code, not claude.ai or Cowork, and Python 3.9 or later under + any of the launcher's three names. Argued in *Goals, non-goals, + anti-goals*. +- **D10** — Plan-writing, in session or delegated, reads the + plan-authoring rule before the plan's first line is written: + `workflow.md` step 4 states that read for both cases, as it already + does for the technical-design rule, and its sentence naming the + lifecycle rule for a delegated plan-writer names this rule too. A + path-scoped rule loads when a matching file is read, and a new plan + has none to read before its first write, after the plan template has shaped the + draft. Argued in *The defect classes*. +- **D9** — The rule names seven defect classes: a check or test that + cannot fail; an expected value fitted to the author's view instead of + the state the previous task leaves; anchors by line number; defects + born of a repair; checking the artifact the consumer loads; fixes in + one wave that undo each other; the same discipline one site away. + Argued in *The defect classes*. + +## The helper + +`wp-phrase-check` answers one question about a set of files: how many times +does this phrase occur. The plan's check is a call such as + + wp-phrase-check ... --phrase "" --before --after --side before|after + +and the helper does what authors kept getting wrong by hand. It joins +each file's lines and collapses every run of whitespace to one space, +and it compares without case, so a phrase split across lines, a +capital after a wrap and a doubled space all count. It prints the +expected value, the actual value and the files it read, and exits +non-zero on a mismatch, so a check never passes in silence. It says how +many files and lines it read, and a missing or unreadable path, or a +run that read nothing, fails, so a mistyped path cannot pass a removal +check. (Developer's ruling, 2026-11-16.) + +A check is vacuous when its result is the same before and after the +step it verifies. The plan runs the same check twice, once before its +step and once after, each run naming its side and verifying the actual +count against that side's number, so a before count is observed and +never only declared — but for a file the step creates or deletes, whose +absent side counts zero by construction and is not run (D4). The helper requires both counts, as numbers, and +fails a check whose two counts match unless the author passes a flag +declaring that the step leaves the phrase unchanged — a ruling that +something stays as it is, say. Leaving a count unchanged becomes a +statement the author makes, never an oversight. This catches the +text-check side of the class that recurred in all three projects; for +tests, D6's observation does the same. A git revision as the +before-state is not offered: plans run uncommitted unless the +developer consents to commits. (Developer's ruling, 2026-11-16.) + +Author's calls on the details: + +- Normalising also drops a line's leading Markdown markers — list + bullets, numbers, blockquote `>` — so a phrase wrapped inside a list + item or a quote still matches. A match never spans two files, and + matches do not overlap. +- Each count is the total over the files named; there is no region + scoping. The before/after pair is what ties a check to the lines a + step writes. +- A count mismatch is reported before vacuity, so the author first + sees the wrong number (the spike reported vacuity on a check whose + count was also wrong). +- The implementation needs Python 3.9 or later and is tested with + `unittest`, beside the plugin's existing tests; the launcher's + fallbacks are tested with stub binaries on a crafted `PATH`. + +The exact flag names are the plan's to settle, within D2–D4. + +## Running everywhere + +Claude Code puts a plugin's `bin/` on the Bash tool's `PATH`, and on +Windows that tool runs in Git Bash, which the plugin's hooks already +need. Python 3 is under different names across systems: `python` is +absent on Debian and Python 2 on old systems, and on Windows `python3` +can be a store placeholder. The launcher therefore tries each name and +confirms the version before running, and fails loudly rather than +running the wrong interpreter. The plugin's one Python script calls +`python3` alone; the helper runs from a plan in any project, in +environments the plugin's maintainers never see, so it carries the +fallbacks. (Developer's ruling, 2026-11-16.) The implementation sits beside the +plugin's other scripts, and the launcher finds it from its own path: +`CLAUDE_PLUGIN_ROOT` is not in the Bash tool's environment. + +## Observing a failure + +Predicting a test's failure message is the step reviewers spent most +on in one project and that its own implementers abandoned for an +observation. An observation cannot be wrong, and it exposes a test +that never fails, which a prediction hides. A plan therefore prescribes +the observation and records nothing in advance. The implementer +records what it saw in its report — the plan is a reviewed document +and stays as approved — and observes it with the change absent, before +it is written or with it reverted. A test that does not fail then stops +the task as blocked, since it proves nothing. (Developer's ruling, 2026-11-16.) + +## The defect classes + +The plan's author is the reader who can prevent a defect; the +plan-adversary catches it a round later. The classes live where the +author meets them: a rule that loads when a plan file is read, +beside the propagation-duties rule. The adversary's card points at the +same rule, so there is one text. Because a new plan has no file to read +before its first write, step 4 of `workflow.md` asks the +plan-writer to read it first (D10). (Developer's ruling, 2026-11-16.) + +The rule holds three things: + +- the seven classes of D9, each in a sentence or two with the question + an author asks before handing the plan on; +- the failing-test rule of D6; +- the check-writing rules the helper does not enforce — compute an + expected value against the state the previous task leaves; a check + correct text can satisfy; the change a step makes, as the + before/after pair states it, never a total fitted to the file; where a check runs on both + sides, the two calls are the same but for the side; prefer a text anchor to a + line number. + +The rule names `wp-phrase-check` as the form for text checks, conditionally, +as rule text names a plugin's tools. Its `paths:` are `docs/plans/**` +and `docs/**/*-plan.md`, the latter reaching plans in ticket +directories. The adversary's card reads the shipped copy +at `${CLAUDE_PLUGIN_ROOT}/rules/plan-authoring.md`, so it reaches the +rule whether or not `sync-rules` installed it. (Author's calls.) + +## Verification + +- `wp-phrase-check` carries its own tests: a phrase wrapped across + lines, a capital after a wrap, doubled whitespace, a missing or + unreadable path and a run that reads no file (D3), the files and + lines a run read printed on success (D3), a count that + differs from its side's number (D4), an equal before/after pair + failing and passing once declared unchanged (D4), each launcher + fallback and the no-Python failure. +- A live session in this repository runs `wp-phrase-check` by name, and a + subagent does too. +- The new rule installs through `sync-rules`; `claude plugin validate` + passes. +- The plugin's identity surfaces, changelog and dev version follow, as + for any component. + +## Out of scope + +- Rewriting existing plans to use the helper. +- A check over code (an AST or a test runner); the helper reads text. + +## 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 — bare "check" beside "hit" in *Problem*, banned by the glossary's **Verification check**; now "gate hit" and "verification check" +- hit fixed 2026-11-16 — D1 argued in *The helper*, which does not argue shipping or `PATH`; now *Running everywhere* +- hit fixed 2026-11-16 — the brace pattern `docs/**/*-{spec,technical-design,plan}.md` was called a plan pattern but also matches specs and technical designs; the rule's `paths:` are now `docs/plans/**` and `docs/**/*-plan.md` +- hit fixed 2026-11-16 — the accepted risk said "a manual permission mode" and the spike paragraph "the default permission mode", never stated to be one; both now say "the default (manual) permission mode" +- hit dismissed 2026-11-16 — `docs/**/*-plan.md` also matches a companion document in a ticket directory, which is no plan; counter: a `paths:` glob cannot read frontmatter, `technical-design.md` already scopes the same way, and a short rule loading beside a companion document costs little and decides nothing +- hit dismissed 2026-11-16 — the lifecycle rule still uses the brace glob this spec rejected for a plan pattern; counter: the lifecycle rule governs all three document classes, so the brace glob is right there; it is wrong only as a plans-only scope + +### 2026-11-16 — architect, fable 5.2, concerns (round 1, full-document) + +Record: `.claude/working-process/2026-11-16-plan-quality-spec/architect-round-1.md`. The gate lines above belong to this round's pre-round episode. + +- fixed 2026-11-16 — [Important] a top-level `bin/` makes the whole plugin uninstallable on claude.ai and Cowork; ruling: 2026-11-16; a third accepted risk, and the README states the requirement +- fixed 2026-11-16 — [Important] the before count could be declared rather than observed; ruling: 2026-11-16; D4 and *The helper* now run the check on each side of its step, each run verifying that side's number +- fixed 2026-11-16 — [Important] a check over a mistyped path read nothing and still passed; ruling: 2026-11-16; D3 and *The helper* now fail a missing or unreadable path and a run that read nothing +- fixed 2026-11-16 — [Important] the rule loaded only at the plan's first write, after the template shaped the draft; ruling: 2026-11-16; new D10 — `workflow.md` step 4 asks plan-writing to read the rule first +- fixed 2026-11-16 — [Minor] the three-name interpreter search was not argued against the plugin's `python3` requirement; ruling: 2026-11-16; *Running everywhere* now says why the helper carries the fallbacks +- fixed 2026-11-16 — [Minor] D5 did not say how the launcher finds the implementation without `CLAUDE_PLUGIN_ROOT`; license: the plugins reference, *Where each variable resolves*; *Running everywhere* now says it finds it from its own path +- fixed 2026-11-16 — [Minor] D6 assumed the change exists, while test-first work observes the failure before it is written; license: `workflow.md` step 6, test-driven where the skill is available; D6 now says "with the change absent — before it is written, or with it reverted" +- fixed 2026-11-16 — [Minor] the rule's "property of the lines a step writes" did not match the helper's only form, a total; license: D4's before/after pair; the rule's item now names the change the pair states +- signal 2026-11-16 — one diff-scoped round earns its cost if the helper's contract changes (F2, F3); if all four Important are disposed by rewording or accepted, a further round is unlikely to repay itself + +Gate lines from the episode before round 2, 2026-11-16 (haiku): + +- hit fixed 2026-11-16 — *Verification*'s test list missed D3's missing-path and no-file cases and D4's side-number and declared-unchanged cases; added +- hit fixed 2026-11-16 — the call form in *The helper* still showed `--expect`; it now carries `--before`, `--after` and a side +- hit fixed 2026-11-16 — D6 said a never-failing test "stops the task as blocked" and *Observing a failure* "is reported as blocked"; both now say it stops the task as blocked +- hit fixed 2026-11-16 — the size target said under 200 lines while the body is about 255; restated as under 260 +- hit fixed 2026-11-16 — "a zero-hit check" beside the glossary's Hit; the test list no longer uses the phrase +- hit fixed 2026-11-16 — "machine" where the `PATH` is what matters, banned by the glossary's **Environment**; reworded twice +- hit dismissed 2026-11-16 — round 1 has eight `fixed` lines for seven findings; counter: F5 carried two suggestions, disposed separately, one by ruling and one by license +- hit fixed 2026-11-16 — an author's-call bullet still named `--expect`, which the call form dropped; it now speaks of each count +- hit fixed 2026-11-16 — *Verification* had no test for D3's printing of what a run read; added +- hit dismissed 2026-11-16 — no test for a missing or non-numeric `--before`/`--after`; counter: required integer arguments are rejected by the standard argument parser before the helper runs, so a test would test the library + +### 2026-11-16 — architect, fable 5.2, concerns (round 2, diff-scoped) + +Record: `.claude/working-process/2026-11-16-plan-quality-spec/architect-round-2.md`. + +- fixed 2026-11-16 — [Important] D3's missing-path failure and D4's two runs collided on a step that creates or deletes a file; ruling: 2026-11-16; D4 now runs only the side on which the file exists, the helper unchanged +- fixed 2026-11-16 — [Minor] the two runs of one check are two copies nothing ties together; license: the anti-goal that the helper bring no defect class of its own; the rule's check-writing items now say the two calls are identical but for the side +- fixed 2026-11-16 — [Minor] D10's edit clause bound only the delegated case while its scope named both; license: D10's own scope clause and `workflow.md` step 4's precedent for the technical-design rule; D10 now has step 4 state the read for both cases +- signal 2026-11-16 — another round earns its cost only if F1 changes the helper (option b); settled by rule text or accepted, a third round is unlikely to repay itself, and the integrity audit reads the whole document + +Round 2's `concerns` is resolved without a further round: the developer settled its one Important finding on 2026-11-16 by rule text, and the reviewer's stop signal judged a third round unlikely to repay itself; the integrity audit at the consumption gate reads the whole document. + +Gate lines from the episode before the integrity audit, 2026-11-16 (haiku): + +- hit fixed 2026-11-16 — the size target said under 260 while the body is 265; restated as under 270 +- hit fixed 2026-11-16 — *The helper* and the rule's item still stated two runs unconditionally after D4 gained its create/delete exception; both now carry it +- hit fixed 2026-11-16 — D4's exception was keyed to "a file" while a call names several; a created or deleted file now gets a check of its own +- hit fixed 2026-11-16 — the pre-round gate lines' note said they move under the first heading, while the lifecycle rule keeps a held-hit episode's lines before it; the note now says they stay +- hit fixed 2026-11-16 — the round 2 close said "one held finding" where the line is `fixed … ruling:`; now "one Important finding" +- hit fixed 2026-11-16 — a gate line's "what changed" misquoted the text it changed; corrected to "stops the task as blocked" +- hit fixed 2026-11-16 — "the plugin's other scripts call `python3`" while one Python script exists; now "the plugin's one Python script" +- hit dismissed 2026-11-16 — the round 2 record cites `workflow.md:98` where the sentence is on 97; counter: the error sits in the dispatch record, which no gate edits, and the spec carries no line number +- hit dismissed 2026-11-16 — "defect class" and "text anchor" have no glossary entry; counter: plain words in their ordinary sense; the grilling minted only the two check terms From 50137186663fc704ed63547c01ddf40cfc80c93a Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:18:04 +0100 Subject: [PATCH 35/59] feat(working-process): phrase-check script for plan verification checks --- .../working-process/scripts/phrase-check.py | 121 +++++++++++ tests/working-process/test_phrase_check.py | 189 ++++++++++++++++++ 2 files changed, 310 insertions(+) create mode 100755 plugins/working-process/scripts/phrase-check.py create mode 100644 tests/working-process/test_phrase_check.py diff --git a/plugins/working-process/scripts/phrase-check.py b/plugins/working-process/scripts/phrase-check.py new file mode 100755 index 0000000..1a4e499 --- /dev/null +++ b/plugins/working-process/scripts/phrase-check.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 +"""Count a phrase in files, ignoring line wrapping and list/quote markers. + +Usage: + phrase-check.py [...] --phrase --before --after + --side before|after [--unchanged] + +Exit codes: 0 pass; 1 check failure (path problem, no path, count +mismatch, vacuous pair); 2 usage error (raised by argparse). +""" + +from __future__ import annotations + +import argparse +import os +import re +import sys + +TOOL = "wp-phrase-check" +MARKERS = re.compile(r"^\s*(?:(?:>\s*|(?:[-*+]|\d+[.)])(?:\s+|$)))*") + + +class Unreadable(Exception): + """A path that cannot be read; the message is the reason.""" + + +def normalise(text: str) -> str: + lines = [MARKERS.sub("", line) for line in text.splitlines()] + return re.sub(r"\s+", " ", " ".join(lines)).strip().casefold() + + +def count_phrase(text: str, phrase: str) -> int: + return normalise(text).count(normalise(phrase)) + + +def read_text(path: str) -> str: + if not os.path.exists(path): + raise Unreadable("no such file") + if not os.path.isfile(path): + raise Unreadable("not a file") + try: + with open(path, "rb") as f: + data = f.read() + except OSError as e: + raise Unreadable(f"cannot be read ({e.strerror})") + try: + return data.decode("utf-8-sig") + except UnicodeDecodeError: + raise Unreadable("not valid UTF-8") + + +def non_negative(value: str) -> int: + n = int(value) + if n < 0: + raise argparse.ArgumentTypeError("must not be negative") + return n + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser( + prog="phrase-check.py", + description="Count a phrase across files after normalising wrapping and markers. " + "A phrase starting with a hyphen is written --phrase=.", + ) + ap.add_argument("paths", nargs="*", metavar="path") + ap.add_argument("--phrase", required=True) + ap.add_argument("--before", required=True, type=non_negative) + ap.add_argument("--after", required=True, type=non_negative) + ap.add_argument("--side", required=True, choices=["before", "after"]) + ap.add_argument("--unchanged", action="store_true", + help="the step leaves the count as it is") + args = ap.parse_args(argv) + + phrase = normalise(args.phrase) + if not phrase: + ap.error("--phrase is empty after normalising") + + expected = args.before if args.side == "before" else args.after + fails: list[str] = [] + rows: list[str] = [] + files = lines = total = 0 + for path in args.paths: + try: + text = read_text(path) + except Unreadable as e: + fails.append(f"fail: {path}: {e}") + continue + n = count_phrase(text, phrase) + nlines = len(text.splitlines()) + files += 1 + lines += nlines + total += n + rows.append(f" {path}: lines {nlines}, matches {n}") + if not args.paths: + fails.append("fail: read no file") + + if fails: + actual = "not counted" + else: + actual = str(total) + if total != expected: + fails.append(f"fail: count mismatch: expected {expected} on side {args.side}, found {total}") + if args.before == args.after and not args.unchanged: + fails.append(f"fail: vacuous: before and after are both {args.before}; " + "pass --unchanged if the step leaves the phrase as it is") + + print(f"{TOOL}: {'FAIL' if fails else 'PASS'}") + print(f'phrase: "{phrase}"') + print(f"side: {args.side}") + print(f"expected: {expected} (before {args.before}, after {args.after})") + print(f"actual: {actual}") + print(f"read: files {files}, lines {lines}") + for row in rows: + print(row) + for f in fails: + print(f) + return 1 if fails else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/working-process/test_phrase_check.py b/tests/working-process/test_phrase_check.py new file mode 100644 index 0000000..6933d25 --- /dev/null +++ b/tests/working-process/test_phrase_check.py @@ -0,0 +1,189 @@ +"""Tests for plugins/working-process/scripts/phrase-check.py.""" + +from __future__ import annotations + +import os +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +REPO = Path(__file__).resolve().parents[2] +SCRIPT = str(REPO / "plugins" / "working-process" / "scripts" / "phrase-check.py") + + +class PhraseCheck(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.dir = tmp.name + + def write(self, name, content): + path = os.path.join(self.dir, name) + with open(path, "wb" if isinstance(content, bytes) else "w", **({} if isinstance(content, bytes) else {"newline": "", "encoding": "utf-8"})) as f: + f.write(content) + return path + + def run_check(self, *args): + return subprocess.run([sys.executable, SCRIPT, *args], capture_output=True, text=True) + + def ok(self, path, phrase, before, after, side="after", actual=None, *extra): + p = self.run_check(path, f"--phrase={phrase}", "--before", str(before), "--after", str(after), "--side", side, *extra) + self.assertEqual(p.returncode, 0, p.stdout + p.stderr) + if actual is not None: + self.assertIn(f"actual: {actual}", p.stdout) + return p + + def test_wrapped_phrase_counts(self): + self.ok(self.write("a.md", "alpha beta\ngamma delta\n"), "beta gamma", 0, 1, actual=1) + + def test_capital_after_wrap(self): + self.ok(self.write("a.md", "the quick\nBrown fox\n"), "quick brown", 0, 1, actual=1) + + def test_doubled_whitespace(self): + path = self.write("a.md", "alpha \t beta\n") + self.ok(path, "alpha beta", 0, 1, actual=1) + self.ok(path, "alpha beta", 0, 1, actual=1) + + def test_crlf_wrap_counts(self): + self.ok(self.write("a.md", b"alpha\r\nbeta\r\n"), "alpha beta", 0, 1, actual=1) + + def test_bom_does_not_hide_first_word(self): + self.ok(self.write("a.md", b"\xef\xbb\xbfalpha beta\n"), "alpha beta", 0, 1, actual=1) + + def test_list_and_quote_markers_dropped(self): + path = self.write("a.md", "- alpha\n beta\n> gamma\n> delta\n1. one\n two\n2) three\n* four\n+ five\n") + for phrase in ("alpha beta", "gamma delta", "one two three four five"): + self.ok(path, phrase, 0, 1, actual=1) + + def test_nested_markers_dropped(self): + self.ok(self.write("a.md", "> - alpha\n> beta\n"), "alpha beta", 0, 1, actual=1) + + def test_inline_markup_untouched(self): + path = self.write("a.md", "**alpha** beta\n---\n-dash\n# head\n") + self.ok(path, "alpha beta", 1, 0, actual=0) + self.ok(path, "**alpha** beta --- -dash # head", 0, 1, actual=1) + + def test_phrase_normalised_like_text(self): + self.ok(self.write("a.md", "alpha beta\n"), "- Alpha\n BETA", 0, 1, actual=1) + + def test_phrase_starting_with_hyphen(self): + self.ok(self.write("a.md", "use --side here\n"), "--side", 0, 1, actual=1) + + def test_no_match_across_files(self): + a = self.write("a.md", "alpha\n") + b = self.write("b.md", "beta\n") + p = self.run_check(a, b, "--phrase=alpha beta", "--before", "1", "--after", "0", "--side", "after") + self.assertEqual(p.returncode, 0, p.stdout) + self.assertIn("actual: 0", p.stdout) + + def test_matches_do_not_overlap(self): + self.ok(self.write("a.md", "aa aa aa\n"), "aa aa", 0, 1, actual=1) + self.ok(self.write("b.md", "ab ab ab ab\n"), "ab ab", 0, 2, actual=2) + + def test_total_over_files_and_what_was_read(self): + a = self.write("a.md", "x\nalpha\n") + b = self.write("b.md", "alpha\nalpha\ny\n") + p = self.run_check(a, b, "--phrase=alpha", "--before", "0", "--after", "3", "--side", "after") + self.assertEqual(p.returncode, 0, p.stdout) + lines = p.stdout.splitlines() + self.assertEqual(lines[0], "wp-phrase-check: PASS") + for want in ("expected: 3 (before 0, after 3)", "actual: 3", "read: files 2, lines 5"): + self.assertIn(want, lines) + self.assertTrue(any(l.endswith("a.md: lines 2, matches 1") for l in lines)) + self.assertTrue(any(l.endswith("b.md: lines 3, matches 2") for l in lines)) + + def test_same_path_twice_counts_twice(self): + a = self.write("a.md", "alpha\n") + p = self.run_check(a, a, "--phrase=alpha", "--before", "0", "--after", "2", "--side", "after") + self.assertEqual(p.returncode, 0, p.stdout) + self.assertIn("read: files 2, lines 2", p.stdout) + + def test_empty_file_is_read(self): + p = self.ok(self.write("a.md", ""), "alpha", 1, 0, actual=0) + self.assertIn("read: files 1, lines 0", p.stdout) + + def test_side_selects_the_number(self): + path = self.write("a.md", "alpha\n") + self.ok(path, "alpha", 1, 0, side="before") + p = self.run_check(path, "--phrase=alpha", "--before", "1", "--after", "0", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertIn("fail: count mismatch: expected 0 on side after, found 1", p.stdout) + + def test_mismatch_fails(self): + path = self.write("a.md", "alpha\n") + p = self.run_check(path, "--phrase=alpha", "--before", "0", "--after", "2", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertEqual(p.stdout.splitlines()[0], "wp-phrase-check: FAIL") + self.assertIn("fail: count mismatch: expected 2 on side after, found 1", p.stdout) + + def test_equal_counts_fail_unless_declared(self): + path = self.write("a.md", "alpha\n") + for side in ("before", "after"): + p = self.run_check(path, "--phrase=alpha", "--before", "1", "--after", "1", "--side", side) + self.assertEqual(p.returncode, 1) + self.assertIn("fail: vacuous", p.stdout) + p = self.run_check(path, "--phrase=alpha", "--before", "1", "--after", "1", "--side", "after", "--unchanged") + self.assertEqual(p.returncode, 0, p.stdout) + self.assertNotIn("fail:", p.stdout) + + def test_mismatch_reported_before_vacuity(self): + path = self.write("a.md", "alpha\n") + p = self.run_check(path, "--phrase=alpha", "--before", "2", "--after", "2", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertIn("fail: count mismatch", p.stdout) + self.assertIn("fail: vacuous", p.stdout) + self.assertLess(p.stdout.index("fail: count mismatch"), p.stdout.index("fail: vacuous")) + + def test_missing_path_fails(self): + p = self.run_check(os.path.join(self.dir, "nope.md"), "--phrase=alpha", "--before", "1", "--after", "0", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertIn("actual: not counted", p.stdout) + self.assertTrue(any(l.startswith("fail:") and l.endswith("no such file") for l in p.stdout.splitlines())) + self.assertNotIn("fail: count mismatch", p.stdout) + + def test_directory_fails(self): + p = self.run_check(self.dir, "--phrase=alpha", "--before", "1", "--after", "0", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertTrue(any(l.startswith("fail:") and l.endswith("not a file") for l in p.stdout.splitlines())) + + def test_invalid_utf8_fails(self): + path = self.write("a.md", b"\xff\xfe alpha\n") + p = self.run_check(path, "--phrase=alpha", "--before", "0", "--after", "1", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertTrue(any(l.startswith("fail:") and l.endswith("not valid UTF-8") for l in p.stdout.splitlines())) + + @unittest.skipIf(os.name == "nt" or (hasattr(os, "geteuid") and os.geteuid() == 0), "chmod 0 does not block") + def test_unopenable_file_fails(self): + path = self.write("a.md", "alpha\n") + os.chmod(path, 0) + p = self.run_check(path, "--phrase=alpha", "--before", "0", "--after", "1", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertTrue(any(l.startswith("fail:") and "cannot be read" in l for l in p.stdout.splitlines())) + + def test_one_bad_path_fails_the_run(self): + a = self.write("a.md", "alpha\n") + p = self.run_check(a, os.path.join(self.dir, "nope.md"), "--phrase=alpha", "--before", "0", "--after", "1", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertIn("actual: not counted", p.stdout) + self.assertIn("read: files 1, lines 1", p.stdout) + + def test_no_path_fails(self): + p = self.run_check("--phrase=alpha", "--before", "1", "--after", "0", "--side", "after") + self.assertEqual(p.returncode, 1) + self.assertIn("fail: read no file", p.stdout) + + def test_blank_phrase_is_usage_error(self): + path = self.write("a.md", "alpha\n") + p = self.run_check(path, "--phrase= ", "--before", "0", "--after", "1", "--side", "after") + self.assertEqual(p.returncode, 2) + + def test_negative_count_is_usage_error(self): + path = self.write("a.md", "alpha\n") + p = self.run_check(path, "--phrase=alpha", "--before=-1", "--after", "0", "--side", "after") + self.assertEqual(p.returncode, 2) + + +if __name__ == "__main__": + unittest.main() From afb0878583cedaddb7831d8bd388e986ec155e0c Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:19:25 +0100 Subject: [PATCH 36/59] feat(working-process): wp-phrase-check launcher in the plugin bin --- plugins/working-process/bin/wp-phrase-check | 28 ++++++ .../test_wp_phrase_check_launcher.py | 98 +++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100755 plugins/working-process/bin/wp-phrase-check create mode 100644 tests/working-process/test_wp_phrase_check_launcher.py diff --git a/plugins/working-process/bin/wp-phrase-check b/plugins/working-process/bin/wp-phrase-check new file mode 100755 index 0000000..6a8b12a --- /dev/null +++ b/plugins/working-process/bin/wp-phrase-check @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Runs scripts/phrase-check.py under the first Python 3.9+ found. +# No readlink -f / realpath: stock macOS lacks them. +self="${BASH_SOURCE[0]}" +while [ -L "$self" ]; do + target="$(readlink "$self")" + case "$target" in + /*) self="$target" ;; + *) self="${self%/*}/$target" ;; + esac +done +dir="$(cd "${self%/*}" && pwd)" +script="$dir/../scripts/phrase-check.py" + +tried="" +for c in "python3" "python" "py -3"; do + read -r -a candidate <<< "$c" + if ! command -v "${candidate[0]}" > /dev/null 2>&1; then + why="not found" + elif "${candidate[@]}" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)' > /dev/null 2>&1; then + exec "${candidate[@]}" "$script" "$@" + else + why="rejected" + fi + tried="${tried:+$tried, }$c ($why)" +done +echo "wp-phrase-check: no Python 3.9 or later found; tried: $tried" >&2 +exit 2 diff --git a/tests/working-process/test_wp_phrase_check_launcher.py b/tests/working-process/test_wp_phrase_check_launcher.py new file mode 100644 index 0000000..d8532fc --- /dev/null +++ b/tests/working-process/test_wp_phrase_check_launcher.py @@ -0,0 +1,98 @@ +"""Tests for plugins/working-process/bin/wp-phrase-check.""" + +from __future__ import annotations + +import os +import shutil +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +REPO = Path(__file__).resolve().parents[2] +LAUNCHER = str(REPO / "plugins" / "working-process" / "bin" / "wp-phrase-check") +BASH = shutil.which("bash") +READLINK = shutil.which("readlink") +PASSING = ["--phrase", "alpha", "--before", "0", "--after", "1", "--side", "after"] + +GOOD = f'#!{BASH}\nexec {sys.executable} "$@"\n' +OLD = f'#!{BASH}\nif [ "$1" = "-c" ]; then exit 1; fi; echo WRONG-INTERPRETER; exit 0\n' +GOOD_PY = f'#!{BASH}\n[ "$1" = "-3" ] || exit 9; shift; exec {sys.executable} "$@"\n' + + +@unittest.skipIf(os.name == "nt", "bash launcher") +class Launcher(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.dir = tmp.name + self.stubs = os.path.join(self.dir, "stubs") + os.mkdir(self.stubs) + os.symlink(READLINK, os.path.join(self.stubs, "readlink")) + self.file = os.path.join(self.dir, "in.md") + with open(self.file, "w") as f: + f.write("alpha\n") + + def stub(self, name, body): + path = os.path.join(self.stubs, name) + with open(path, "w") as f: + f.write(body) + os.chmod(path, 0o755) + + def run_launcher(self, *args, launcher=LAUNCHER): + return subprocess.run([BASH, launcher, *args], env={"PATH": self.stubs}, capture_output=True, text=True) + + def assert_pass(self, r): + self.assertEqual(r.returncode, 0, r.stderr) + self.assertTrue(r.stdout.startswith("wp-phrase-check: PASS"), r.stdout) + + def test_python3_runs(self): + self.stub("python3", GOOD) + self.assert_pass(self.run_launcher(self.file, *PASSING)) + + def test_old_python3_is_skipped_for_python(self): + self.stub("python3", OLD) + self.stub("python", GOOD) + r = self.run_launcher(self.file, *PASSING) + self.assert_pass(r) + self.assertNotIn("WRONG-INTERPRETER", r.stdout) + + def test_py_launcher_is_last_resort(self): + self.stub("py", GOOD_PY) + self.assert_pass(self.run_launcher(self.file, *PASSING)) + + def test_no_python_names_what_it_tried(self): + self.stub("python3", OLD) + r = self.run_launcher(self.file, *PASSING) + self.assertEqual(r.returncode, 2) + self.assertEqual(r.stdout, "") + for s in ("python3 (rejected)", "python (not found)", "py -3 (not found)"): + self.assertIn(s, r.stderr) + + def test_exit_code_passes_through(self): + self.stub("python3", GOOD) + r = self.run_launcher(self.file, "--phrase", "alpha", "--before", "0", "--after", "2", "--side", "after") + self.assertEqual(r.returncode, 1) + self.assertTrue(r.stdout.startswith("wp-phrase-check: FAIL"), r.stdout) + + def test_symlinked_launcher_finds_script(self): + self.stub("python3", GOOD) + other = tempfile.TemporaryDirectory() + self.addCleanup(other.cleanup) + link = os.path.join(other.name, "link") + os.symlink(LAUNCHER, link) + self.assert_pass(self.run_launcher(self.file, *PASSING, launcher=link)) + + def test_path_with_space_survives_launcher(self): + self.stub("python3", GOOD) + spaced = os.path.join(self.dir, "two words.md") + with open(spaced, "w") as f: + f.write("alpha\n") + r = self.run_launcher(spaced, *PASSING) + self.assert_pass(r) + self.assertTrue(any(l.endswith("two words.md: lines 1, matches 1") for l in r.stdout.splitlines()), r.stdout) + + +if __name__ == "__main__": + unittest.main() From 0177ba8a609fa955e6806dc0dc027f2644f11181 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:20:28 +0100 Subject: [PATCH 37/59] feat(working-process): plan-authoring rule with the recurring defect classes --- .../working-process/rules/plan-authoring.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 plugins/working-process/rules/plan-authoring.md diff --git a/plugins/working-process/rules/plan-authoring.md b/plugins/working-process/rules/plan-authoring.md new file mode 100644 index 0000000..438b820 --- /dev/null +++ b/plugins/working-process/rules/plan-authoring.md @@ -0,0 +1,79 @@ +--- +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. From aa781ee197781ffb1200565dcdf32af80589698d Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:21:06 +0100 Subject: [PATCH 38/59] feat(working-process): plan-writing and the plan-adversary read the plan-authoring rule --- .../working-process/agents/plan-adversary.md | 7 +++++++ plugins/working-process/rules/workflow.md | 17 +++++++++++------ 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/plugins/working-process/agents/plan-adversary.md b/plugins/working-process/agents/plan-adversary.md index a1879d5..b8a366f 100644 --- a/plugins/working-process/agents/plan-adversary.md +++ b/plugins/working-process/agents/plan-adversary.md @@ -19,6 +19,13 @@ your wording, and — re-tightening the shared file's "called out" floor — a plan contradicting a glossary term or a recorded ADR is a finding (evidence = that file). +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). + ## Ground rules - Every finding cites evidence: `file:line`, a quote from the plan, a diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 9806370..d6062d9 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -115,13 +115,18 @@ disables its suggestion — never the work itself. pair's sequencing at this gate is in the `review-loop` skill's procedure reference, when that skill is available. - Then write the + 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 requires - reading it before the plan is written: that rule carries the - annotations a plan owes a registered design spec, and a separate - context cannot count on it loading. + 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. 5. **Plan → adversary review.** Before implementing a non-trivial plan, offer a working-process plan-adversary agent dispatch (when available); dispatch and stamping follow the `review-loop` skill's From 4534310c7d1c83abf9243acc3a0799e446aac7a6 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:21:58 +0100 Subject: [PATCH 39/59] docs(working-process): wp-phrase-check and plan-authoring in README, catalog and changelog --- .claude-plugin/marketplace.json | 2 +- README.md | 2 +- .../.claude-plugin/plugin.json | 4 ++-- plugins/working-process/CHANGELOG.md | 15 ++++++++++++++ plugins/working-process/README.md | 20 +++++++++++++++---- 5 files changed, 35 insertions(+), 8 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7e5ce6e..5c5b333 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, 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, 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 command, plus distributed process rules" }, { "name": "python-standards", diff --git a/README.md b/README.md index ef81147..0d0d002 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, review-loop 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` command, 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/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index d4cfff9..b384ee7 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "working-process", - "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, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.20.0-dev.9.process-context", + "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 command for a plan's verification checks over text, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", + "version": "0.20.0-dev.10.plan-quality", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index a30df8d..714441d 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -68,6 +68,21 @@ Released versions of this plugin, newest first. - 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. +- `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. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index 66f255f..343a4a1 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -106,6 +106,12 @@ verdict dispatch and the integrity audit itself. - **`sync-rules` skill** — installs, updates, and uninstalls the rule files shipped by plugins of this marketplace (Rules payloads); see the "Process rules" section. +- **`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. Each persona is single-sourced in its file at the plugin root — [ARCHITECT_PERSONA.md](./ARCHITECT_PERSONA.md) and @@ -122,6 +128,8 @@ exist, so it speaks the project's language from its first message. - Claude Code ≥ 2.1.207 (verified — rules distribution needs subdirectory rules loading; the skills and agents alone work on ≥ 2.1.143). +- 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. - The `superpowers` plugin — declared as a dependency and installed automatically alongside this plugin. - Optional companion: the `elements-of-style` plugin. When its @@ -132,8 +140,10 @@ exist, so it speaks the project's language from its first message. /plugin marketplace add obra/superpowers-marketplace /plugin install elements-of-style@superpowers-marketplace -- `python3` 3.9 or later, standard library only, for the propagation - auditor's coverage duty. +- 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`. ## Extending with a domain checklist @@ -228,7 +238,7 @@ new gates merely stay silent. ## Process rules -The plugin ships eight rule files in `rules/` — the preferred workflow +The plugin ships nine rule files in `rules/` — the preferred workflow (always loaded once installed), the process settings (`process-settings.md`, always loaded: the settings files, their grammar, the block and how a key is read), frontmatter and lifecycle @@ -236,7 +246,9 @@ for judged documents and plans, what a technical design must contain (`technical-design.md`, loaded while one is open), Process directory conventions, ticket frontmatter, the propagation duties keyed by the edit that triggers them (`propagation-duties.md`, loaded while a design -spec, technical design, plan or domain document is open), and the +spec, technical design, 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 review-report contract (`review-reports.md`: where a code-review run writes its Review report and what shape it takes; domain review skills locate the installed contract via its contract probe — the From 6c4ce346449810cbb346511484381ba04eace1d3 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:24:37 +0100 Subject: [PATCH 40/59] fix(working-process): wp-phrase-check resolves a bare script name; tighten phrase-check tests --- plugins/working-process/bin/wp-phrase-check | 4 +++- tests/working-process/test_phrase_check.py | 6 +++++- tests/working-process/test_wp_phrase_check_launcher.py | 6 ++++++ 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/plugins/working-process/bin/wp-phrase-check b/plugins/working-process/bin/wp-phrase-check index 6a8b12a..68b9a4a 100755 --- a/plugins/working-process/bin/wp-phrase-check +++ b/plugins/working-process/bin/wp-phrase-check @@ -2,11 +2,13 @@ # Runs scripts/phrase-check.py under the first Python 3.9+ found. # No readlink -f / realpath: stock macOS lacks them. self="${BASH_SOURCE[0]}" +case "$self" in */*) ;; *) self="./$self" ;; esac while [ -L "$self" ]; do target="$(readlink "$self")" case "$target" in /*) self="$target" ;; - *) self="${self%/*}/$target" ;; + */*) self="${self%/*}/$target" ;; + *) self="${self%/*}/./$target" ;; esac done dir="$(cd "${self%/*}" && pwd)" diff --git a/tests/working-process/test_phrase_check.py b/tests/working-process/test_phrase_check.py index 6933d25..b0afe61 100644 --- a/tests/working-process/test_phrase_check.py +++ b/tests/working-process/test_phrase_check.py @@ -170,19 +170,23 @@ def test_one_bad_path_fails_the_run(self): self.assertIn("read: files 1, lines 1", p.stdout) def test_no_path_fails(self): - p = self.run_check("--phrase=alpha", "--before", "1", "--after", "0", "--side", "after") + p = self.run_check("--phrase=alpha", "--before", "1", "--after", "1", "--side", "after") self.assertEqual(p.returncode, 1) self.assertIn("fail: read no file", p.stdout) + self.assertIn("actual: not counted", p.stdout) + self.assertNotIn("vacuous", p.stdout) def test_blank_phrase_is_usage_error(self): path = self.write("a.md", "alpha\n") p = self.run_check(path, "--phrase= ", "--before", "0", "--after", "1", "--side", "after") self.assertEqual(p.returncode, 2) + self.assertIn("--phrase is empty after normalising", p.stderr) def test_negative_count_is_usage_error(self): path = self.write("a.md", "alpha\n") p = self.run_check(path, "--phrase=alpha", "--before=-1", "--after", "0", "--side", "after") self.assertEqual(p.returncode, 2) + self.assertIn("must not be negative", p.stderr) if __name__ == "__main__": diff --git a/tests/working-process/test_wp_phrase_check_launcher.py b/tests/working-process/test_wp_phrase_check_launcher.py index d8532fc..9aded31 100644 --- a/tests/working-process/test_wp_phrase_check_launcher.py +++ b/tests/working-process/test_wp_phrase_check_launcher.py @@ -84,6 +84,12 @@ def test_symlinked_launcher_finds_script(self): os.symlink(LAUNCHER, link) self.assert_pass(self.run_launcher(self.file, *PASSING, launcher=link)) + def test_bare_name_invocation_from_bin_dir(self): + self.stub("python3", GOOD) + r = subprocess.run([BASH, "wp-phrase-check", self.file, *PASSING], env={"PATH": self.stubs}, + cwd=os.path.dirname(LAUNCHER), capture_output=True, text=True) + self.assert_pass(r) + def test_path_with_space_survives_launcher(self): self.stub("python3", GOOD) spaced = os.path.join(self.dir, "two words.md") From c9074e82c7c4d79b4c953eff6bf9e0f23eb01fe0 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 19:28:27 +0100 Subject: [PATCH 41/59] fix(working-process): phrase-check hardening and plan-authoring count form --- plugins/working-process/CHANGELOG.md | 3 ++- plugins/working-process/bin/wp-phrase-check | 2 +- plugins/working-process/rules/plan-authoring.md | 8 ++++---- plugins/working-process/scripts/phrase-check.py | 1 + tests/working-process/test_phrase_check.py | 4 ++++ 5 files changed, 12 insertions(+), 6 deletions(-) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 714441d..aec3ce4 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -67,7 +67,6 @@ Released versions of this plugin, newest first. - 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. - `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 @@ -83,6 +82,8 @@ Released versions of this plugin, newest first. 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. +- Run `sync-rules` after updating: both rules shrink, and the new + `plan-authoring.md` also arrives through `sync-rules`. ## 0.19.0 — 2026-11-13 diff --git a/plugins/working-process/bin/wp-phrase-check b/plugins/working-process/bin/wp-phrase-check index 68b9a4a..8d22acf 100755 --- a/plugins/working-process/bin/wp-phrase-check +++ b/plugins/working-process/bin/wp-phrase-check @@ -11,7 +11,7 @@ while [ -L "$self" ]; do *) self="${self%/*}/./$target" ;; esac done -dir="$(cd "${self%/*}" && pwd)" +dir="$(cd -- "${self%/*}" > /dev/null && pwd)" script="$dir/../scripts/phrase-check.py" tried="" diff --git a/plugins/working-process/rules/plan-authoring.md b/plugins/working-process/rules/plan-authoring.md index 438b820..a97b56b 100644 --- a/plugins/working-process/rules/plan-authoring.md +++ b/plugins/working-process/rules/plan-authoring.md @@ -57,10 +57,10 @@ 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 +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 count matches, not lines (`grep -oiF -- "" | wc -l`) — and state both numbers beside the check. The command cannot enforce the rest: diff --git a/plugins/working-process/scripts/phrase-check.py b/plugins/working-process/scripts/phrase-check.py index 1a4e499..4287810 100755 --- a/plugins/working-process/scripts/phrase-check.py +++ b/plugins/working-process/scripts/phrase-check.py @@ -58,6 +58,7 @@ def non_negative(value: str) -> int: def main(argv: list[str] | None = None) -> int: ap = argparse.ArgumentParser( + allow_abbrev=False, prog="phrase-check.py", description="Count a phrase across files after normalising wrapping and markers. " "A phrase starting with a hyphen is written --phrase=.", diff --git a/tests/working-process/test_phrase_check.py b/tests/working-process/test_phrase_check.py index b0afe61..b5db7a2 100644 --- a/tests/working-process/test_phrase_check.py +++ b/tests/working-process/test_phrase_check.py @@ -136,6 +136,10 @@ def test_mismatch_reported_before_vacuity(self): self.assertIn("fail: vacuous", p.stdout) self.assertLess(p.stdout.index("fail: count mismatch"), p.stdout.index("fail: vacuous")) + def test_abbreviated_option_rejected(self): + p = self.run_check(self.write("a.md", "alpha\n"), "--phrase=alpha", "--bef", "0", "--after", "1", "--side", "after") + self.assertEqual(p.returncode, 2, p.stdout + p.stderr) + def test_missing_path_fails(self): p = self.run_check(os.path.join(self.dir, "nope.md"), "--phrase=alpha", "--before", "1", "--after", "0", "--side", "after") self.assertEqual(p.returncode, 1) From d42463a34c6bd33bdb7cbe2f30b58d5bfce854ef Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Mon, 16 Nov 2026 20:29:10 +0100 Subject: [PATCH 42/59] docs(working-process): plan quality spec and plan implemented --- docs/plans/2026-11-16-plan-quality-plan.md | 2 +- docs/specs/2026-11-16-plan-quality-spec.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plans/2026-11-16-plan-quality-plan.md b/docs/plans/2026-11-16-plan-quality-plan.md index 7e45fe6..643d8cd 100644 --- a/docs/plans/2026-11-16-plan-quality-plan.md +++ b/docs/plans/2026-11-16-plan-quality-plan.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-16 -status: approved +status: implemented spec: ../specs/2026-11-16-plan-quality-spec.md branch: feature/plan-quality base: develop diff --git a/docs/specs/2026-11-16-plan-quality-spec.md b/docs/specs/2026-11-16-plan-quality-spec.md index e0de0a3..f4c7209 100644 --- a/docs/specs/2026-11-16-plan-quality-spec.md +++ b/docs/specs/2026-11-16-plan-quality-spec.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-11-16 -status: approved +status: implemented grilled: 2026-11-16 architect: concerns (resolved 2026-11-16) integrity: 2026-11-16 (sha: b40d9eb) From 75004598a20ebea9538916a7738a11c955be1d7c Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 17 Nov 2026 13:03:17 +0100 Subject: [PATCH 43/59] docs(working-process): document-check spec and glossary terms --- docs/domain/glossary.md | 21 +- docs/specs/2026-11-17-document-check-spec.md | 472 +++++++++++++++++++ 2 files changed, 488 insertions(+), 5 deletions(-) create mode 100644 docs/specs/2026-11-17-document-check-spec.md diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index fcfe1be..d757fb5 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -502,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 @@ -528,6 +530,15 @@ 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. @@ -584,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 diff --git a/docs/specs/2026-11-17-document-check-spec.md b/docs/specs/2026-11-17-document-check-spec.md new file mode 100644 index 0000000..128818d --- /dev/null +++ b/docs/specs/2026-11-17-document-check-spec.md @@ -0,0 +1,472 @@ +--- +ticket: none +date: 2026-11-17 +status: approved +grilled: 2026-11-17 +architect: concerns (resolved 2026-11-17) +integrity: 2026-11-17 (sha: d31a3a4) +decisions: registered +branch: feature/document-check +base: develop +--- + +# Document check — the gate's mechanical half + +The propagation gate calls documents clean where a script could have +proved them wrong. This spec ships `wp-document-check`, a script that +runs Document checks over the mechanical classes, and makes the +dispatcher run it, and the existing `decision-coverage` script, beside +the auditor rather than through it. It is package 4 of the release +queue, widened from technical designs to all three document classes on +the evidence below. + +## Problem + +Evidence gathered 2026-11-16 and 2026-11-17 from four sources (records +in the developer's private store, not committed): the technical-design +dogfood in a devcontainer project, gate records in a web-application +project and in a Salesforce project, and this repository's own review +rounds. + +- **The gate misses what a parse settles.** About 70 defects passed a + gate and surfaced later in an architect, adversary, integrity or + implementation read. About 30 belonged to classes a script decides + without judgment: an internal reference to a section that does not + exist ("the remove sequences below"), a `path:line` citation outside + its file or off its symbol, a quoted license that does not occur in + the line it cites, a named document that does not exist, a + technical-design table relation with no row behind it, and an + `integrity:` stamp whose hash no longer matches (left out, see + *Non-goals*). +- **The gate says "checked" where it did not check.** On those classes + the auditor also reported "consistent" or `CLEAN`: Sonnet in 10 of 18 + controlled runs, Haiku in 4 of 4. Five consumer enumerations in the + web-application project claimed "checked, no hit" and were wrong. +- **The auditor skips scripts it is told to run.** The card tells it + to run `decision-coverage.py` and copy the output. In the Salesforce + project, three of the four runs whose brief required the script's + lines returned without them. + +A rule asking the auditor to try harder has already failed: the card +already says "derive, never recall". What is missing is a Document check the +auditor cannot skip. + +## Goals, non-goals, anti-goals + +Goals: + +- A gate never passes a document carrying a defect of a form the + Document checks settle. +- The script runs on every gate, whatever the auditor does, unless the + developer orders a dispatch without it (D8). +- The auditor never writes "checked, no hit" for a consumer enumeration + it did not run. + +Non-goals: + +- Counters ("four rows" against the table below): recognising them + needs a heuristic, and a heuristic's false hits would block the gate. +- Identifier occurrences in the script. The auditor already enumerates + consumers; D7 makes it show its work. +- Running a plan's published commands — a harness job, not a text check. +- Semantic defects: contradictory behaviour, a lost qualifier, sequence + order. They drove most integrity-audit finds and stay with the + readers. +- Re-measuring Haiku against Sonnet on the gate. +- The `integrity:` stamp. After a licensed fix wave a stamp is stale by + design, so on every gate but the consumption gate a stale stamp is + expected; the consumption gate already recomputes and compares it. +- Launchers for the bash scripts in `scripts/`; their callers (hooks, + the settings block, `sync-rules`) resolve them by path already. + +Anti-goals: + +- A script hit that needs judgment to confirm. A false hit blocks the + gate and wastes a fix wave; what the script cannot settle goes to its + `not checked` lines instead. +- The script's result reaching the auditor. The two read independently. + +Constraints and estimates (estimates, never thresholds): + +- The script is about 300–400 lines of Python 3.9+, standard library + only; the plan about 6–8 tasks. +- Reused: the launcher from package 6, adapted by two lines (D4), + `decision-coverage.py` (its logic untouched), and the declared table relations of + the technical-design rule. +- Accepted risks: on macOS a `/usr/bin/python3` stub may open an + install dialog rather than fail (untested, as for `wp-phrase-check`); + the script covers fewer than the 30 or so known misses in mechanical + classes — the stamp and backticked paths left it after round 1 — and + the rest stays with the auditor or with nobody. + +## Decisions + +- **D1** — The plugin ships `bin/wp-document-check`, running + `scripts/document-check.py`, on any design spec, technical design or + plan. Argued in *The Document checks*. +- **D2** — The script reports a hit only where its parse settles the + defect without judgment. Every form it cannot settle is counted on a + `not checked` line, never reported as a hit. Argued in *The Document checks*. +- **D3** — Two Document checks run on every document: internal + references and citations, a Markdown link target counting as a + citation. Table closure runs on a + technical design alone, on the segments D10 settles; the segments it + leaves not checked stay the auditor's, under duty 11 (D12). Argued in + *The Document checks*. +- **D4** — One launcher serves every Python script: `bin/wp-` + runs `scripts/.py`, the name read from the launcher's own file + name. `bin/` carries identical copies, never symlinks, which break in + a Windows checkout. Argued in *One launcher*. +- **D5** — `decision-coverage` moves behind the launcher as + `wp-decision-coverage`; its logic and output do not change. Argued in + *One launcher*. +- **D6** — The dispatcher runs `wp-document-check` and, on a plan or a + design spec, `wp-decision-coverage` before it dispatches the auditor, + and disposes of their hits — fixed, dismissed, or held, which ends the + episode as a held hit does today — until both scripts are clean of + undisposed hits. That loop costs seconds and spends none + of the episode's re-dispatches. It then dispatches the auditor, which + no longer runs either script. The gate passes once every hit from + either side is disposed. Argued in *Who runs it*. +- **D7** — The auditor's card forbids "checked, no hit" on a consumer + enumeration unless the report shows the command it ran and the hit + count from its output; without them the line reads `not checked`. + Argued in *Who runs it*. +- **D8** — A script that cannot run — no Python 3.9+, a crash, any exit + other than 0 — is an ordinary error, never a hit: the gate stops and + its message goes to the developer. Where the message names a cause in + a document, such as a `spec:` pointing at a missing file, the session + may fix it and re-run; otherwise the developer decides, installing + Python and re-running, or ordering the dispatch without Document + checks, an answer that holds for the rest of the session. Nothing is + written to the ledger. Argued in *Who runs it*. +- **D9** — A Markdown link or a `path:line` that does not resolve is a + hit only when it names a directory, that directory exists, and a plan + does not create the file in a `Create:` line; a bare file name and + every other unresolved path are not checked. A missing backticked + path carrying no line is not checked on any document. Whether git ignores the path + plays no part. Argued in *The Document checks*. +- **D10** — Table closure resolves only the cell segments that equal a + row of the target table, after parenthesised text is dropped and the + cell is split at commas and semicolons. A segment naming more than + one row and an empty side are hits; a segment naming no row is not + checked. The declaration rows come from the plugin's own copy of the + technical-design rule. Argued in *The Document checks*. +- **D11** — The scripts run at every point the gate fires — before a + verdict dispatch, after a fix wave, before an integrity audit, and at + the authoring-time offer, accepted or declined — whether or not the + auditor is available. + Without the auditor the gate is the scripts alone, and gate lines and + the held batch apply to their hits unchanged; script re-runs are + unbounded on purpose, since each costs seconds. + Argued in *Who runs it*. +- **D12** — The duty numbering stays: duties 10 and 11 keep their + numbers and their rows in the author's checklist rule. Duty 10's + first line says the dispatcher's script performs it, and its steps + stay as the definition the script implements. Duty 11 stays the + auditor's for a name matching no row — the form D10 leaves not + checked, named by form since the auditor never sees the script's + output — and its text says the script resolves the rest as D10 + defines. Argued in *Who + runs it*. +- **D13** — The scripts' output never reaches the auditor's brief, and + the relay reports the scripts' dispositions and the auditor's hits + together. Argued in *Who runs it*. +- **D14** — The plan sweeps every shipped sentence D1, D3, D5, D6, D8 + or D11 make false, enumerating them by grep, in a task of its own. + Argued in *Who runs it*. +- **D15** — Under `## Review rounds` the Document checks read only the + lines below the last round heading, the round in progress; earlier + rounds record past states whose citations later waves moved, so + checking them would breed a dismissal every gate. Argued in + *Citations*. + +## The Document checks + +`wp-document-check ` reads one document and prints one line +per hit, then three summary lines — `references`, `citations`, +`table-closure` — then exits 0 whenever the +Document checks ran, hits or not; 1 when the document cannot be read; 2 on a +usage error — the exit codes `decision-coverage` already uses. A hit +names the site, the claim and the Document check, by the same three +names: + + — — check: + +A summary line counts what the Document check read and what it could not settle: + + document-check: references 14 checked, 3 not checked + document-check: citations 9 checked, 4 not checked + document-check: table-closure not applicable + +The script's `table-closure` summary line replaces the card's +`table-closure:` line; the card's rule that no other document carries +that line goes with it. + +The document type is read as `decision-coverage` reads it, the path +test first: `technical-designs/` directly under `docs/`, or a file name +ending `-technical-design.md` (a ticket directory's design), marks a +technical design; otherwise a frontmatter `spec:` field marks a plan, +and its absence a design spec. A technical design also carries `spec:`, +which is why the path decides first. + +**Internal references.** A section named in italics or quotes beside +"below" or "above" resolves to a heading of the document, below or +above where the text says so, and a plan's "Task N" resolves to a task +heading. A name matching no heading may name another document's +section, so it is not checked; so are a bare "below", a `§N` (in this +repository it mostly cites another document) and a "Step N", whose +steps are list items numbered per task. What this catches is a named +section on the wrong side and a "Task N" with no task. Not caught: the +measured miss of a technical design citing "remove sequences below" +that did not exist — unformatted, and a name matching no heading +besides — and three step references pointing at the wrong, existing +steps after a renumbering; both take judgment, and stay the auditor's. + +**Citations.** A `path:line` or `path:a-b` names an existing file, and +its line or range lies inside it; an unresolved path follows D9. Written `` `symbol` (path:line) ``, +the symbol also occurs on the cited line. Any other shape near a +citation is not checked. A `license:` or `ruling:` clause carrying a +double-quoted string and a location — a path, a `path:line` or a +heading of the same document — finds that string at the location, +normalised as `wp-phrase-check` normalises (a line's leading list or +quote marker dropped, lines joined, whitespace collapsed, case +ignored). A Markdown link target resolves to an existing file, +relative to the document or to the repository root, by the same D9 +rule. A path that exists in the author's checkout resolves whether git +tracks it or not, since the gate runs there. A backticked path carrying +no line is counted and, when missing, not checked (D9): a design spec or +a technical design names files not yet written, and a plan names +conventions and placeholders as paths, so a missing one cannot be told +from a defect without judgment. Measured misses: nine `path:line` +citations off by lines in one plan; nine license quotes that did not +occur in the ruling they cited — ledger lines, which D15 keeps in +reach while their round is in progress. Not caught: a ledger citing a +"technical design round 2 integrity note" that never existed, and the +stale `.claude/memory/INDEX.md` names the spike found — prose and +backticked paths, which the auditor's consumer enumeration still +reaches. + +**Table closure** (technical design only). For every relation the +technical-design rule declares, the script splits each cell as D10 +says: `producer → consumer` at the arrow first, then at commas and +semicolons, `external: ` being no reference. Dropping +parenthesised text and splitting at semicolons reads more loosely than +the rule's comma grammar, on purpose: a prose cell still yields the +part names it holds, and since an unmatched segment is not checked +(D10), no hit arises that the rule's own grammar would not raise. It +reads the declaration table's rows from the plugin's own copy of the +rule, in the plugin's `rules/` directory beside `scripts/`, so the copy matches the script's version; the +splitting grammar is code, and a declaration that changes it changes +the script too. The `table-closure:` line moves here; a name matching +no row stays the auditor's, under duty 11 (D12). Real designs write prose in these cells — "the +platform", "Host tasks (`profile:new` once)" — so a strict reading +would block every design on prose; D10 trades recall for no false hit. +Caught: an empty side and a name matching several rows. Not caught: +the four measured relations naming no row, which stay the auditor's +under duty 11, and the false "tables absent", which was an auditor's +claim the script's count of relations now replaces. + +## One launcher + +Package 6 shipped one launcher for one script. Generalising it costs +two lines — the script path and the error message's name: the launcher derives `scripts/.py` from its own name +`wp-`, and each command in `bin/` is a copy of the same file. A +test asserts the copies are byte-identical and that each resolves to an +existing script. + +`decision-coverage.py` runs today as +`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/decision-coverage.py`, which has +no fallback where only `python` or `py -3` exists. Behind the launcher +it gains the fallback and the plugin keeps one convention for calling +its scripts. Only Python scripts get a launcher; the bash scripts gain +nothing from one. + +## Who runs it + +The dispatcher runs both scripts first, synchronously — each finishes in +seconds — and disposes of their hits until none is undisposed: `hit +fixed`, `hit dismissed` where the session believes one wrong, or, for a +`wp-decision-coverage` coverage hit only, `hit held`, which ends the +episode as today — the same ledger lines as the auditor's. Running them first means the +auditor reads the text the script fixes produced, rather than a text +those fixes are about to change, and a script re-run spends none of the +episode's two re-dispatches. Only then does the dispatcher send the +auditor, in the background as before, with nothing from the scripts in +its brief. The relay reports the scripts' dispositions and the +auditor's hits together. + +The procedure's gate section and the card change together: the card +drops duty 10's "run the derivation" paragraph and its +`decision-coverage:` lines and the `table-closure:` line, since the +dispatcher now carries them. Every shipped sentence that D1, D3, D5, +D6, D8 or D11 make false changes with them — whatever the auditor did +that the scripts now do, the gate's precondition and order, and every +enumeration of the plugin's commands — and the plan enumerates those +sentences by grep. The spec names none of them: three gate runs each +found sites a list here had missed. + +The scripts do not depend on the auditor (D11): they cost seconds and +cannot be skipped, so they run at every point the gate fires — at the +authoring-time offer too, whether or not it is accepted, since they +only read — and where the auditor is not installed they are the gate. +The duties keep their numbers (D12), so no "duty N" citation breaks. + +The auditor keeps the consumer enumeration, the class the script leaves +alone, and the table-closure segments the script cannot settle. One +sentence in its card (D7) closes the gap the evidence showed: "checked, +no hit" on a changed identifier requires the command and the count from +its output in the report. + +A script that cannot run is an error, as an agent that dies is (D8). A +launcher that finds no Python prints the interpreters it tried and +exits non-zero; a crash or an unreadable document exits non-zero too. +The dispatcher stops the gate and puts the message to the developer. +An unreadable document is often a document-side cause — `decision-coverage` +exits 1 on a `spec:` naming a missing file, which the auditor's card +makes a fixable hit today — so where the message names such a cause the +session fixes it and re-runs, as it would that hit. Otherwise the +developer installs Python and re-runs, or orders the dispatch anyway, +as they may order any step; that answer holds for the session, since a +deterministic failure would stop every later gate on the document. +Nothing reaches the ledger, and no held class or ledger shape is added. +The README already lists Python 3.9+ as a requirement. + +## Settled for the plan + +Calls made after the integrity audit, as the builder would make them; +none changes what is built: + +- A name is matched to a heading after the `wp-phrase-check` + normalisation, at any heading level; "beside" means in the same + sentence. Fenced blocks are not read. +- A citation token is `path:line` or `path:a-b`, backticked or not; + its path resolves against the document's directory, then the + repository root. A bare file name is skipped whole (D9). +- A `Create:` line is read in the plan under check only, in the shape + the writing-plans template gives it (`- Create: \`path\``). A URL or + `#anchor` link target is not checked. +- In a `license:` or `ruling:` clause the first double-quoted string is + the quote, and the location is the first `path:line`, path or + italicised heading after it; a clause with neither is not checked. +- The scripts re-run before every auditor re-dispatch, since a fix wave + can break what they check. Their gate lines carry the caption + `(document-check)` or `(decision-coverage)` where today's carry the + model. +- At a declined authoring-time offer the scripts' hits are shown to the + developer and written nowhere, since no gate episode runs. +- The developer's order under D8 covers the failing document for the + session and both scripts on it; without the auditor "the dispatch" is + the one the gate guarded, and the relay says Document checks did not + run. +- Table closure finds Parts, Contracts and State by their section + headings and columns by header text, matching cells after stripping + backticks and casefolding. A side holding only `external:` names is + not empty; one holding only parenthesised text is. +- Duty 10's lead-in to its steps survives the card edit. +- The launcher reads its name from the path it was invoked by, before + resolving symlinks. Exit 2 for no Python and for usage alike is + intended: D8 treats every non-zero exit as an error. + +## Verification + +- Unit tests for each Document check against fixtures holding one known defect + and its clean twin, drawn from the measured misses above. +- A run over every spec and plan in `docs/` of this repository and + over two technical designs from other projects. The gate reads only + documents not yet `implemented`, and on those no hit may be false + (D2). Hits on `implemented` documents are listed and classified, not + narrowed away. The first spike of 2026-11-17 found 30 there, 12 of + them real (stale names, stale stamps, moved files) and 18 that a gate + would dismiss; with the integrity stamp dropped and backticked paths + not checked, most of both groups leave the gate's reach. +- The launcher test covers all three commands, and the copies' identity. +- A live gate in this repository with the plugin loaded from the + checkout: the dispatcher runs both scripts before the auditor, and + the relay carries their lines. + +## Out of scope + +Everything under *Non-goals*, and the tier of the auditor itself. + +## Review rounds + +Gate lines from the pre-round propagation episodes, 2026-11-17 (haiku). The first episode held a hit, so they stay here, before the first round heading. + +- hit fixed 2026-11-17 — document type rule omits the `-technical-design.md` arm decision-coverage reads; added it +- hit fixed 2026-11-17 — glossary Decision coverage says "derived by the propagation auditor", which D6 changes; named in *Who runs it* among the surfaces that change +- hit fixed 2026-11-17 — PROCEDURE "the coverage duty's hits alone" goes false under D8; named in *Who runs it* +- hit fixed 2026-11-17 — PROCEDURE "the card writes those lines on every run" goes false under D3/D6; named in *Who runs it* +- hit fixed 2026-11-17 — LEDGER "`hit held` is scoped to the coverage duty's hits" goes false under D8; named in *Who runs it* +- hit fixed 2026-11-17 — normalisation parenthetical omits marker stripping; added it +- hit dismissed 2026-11-17 — bare "check" near a Hit at glossary.md:504, :522, :533 and spec D8; counter: 504 and 522 define the generic noun the ban qualifies, 533 is the term's own definition, and D8's "checking by hand" is a verb, not the noun the ban names +- hit dismissed 2026-11-17 — launcher, propagation gate, dispatcher, table closure, integrity stamp lack glossary entries; counter: duty 5 flags a name the source does not define, and each is defined at its source — spec D4 and the CHANGELOG (launcher), the workflow rule (propagation gate, dispatcher), card duty 11 and the technical-design rule's Declared table relations (table closure), the lifecycle rule (integrity stamp); the glossary is no closed dictionary +- hit dismissed 2026-11-17 — bare `check:` label in the hit-line template; counter: it is the output field's name, a literal the script prints, not prose; settled in grilling question 1 +- hit fixed 2026-11-17 — "Five more sentences" enumerated four; replaced by a general clause plus the full list the gate found +- hit fixed 2026-11-17 — D10's semicolon and parenthesis drop is not in the rule's grammar; the Table closure paragraph now says it reads more loosely on purpose and can add no hit the rule would not +- hit fixed 2026-11-17 — the rule is not "beside the script"; now "in the plugin's rules/ directory beside scripts/" +- hit fixed 2026-11-17 — nine more consumers of the changed arrangement (README ×3, propagation-duties, workflow, LEDGER ×2, integrity-auditor, glossary Hit); *Who runs it* now states the class and lists them, the plan enumerates by grep +- hit fixed 2026-11-17 — the *Who runs it* list missed 14 more sites (PROCEDURE ×2, lifecycle ×2, technical-design rule, plan-adversary card, README ×4, propagation-duties, glossary Audit agent, SETTINGS_REGISTRY, decision-coverage docstring); list replaced by the class, the surfaces it spans, and the plan's grep +- hit fixed 2026-11-17 — the D8 held hit had no reachable terminal shape; D8 now names both closing lines, a ruling-carrying `hit dismissed` being the new shape; ruling: 2026-11-17 +- hit fixed 2026-11-17 — the class in *Who runs it* omitted the gate-line sentences D8 falsifies (LEDGER:240, :253-254, :307, glossary Hit); class widened to "the held kinds and the gate lines' terminal shapes" +- hit fixed 2026-11-17 — D8's `hit fixed … ruling:` misuses the ruling shape, which records a decision the document now carries; install path now the ordinary `hit fixed` without `ruling:`, the dismissal keeps it +- hit fixed 2026-11-17 — "the settings registry" holds no old-arrangement sentence; the areas list is gone +- hit fixed 2026-11-17 — command-set enumerations (marketplace.json, plugin.json, root README) go stale under D1/D5; class now names "every enumeration of the plugin's commands" +- hit fixed 2026-11-17 — the record's "13 more sites" listed 14; corrected +- hit fixed 2026-11-17 — the launcher dismissal cited README and bin/, which do not define it; counter now cites spec D4 and the CHANGELOG +- hit fixed 2026-11-17 — the launcher dismissal's counter said the technical-design rule defines "table closure"; it now cites card duty 11 and the rule's Declared table relations + +### 2026-11-17 — architect, fable 5.2, concerns (round 1, full-document) + +Record: `.claude/working-process/2026-11-17-document-check-spec/architect-round-1.md`. + +- fixed 2026-11-17 — [Important] F1: the `integrity:` stamp check reports a state the rules call expected (stale after a licensed fix wave), so every gate ends in a dismissal; ruling: 2026-11-17; the integrity stamp is dropped from the Document checks and listed as a non-goal; D3 now names three checks +- fixed 2026-11-17 — [Important] F2: D10 leaves a name matching no Parts row unchecked while D3 takes duty 11 off the auditor, so dangling names have no owner; ruling: 2026-11-17; duty 11 stays the auditor's for the segments the script reports not checked; D3, D12 and the Table closure paragraph say so +- fixed 2026-11-17 — [Important] F3: running the scripts beside the auditor makes it read a document the script fixes then change, spending the episode's re-dispatches; ruling: 2026-11-17; D6 runs both scripts first, disposes of their hits outside the episode bound, then dispatches the auditor; *Who runs it* argues the order +- fixed 2026-11-17 — [Important] F4: D8 writes one checkout's missing interpreter into a document's ledger as a held hit with a new shape; ruling: 2026-11-17; D8 now makes a script that cannot run an ordinary error the developer decides, with nothing in the ledger, reversing the 2026-11-17 ruling's ledger shapes +- fixed 2026-11-17 — [Important] F5: on plans, backticked convention paths and placeholders make hits the author must dismiss, against D2; ruling: 2026-11-17; D9 leaves a missing backticked path not checked on every document; Named documents checks links only +- fixed 2026-11-17 — [Minor] F6: Goal 1 promised the class where D2 delivers the forms a parse settles; license: D2; Goal 1 now says "a defect of a form the Document checks settle" +- fixed 2026-11-17 — [Minor] F7: D11 runs the scripts "at the authoring-time offer", an offer that may be declined; ruling: 2026-11-17; D11 and *Who runs it* say the scripts run at the authoring-time offer whether or not it is accepted +- fixed 2026-11-17 — [Minor] F7: D11 did not say gate lines, the held batch and the bound apply without the auditor; license: D11; D11 now says so +- fixed 2026-11-17 — [Minor] F8: the card keeps duties 10 and 11 as instructions and duty 11 stricter than D10; license: D10 and D12; D12 now has each duty's first line say the auditor does not perform it and duty 11 state what D10 checks +- fixed 2026-11-17 — [Minor] F9: the glossary's Decision coverage map was "derived by the propagation auditor", false under D6; license: D6; the entry now names `wp-decision-coverage` run by the dispatcher +- signal 2026-11-17 — F1–F5 need rulings; one diff-scoped round after them earns its cost, a third is unlikely to repay itself + +Gate lines from the episode before round 2, 2026-11-17 (haiku): + +- hit fixed 2026-11-17 — the F2 line says D3 names the owner of the unsettled table-closure segments, and D3 did not; D3 now does +- hit dismissed 2026-11-17 — ledger lines (the episode-2 class widening, F8's "each duty's first line", the "checking by hand" counter) describe text later waves replaced; counter: a ledger line records the document as that wave left it, and the F2 and F4 rulings later in the same round superseded those words +- hit dismissed 2026-11-17 — the round-1 record's line citations (spec, PROCEDURE, glossary:597) and its size match no committed state; counter: the record is the reviewer's verbatim report against the working copy it read, which the round's own fixes then moved, and its size was measured on that copy +- hit dismissed 2026-11-17 — bare "check" beside a hit at propagation-auditor.md:181 and :350; counter: the ban predates this change (minted with **Verification check**), the lines are shipped card text this spec does not reach, and the plan's sweep of the card under D12 can take them +- hit dismissed 2026-11-17 — launcher, integrity stamp, propagation gate, dispatcher, table closure lack glossary entries; counter: re-raised without new evidence against the dismissal of the first pre-round episode +- hit fixed 2026-11-17 — "Generalising it costs one line", while the launcher names its script on two lines (path and error message); now "two lines" +- hit dismissed 2026-11-17 — six round-1 record citations are off by two to seven lines (spec 255-258, 206-208, 299-300; PROCEDURE 351, 360-361; glossary 597); counter: the record is the reviewer's report copied verbatim and never corrected; the reviewed working copy was the parent commit plus the grilling's uncommitted edits (the glossary's new entry put 587 at 597), and the off-by-two citations are the reviewer's own; the relay checked each against the files and triage acted on the located text +- hit fixed 2026-11-17 — the glossary's Document check entry ran table closure on all three classes, against D3; it now says a technical design alone +- hit fixed 2026-11-17 — "package 4" names a queue item scoped to technical designs while D1 covers three classes; the opening now says the package was widened +- hit dismissed 2026-11-17 — bare "check" at propagation-auditor.md:215 beside a hit, and the earlier counter's :350, which reads "checks"; counter: as for :181, a ban older than this change on shipped card text the plan's card sweep takes; :350 was cited in error and needs nothing +- hit dismissed 2026-11-17 — the ledger's round-1 block carries two F7 lines for one finding; counter: F7 was split, one half held and ruled, the other fixed by license, so it takes one line per disposition +- hit dismissed 2026-11-17 — re-raises of the `check:` field name, the round-1 record's citations and size, the historical ledger lines, and the glossary gaps; counter: each is disposed earlier in this ledger and the run brings no new evidence + +### 2026-11-17 — architect, fable 5.2, concerns (round 2, diff-scoped) + +Record: `.claude/working-process/2026-11-17-document-check-spec/architect-round-2.md`. Ordered by the developer after the gate episode before it spent its re-dispatches. + +- fixed 2026-11-17 — [Important] F1: D8's "any exit other than 0" makes a document-side failure (a `spec:` naming a missing file, which `decision-coverage` exits 1 on) an environment error, regressing what the shipped card makes a fixable hit; ruling: 2026-11-17; D8 and *Who runs it* let the session fix a document-side cause the message names and re-run; otherwise the developer decides +- fixed 2026-11-17 — [Minor] F2: how long the developer's "order the dispatch without Document checks" stands is unsaid, and a deterministic crash stops every later gate; ruling: 2026-11-17; D8 says the developer's order to dispatch without Document checks holds for the session +- fixed 2026-11-17 — [Minor] F3: the script loop listed only fixed and dismissed, and D11 applied an episode bound that counts nothing without the auditor; license: the procedure's held exception for coverage hits; D6 adds "or held, which ends the episode", D11 says script re-runs are unbounded on purpose +- fixed 2026-11-17 — [Minor] F4: duty 11's remainder was defined by script output the auditor never sees; license: the card's own "a name matching no row"; D12 and *Table closure* now name the form +- fixed 2026-11-17 — [Minor] F5: D9's exemption caught a backticked `path:line`; license: *Named documents* limits it to `.md` paths; D9 now says "a backticked path carrying no line" +- fixed 2026-11-17 — [Minor] F6: *Named documents* now reads only Markdown links — 0 in the 8 live documents — and catches neither measured miss; ruling: 2026-11-17; *Named documents* is dropped as a Document check; D3 names two checks and Citations resolves link targets by D9 +- fixed 2026-11-17 — [Minor] F7: "about 30 of the 70" predates dropping the stamp and backticked paths; license: the spec's own Verification; Problem says "belonged", Constraints says the script covers fewer than the 30 +- fixed 2026-11-17 — [Minor] F8: the glossary's Hit entry omitted `wp-decision-coverage` as a hit source after D6; license: D6; the entry now lists it +- signal 2026-11-17 — a third round is unlikely to earn its cost; F1 needs a ruling, F2–F8 are clause-level, and the joint integrity audit at the consumption gate reads the whole body + +Round 2's `concerns` is resolved without a further round: the developer settled F1, F2 and F6 on 2026-11-17, the licensed Minor fixes landed, and the reviewer's stop signal judged a third round unlikely to repay itself; the integrity audit at the consumption gate reads the whole document. + + +Gate lines from the episode before the integrity audit, 2026-11-17 (haiku): + +- hit dismissed 2026-11-17 — the glossary states in the present tense that `wp-document-check` and `wp-decision-coverage` run, and neither has shipped; counter: the glossary edits ride on this package's branch and merge with the implementation, so no shipped state ever carries one without the other +- hit dismissed 2026-11-17 — the shipped sites carrying the old invocation and output claim (README, PROCEDURE, the card) are not named; counter: *Who runs it* defers their enumeration to the plan's grep by design, after three runs found a named list stale +- hit dismissed 2026-11-17 — launcher, dispatcher, table closure, episode, integrity stamp, propagation gate and held batch lack glossary entries; counter: re-raised without new evidence against the pre-round dismissal +- hit dismissed 2026-11-17 — the round-2 record's spec citations no longer carry the text they quote; counter: the record is the reviewer's verbatim report on the copy it read, which the round's own fixes then moved From 03a763389c13379d54b5137eaba77d31a3c7ce1e Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 17 Nov 2026 14:09:37 +0100 Subject: [PATCH 44/59] docs(working-process): document-check plan --- docs/plans/2026-11-17-document-check-plan.md | 314 +++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 docs/plans/2026-11-17-document-check-plan.md 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..ae815e9 --- /dev/null +++ b/docs/plans/2026-11-17-document-check-plan.md @@ -0,0 +1,314 @@ +--- +ticket: none +date: 2026-11-17 +status: approved +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 `