kaizen-agent 1.7.1 → 1.7.2

package/skills/kaizen/spec-build.md

@@ -1,119 +1,119 @@
-# Kaizen — implement stage
-
-Read with [`spec.md`](spec.md) (core: track, intake, resume). This file is the
-builder's contract. The planner and reviewer do not read it.
-
----
-## Stage 2 — Implement
-
-**Agent:** builder. **Input:** `01-plan.md`, `02-approval.md`, the track.
-**Output:** the deliverable itself, plus `03-impl.md`.
-
-The builder produces whatever the track's deliverable is — code, a chapter, the
-campaign copy, the runbook — and nothing else.
-
-This file is the contract whether the builder is a dispatched agent or the main
-thread working inline (see `build.executor`). Working inline changes who is typing,
-not what is owed: the plan is still the scope, a step that turns out wrong still
-stops the stage instead of being improvised around, and `03-impl.md` is still written
-before the reviewer is called. The temptation inline is to skip the file because the
-work is already visible in the conversation — but the reviewer never sees that
-conversation, and reads the file instead.
-
-Rules:
-
-- Work only within the plan's scope. Something out of scope that clearly needs doing
-  is written to `03-impl.md` as a note, not produced.
-- If a step turns out to be impossible or wrong, stop and report. Do not improvise a
-  different approach — that silently discards the approval the plan received.
-- Match what is already there: a codebase's conventions and idioms, a manuscript's
-  voice and structure, a brand's tone. New work should be indistinguishable in style
-  from the surrounding material.
-- Carry out the plan's verification and record the real result, whatever the track's
-  verification is.
-- Every technique the plan's `reason`-tier gate covers — a new dependency, a new
-  abstraction, a new file, a new section — is allowed, and costs one written line
-  saying what it serves. The line is the price of the technique, not a request for
-  permission. No line means the reviewer records a finding.
-- The `git.*` settings apply only where the work sits in a git repository. In a plain
-  folder there is no branch to make and no commit to skip, and that absence is not a
-  finding.
-
-**Baseline first, in any track with an existing suite of checks.** Before changing
-anything, run whatever already proves the existing material correct — the test suite,
-the linter, the link checker, the fact-check pass — and record the result in
-`03-impl.md`. Run it again after. Two results, before and after, are what turn "my
-change works" into "nothing else broke". A check already failing before the change is
-not this run's finding; a check that passed before and fails after is, and it stops
-the stage.
-
-**Keep the working transcript small.** Everything the builder reads stays in its
-context and is re-read on every request that follows, so a full test-suite dump at the
-start of the stage is paid for again at every step after it. Pipe long output through
-a filter that keeps the decisive lines — the failure count, the failing test names, the
-first error — and read the full output only when a check actually fails. The same holds
-for reading material: open the manifest's paths at the ranges the plan names, not whole
-files, and never re-read a file this stage already changed. `03-impl.md` records the
-result, not the transcript.
-
-**Read the plan's File manifest instead of searching.** The planner already located
-every path this run touches. Search the material only for what the manifest does not
-cover, and note in `03-impl.md` what was missing from it.
-
-`03-impl.md` must list: what was produced or changed with a one-line reason each,
-deviations from the plan and why, verification carried out with its actual result,
-and anything deliberately left undone. Report failures honestly; a false claim of
-success poisons the review stage, which trusts this report.
-
-**A `## Preview` section says how to see the result.** For an app or service: the
-commands to start it locally and the URL to open, copied from the material's own README
-where one exists. For anything else — a document, copy, a runbook, a memo — the path
-to open, or the result itself when it fits in a screen. The board shows this section on
-the run's card, so a person can try the work without reading the rest of the report.
-
-**The gate block closes the stage.** `03-impl.md` ends with one line per gate item
-from the plan's Verification section:
-
-```
-G-01 PASS: ran `php artisan test --filter=Payroll` — 214 passed, 0 failed
-G-02 PASS: cash→transfer switch exercised in the UI; bank rows validated, 422 gone
-G-03 FAIL: payslip PDF still prints the old label
-```
-
-A `PASS` states what was actually done and what came back — the command and its
-output, the page opened and what appeared, the person who read it and what they
-understood. `PASS` on its own is not a result, and neither is a restatement of the
-gate item; both are read as an admission the check did not happen.
-
-**Work that was never executed cannot pass.** In any track where the deliverable can
-be run, opened, or read by someone, doing so is part of building it: the suite run,
-the page opened and clicked, the runbook walked start to finish, the copy read aloud.
-A gate item whose evidence is an argument that the code should work is a `FAIL`.
-
-The stage does not hand off with a `FAIL` standing. Fix it and re-run the gate, or —
-if it cannot be fixed inside the plan's scope — stop and report, exactly as with an
-impossible step. A `FAIL` carried into review wastes the reviewer's pass on something
-already known to be broken.
-
-## Stage 4 — Fix loop
-
-Governed by `auto_fix`. See the skill's fix-loop section for the exact behavior.
-
-Each iteration writes `05-iterations/NN-fix.md` (what the builder changed) and
-`NN-recheck.md` (what the reviewer found afterward). The loop ends when the reviewer
-reports nothing at or above the threshold, or `max_iterations` is reached.
-
-A finding the loop could not close is escalated to the user with the reviewer's
-description intact — never quietly downgraded to make the run look clean.
-
-**An iteration reads the finding, the work, and the gate.** Not the plan. Fixing a
-named defect needs the reviewer's line, the diff so far, and the gate the result must
-still pass; it does not need the framing, the alternatives rejected, or the out-of-scope
-list, all of which were settled before the finding existed. Read `01-plan.md` only when
-a finding turns on what was approved — a scope question, or a fix that would take the
-work outside it.
-
-Fix what the finding names and stop. A second defect noticed while fixing the first is
-a note in the iteration file, not a second fix: it has not been reviewed, and the
-recheck is scoped to what the iteration claims to have changed.
-
+# Kaizen — implement stage
+
+Read with [`spec.md`](spec.md) (core: track, intake, resume). This file is the
+builder's contract. The planner and reviewer do not read it.
+
+---
+## Stage 2 — Implement
+
+**Agent:** builder. **Input:** `01-plan.md`, `02-approval.md`, the track.
+**Output:** the deliverable itself, plus `03-impl.md`.
+
+The builder produces whatever the track's deliverable is — code, a chapter, the
+campaign copy, the runbook — and nothing else.
+
+This file is the contract whether the builder is a dispatched agent or the main
+thread working inline (see `build.executor`). Working inline changes who is typing,
+not what is owed: the plan is still the scope, a step that turns out wrong still
+stops the stage instead of being improvised around, and `03-impl.md` is still written
+before the reviewer is called. The temptation inline is to skip the file because the
+work is already visible in the conversation — but the reviewer never sees that
+conversation, and reads the file instead.
+
+Rules:
+
+- Work only within the plan's scope. Something out of scope that clearly needs doing
+  is written to `03-impl.md` as a note, not produced.
+- If a step turns out to be impossible or wrong, stop and report. Do not improvise a
+  different approach — that silently discards the approval the plan received.
+- Match what is already there: a codebase's conventions and idioms, a manuscript's
+  voice and structure, a brand's tone. New work should be indistinguishable in style
+  from the surrounding material.
+- Carry out the plan's verification and record the real result, whatever the track's
+  verification is.
+- Every technique the plan's `reason`-tier gate covers — a new dependency, a new
+  abstraction, a new file, a new section — is allowed, and costs one written line
+  saying what it serves. The line is the price of the technique, not a request for
+  permission. No line means the reviewer records a finding.
+- The `git.*` settings apply only where the work sits in a git repository. In a plain
+  folder there is no branch to make and no commit to skip, and that absence is not a
+  finding.
+
+**Baseline first, in any track with an existing suite of checks.** Before changing
+anything, run whatever already proves the existing material correct — the test suite,
+the linter, the link checker, the fact-check pass — and record the result in
+`03-impl.md`. Run it again after. Two results, before and after, are what turn "my
+change works" into "nothing else broke". A check already failing before the change is
+not this run's finding; a check that passed before and fails after is, and it stops
+the stage.
+
+**Keep the working transcript small.** Everything the builder reads stays in its
+context and is re-read on every request that follows, so a full test-suite dump at the
+start of the stage is paid for again at every step after it. Pipe long output through
+a filter that keeps the decisive lines — the failure count, the failing test names, the
+first error — and read the full output only when a check actually fails. The same holds
+for reading material: open the manifest's paths at the ranges the plan names, not whole
+files, and never re-read a file this stage already changed. `03-impl.md` records the
+result, not the transcript.
+
+**Read the plan's File manifest instead of searching.** The planner already located
+every path this run touches. Search the material only for what the manifest does not
+cover, and note in `03-impl.md` what was missing from it.
+
+`03-impl.md` must list: what was produced or changed with a one-line reason each,
+deviations from the plan and why, verification carried out with its actual result,
+and anything deliberately left undone. Report failures honestly; a false claim of
+success poisons the review stage, which trusts this report.
+
+**A `## Preview` section says how to see the result.** For an app or service: the
+commands to start it locally and the URL to open, copied from the material's own README
+where one exists. For anything else — a document, copy, a runbook, a memo — the path
+to open, or the result itself when it fits in a screen. The board shows this section on
+the run's card, so a person can try the work without reading the rest of the report.
+
+**The gate block closes the stage.** `03-impl.md` ends with one line per gate item
+from the plan's Verification section:
+
+```
+G-01 PASS: ran `php artisan test --filter=Payroll` — 214 passed, 0 failed
+G-02 PASS: cash→transfer switch exercised in the UI; bank rows validated, 422 gone
+G-03 FAIL: payslip PDF still prints the old label
+```
+
+A `PASS` states what was actually done and what came back — the command and its
+output, the page opened and what appeared, the person who read it and what they
+understood. `PASS` on its own is not a result, and neither is a restatement of the
+gate item; both are read as an admission the check did not happen.
+
+**Work that was never executed cannot pass.** In any track where the deliverable can
+be run, opened, or read by someone, doing so is part of building it: the suite run,
+the page opened and clicked, the runbook walked start to finish, the copy read aloud.
+A gate item whose evidence is an argument that the code should work is a `FAIL`.
+
+The stage does not hand off with a `FAIL` standing. Fix it and re-run the gate, or —
+if it cannot be fixed inside the plan's scope — stop and report, exactly as with an
+impossible step. A `FAIL` carried into review wastes the reviewer's pass on something
+already known to be broken.
+
+## Stage 4 — Fix loop
+
+Governed by `auto_fix`. See the skill's fix-loop section for the exact behavior.
+
+Each iteration writes `05-iterations/NN-fix.md` (what the builder changed) and
+`NN-recheck.md` (what the reviewer found afterward). The loop ends when the reviewer
+reports nothing at or above the threshold, or `max_iterations` is reached.
+
+A finding the loop could not close is escalated to the user with the reviewer's
+description intact — never quietly downgraded to make the run look clean.
+
+**An iteration reads the finding, the work, and the gate.** Not the plan. Fixing a
+named defect needs the reviewer's line, the diff so far, and the gate the result must
+still pass; it does not need the framing, the alternatives rejected, or the out-of-scope
+list, all of which were settled before the finding existed. Read `01-plan.md` only when
+a finding turns on what was approved — a scope question, or a fix that would take the
+work outside it.
+
+Fix what the finding names and stop. A second defect noticed while fixing the first is
+a note in the iteration file, not a second fix: it has not been reviewed, and the
+recheck is scoped to what the iteration claims to have changed.
+

