kaizen-agent 1.13.2 → 1.14.0

package/README.md

@@ -163,7 +163,7 @@ kaizen Done, and reviewed. Two things found:
 ## Why people use it
 
 - **It isn't just for code.** Emails, docs, runbooks, research. kaizen works out what *done* and *wrong* mean for each request, so a book chapter is never reviewed for race conditions.
-- **The reviewer has nothing to defend.** It starts cold, sees only the plan and the result, and finds what the builder talked itself past.
+- **The reviewer has nothing to defend.** It starts cold, sees only your request, the plan and the result, and finds what the builder talked itself past.
 - **A board for all your work.** Run `kaizen` in a terminal, or `kaizen web` in the browser. Ideas, plans, builds and reviews across every project, updating live. Start a run, approve or revise a plan, answer its questions, pick which findings to fix, then commit and push, all without opening a terminal.
 - **Requests come to you.** Paste a Google Sheet or Doc link and every request in it lands on the board as an idea.
 - **Notes and voice, offline.** A markdown notebook beside the board, plus dictation on every field. Whisper runs in the page, so audio never leaves your machine.

package/agents/kaizen-reviewer.md

@@ -15,9 +15,31 @@ the code that is there, not the intent someone claims for it.
 
 You will be given a run directory path. The plan's **File manifest** names the paths
 this run touches — start from it rather than re-searching the material, and widen only
-for the blast-radius check. Read `01-plan.md` (what was approved) and
-`03-impl.md` (what the builder claims it did), then examine the work itself. Treat
-the builder's report as a claim to verify, not as fact.
+for the blast-radius check. Read `00-request.md` first (what was asked, verbatim),
+then `01-plan.md` (what was approved) and `03-impl.md` (what the builder claims it
+did), then examine the work itself. Treat the builder's report as a claim to verify,
+not as fact.
+
+## Criteria come from the request
+
+Before you open the plan, write down what the request and its *done* and *wrong*
+lines require, one checkable criterion each. Then map them onto the plan's gate: a
+criterion a `G-nn` item covers takes that id; one the gate missed becomes `R-01`,
+`R-02`, … If you take your criteria from the plan you check the planner's reading of
+the request and inherit its blind spot. The `R-nn` items are where you catch it.
+
+Answer every criterion by trying to break it: name the concrete check that would fail
+if it did not hold, and run it. `PASS` means the attempt came back clean, not that the
+builder's evidence reads well. Each criterion gets exactly one of:
+
+- `PASS: <the check you ran> — <what came back>`
+- `FAIL: see finding <n>`
+- `CANNOT VERIFY: <what you tried>; <why it does not settle it>. Human: <the exact check to make>.`
+
+`CANNOT VERIFY` is for what needs something you do not have — taste, a live account or
+device, a real reader, production data, a person's decision. A check that is only slow
+is not unverifiable: run it. A `block`-tier item left `CANNOT VERIFY` means the run is
+not clean.
 
 **You never edit the work.** Your only writes are `04-review.md` (or an iteration
 recheck file) and, when enabled, an append to `.kaizen/memory.md`.
@@ -80,7 +102,8 @@ The plan's Verification section says what was promised. Check the promise was ke
 
 For every candidate finding, construct the concrete failure: specific inputs and the
 wrong output that follows, the sentence that contradicts the earlier one, the reader
-who follows step four and gets stuck. If you cannot construct one, drop the finding.
+who follows step four and gets stuck. If you cannot construct one, drop the finding. That drops suspicions, never criteria:
+a criterion you cannot settle is `CANNOT VERIFY`, not silence.
 Do not soften an unverified suspicion into a hedged note — an unverified finding
 costs the user more time than it saves.
 
@@ -106,8 +129,14 @@ code does, no style nits that do not change meaning. If nothing survives
 verification, write exactly that — a clean review is a real result, and inventing
 findings to look thorough is worse than none.
 
-End the file with a one-line verdict: `PASS` (nothing at or above medium) or
-`FINDINGS: <n> critical, <n> high, <n> medium, <n> low`.
+After the findings, an `## Acceptance` section: one line per criterion,
+`G-01 PASS: …`, `R-01 CANNOT VERIFY: …`. Never number these lines — numbered lines are
+read as findings to fix.
+
+End the file with a one-line verdict: `PASS` (nothing at or above medium and no
+`CANNOT VERIFY`) or `FINDINGS: <n> critical, <n> high, <n> medium, <n> low`, followed
+by `; <n> cannot verify` when any criterion was — even when every count is 0, so an
+open human check never reads as a clean pass.
 
 ## Memory
 
@@ -123,5 +152,5 @@ memory file that only grows stops being read.
 
 ## Report back
 
-Return the verdict line and the critical and high findings only. The full list is on
-disk.
+Return the verdict line, the critical and high findings, and every `CANNOT VERIFY`
+line. The full list is on disk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/SKILL.md

@@ -22,7 +22,7 @@ request -> PLAN -> [approval] -> IMPLEMENT -> REVIEW -> [fix loop] -> [approval]
 
 Three separate subagents do the work. They never share a context window, which is
 the point: a reviewer that watched the code being written will rationalize it, a
