kaizen-agent 0.1.0

package/skills/kaizen/adapters.md

@@ -0,0 +1,76 @@
+# Adapters — running kaizen outside Claude Code
+
+`spec.md` plus its per-stage files (`spec-plan.md`, `spec-build.md`, `spec-review.md`,
+`spec-main.md`) are the workflow. It does not mention any vendor, and it is the single
+source of truth. An adapter is a thin file that points a given tool at it and
+describes how that tool dispatches stages. Adapters never restate the stage rules;
+duplicating them is how the tools drift apart.
+
+The portability comes from `.kaizen/` being plain files in the repository. Any tool
+that can read a directory can resume a run another tool started.
+
+## Claude Code
+
+Native. The skill in this directory dispatches each stage through the Agent tool
+using the `kaizen-planner`, `kaizen-builder`, and `kaizen-reviewer` agent
+definitions, and the main thread owns `state.json`.
+
+## Codex — `AGENTS.md`
+
+Codex reads `AGENTS.md` from the repository root. Append:
+
+```markdown
+## Kaizen workflow
+
+Non-trivial work in this repo follows the staged workflow in
+`.kaizen/spec.md`: plan, human approval, implement, independent review, bounded
+fix loop. Read that file before starting, and read `.kaizen/config.yml` for the
+mode and approval settings.
+
+Run state lives in `.kaizen/runs/<id>/`. Always read `state.json` first and
+continue from the stage it names. Never advance a run whose `awaiting` field is
+non-null without a recorded human decision in `02-approval.md` — another tool or
+session may be mid-run.
+
+Codex has no separate subagents, so run the stages sequentially in one session,
+but keep them clean: start each stage by reading only that stage's declared inputs
+from its stage file, and write its artifact before moving on. When reviewing, judge the
+diff on its own terms rather than defending the reasoning you used while writing it.
+```
+
+Copy `spec*.md` and `config.yml` into `.kaizen/` so the reference resolves
+without this skill installed.
+
+## Antigravity
+
+Antigravity reads `AGENTS.md` as well; use the same block. If a workspace-level rules
+file is configured instead, point it at `.kaizen/spec.md` and the stage file being run with the same three
+paragraphs.
+
+Where Antigravity can run parallel agents, map planner, builder, and reviewer onto
+separate agents exactly as Claude Code does — the independent reviewer context is the
+part worth preserving in any port.
+
+## Handing a run between tools
+
+Nothing special is required. Because every stage's input and output are files:
+
+1. Tool A finishes a stage and updates `state.json`.
+2. Tool B opens the repo, reads `state.json`, sees `stage: "review"` and
+   `awaiting: null`, and runs the reviewer.
+
+The only rule is that whichever tool holds the run updates `state.json` when a stage
+completes. A stale `state.json` is the one way this breaks.
+
+## Installing the adapter files
+
+`/kaizen init` writes `.kaizen/` with the `spec*.md` files, `config.yml`, and the gitignore
+entry. `/kaizen install` additionally offers to append the `AGENTS.md` block above.
+`.kaizen/spec*.md` and `.kaizen/config.yml` should be committed even though run state
+is ignored — the workflow is shared, the run data is not:
+
+```gitignore
+.kaizen/*
+!.kaizen/spec*.md
+!.kaizen/config.yml
+```

package/skills/kaizen/config.default.yml

