@pmelab/gtd 32.1.0 → 34.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "32.1.0",
+  "version": "34.0.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -405,9 +405,10 @@ phone UI does not show them).
 
 ### The workflow it ships with
 
-One built-in workflow drives all of that. From where you sit, it has four
+One built-in workflow drives all of that. From where you sit, it has three
 moments — everything between them runs without you, with the judged exceptions
-noted in steps 3 and 4 below.
+noted in step 3 below — plus a fourth, review, only on `refactor-first` or when
+you open the `review` door.
 
 1. **You sketch.** Change anything, or write the idea into `.gtd/TODO.md`. Rough
    is fine; it is treated as a sketch, not as work.
@@ -431,13 +432,15 @@ noted in steps 3 and 4 below.
    [the naive pass](#the-naive-pass) below; with [flag mode](#the-naive-pass)
    off, neither runs). Then the change is built test-first, checked against the
    full suite (`testCommand`) and fixed until it passes — so keep that suite
-   fast; gtd has no lighter one. Scenario wording is not frozen: you sign the
-   scenarios off once, in the review's `## Scenarios` chunk, where any assertion
-   an existing scenario lost is marked `Weakened:`. After the build the quality
-   lap runs. Three points along the process (two with flag mode off) are judged
-   rather than always asking you outright — each stops and hands you a verdict
-   to make (`gtd judge answer`, or land with a clean tree to accept the
-   conservative default, which never skips work;
+   fast; gtd has no lighter one. Scenario wording is not frozen: a review's
+   `## Scenarios` chunk marks any assertion an existing scenario lost as
+   `Weakened:` — **risk: `feature` has no review, so a build turn that weakens a
+   scenario reaches `idle` unflagged unless you open the `review` door.** After
+   the build the quality lap runs, and the process ends: the feature workflow
+   has no human review of the finished change. Two points along the process (one
+   with flag mode off) are judged rather than always asking you outright — each
+   stops and hands you a verdict to make (`gtd judge answer`, or land with a
+   clean tree to accept the conservative default, which never skips work;
    `gtd judge run --provider fixed --answers <path>` — or the
    `GTD_JUDGE_ANSWERS` env var, inline JSON — answers one from a file, piped
    between `gtd judge --json` and `gtd judge answer`;
@@ -456,8 +459,6 @@ noted in steps 3 and 4 below.
      or get rejected and retried?
    - Every red round after the first: was the failure identical, new, or
      progress?
-   - After you review: is each of your notes an edit, a question, a nit or
-     praise?
 
    gtd itself never calls a judge: `gtd loop`, the Claude Code mod and the
    reference driver answer these through `gtd judge run` (auto selection: jev
@@ -469,18 +470,22 @@ noted in steps 3 and 4 below.
    and skip a gate unattended.**
 
    Once the change is built, the whole change goes through a qualitative review
-   lap before you see anything: six lenses, one turn each, in order —
-   `correctness`, `owasp-security`, `ponytail-review`, `test-audit`,
-   `conventions`, `spec-challenge`. `correctness`, `owasp-security` and
-   `spec-challenge` run on the planner model (`smart`), the other three on the
-   coder model (`base`); a `qualityReviews` entry `<lens>=<model>` picks a
-   lens's own. Each traces the change from its own angle and records every
-   finding, blocking or not; one fix turn then fixes ALL of them once, with no
-   re-review after the fix. A clean turn means approval only when that lens
-   found nothing at all. This lap is where code quality is looked at, and every
-   round pays for it. It never replaces step 4 — your review stays the final
-   gate, and nothing here skips it. The `fix` door (below) repairs a red
-   baseline through this same lap.
+   lap: six lenses, one turn each, in order — `correctness`, `owasp-security`,
+   `ponytail-review`, `test-audit`, `conventions`, `spec-challenge`.
+   `correctness`, `owasp-security` and `spec-challenge` run on the planner model
+   (`smart`), the other three on the coder model (`base`); a `qualityReviews`
+   entry `<lens>=<model>` picks a lens's own. Each traces the change from its
+   own angle and records every finding, blocking or not; one fix turn then fixes
+   ALL of them once, with no re-review after the fix. A clean turn means
+   approval only when that lens found nothing at all. This lap is where code
+   quality is looked at, and every round pays for it. It is the last look the
+   feature workflow takes: the process ends at `idle` once it is clean (and the
+   suite green), with no review rest — **risk: nothing re-reads the code the
+   single fix turn writes; only the suite gates it.** Findings the fix cap
+   leaves in `.gtd/QUALITY.md` rest at `build.quality-unresolved` until you
+   delete or empty the file; the suite then runs on any hand edits. **Nobody
+   signs the finished change off unless you open the `review` door** (below).
+   The `fix` door repairs a red baseline through this same lap.
 
    A red suite that keeps failing past a few fix attempts escalates instead of
    retrying forever: an agent turn reads the failing output and writes
@@ -491,22 +496,28 @@ noted in steps 3 and 4 below.
    instead of a third being written, and editing it is what gets the next
    attempt anywhere new.
 
-4. **You review.** You get a review document listing what changed and what to
-   look at. Before you see it, an automatic risk-fix pass
-   (`build.review.fix.risks.fixing`) runs. Any risk the reviewer names (a note
-   opening with `Risk:`) is fixed first, the suite kept green, and the review
-   rewritten — once per review round, so a risk the rewrite still names reaches
-   you unfixed; risk: a fix lands with no check that the risk was real. Tick the
-   boxes to approve, or write what is wrong. Approving ends the process;
-   feedback is judged note by note, each as `edit`, `question`, `nit` or
-   `praise`. An `edit` sends the process back to step 2 for re-derived
-   requirements, and the implementation is amended to meet them. A `question` is
-   answered inline under your note and the process stops at the review again —
-   no new plan. A `nit` is fixed in one batch, the suite must go green (a red
-   one gets fix turns first), then a fresh review of the change stops at the
-   review again. `praise` is dropped; a round of only praise signs off. When a
-   round mixes them, questions are answered and nits fixed first, then the edits
-   are planned — risk: the planning lap may redo nit fixes it touches.
+4. **You review — the refactor, or on request.** The feature workflow asks for
+   one review only on `refactor-first`: of the refactor slice, before the
+   feature is built (see [the naive pass](#the-naive-pass)). For the finished
+   change run `gtd door review <commitish>` (`/gtd review [base]`); that review
+   hands notes to `fix` instead of re-planning (below). Either way you get a
+   review document listing what changed and what to look at. Before you see it,
+   an automatic risk-fix pass (`build.review.fix.risks.fixing`) runs. Any risk
+   the reviewer names (a note opening with `Risk:`) is fixed first, the suite
+   kept green, and the review rewritten — once per review round, so a risk the
+   rewrite still names reaches you unfixed; risk: a fix lands with no check that
+   the risk was real. Tick the boxes to approve, or write what is wrong. At the
+   refactor review, approving moves on to the feature; feedback is judged note
+   by note (a third judged point), each as `edit`, `question`, `nit` or
+   `praise`. An `edit` re-derives the refactor (in a custom workflow built on
+   `buildTail`, it sends the process back to step 2 for re-derived
+   requirements). A `question` is answered inline under your note and the
+   process stops at the review again — no new plan. A `nit` is fixed in one
+   batch, the suite must go green (a red one gets fix turns first), then a fresh
+   review of the change stops at the review again. `praise` is dropped; a round
+   of only praise signs off. When a round mixes them, questions are answered and
+   nits fixed first, then the edits are planned — risk: the planning lap may
+   redo nit fixes it touches.
 
    Each `edit` note also gets a severity tier from four judge questions
    (security, reversibility, blast radius, new concept). `critical` and `should`
@@ -526,7 +537,7 @@ noted in steps 3 and 4 below.
 You never talk to it. Every exchange is a file in `.gtd/` that you edit in your
 own editor, and every answer you give is a commit. Your test suite is the gate
 throughout: a red baseline stops the process before it starts, and a red build
-is fixed before review.
+is fixed before the process ends.
 
 Prefer a phone or another device over your editor? `gtd ui` opens the file whose
 turn it is as a small web app, over Tailscale — including a step that names no
@@ -588,19 +599,21 @@ home directory — fails every command until you delete it. See
 
 #### The naive pass
 
-After design the agent first implements the requirements directly. A judge
-checks whether it changed anything outside the expected set (tests, steering
-files; see `seamAllow`). Incidental changes land; a needed seam change is
-refactored first, in its own slice with its own quality lap
-(`refactorQualityReviews`) and review, before the feature is implemented and
-reviewed; a wrong approach is retried twice, then rests for you to steer or
-overrule it. `gtd slices` lists the `refactor` and `feature` slices. A refactor
-that already carried the whole feature leaves the implementation nothing to do:
-its empty turn passes, and the feature review covers the whole change. Feedback
-at the feature review re-runs design and the implementation, never the naive
-pass; feedback at the refactor review re-runs the refactor, never design; a
-refactor-review change the refactor cannot build is refused, and the only way
-out is `gtd abandon`. A process from 27.5.0 or later whose judge ruled
+After design the agent first implements the requirements directly,
+breadth-first, with a behaviour-level acceptance test per criterion that names
+its ID (`[AC-3] …`) and reaches only code that existed before the pass. The pass
+is sent back while a criterion's ID is missing from its tests, a test imports a
+file it added, or the suite is red on it. A judge checks whether it changed
+anything outside the expected set (tests, steering files; see `seamAllow`).
+Incidental changes land; a needed seam change is refactored first, in its own
+slice with its own quality lap (`refactorQualityReviews`) and review, before the
+feature is implemented; a wrong approach is retried twice, then rests for you to
+steer or overrule it. `gtd slices` lists the `refactor` and `feature` slices. A
+refactor that already carried the whole feature leaves the implementation
+nothing to do: its empty turn passes, and the feature's quality lap covers the
+whole change. Feedback at the refactor review re-runs the refactor, never
+design; a refactor-review change the refactor cannot build is refused, and the
+only way out is `gtd abandon`. A process from 27.5.0 or later whose judge ruled
 `refactor-first` must `gtd abandon` too. Each slice's quality lap reviews only
 that slice. Details in
 [the naive-pass path](docs/configuration.md#the-naive-pass-path).

package/dist/chunks/{reserved-2fV0mj14.mjs → reserved-BcJgt5_R.mjs}

@@ -416,6 +416,17 @@ carries it.
 What each change does next (then run \`gtd land\`):
 - **Continue** — having undone the sketch by hand, check the test baseline is green and start triage (**start-gate.check**).
 `;
+const qualityUnresolvedMessage = () => `The quality lap's fix turns hit their cap and \`.gtd/QUALITY.md\` still
+holds findings. Nothing reviews the change after this, so the process
+will not end with them open.
+
+Fix what matters by hand, then delete or empty \`.gtd/QUALITY.md\` —
+dropping a finding is your call to make.
+
+What each change does next (then run \`gtd land\`):
+- **Delete or empty \`.gtd/QUALITY.md\`** — the suite runs on your edits, then the process ends (**idle**).
+- **Anything else** — rests here again.
+`;
 const startGateBlockedMessage = () => `The test baseline is red — gtd will not start new work on a broken suite.
 \`.gtd/FEEDBACK.md\` holds the failing output.
 
@@ -1203,24 +1214,47 @@ Print the closing message and stop — this writes nothing itself.
 `;
 };
 const listed = (paths, unreadable = []) => paths.map((path) => `  - \`${displayPath(path)}\`${unreadable.includes(path) ? " (unreadable)" : ""}`).join("\n");
+const isRed = (retry) => "red" in retry;
+const isFault = (retry) => "fault" in retry;
+const pickUp = (hash) => `Pick it up — \`git diff --binary ${hash}^ ${hash} | git apply\``;
 const criteriaBinding = (refused) => `- Its \`## Acceptance Criteria\` (\`AC-<n>\`) bind this turn: re-read them from
   the file, never from memory, and stop only when each one holds. They are
   settled — ${refused ? "a turn that changes them is refused" : "leave them as they are"}`;
-const naivePassPrompt = (rejection) => `${stateFileRules}
+const naiveRetry = (retry) => isFault(retry) ? `
+Your previous attempt's (\`${retry.hash}\`) tests fall short:
+${retry.fault}
+${pickUp(retry.hash)} — and fix its tests; do not start over.
+` : isRed(retry) ? `
+Your previous attempt (\`${retry.red}\`) left the suite red; \`.gtd/FEEDBACK.md\`
+holds the output. ${pickUp(retry.red)}
+— and fix it until the suite is green; do not start over.
+` : `
+Your previous attempt was rejected: the judge answered \`reject\` (p=${retry.p}),
+meaning the naive pass solved the task the wrong way — discard it and
+re-implement. It changed these files outside the expected set:
+${listed(retry.strays)}
+Start over and choose a different approach; do not rebuild the same diff.
+`;
+const naivePassPrompt = (retry) => `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
 ${criteriaBinding(false)}
 - Implement them the quickest way that works — the naive version. Do not
   restructure, abstract or refactor around the change; a later step judges
   the shape of your diff and a reviewer makes it fit
-- Add tests as you go, and leave \`.gtd/\` untouched
+- Work breadth-first: rough out every part of the change before finishing any
+  one, so a run cut off midway still shows the whole shape
+- Write behaviour-level acceptance tests, at least one per criterion, each
+  naming its ID in the test or scenario name (\`[AC-3] …\`). Test through code
+  that existed before this pass — a public entry point, the CLI, an existing
+  module's exports — never a file this pass adds: that is naive structure a
+  later reset and refactor replaces. A pass that leaves a criterion's ID out
+  of its tests, or whose test imports a file it added, is sent back
+- Run \`${env.testCommand}\` and finish only once it is green with every
+  criterion's test passing: the next step runs it on your diff and sends a red
+  pass back
+- Leave \`.gtd/\` untouched
 - Leave everything uncommitted and finish your turn — do not commit
-${rejection === void 0 ? "" : `
-Your previous attempt was rejected: the judge answered \`reject\` (p=${rejection.p}),
-meaning the naive pass solved the task the wrong way — discard it and
-re-implement. It changed these files outside the expected set:
-${listed(rejection.strays)}
-Start over and choose a different approach; do not rebuild the same diff.
-`}`;
+${retry === void 0 ? "" : naiveRetry(retry)}`;
 const implementBuildingPrompt = (reference, tier, amend, afterRefactor, flagMode = true) => `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
 ${criteriaBinding(true)}
@@ -1245,8 +1279,41 @@ const implementFixPrompt = () => `${stateFileRules}
 ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `;
-const seamSteerMessage = (rejection) => `The naive pass was rejected three times and the retries are spent.
-The last attempt changed these files outside the expected set:
+const steerChoices = (overrule) => `Two ways forward (then run \`gtd land\`):
+- **Steer** — edit \`.gtd/REQUIREMENTS.md\` to redirect the change; the naive
+  pass runs again with a fresh retry budget
+- **Overrule** — ${overrule}
+
+An edit together with an approval counts as steer. Only
+\`.gtd/REQUIREMENTS.md\` is meant to change here: any other edit lands on the
+branch unjudged.
+`;
+const seamSteerMessage = (retry) => isFault(retry) ? `The naive pass failed three times and the retries are spent. The last
+attempt's tests (\`git show ${retry.hash}\`) fall short:
+${retry.fault}
+
+${steerChoices(`land a clean tree to go on with the last attempt as it is:
+  \`seam.check\` runs its suite and the seam judge rules on its shape. Use it
+  when the rule cannot fit this change (tests the globs do not see, or no
+  entry point that existed before). Risk: a criterion may have no test that
+  survives a later refactor — the choice is recorded in history.`)}` : isRed(retry) ? `The naive pass failed three times and the retries are spent. The last
+attempt left the suite red: \`.gtd/FEEDBACK.md\` holds the last run's output; \`git show ${retry.red}\` shows
+the last attempt.
+
+Two ways forward (then run \`gtd land\`):
+- **Steer** — edit \`.gtd/REQUIREMENTS.md\` to redirect the change; the naive
+  pass runs again with a fresh retry budget
+- **Overrule** — land a clean tree to go on with the last attempt as it is:
+  the seam judge rules on its shape, and the implementation's health loop
+  must turn the suite green. Risk: the criteria's tests never passed on the
+  naive pass — the choice is recorded in history.
+
+An edit together with an approval counts as steer. Only
+\`.gtd/REQUIREMENTS.md\` is meant to change here: any other edit lands on the
+branch unjudged.
+` : seamRejectedMessage(retry);
+const seamRejectedMessage = (rejection) => `The naive pass failed three times and the retries are spent. The judge
+rejected the last attempt: it changed these files outside the expected set:
 ${listed(rejection.strays)}
 
 Two ways forward (then run \`gtd land\`):
@@ -1573,4 +1640,4 @@ const steering = {
 	[REVIEW]: "review"
 };
 //#endregion
-export { reviewEditNotesCapture as $, buildReviewCollectingPrompt as A, designTriagePrompt as B, planner as C, agentWithSkills as D, reviewing as E, clearCriteriaQuestion as F, implementBuildingPrompt as G, fixReviewNotesPrompt as H, criterionLine as I, normaliseCriteriaScript as J, implementFixPrompt as K, deferNotesScript as L, buildReviewTriageMessage as M, builderSystem as N, buildReviewAnswerQuestionsPrompt as O, clearCriteriaMessage as P, refactorRules as Q, designGateAnswerMessage as R, fixRisks as S, reviewQuality as T, handOffAwaitReviewMessage as U, finisherSystem as V, idleMessage as W, refactorDroppedRefusal as X, refactorBuildingPrompt as Y, refactorFixPrompt as Z, REVIEW as _, flagModeOn as a, seamSteerMessage as at, fixCheck as b, baseline as c, unwindFailure as ct, guarded as d, testFileGlobs as dt, reviewEditsCapture as et, healthy as f, flagMentions as ft, REQUIREMENTS as g, requireFlag as gt, REFACTOR as h, registryEntry as ht, skills as i, seamByHandMessage as it, buildReviewFixNitsPrompt as j, buildReviewAwaitAfterDeferMessage as k, escalation as l, defaults as lt, QUALITY as m, flipProblems as mt, summary as n, reviewNotesCapture as nt, flagShipped as o, startGateBlockedMessage as ot, FEEDBACK as p, flagReferences as pt, naivePassPrompt as q, access as r, reviewerSystem as rt, shipped as s, unwindFailedMessage as st, steering as t, reviewGateBlockedMessage as tt, gate as u, envDefaults as ut, awaitReview as v, reviewMissing as w, fixQuality as x, coder as y, designSystem as z };
+export { refactorRules as $, buildReviewCollectingPrompt as A, designTriagePrompt as B, planner as C, agentWithSkills as D, reviewing as E, clearCriteriaQuestion as F, implementBuildingPrompt as G, fixReviewNotesPrompt as H, criterionLine as I, normaliseCriteriaScript as J, implementFixPrompt as K, deferNotesScript as L, buildReviewTriageMessage as M, builderSystem as N, buildReviewAnswerQuestionsPrompt as O, clearCriteriaMessage as P, refactorFixPrompt as Q, designGateAnswerMessage as R, fixRisks as S, reviewQuality as T, handOffAwaitReviewMessage as U, finisherSystem as V, idleMessage as W, refactorBuildingPrompt as X, qualityUnresolvedMessage as Y, refactorDroppedRefusal as Z, REVIEW as _, requireFlag as _t, flagModeOn as a, seamByHandMessage as at, fixCheck as b, baseline as c, unwindFailedMessage as ct, guarded as d, envDefaults as dt, reviewEditNotesCapture as et, healthy as f, testFileGlobs as ft, REQUIREMENTS as g, registryEntry as gt, REFACTOR as h, flipProblems as ht, skills as i, reviewerSystem as it, buildReviewFixNitsPrompt as j, buildReviewAwaitAfterDeferMessage as k, escalation as l, unwindFailure as lt, QUALITY as m, flagReferences as mt, summary as n, reviewGateBlockedMessage as nt, flagShipped as o, seamSteerMessage as ot, FEEDBACK as p, flagMentions as pt, naivePassPrompt as q, access as r, reviewNotesCapture as rt, shipped as s, startGateBlockedMessage as st, steering as t, reviewEditsCapture as tt, gate as u, defaults as ut, awaitReview as v, reviewMissing as w, fixQuality as x, coder as y, designSystem as z };

package/dist/chunks/{tail-BynhCfuv.mjs → tail-CM_fa93v.mjs}

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../flows.mjs";
 import { fixFindings, lensEntriesOf, lensOf, qualityLap as qualityLap$1, reviewToHandOff } from "../workflow-kit.mjs";
-import { E as reviewing, S as fixRisks, T as reviewQuality, U as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, d as guarded, f as healthy, l as escalation, m as QUALITY, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-2fV0mj14.mjs";
+import { E as reviewing, S as fixRisks, T as reviewQuality, U as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, d as guarded, f as healthy, l as escalation, m as QUALITY, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-BcJgt5_R.mjs";
 //#region src/workflows/shared/tail.ts
 /** The reviewer's own `.gtd/REVIEW.md`, kept beside the human's notes so `fix` can tell them apart. */
 const REVIEW_ORIG = ".gtd/REVIEW.orig.md";

package/dist/testkit.mjs

@@ -5,13 +5,13 @@ import { $ as logWarning, $i as NodeInspectSymbol, $n as map$5, $r as make$19, $
 import { createRequire } from "node:module";
 import * as Crypto from "node:crypto";
 import { createHash } from "node:crypto";
+import * as Path from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { PassThrough } from "node:stream";
 import * as NFS from "node:fs";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as OS from "node:os";
 import { homedir, tmpdir } from "node:os";
-import * as Path from "node:path";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import * as ChildProcess from "node:child_process";
 import { execFileSync, execSync, spawnSync } from "node:child_process";
 import * as NodeUrl from "node:url";

package/dist/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
-import { gt as requireFlag, ht as registryEntry, i as skills, lt as defaults, n as summary, o as flagShipped, pt as flagReferences, r as access, t as steering, ut as envDefaults, y as coder } from "../chunks/reserved-2fV0mj14.mjs";
-import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-BynhCfuv.mjs";
+import { _t as requireFlag, dt as envDefaults, gt as registryEntry, i as skills, mt as flagReferences, n as summary, o as flagShipped, r as access, t as steering, ut as defaults, y as coder } from "../chunks/reserved-BcJgt5_R.mjs";
+import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-CM_fa93v.mjs";
 //#region src/workflows/cleanup/cleanup.ts
 const removingPrompt = (name, registry) => `Clean up the release flag "${name}", which is default-on: delete its entry in ${registry}, and remove every \`GTD_FLAG_${name.toUpperCase()}\` check from the shipped sources. Keep the flag-on path; delete code only the off path reached, including tests that pin the off path.`;
 const cleanupFlow = async () => {