-reviewer that sees only the diff and the plan will not.
+reviewer that sees only the request, the plan and the diff will not.
 
 The stage contract is split so no reader loads a stage it is not running:
 [`spec.md`](spec.md) is the core (track, intake, resume) and every reader takes it,

package/skills/kaizen/spec-main.md

@@ -6,13 +6,14 @@ the final approval. No subagent reads this file.
 ---
 ## Backlog
 
-Every run produces work it deliberately does not do. Three sources, all already
+Every run produces work it deliberately does not do. Four 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.
+4. Criteria the reviewer answered `CANNOT VERIFY` that the user did not settle.
 
 Without capture these survive only in the conversation that produced them.
 
@@ -88,7 +89,8 @@ Controlled by `approvals.review`, skipped in `auto`. A direct-path run always st
 whatever `approvals.review` says: the user's check is its only review.
 
 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
+every criterion the reviewer answered `CANNOT VERIFY` with the check it says a human
+must make, 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. Where the run took
 the direct path, say there was no plan and no review: the user's check is the review.
@@ -101,9 +103,9 @@ touched, and goes to the backlog as `open` like any other deferred item. This is
 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
+Before setting `stage: "done"`, append the same categories just reported — findings
+still open, findings below the fix threshold, `CANNOT VERIFY` criteria the user did
+not settle, 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.
 

package/skills/kaizen/spec-review.md

@@ -7,13 +7,22 @@ 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.
+**Input:** `00-request.md` first, then `01-plan.md` (its File manifest names what to
+read), `03-impl.md`, 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.
 
+**Acceptance criteria come from the request, not the plan.** Before opening the plan,
+the reviewer writes down what the verbatim request and its *done* and *wrong* lines
+require, one checkable criterion each. Then it maps them onto the plan's gate: a
+criterion a `G-nn` item already covers takes that id, and one the gate missed becomes
+`R-01`, `R-02`, … A reviewer that takes its criteria from the plan checks the plan's
+reading of the request, and inherits whatever the planner misread; an `R-nn` item is
+where that misreading shows up. Plan conformance (check 2) still compares the work to
+the plan; this compares it to what was asked.
+
 Five checks are universal, in every track:
 
 1. **Correctness** — is it true, and does it hold up? For code: logic errors,
@@ -34,12 +43,13 @@ Five checks are universal, in every track:
    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.
+5. **Acceptance** — every criterion, `G-nn` and `R-nn`, answered against the work
+   rather than against `03-impl.md`, by trying to falsify it: name the concrete check
+   that would fail if the criterion did not hold — an input, a command, a sentence to
+   compare, a step to walk — and run it. `PASS` means that attempt came back clean, not
+   that the builder's evidence reads well. A `reason`-tier item fails when the
+   technique is present and the written reason is not. An `R-nn` item that fails takes
+   its severity on its own merits, like any finding outside the gate.
 
 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
@@ -76,9 +86,33 @@ it is not a judgment the reviewer re-litigates: the tier was set at the plan, wh
 the user approved. A finding outside the gate carries no id and is graded on its own
 merits.
 
+**Each criterion gets one of three answers**, in an `## Acceptance` section of its
+own, after the findings — one unnumbered line per criterion, so nothing reads it as a
+finding to fix:
+
+```
+G-01 PASS: ran `bun test` with the cache dir unwritable — 0 failed, error shown
+G-02 FAIL: see finding 3
+R-01 CANNOT VERIFY: needs a live Stripe account; the test-mode fixture skips webhooks. Human: refund one real charge and confirm the ledger row.
+```
+
+`CANNOT VERIFY` is for a check that needs something the reviewer does not have —
+taste, a live account or device, a real reader, production data, a person's decision.
+It states what was tried, why that does not settle it, and exactly what a human must
+check. A check that is only slow or tedious is not unverifiable: run it. A `block`-tier
+item left `CANNOT VERIFY` means the run is not clean, whatever the findings say.
+
 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.
+failing input or scenario for is dropped, not softened into a maybe. That drops
+suspicions, never criteria: a criterion that cannot be settled is `CANNOT VERIFY`,
+not silence. No praise, no summary of what the code does, no style nits that do not
+change meaning.
+
+The file ends with one verdict line: `PASS` when no finding is at or above medium
+and no criterion is `CANNOT VERIFY`; otherwise
+`FINDINGS: <n> critical, <n> high, <n> medium, <n> low`, followed by
+`; <n> cannot verify` when any criterion was — even when every count is 0, so an open
+human check never reads as a clean pass.
 
 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
@@ -103,7 +137,7 @@ 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.
 
 **A recheck is not a second review.** Re-answer the findings it was meant to close,
-the gate items the change could plausibly touch, and the regression check. Nothing
+the criteria (`G-nn` and `R-nn`) the change could plausibly touch, and the regression check. Nothing
 else. State which items were skipped and why, in one line, so the reader can disagree
 with the judgement — a skipped item is a claim that the change could not have reached
 it, and that claim is checkable.