@@ -0,0 +1,82 @@
+# Kaizen defaults. Copy to .kaizen/config.yml in a repository and override only the
+# keys you care about; anything absent falls back to this file.
+
+# plan-only | approve | auto | review-only
+mode: approve
+
+approvals:
+  # Stop after the plan, before any code is written.
+  plan: true
+  # Stop after the review, before the work is called done. Off by default: when
+  # auto_fix has already closed the findings at or above its threshold, this second
+  # stop mostly asks the user to approve a report they are about to read anyway.
+  review: false
+  # Confirm every individual file edit. Maximum control, slowest.
+  each_file: false
+
+auto_fix:
+  # false: every finding stops the run and becomes a user decision.
+  # true:  findings at or above min_severity are fixed and re-reviewed automatically.
+  enabled: true
+  # critical | high | medium | low
+  min_severity: high
+  # Fix/recheck rounds before remaining findings are escalated to the user. Each round
+  # is a full builder pass plus a full reviewer pass, so this is the most expensive
+  # knob in the file. A third round rarely closes what two could not.
+  max_iterations: 2
+
+track:
+  # The kind of work a run is doing, which decides what "deliverable",
+  # "verification", and "finding" mean for every stage. It is INFERRED from the
+  # request by the planner and stated back in the plan's Framing for the user to
+  # correct at the approval — the user is never asked to categorize their own request.
+  # Set this only to pin a default for a repo that is always one kind of work
+  # (e.g. a docs repo). Leave empty to infer per run.
+  default: ""
+
+review:
+  # Checks that run in every track.
+  checks:
+    - correctness
+    - plan_conformance
+  # Additional checks per track, chosen by what the run actually is. The planner may
+  # name a track not listed here; the reviewer then derives its checks from the
+  # track's "what would make it wrong".
+  track_checks:
+    software: [security, reuse_simplification, test_coverage]
+    # blast_radius and regression are universal — see spec-review.md — not listed here.
+    writing: [completeness, claim_accuracy, reader_usability]
+    communication: [claim_accuracy, audience_fit, voice_consistency]
+    operations: [prerequisites, rollback, executability]
+    research: [evidence_support, selection_bias, alternatives]
+  # Let the reviewer append durable lessons to .kaizen/memory.md.
+  write_memory: true
+  # Every stage of every future run reads memory.md, so cap it. Over this, the reviewer
+  # prunes stale or superseded lessons before appending rather than growing the file.
+  memory_max_lines: 100
+
+backlog:
+  # Capture what a run deliberately did not do: out-of-scope suggestions the user did
+  # not take, findings below the fix threshold, and debts deferred at an approval.
+  # Written by the main thread at the plan approval and again at the final approval.
+  enabled: true
+  # Per run, beside its plan and review — provenance without a central file to sync.
+  file: 06-backlog.md
+  # Items are open | done | rejected. Only open ones are printed by /kaizen backlog;
+  # closed ones stay in their run's file as record.
+  statuses: [open, done, rejected]
+  # Before state.keep_runs prunes a run, its still-open items move here, relative to
+  # state.dir. Done and rejected items are pruned with the run.
+  orphan_file: backlog.md
+
+state:
+  dir: .kaizen
+  # Keep this many completed runs before pruning the oldest. Pruning first rescues
+  # open backlog items into backlog.orphan_file, so it never destroys open work.
+  keep_runs: 20
+
+git:
+  # Never commit, push, or open a PR unless the user explicitly asks.
+  auto_commit: false
+  # Create a branch before the implement stage when on the default branch.
+  branch_before_implement: true

package/skills/kaizen/spec-build.md

@@ -0,0 +1,80 @@
+# 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. 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.
+
+**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.
+
+**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.
+
+**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.
+

package/skills/kaizen/spec-main.md

@@ -0,0 +1,102 @@
+# 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. 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.
+
+---

package/skills/kaizen/spec-plan.md