package/skills/kaizen/spec-main.md

@@ -1,104 +1,104 @@
-# Kaizen — main thread
-
-Read with [`spec.md`](spec.md) (core: track, intake, resume). Backlog bookkeeping and
-the final approval. No subagent reads this file.
-
----
-## Backlog
-
-Every run produces work it deliberately does not do. Three sources, all already
-written down by the time a run ends:
-
-1. Out of scope suggestions the planner listed and the user did not fold into the
-   approved scope.
-2. Findings below `auto_fix.min_severity`, and findings the fix loop could not close.
-3. Debts deferred at an approval because they fell outside the approved scope.
-
-Without capture these survive only in the conversation that produced them.
-
-`backlog.enabled: false` skips both capture points — the `02-approval.md` append at
-plan approval and the `06-backlog.md` append at final approval — for that run. The run
-still executes normally; it simply ends without a backlog file.
-
-**Where it lives.** Each run holds its own backlog at `runs/<id>/06-backlog.md`, beside
-the plan and the review that produced the items. There is no central backlog file to
-keep in sync, and no copying: provenance is the directory the item sits in.
-
-`<state.dir>/backlog.md`, beside `memory.md`, exists for exactly one purpose — an
-orphanage. Before `state.keep_runs` prunes a run directory, that run's **open** items
-are moved into it, so pruning never destroys outstanding work. Items already `done` or
-`rejected` are pruned with their run. Nothing else is ever written there, and
-`06-backlog.md` is never replaced by it.
-
-`/kaizen backlog` reads `<state.dir>/backlog.md` as well as every
-`runs/*/06-backlog.md`, and prints its open items last, under an **Orphaned** group —
-otherwise a rescued item would be invisible to the only command that lists outstanding
-work. Orphaned items count towards the open backlog count `/kaizen status` reports.
-
-An abandoned run — `stage: "abandoned"`, set by `/kaizen abort` — is not open work. Its
-`06-backlog.md` is left as it stands, and its items are neither printed by `/kaizen
-backlog` nor counted.
-
-**Item format.** One item per line:
-
-```
-- <status>: <item text> | <reason>
-```
-
-`<status>` is `open`, `done`, or `rejected`. A finding moved into the backlog keeps the
-reviewer's line verbatim — `<where>: <severity>: <problem>. <fix>.` — so nothing is
-rewritten in transit. `rejected` requires a reason after `|` on the same line; "not
-doing this" with no reason is how the same suggestion returns three runs later. `done`
-may carry a reason the same way, and usually names the run that closed it.
-
-Items are appended, never deleted. Closing an item means editing its status in place;
-it stays in its run's file as record. `/kaizen backlog` prints `open` items only, so
-the active list is bounded by what is genuinely outstanding rather than by history.
-
-Because a `<where>` reference must still resolve after its run closes, it is written as
-a path relative to the repository, not to the run directory.
-
-**Who writes it.** The main thread, at two file writes that already happen
-unconditionally:
-
-| Capture point | Stage | What gets appended |
-|---|---|---|
-| Writing `02-approval.md`, when the decision is an approval | Plan approval | Every out-of-scope suggestion not folded into the approved scope, and anything cut from scope at the approval |
-| Setting `stage: "done"` | Final approval | Findings still open, findings below the fix threshold, and out-of-scope notes the builder wrote into `03-impl.md` |
-
-Neither is optional and neither is a separate step to remember — a run cannot finish
-without touching both files.
-
-No subagent writes the backlog. The reviewer runs *before* the fix loop and cannot know
-which of its findings will be closed; it would log items that get fixed minutes later.
-The planner is not present at the approval where its suggestions are accepted or
-declined. This also keeps the workflow working under adapters where there are no
-subagents at all.
-
----
-
-## Final approval
-
-Controlled by `approvals.review`, skipped in `auto`.
-
-Report: what was built, verification results, findings fixed, findings still open,
-and anything the builder noted as out of scope. Where the run used `runner: lite`, say
-so in that report — the reviewer saw the work, and nobody should read a same-session
-review as an independent one because the output looked the same. Then stop. Committing, pushing, or
-opening a pull request happens only if the user asks.
-
-**Open findings are offered by number.** List them with the reviewer's numbering
-intact and let the user name which to fix — "fix 2 and 5". A number not named is not
-touched, and goes to the backlog as `open` like any other deferred item. This is the
-same granularity the fix loop already works at; the only change is that the user
-picks the subset instead of accepting or declining the whole review.
-
-Before setting `stage: "done"`, append the same three categories just reported —
-findings still open, findings below the fix threshold, and the builder's out-of-scope
-notes from `03-impl.md` — to `runs/<id>/06-backlog.md`, each as `open`, in the format
-given in *Backlog* above. Every input is already assembled at this moment; the only
-change is that it is written down rather than spoken and discarded.
-
-Set `stage: "done"` in `state.json` once the user accepts.
-
----
+# Kaizen — main thread
+
+Read with [`spec.md`](spec.md) (core: track, intake, resume). Backlog bookkeeping and
+the final approval. No subagent reads this file.
+
+---
+## Backlog
+
+Every run produces work it deliberately does not do. Three sources, all already
+written down by the time a run ends:
+
+1. Out of scope suggestions the planner listed and the user did not fold into the
+   approved scope.
+2. Findings below `auto_fix.min_severity`, and findings the fix loop could not close.
+3. Debts deferred at an approval because they fell outside the approved scope.
+
+Without capture these survive only in the conversation that produced them.
+
+`backlog.enabled: false` skips both capture points — the `02-approval.md` append at
+plan approval and the `06-backlog.md` append at final approval — for that run. The run
+still executes normally; it simply ends without a backlog file.
+
+**Where it lives.** Each run holds its own backlog at `runs/<id>/06-backlog.md`, beside
+the plan and the review that produced the items. There is no central backlog file to
+keep in sync, and no copying: provenance is the directory the item sits in.
+
+`<state.dir>/backlog.md`, beside `memory.md`, exists for exactly one purpose — an
+orphanage. Before `state.keep_runs` prunes a run directory, that run's **open** items
+are moved into it, so pruning never destroys outstanding work. Items already `done` or
+`rejected` are pruned with their run. Nothing else is ever written there, and
+`06-backlog.md` is never replaced by it.
+
+`/kaizen backlog` reads `<state.dir>/backlog.md` as well as every
+`runs/*/06-backlog.md`, and prints its open items last, under an **Orphaned** group —
+otherwise a rescued item would be invisible to the only command that lists outstanding
+work. Orphaned items count towards the open backlog count `/kaizen status` reports.
+
+An abandoned run — `stage: "abandoned"`, set by `/kaizen abort` — is not open work. Its
+`06-backlog.md` is left as it stands, and its items are neither printed by `/kaizen
+backlog` nor counted.
+
+**Item format.** One item per line:
+
+```
+- <status>: <item text> | <reason>
+```
+
+`<status>` is `open`, `done`, or `rejected`. A finding moved into the backlog keeps the
+reviewer's line verbatim — `<where>: <severity>: <problem>. <fix>.` — so nothing is
+rewritten in transit. `rejected` requires a reason after `|` on the same line; "not
+doing this" with no reason is how the same suggestion returns three runs later. `done`
+may carry a reason the same way, and usually names the run that closed it.
+
+Items are appended, never deleted. Closing an item means editing its status in place;
+it stays in its run's file as record. `/kaizen backlog` prints `open` items only, so
+the active list is bounded by what is genuinely outstanding rather than by history.
+
+Because a `<where>` reference must still resolve after its run closes, it is written as
+a path relative to the repository, not to the run directory.
+
+**Who writes it.** The main thread, at two file writes that already happen
+unconditionally:
+
+| Capture point | Stage | What gets appended |
+|---|---|---|
+| Writing `02-approval.md`, when the decision is an approval | Plan approval | Every out-of-scope suggestion not folded into the approved scope, and anything cut from scope at the approval |
+| Setting `stage: "done"` | Final approval | Findings still open, findings below the fix threshold, and out-of-scope notes the builder wrote into `03-impl.md` |
+
+Neither is optional and neither is a separate step to remember — a run cannot finish
+without touching both files.
+
+No subagent writes the backlog. The reviewer runs *before* the fix loop and cannot know
+which of its findings will be closed; it would log items that get fixed minutes later.
+The planner is not present at the approval where its suggestions are accepted or
+declined. This also keeps the workflow working under adapters where there are no
+subagents at all.
+
+---
+
+## Final approval
+
+Controlled by `approvals.review`, skipped in `auto`.
+
+Report: what was built, verification results, findings fixed, findings still open,
+and anything the builder noted as out of scope. Where the run used `runner: lite`, say
+so in that report — the reviewer saw the work, and nobody should read a same-session
+review as an independent one because the output looked the same. Then stop. Committing, pushing, or
+opening a pull request happens only if the user asks.
+
+**Open findings are offered by number.** List them with the reviewer's numbering
+intact and let the user name which to fix — "fix 2 and 5". A number not named is not
+touched, and goes to the backlog as `open` like any other deferred item. This is the
+same granularity the fix loop already works at; the only change is that the user
+picks the subset instead of accepting or declining the whole review.
+
+Before setting `stage: "done"`, append the same three categories just reported —
+findings still open, findings below the fix threshold, and the builder's out-of-scope
+notes from `03-impl.md` — to `runs/<id>/06-backlog.md`, each as `open`, in the format
+given in *Backlog* above. Every input is already assembled at this moment; the only
+change is that it is written down rather than spoken and discarded.
+
+Set `stage: "done"` in `state.json` once the user accepts.
+
+---