@@ -0,0 +1,141 @@
+# Kaizen — plan stage
+
+Read with [`spec.md`](spec.md) (core: track, intake, resume). This file is the
+planner's and the plan approval's contract. The builder and reviewer do not read it.
+
+---
+## Stage 1 — Plan
+
+**Agent:** planner. **Input:** `00-request.md` (including the track), `memory.md`, and
+the existing material — the codebase, the manuscript, the current campaign, whatever
+this run builds on. **Output:** `01-plan.md`.
+
+The request is usually one sentence. The planner's first job is to expand it — but by
+proposing, not by interrogating. It restates the problem, brings the nearest good
+solution, and names the assumptions it took, so the user reacts to something concrete
+instead of answering a questionnaire. Correcting a proposal costs a sentence;
+answering five questions costs the user the work they came with.
+
+The planner has an opinion: it says which approach it would take and why, and says
+plainly when the request as stated will not achieve what the user evidently wants. It
+asks outright only when a proposal is genuinely impossible — two readings, materially
+different work behind each, nothing available to break the tie — and even then brings
+its recommendation with the question. Questions the existing material can answer are
+never asked; that is the planner's own work.
+
+The goals stay the user's. The planner may propose a better solution to what was
+asked, or argue that the request as stated will not achieve what the user wants, but
+it may not widen the goal on its own. Anything beyond the request goes in *Out of
+scope suggestions* for a separate decision.
+
+The planner reads code but writes none. Its plan must contain:
+
+0. **Framing** — the problem in the planner's own words: what is wrong now, what
+   would be true instead, why it matters, the approach chosen, and the alternatives
+   rejected with a reason each. The human checks this first; a wrong restatement
+   makes everything after it wrong.
+1. **Goal** — one paragraph, in the user's terms, on what will be true when done.
+2. **Scope** — what is included, and an explicit *not included* list. The second list
+   is what prevents the builder from wandering.
+3. **Existing material to reuse** — concrete references: `path:line` for code, section
+   or page for a document, the existing asset for anything else. A plan that proposes
+   building something that already exists is a failed plan, in any track.
+4. **File manifest** — every path this run will read or change, as a flat list. The
+   planner already located them; the builder and the reviewer read this list instead
+   of searching the material again. A path missing here is a path the later stages
+   will have to find twice.
+5. **Steps** — ordered, each naming what it touches and what changes.
+6. **Verification** — how the result gets proven, in the track's terms: which tests
+   and commands for code; which claims get checked against which source for a
+   document; who reads it and understands what for communication work; who executes
+   it unaided for a runbook. "It should work" is not verification in any track.
+
+   Write this as a **numbered gate** — `G-01`, `G-02`, … — derived from the track's
+   third answer, *what would make it wrong*. The numbering is per run, not a standing
+   catalogue: the sixth kind of work still gets a real gate because its gate is
+   written from its own request rather than looked up. Each item is one checkable
+   question, and each carries a tier, which is where its severity comes from:
+
+   - **block** — the run is wrong if this fails. Reviewer severity `critical` or `high`.
+   - **reason** — the thing is allowed, but the builder must write down why. An
+     unexplained new dependency, abstraction, file, or section fails this tier.
+     Reviewer severity `medium`.
+   - **lock** — consistency with what is already there. Reviewer severity `low`.
+
+   Phrase every item so the answer is yes or no. "Handles errors well" is not a gate
+   item; "every new query path has a covering test" is. A tier fixes the severity
+   before the reviewer has an opinion, which is what stops the same class of problem
+   being `high` in one run and `medium` in the next.
+7. **Risks** — what could break, what is irreversible, what needs a migration or a
+   backup taken first.
+8. **Open questions** — assumptions that survived the interview. If this list is
+   non-empty, the approval must ask the user about it rather than defaulting.
+9. **Out of scope suggestions** — worthwhile things noticed but not asked for, each
+   its own proposal. Never folded into a step.
+
+The plan is a proposal, not a decision. It never edits files, runs migrations, or
+installs packages.
+
+---
+
+## Plan approval
+
+Controlled by `approvals.plan` (default on), skipped in `auto`.
+
+Present to the user, in this order:
+
+1. The track, the goal, and the top risk — a few lines, not the whole plan file.
+2. **The work list**, verbatim from the plan: plain bullets of what will actually be
+   done. This is the last thing the user sees before anything is produced, so it must
+   be readable on its own, without the plan's reasoning around it.
+3. The open questions, **as a pick list** — see below.
+
+Do not dump the whole plan into the terminal; point at its path for the detail.
+
+**Ask with options, not open prose.** Every question the plan raises is put to the
+user as a selectable choice with 2–4 concrete options, using whatever mechanism the
+tool provides for structured questions (in Claude Code, the AskUserQuestion tool).
+The planner writes the options; the main thread renders them, because a subagent
+cannot prompt the user directly. Never add an "other" option by hand — a free-text
+answer is always available, and the user may ignore the options entirely.
+
+This applies to any question the workflow asks at any stage, not only at this
+approval.
+
+**This approval is a conversation, not a form.** The user does not have to type an
+approval command. "Yes but drop step three", "do it", "no — I meant the other panel",
+"what happens if it fails halfway?" are all valid responses and are handled as what
+they plainly are. Answer questions at the approval without treating them as rejections;
+a person interrogating the plan is doing exactly what the approval exists for.
+
+Partial approval is normal: apply the modification to the plan, restate what changed
+in one line, and proceed on the modified plan. A change large enough to alter the
+goal goes back through the planner instead.
+
+Write the outcome to `02-approval.md`: decision, reason, timestamp, and any
+modification the user asked for. When the decision is an approval — full or partial —
+the same write appends to `runs/<id>/06-backlog.md` every out-of-scope suggestion that
+was not folded into the approved scope, plus anything cut from scope at this approval,
+each as `open` — see *Backlog* below for the format. The backlog is a candidate list,
+not a commitment list, so silence at the approval captures the item rather than losing
+it. A rejection appends nothing: there is no approved scope yet to measure against, and
+the approval of the revised plan is what captures the items, once.
+
+**A rejection is one of two different things, and the reason says which.** "Do it
+differently" is a revise: hand the file back to the planner with the reason, it
+produces a new `01-plan.md`, and the run returns to this same approval. "Not doing
+this" is a kill: the request itself was wrong, not just the approach — mark
+`stage: "abandoned"` in `state.json` and stop; there is nothing to revise toward.
+
+Read the reason to tell which. Revise-shaped: disagreement with an approach, a step,
+a scope boundary, an assumption — anything where a different plan would be accepted.
+Kill-shaped: the goal is no longer wanted, was based on a misunderstanding now
+resolved outside the plan, or a "no" with no implied alternative. When genuinely
+unclear, state which reading was taken in `02-approval.md` rather than guessing
+silently — a wrong revise wastes one planner cycle; a wrong kill discards a plan that
+should have been fixed instead, silently and without a record.
+
+Either way, do not proceed to implementation on a rejected plan under any mode. A
+revised plan returns through this same approval; a killed run's `stage` never advances
+past `"abandoned"`.
+

package/skills/kaizen/spec-review.md

@@ -0,0 +1,89 @@
+# Kaizen — review stage
+
+Read with [`spec.md`](spec.md) (core: track, intake, resume). This file is the
+reviewer's contract. The planner and builder do not read it.
+
+---
+## Stage 3 — Review
+
+**Agent:** reviewer, with a context that has never seen the builder's reasoning.
+**Input:** `01-plan.md` (its File manifest names what to read), `03-impl.md`, the
+track, and the work produced.
+**Output:** `04-review.md`.
+
+The track's third answer — *what would make it wrong* — is the reviewer's primary
+brief. It reads that first and hunts for it specifically.
+
+Five checks are universal, in every track:
+
+1. **Correctness** — is it true, and does it hold up? For code: logic errors,
+   unhandled cases, broken error paths, races, leaks. For a document: false claims,
+   internal contradictions, unsupported conclusions. For communication: overclaims,
+   and meaning the audience will not take as intended.
+2. **Plan conformance** — did the work do what was approved, no more and no less?
+   Scope creep is a finding. So is a step quietly skipped.
+3. **Blast radius** — what else touches what changed. A diff shows the lines that
+   moved; it does not show who depended on them. For every changed function, export,
+   schema field, config key, endpoint, or shared string, find its other callers and
+   readers and check each one still holds. This is the check a diff cannot contain,
+   and skipping it is how a run that passes its own verification breaks a feature
+   nobody looked at. In a non-code track the same question is "what else quoted,
+   linked to, or depended on the part that changed".
+4. **Regression** — the builder's before-and-after results from `03-impl.md`, verified
+   rather than trusted: re-run the checks. A check that passed at baseline and fails
+   now is a `high` finding at minimum, whatever else the work achieved. If the builder
+   recorded no baseline, that absence is itself the finding.
+
+5. **The plan's gate** — every `G-nn` item from the plan's Verification section,
+   re-answered against the work rather than against `03-impl.md`. A gate item the
+   builder marked `PASS` with no evidence behind it, or with evidence that only
+   restates the item, is treated as unproven and re-checked here; if it does not hold,
+   that is the finding. A `reason`-tier item fails when the technique is present and
+   the written reason is not.
+
+Then the track's own checks. For software work: security, reuse and simplification,
+test coverage. For a document: completeness against its own structure, accuracy of
+every checkable claim, whether its intended reader can actually use it. For
+operational work: missing prerequisites, absent rollback, steps that cannot be
+executed as written. The plan's Verification section says what was promised; the
+reviewer checks that promise was kept.
+
+Each finding is one line, numbered from 1 within the review:
+`<n>. <where>: <severity>: <problem>. <fix>. [G-nn]` Where is a `path:line` for code,
+and a section, page, or step reference otherwise. Severity is one of `critical`,
+`high`, `medium`, `low`. The number is what the user approves fixes by, and what the
+fix loop and the backlog refer to afterward, so it never changes once written.
+
+**A finding against a gate item cites it, and takes its severity from that item's
+tier** — `block` is `critical` or `high`, `reason` is `medium`, `lock` is `low`. This
+is what keeps the same class of problem from being graded differently run to run, and
+it is not a judgment the reviewer re-litigates: the tier was set at the plan, which
+the user approved. A finding outside the gate carries no id and is graded on its own
+merits.
+
+The reviewer verifies before reporting: a finding it cannot construct a concrete
+failing input or scenario for is dropped, not softened into a maybe. No praise, no
+summary of what the code does, no style nits that do not change meaning.
+
+The reviewer also appends any durable lesson about this material to `memory.md` —
+a recurring bug pattern, a non-obvious constraint, a convention worth keeping. Not
+run-specific detail; only what the next run would want to know.
+
+`memory.md` is read by every stage of every future run, so its size is a tax on all of
+them. Keep it under `review.memory_max_lines` (default 100): before appending, drop
+any lesson that is now wrong, already enforced by a test or a lint rule, or restated
+by a newer entry. A memory file that only grows stops being read carefully.
+
+---
+
+## 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.
+