@pmelab/gtd 29.2.2 → 29.2.4

package/.claude-plugin/plugin.json

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

package/README.md

@@ -324,36 +324,39 @@ Then, in any repository:
 /gtd Add a --json flag to the export command
 ```
 
-That starts a process from your requirements and drives it until it needs you. A
-long, multi-line requirements paste still starts a process; if Claude Code never
-expanded the paste, gtd says it could not read it, and you write the
-requirements to `.gtd/TODO.md` and run `/gtd`. `/gtd fix`, `/gtd review [base]`,
-`/gtd rollout <flag>` and `/gtd cleanup <flag>` (where the config exports them)
-take the doors described below; text whose word count does not fit a door's args
-(bare `/gtd rollout` included) starts a process from that text as requirements.
-At every human rest Claude itself takes over: it walks you through the open
-questions one at a time, answers your own questions about the plan or the diff,
-records what you decide in the steering file the way the step asks, and moves
-the process on only when you say so; a review you leave untouched signs off.
-While a step runs you can keep asking; requests for changes wait for the next
-rest. When the process finishes, Claude offers to squash it and open its pull
-request(s) (or run `/gtd ship`; `GTD_SHIP_MODE` picks one stacked pull request
-per slice or one commit per slice, see the [driver doc](docs/driver.md)); a
-process started for an issue ships with `Closes #N` on its top pull request;
-re-running `/gtd ship` after a lower stacked pull request merged restacks the
-rest (it refuses, with nothing changed, when that pull request merged anywhere
-but the default branch (unless into a lower slice branch before that one merged
-into it), a slice branch is checked out in another worktree, an unrelated local
-branch sits inside the rebased commits, or a slice's change is already upstream;
-a failed rebase is rolled back). A process can change hands at any gate: ask
-Claude to hand it off (or run `/gtd throw @dev`) and it opens a draft pull
-request assigned to them, and `/gtd catch <pr>` picks it up exactly where it
-waits, so whoever wrote the requirements can hand the architecture to someone
-else. Ship, hand-off and throw answer at once and run in the background, with
-progress on the status line; they report by waking Claude, a toast, a transcript
-line and a push notification, and a failed push or `gh` call reports as a
-failure. While a ship or hand-off runs or is queued, `/gtd catch`, the doors,
-`/gtd <requirements>` and bare `/gtd` wait for its report. See
+That starts a process from your requirements and drives it until it needs you.
+The requirements go to the top of `.gtd/TODO.md`; deferred review notes already
+there stay. A long, multi-line requirements paste still starts a process; if
+Claude Code never expanded the paste, gtd says it could not read it, and you add
+the requirements to the top of `.gtd/TODO.md` and run `/gtd`. `/gtd fix`,
+`/gtd review [base]`, `/gtd rollout <flag>` and `/gtd cleanup <flag>` (where the
+config exports them) take the doors described below; text whose word count does
+not fit a door's args (bare `/gtd rollout` included) starts a process from that
+text as requirements. At every human rest Claude itself takes over: it walks you
+through the open questions one at a time, answers your own questions about the
+plan or the diff, records what you decide in the steering file the way the step
+asks, and moves the process on only when you say so; a review you leave
+untouched signs off. While a step runs you can keep asking; requests for changes
+wait for the next rest. When the process finishes, Claude offers to squash it
+and open its pull request(s) (or run `/gtd ship`; `GTD_SHIP_MODE` picks one
+stacked pull request per slice or one commit per slice, see the
+[driver doc](docs/driver.md)); a process started for an issue ships with
+`Closes #N` on its top pull request; a closed pull request whose branch was
+deleted from origin is left behind and a new one opens; re-running `/gtd ship`
+after a lower stacked pull request merged restacks the rest (it refuses, with
+nothing changed, when that pull request merged anywhere but the default branch
+(unless into a lower slice branch before that one merged into it), a slice
+branch is checked out in another worktree, an unrelated local branch sits inside
+the rebased commits, or a slice's change is already upstream; a failed rebase is
+rolled back). A process can change hands at any gate: ask Claude to hand it off
+(or run `/gtd throw @dev`) and it opens a draft pull request assigned to them,
+and `/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
+requirements can hand the architecture to someone else. Ship, hand-off and throw
+answer at once and run in the background, with progress on the status line; they
+report by waking Claude, a toast, a transcript line and a push notification, and
+a failed push or `gh` call reports as a failure. While a ship or hand-off runs
+or is queued, `/gtd catch`, the doors, `/gtd <requirements>` and bare `/gtd`
+wait for its report. See
 [Inside Claude Code](https://github.com/pmelab/gtd/blob/main/docs/driver.md#inside-claude-code-the-gtd-mod).
 
 ### Then let an agent build your own

package/claude/hooks/paste.ts

@@ -10,7 +10,7 @@ export function pastedCommand(text: string): Pasted | undefined {
   if (!arg) return undefined
   if (PLACEHOLDER.test(arg)) {
     return {
-      lost: "The pasted requirements did not arrive whole. Write them to .gtd/TODO.md and run /gtd.",
+      lost: "The pasted requirements did not arrive whole. Add them to the top of .gtd/TODO.md and run /gtd.",
     }
   }
   return { arg }

package/claude/hooks/register.tsx

@@ -17,6 +17,7 @@ import { catchFrom, throwTo } from "./handoff"
 import { jobs } from "./jobs"
 import { documents, readDocument } from "./schema"
 import { READ_ONLY_GIT, ship } from "./ship"
+import { withRequirements } from "./sketch"
 import type { Shipped, ShipIo } from "./ship"
 import { collectAnswer } from "./delegate"
 import { decideCommand, decideContinue, decideJob, restId, TOOLS } from "./tools"
@@ -331,7 +332,8 @@ async function begin($: $, requirements: string) {
   const file = b.file ?? ".gtd/TODO.md"
   const path = `${root}/${file}`
   await $.process.run(["mkdir", "-p", path.slice(0, path.lastIndexOf("/"))])
-  await $.fs.write(path, requirements + "\n")
+  const existing = (await $.fs.exists(path)) ? await $.fs.read(path) : ""
+  await $.fs.write(path, withRequirements(existing, requirements))
   await start($)
   return `Started a new gtd process from ${file}.`
 }

package/claude/hooks/ship.ts

@@ -633,7 +633,13 @@ export const NO_PR_FOUND = "no pull requests found"
 
 // `gh pr view <branch>`: only NO_PR_FOUND reads as none; any
 // other failure (auth, network) must refuse, or ship would open a duplicate PR.
-async function viewPr(io: ShipIo, branch: string): Promise<View | undefined | string> {
+// A closed PR whose branch origin lost is an abandoned earlier ship and reads as
+// none; `abandoned` is recorded before the push so a retry, with origin holding
+// the branch again, still reads it as none. `gone`: a tracking ref is stale.
+async function readPr(
+  io: ShipIo,
+  branch: string,
+): Promise<{ view?: View; gone?: boolean; abandoned?: number } | string> {
   const v = await io.run([
     "gh",
     "pr",
@@ -643,14 +649,41 @@ async function viewPr(io: ShipIo, branch: string): Promise<View | undefined | st
     "number,title,body,url,state,baseRefName,mergedAt",
   ])
   if (v.code !== 0) {
-    if (v.err.includes(NO_PR_FOUND)) return undefined
+    if (v.err.includes(NO_PR_FOUND)) return {}
     return `gh pr view ${branch} failed: ${v.err.trim()}`
   }
+  let view: View
   try {
-    return JSON.parse(v.out) as View
+    view = JSON.parse(v.out) as View
   } catch {
     return `gh pr view ${branch} returned something unreadable.`
   }
+  if (view.state !== "CLOSED") return { view }
+  const key = await io.run(["git", "config", "--local", "--get", ABANDONED_KEY(branch)])
+  const recorded = key.out.trim() === String(view.number)
+  const ls = await io.run(["git", "ls-remote", "origin", `refs/heads/${branch}`])
+  const gone = ls.code === 0 && !ls.out.trim()
+  if (recorded) return { gone }
+  return gone ? { gone, abandoned: view.number } : { view }
+}
+
+const ABANDONED_KEY = (branch: string) => `branch.${branch}.gtdAbandonedPr`
+
+// Once the new PR opens, gh pr view finds it: the record has served its purpose.
+async function settled<T extends Shipped>(io: ShipIo, branch: string, done: T) {
+  if (done.ok) await io.run(["git", "config", "--local", "--unset", ABANDONED_KEY(branch)])
+  return done
+}
+
+async function abandon(io: ShipIo, branch: string, pr: number | undefined) {
+  if (pr === undefined) return undefined
+  const set = await io.run(["git", "config", "--local", ABANDONED_KEY(branch), String(pr)])
+  return set.code === 0 ? undefined : `git config failed.\n${set.err}`.trimEnd()
+}
+
+async function viewPr(io: ShipIo, branch: string): Promise<View | undefined | string> {
+  const read = await readPr(io, branch)
+  return typeof read === "string" ? read : read.view
 }
 
 // `dead` names belong to a retired record gtd built itself: not a collision.
@@ -1512,10 +1545,13 @@ async function shipLink(
   const l = links[i]!
   const lower = i ? links[i - 1]! : undefined
   const base = baseOf(links, i, baseBranch)
-  const view = await viewPr(io, l.branch)
-  if (typeof view === "string")
-    return { step: "pull request", why: `${view} ${l.branch} was not pushed; /gtd ship retries.` }
-  const pushed = await pushLink(io, git, l, i < links.length - 1)
+  const read = await readPr(io, l.branch)
+  if (typeof read === "string")
+    return { step: "pull request", why: `${read} ${l.branch} was not pushed; /gtd ship retries.` }
+  const { view, gone } = read
+  const marked = await abandon(io, l.branch, read.abandoned)
+  if (marked) return { step: "push", why: marked }
+  const pushed = await pushLink(io, git, { ...l, fresh: l.fresh || gone }, i < links.length - 1)
   if (pushed) return { step: "push", why: pushed }
   const lowerRef = lower?.branch ?? baseRef
   const ctx: Ctx = {
@@ -1528,6 +1564,7 @@ async function shipLink(
   }
   const done = await sliceStep(io, git, ok, l, view, base, lowerRef, ctx)
   if ("step" in done) return done
+  if (!view) await settled(io, l.branch, done)
   if (done.number === undefined && i < links.length - 1)
     return { step: "pull request", why: "its number could not be read from gh's reply." }
   return done
@@ -1764,17 +1801,24 @@ async function pullRequest(
   if (mergeBase === (await git("rev-parse", "HEAD")))
     return fail(`HEAD is an ancestor of ${baseRef}: nothing to describe.`)
 
-  const existing = await viewPr(io, branch)
-  if (typeof existing === "string")
+  const read = await readPr(io, branch)
+  if (typeof read === "string")
     return fail(
-      `${existing} ${branch} was not pushed; the squash and history ref stay, /gtd ship retries.`,
+      `${read} ${branch} was not pushed; the squash and history ref stay, /gtd ship retries.`,
     )
+  const { view: existing, gone } = read
   if (existing && existing.state !== "OPEN")
     return fail(`The pull request for ${branch} is ${existing.state}, not open.`)
-  const pushed = await pushBranch(io, branch)
+  const marked = await abandon(io, branch, read.abandoned)
+  if (marked) return fail(`${marked} ${branch} was not pushed; /gtd ship retries.`)
+  const pushed = await pushBranch(io, branch, "HEAD", undefined, gone)
   if (pushed) return fail(pushed)
   if (!existing)
-    return createPr(io, git, branch, baseBranch, baseRef, { from: mergeBase, to: "HEAD" })
+    return settled(
+      io,
+      branch,
+      await createPr(io, git, branch, baseBranch, baseRef, { from: mergeBase, to: "HEAD" }),
+    )
   // A branch once shipped as a stack keeps the PR aimed at a slice branch; any
   // other base is the author's own and stays.
   const onSlice = recorded.some((n) => existing.baseRefName === `${branch}-${n}`)

package/claude/hooks/sketch.ts

@@ -0,0 +1,6 @@
+// New requirements go above what the steering file already holds, untouched:
+// a deferred review note the start diff alters reads as the human's edit.
+export function withRequirements(existing: string, requirements: string): string {
+  const head = `${requirements.trimEnd()}\n`
+  return existing.trim() ? `${head}\n${existing}` : head
+}

package/dist/chunks/{reserved-vvu5yc3I.mjs → reserved-BduvUQxQ.mjs}

@@ -770,9 +770,13 @@ ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `;
 const refactorRules = (strays, pattern) => `- Behaviour-neutral: the suite's outcome must not change
-- Change only these paths, nothing else, and never a test file even
-  when it is one of them:
+- Change only these paths, nothing else:
 ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
+- An existing test file only where a changed call shape reaches it:
+  update its call sites, inside an assertion too;
+  never add or delete a test file,
+  never add, remove or alter a test or an assertion, and never
+  change what an assertion checks, an expected value or a snapshot
 - Introduce no new flag read and add no second read of an existing one:
   every match of \`${pattern}\` may move, never increase in number`;
 const withRules = (rules) => rules === void 0 ? "" : `${rules}\n`;
@@ -782,8 +786,13 @@ ${feedback ? `- The package carries a \`## Review feedback\` section: a human's
   last refactor. Act on it, within the rules below
 ` : ""}${refactorRules(strays, pattern)}
 ${reference === void 0 ? "" : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
-  earlier attempt at this change. Read it for ideas; never apply,
-  cherry-pick or check it out — write a fresh refactor
+  earlier attempt at this change, and \`git show --stat ${reference}\`
+  lists every file it touched, the test call sites included.
+  Read it; never apply, cherry-pick or check it out
+- Its changes to these paths' existing code are the seam: write that
+  restructuring afresh here, minus the feature's own behaviour. A
+  refactor that touches none of it is wrong, however clean — never
+  swap in an unrelated tidy-up
 `}- Leave everything uncommitted and finish your turn — do not commit
 `;
 const refactorFixPrompt = (strays, pattern) => `${stateFileRules}
@@ -1099,11 +1108,11 @@ const closedFold = (round, target) => round === "edits" ? `- Fold every hand-edi
 /** `refactor` retargets the prompt at `.gtd/REFACTOR.md` and fences it to the strays. A concern outside the fence is not folded; if nothing at all is written the landing is refused, but a partly buildable round drops the rest silently. */
 const buildReviewCollectingPrompt = (capture, refactor) => {
 	const target = refactor ? ".gtd/REFACTOR.md" : ".gtd/REQUIREMENTS.md";
-	const fence = refactor ? `- The next refactor may change only these paths, and never a test file
-  or a flag read:
+	const fence = refactor ? `- The next refactor may change only these paths, plus an existing test
+  file's call sites, and never a flag read:
 ${refactor.strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
-  A concern needing any other path, a test file, a new or added flag
-  read, or a change in behaviour (that belongs to the feature, not this
+  A concern needing any other path, a new or changed test or assertion,
+  a new or added flag read, or a change in behaviour (that belongs to the feature, not this
   refactor) cannot be built: do not fold it
 ` : "";
 	const actionable = refactor ? `The round is actionable if the human left a note on
@@ -1207,7 +1216,7 @@ ${removed.map(({ path, lines }) => lines.map((a) => `    ${path} — ${a.scenari
 const lapRange = {
 	first: "it covers everything since the base.",
 	feedback: "it starts at the previous review's boundary, so it covers only what is new since the previous review.",
-	refactor: "it covers the whole refactor since it started, on every round."
+	refactor: "it covers the whole refactor since it started, on every round. A refactor may update an existing test's call sites only: give any test-file hunk its own chunk, and say so if it changes a test, an assertion or an expected value."
 };
 const buildReviewReviewingPrompt = (base, lap, carry, removed = []) => `${styleBlock}
 

package/dist/chunks/{tail--WYGA4LA.mjs → tail-pgq1Fbbv.mjs}

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../flows.mjs";
 import { fixFindings, lensesOf, qualityLap as qualityLap$1, reviewToHandOff } from "../workflow-kit.mjs";
-import { E as reviewing, S as fixRisks, T as reviewQuality, W as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, c as escalation, d as healthy, m as QUALITY, u as guarded, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-vvu5yc3I.mjs";
+import { E as reviewing, S as fixRisks, T as reviewQuality, W as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, c as escalation, d as healthy, m as QUALITY, u as guarded, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-BduvUQxQ.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/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
-import { _t as registryEntry, a as flagShipped, dt as defaults, ft as envDefaults, ht as flagReferences, i as skills, n as summary, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-vvu5yc3I.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail--WYGA4LA.mjs";
+import { _t as registryEntry, a as flagShipped, dt as defaults, ft as envDefaults, ht as flagReferences, i as skills, n as summary, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-BduvUQxQ.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-pgq1Fbbv.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 () => {

package/dist/workflows/feature.mjs

@@ -1,7 +1,7 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, judgeDiffShape, kept, mark, matches, numeric, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, slice, start, vars } from "../flows.mjs";
 import { lensesOf, review as review$1 } from "../workflow-kit.mjs";
-import { $ as refactorFixPrompt, A as architectureDecomposePrompt, B as designSystem, C as planner, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as idleMessage, I as buildReviewTriageMessage, J as naivePassPrompt, K as implementBuildingPrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as refactorDroppedRefusal, R as deferNotesScript, S as fixRisks, V as designTriagePrompt, X as packagesItemFixSuitePrompt, Y as packagesItemBuildingPrompt, Z as refactorBuildingPrompt, _ as REVIEW, at as reviewerSystem, b as fixCheck, ct as startGateBlockedMessage, d as healthy, dt as defaults, et as refactorRules, f as ARCHITECTURE, ft as envDefaults, g as REQUIREMENTS, h as REFACTOR, i as skills, it as reviewNotesCapture, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as gate, lt as unwindFailedMessage, n as summary, nt as reviewEditsCapture, o as shipped, ot as seamByHandMessage, p as FEEDBACK, pt as testFileGlobs, q as implementFixPrompt, r as access, st as seamSteerMessage, t as steering, tt as reviewEditNotesCapture, u as guarded, ut as unwindFailure, v as awaitReview, w as reviewMissing, y as coder, z as designGateAnswerMessage } from "../chunks/reserved-vvu5yc3I.mjs";
-import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail--WYGA4LA.mjs";
+import { $ as refactorFixPrompt, A as architectureDecomposePrompt, B as designSystem, C as planner, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as idleMessage, I as buildReviewTriageMessage, J as naivePassPrompt, K as implementBuildingPrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as refactorDroppedRefusal, R as deferNotesScript, S as fixRisks, V as designTriagePrompt, X as packagesItemFixSuitePrompt, Y as packagesItemBuildingPrompt, Z as refactorBuildingPrompt, _ as REVIEW, at as reviewerSystem, b as fixCheck, ct as startGateBlockedMessage, d as healthy, dt as defaults, et as refactorRules, f as ARCHITECTURE, ft as envDefaults, g as REQUIREMENTS, h as REFACTOR, i as skills, it as reviewNotesCapture, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as gate, lt as unwindFailedMessage, n as summary, nt as reviewEditsCapture, o as shipped, ot as seamByHandMessage, p as FEEDBACK, pt as testFileGlobs, q as implementFixPrompt, r as access, st as seamSteerMessage, t as steering, tt as reviewEditNotesCapture, u as guarded, ut as unwindFailure, v as awaitReview, w as reviewMissing, y as coder, z as designGateAnswerMessage } from "../chunks/reserved-BduvUQxQ.mjs";
+import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-pgq1Fbbv.mjs";
 //#region src/workflows/shared/fences.ts
 const markFenced = (text) => {
 	let fence;
@@ -516,6 +516,35 @@ const requireNoTestFiles = () => {
 	if (tests.length === 0) return;
 	refuse(`gtd land: refactor-tests: the refactor may not change a test file — revert these:\n${tests.map((path) => `  - ${path}`).join("\n")}`);
 };
+const holdsCallSites = (path) => !path.endsWith(".feature") && !path.endsWith(".snap");
+const COMMENT = /(?<![*/])\/\*[\s\S]*?\*\/|(?<!:)\/\/.*$/gm;
+const ASSERTION = /\b(?:expect|assert\w*)\s*[.(]/g;
+const TEST_CASE = /(?<![.\w])x?(?:it|test|describe)\s*[.(]/g;
+const MODIFIER = /(?<![.\w])(?:it|test|describe)\.(skip|only|todo|fails|skipIf|runIf)\b|(?<![.\w])(x)(?:it|test|describe)\b/g;
+const counts = (text) => {
+	const live = text.replace(COMMENT, "");
+	const modifiers = [...live.matchAll(MODIFIER)].map((m) => m[1] ?? m[2]).sort();
+	return JSON.stringify([
+		[...live.matchAll(ASSERTION)].length,
+		[...live.matchAll(TEST_CASE)].length,
+		modifiers
+	]);
+};
+const tested = (text) => {
+	const live = text.replace(COMMENT, "");
+	return live.search(ASSERTION) >= 0 || live.search(TEST_CASE) >= 0;
+};
+const callSitesOnly = ({ path, status, before, after }) => status === "modified" && holdsCallSites(path) && before !== void 0 && after !== void 0 && tested(before) && counts(before) === counts(after);
+/**
+* The test-file half of the refactor guard: an existing test may follow a changed call shape,
+* nothing more. Returns the test files it admitted, which the scope check then allows.
+*/
+const requireTestCallSitesOnly = () => {
+	const tests = changes().filter((c) => isCode(c.path) && isTestFile(c.path));
+	const refused = tests.filter((c) => !callSitesOnly(c)).map((c) => c.path);
+	if (refused.length > 0) refuse(`gtd land: refactor-tests: the refactor may update an existing test file's call sites only — never add, delete, skip or comment out a test or an assertion, or touch a snapshot, a .feature file or test data; revert these:\n${refused.map((path) => `  - ${path}`).join("\n")}`);
+	return tests.map((c) => c.path);
+};
 const flagExpression = (pattern) => {
 	if (pattern.trim() === "") throw new Error("gtd: refactorFlagPattern must not be blank");
 	let expression;
@@ -571,12 +600,16 @@ const packageLines = (strays, pattern, reference) => [
 	"## Rules",
 	"",
 	"- The suite's outcome must not change",
-	"- Change only the paths above, and never a test file",
+	"- Change only the paths above, plus an existing test file where a changed call shape reaches it: never add or delete a test file, and never add, remove or alter a test or an assertion",
 	`- Introduce no flag read and add no second read of an existing one (\`${pattern}\`)`,
 	"",
 	"## Reference",
 	"",
-	reference === void 0 ? "None." : `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+	...reference === void 0 ? ["None."] : [
+		`Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+		"",
+		"Its changes to the existing code above are the seam this refactor exists to land, minus the feature's own behaviour."
+	],
 	""
 ];
 const demoteHeadings = (text) => {
@@ -609,8 +642,7 @@ const plan = (shape, options) => {
 	};
 };
 const guardOf = ({ pattern, strays }, entry) => () => {
-	requireNoTestFiles();
-	requireWithin(strays);
+	requireWithin([...strays, ...requireTestCallSitesOnly()]);
 	requireNoNewFlags(pattern, entry);
 };
 /** Derive, build, check and close one refactor lap; `feedback` is the collected review text of the lap before. */
@@ -651,7 +683,11 @@ const refactorLap = async (p, guard, feedback) => {
 	});
 	await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" });
 };
-const strayAccess = (strays) => ({ write: [...strays, ".gtd/**"] });
+const strayAccess = (strays) => ({ write: [
+	...strays,
+	...testFileGlobs,
+	".gtd/**"
+] });
 const refactorFirst = async (shape, options = {}) => {
 	const p = plan(shape, options);
 	if (p === void 0) return false;
@@ -886,4 +922,4 @@ const feature = shipped(ordinaryStart);
 //#region src/workflows/feature/index.ts
 var feature_default = feature;
 //#endregion
-export { REFACTOR_PACKAGE, access, afterTail, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, build, buildTail, collecting, declaredTests, decompose, feature_default as default, defaults, deferNotes, design, envDefaults, feature, fixNits, fixSuite, implement, judgeSeam, naivePass, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, reUnwind, refactorCollecting, refactorFirst, refactorStrays, requireDeclaredTests, requireNoNewFlags, requireNoTestFiles, requireWithin, reviewedRefactor, seamBuild, skills, steering, summary, triage, unwind };
+export { REFACTOR_PACKAGE, access, afterTail, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, build, buildTail, collecting, declaredTests, decompose, feature_default as default, defaults, deferNotes, design, envDefaults, feature, fixNits, fixSuite, implement, judgeSeam, naivePass, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, reUnwind, refactorCollecting, refactorFirst, refactorStrays, requireDeclaredTests, requireNoNewFlags, requireNoTestFiles, requireTestCallSitesOnly, requireWithin, reviewedRefactor, seamBuild, skills, steering, summary, triage, unwind };

package/dist/workflows/fix.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
-import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, _ as REVIEW, dt as defaults, ft as envDefaults, i as skills, n as summary, o as shipped, r as access, s as baseline, t as steering, y as coder } from "../chunks/reserved-vvu5yc3I.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail--WYGA4LA.mjs";
+import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, _ as REVIEW, dt as defaults, ft as envDefaults, i as skills, n as summary, o as shipped, r as access, s as baseline, t as steering, y as coder } from "../chunks/reserved-BduvUQxQ.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-pgq1Fbbv.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,6 +1,6 @@
 import { start } from "../flows.mjs";
-import { dt as defaults, ft as envDefaults, i as skills, l as gate, n as summary, o as shipped, r as access, rt as reviewGateBlockedMessage, t as steering } from "../chunks/reserved-vvu5yc3I.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail--WYGA4LA.mjs";
+import { dt as defaults, ft as envDefaults, i as skills, l as gate, n as summary, o as shipped, r as access, rt as reviewGateBlockedMessage, t as steering } from "../chunks/reserved-BduvUQxQ.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-pgq1Fbbv.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/dist/workflows/rollout.mjs

@@ -1,5 +1,5 @@
 import { agent, changesSince, glob, head, mark, read, refuse, removeScript, run, scope, vars } from "../flows.mjs";
-import { a as flagShipped, dt as defaults, ft as envDefaults, gt as flipProblems, i as skills, l as gate, mt as flagMentions, n as summary, p as FEEDBACK, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-vvu5yc3I.mjs";
+import { a as flagShipped, dt as defaults, ft as envDefaults, gt as flipProblems, i as skills, l as gate, mt as flagMentions, n as summary, p as FEEDBACK, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-BduvUQxQ.mjs";
 //#region src/workflows/rollout/rollout.ts
 const flippingPrompt = (name, registry) => `Roll out the release flag "${name}": in ${registry}, set \`defaultOn: true\` on its entry. Change nothing else — no other entry, no other field, no other file, no comments.`;
 const suiteBlockedMessage = () => "The suite is red after the rollout. Fix it by hand — a rollout may only touch the flag's registry entry — then land.";

package/dist/workflows.mjs

@@ -17554,9 +17554,13 @@ ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `;
 const refactorRules = (strays, pattern) => `- Behaviour-neutral: the suite's outcome must not change
-- Change only these paths, nothing else, and never a test file even
-  when it is one of them:
+- Change only these paths, nothing else:
 ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
+- An existing test file only where a changed call shape reaches it:
+  update its call sites, inside an assertion too;
+  never add or delete a test file,
+  never add, remove or alter a test or an assertion, and never
+  change what an assertion checks, an expected value or a snapshot
 - Introduce no new flag read and add no second read of an existing one:
   every match of \`${pattern}\` may move, never increase in number`;
 const withRules = (rules) => rules === void 0 ? "" : `${rules}\n`;
@@ -17566,8 +17570,13 @@ ${feedback ? `- The package carries a \`## Review feedback\` section: a human's
   last refactor. Act on it, within the rules below
 ` : ""}${refactorRules(strays, pattern)}
 ${reference === void 0 ? "" : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
-  earlier attempt at this change. Read it for ideas; never apply,
-  cherry-pick or check it out — write a fresh refactor
+  earlier attempt at this change, and \`git show --stat ${reference}\`
+  lists every file it touched, the test call sites included.
+  Read it; never apply, cherry-pick or check it out
+- Its changes to these paths' existing code are the seam: write that
+  restructuring afresh here, minus the feature's own behaviour. A
+  refactor that touches none of it is wrong, however clean — never
+  swap in an unrelated tidy-up
 `}- Leave everything uncommitted and finish your turn — do not commit
 `;
 const refactorFixPrompt = (strays, pattern) => `${stateFileRules}
@@ -17883,11 +17892,11 @@ const closedFold = (round, target) => round === "edits" ? `- Fold every hand-edi
 /** `refactor` retargets the prompt at `.gtd/REFACTOR.md` and fences it to the strays. A concern outside the fence is not folded; if nothing at all is written the landing is refused, but a partly buildable round drops the rest silently. */
 const buildReviewCollectingPrompt = (capture, refactor) => {
 	const target = refactor ? ".gtd/REFACTOR.md" : ".gtd/REQUIREMENTS.md";
-	const fence = refactor ? `- The next refactor may change only these paths, and never a test file
-  or a flag read:
+	const fence = refactor ? `- The next refactor may change only these paths, plus an existing test
+  file's call sites, and never a flag read:
 ${refactor.strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
-  A concern needing any other path, a test file, a new or added flag
-  read, or a change in behaviour (that belongs to the feature, not this
+  A concern needing any other path, a new or changed test or assertion,
+  a new or added flag read, or a change in behaviour (that belongs to the feature, not this
   refactor) cannot be built: do not fold it
 ` : "";
 	const actionable = refactor ? `The round is actionable if the human left a note on
@@ -17991,7 +18000,7 @@ ${removed.map(({ path, lines }) => lines.map((a) => `    ${path} — ${a.scenari
 const lapRange = {
 	first: "it covers everything since the base.",
 	feedback: "it starts at the previous review's boundary, so it covers only what is new since the previous review.",
-	refactor: "it covers the whole refactor since it started, on every round."
+	refactor: "it covers the whole refactor since it started, on every round. A refactor may update an existing test's call sites only: give any test-file hunk its own chunk, and say so if it changes a test, an assertion or an expected value."
 };
 const buildReviewReviewingPrompt = (base, lap, carry, removed = []) => `${styleBlock}
 
@@ -38344,6 +38353,35 @@ const requireNoTestFiles = () => {
 	if (tests.length === 0) return;
 	refuse(`gtd land: refactor-tests: the refactor may not change a test file — revert these:\n${tests.map((path) => `  - ${path}`).join("\n")}`);
 };
+const holdsCallSites = (path) => !path.endsWith(".feature") && !path.endsWith(".snap");
+const COMMENT = /(?<![*/])\/\*[\s\S]*?\*\/|(?<!:)\/\/.*$/gm;
+const ASSERTION = /\b(?:expect|assert\w*)\s*[.(]/g;
+const TEST_CASE = /(?<![.\w])x?(?:it|test|describe)\s*[.(]/g;
+const MODIFIER = /(?<![.\w])(?:it|test|describe)\.(skip|only|todo|fails|skipIf|runIf)\b|(?<![.\w])(x)(?:it|test|describe)\b/g;
+const counts = (text) => {
+	const live = text.replace(COMMENT, "");
+	const modifiers = [...live.matchAll(MODIFIER)].map((m) => m[1] ?? m[2]).sort();
+	return JSON.stringify([
+		[...live.matchAll(ASSERTION)].length,
+		[...live.matchAll(TEST_CASE)].length,
+		modifiers
+	]);
+};
+const tested = (text) => {
+	const live = text.replace(COMMENT, "");
+	return live.search(ASSERTION) >= 0 || live.search(TEST_CASE) >= 0;
+};
+const callSitesOnly = ({ path, status, before, after }) => status === "modified" && holdsCallSites(path) && before !== void 0 && after !== void 0 && tested(before) && counts(before) === counts(after);
+/**
+* The test-file half of the refactor guard: an existing test may follow a changed call shape,
+* nothing more. Returns the test files it admitted, which the scope check then allows.
+*/
+const requireTestCallSitesOnly = () => {
+	const tests = changes().filter((c) => isCode(c.path) && isTestFile(c.path));
+	const refused = tests.filter((c) => !callSitesOnly(c)).map((c) => c.path);
+	if (refused.length > 0) refuse(`gtd land: refactor-tests: the refactor may update an existing test file's call sites only — never add, delete, skip or comment out a test or an assertion, or touch a snapshot, a .feature file or test data; revert these:\n${refused.map((path) => `  - ${path}`).join("\n")}`);
+	return tests.map((c) => c.path);
+};
 const flagExpression = (pattern) => {
 	if (pattern.trim() === "") throw new Error("gtd: refactorFlagPattern must not be blank");
 	let expression;
@@ -38399,12 +38437,16 @@ const packageLines = (strays, pattern, reference) => [
 	"## Rules",
 	"",
 	"- The suite's outcome must not change",
-	"- Change only the paths above, and never a test file",
+	"- Change only the paths above, plus an existing test file where a changed call shape reaches it: never add or delete a test file, and never add, remove or alter a test or an assertion",
 	`- Introduce no flag read and add no second read of an existing one (\`${pattern}\`)`,
 	"",
 	"## Reference",
 	"",
-	reference === void 0 ? "None." : `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+	...reference === void 0 ? ["None."] : [
+		`Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+		"",
+		"Its changes to the existing code above are the seam this refactor exists to land, minus the feature's own behaviour."
+	],
 	""
 ];
 const demoteHeadings = (text) => {
@@ -38437,8 +38479,7 @@ const plan = (shape, options) => {
 	};
 };
 const guardOf = ({ pattern, strays }, entry) => () => {
-	requireNoTestFiles();
-	requireWithin(strays);
+	requireWithin([...strays, ...requireTestCallSitesOnly()]);
 	requireNoNewFlags(pattern, entry);
 };
 /** Derive, build, check and close one refactor lap; `feedback` is the collected review text of the lap before. */
@@ -38479,7 +38520,11 @@ const refactorLap = async (p, guard, feedback) => {
 	});
 	await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" });
 };
-const strayAccess = (strays) => ({ write: [...strays, ".gtd/**"] });
+const strayAccess = (strays) => ({ write: [
+	...strays,
+	...testFileGlobs,
+	".gtd/**"
+] });
 const refactorFirst = async (shape, options = {}) => {
 	const p = plan(shape, options);
 	if (p === void 0) return false;
@@ -38905,4 +38950,4 @@ var workflows_default = feature;
 */
 const doors = {};
 //#endregion
-export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, awaitReview, base, baseline, build, buildTail, builtInLenses, cleanup, cleanupFlow, closeReview, coder, collecting, declaredTests, decompose, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, envDefaults, escalate, escalation, escalationExhausted, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, fixSuite, gate, guarded, handOffReview, handOffTail, healthy, implement, judgeSeam, lensesOf, naivePass, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, planner, qualityLap, reUnwind, refactorCollecting, refactorFirst, refactorStrays, requireDeclaredTests, requireNoNewFlags, requireNoTestFiles, requireWithin, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewedRefactor, reviewing, rollout, rolloutFlow, seamBuild, skills, steering, summary, tail, threads, triage, unwind };
+export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, awaitReview, base, baseline, build, buildTail, builtInLenses, cleanup, cleanupFlow, closeReview, coder, collecting, declaredTests, decompose, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, envDefaults, escalate, escalation, escalationExhausted, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, fixSuite, gate, guarded, handOffReview, handOffTail, healthy, implement, judgeSeam, lensesOf, naivePass, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, planner, qualityLap, reUnwind, refactorCollecting, refactorFirst, refactorStrays, requireDeclaredTests, requireNoNewFlags, requireNoTestFiles, requireTestCallSitesOnly, requireWithin, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewedRefactor, reviewing, rollout, rolloutFlow, seamBuild, skills, steering, summary, tail, threads, triage, unwind };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "29.2.2",
+  "version": "29.2.4",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/workflows/feature/refactor-review.feature

@@ -13,7 +13,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
     And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
 
-  Scenario: with a narrowed seamAllow a test-named file written by the refactor is refused
+  Scenario: with a narrowed seamAllow a test file added by the refactor is refused
     Given an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
     And an environment variable "GTD_SEAMALLOW" set to "docs/**"
     And a file "src/calc.ts" with:
@@ -85,12 +85,12 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       import { expect, it } from "vitest"
       it("adds", () => expect(2 + 2).toBe(4))
       """
-    And step "refactor.building" writes "src/calc.test.ts" with:
+    And step "refactor.building" writes "src/calc.spec.ts" with:
       """
       import { expect, it } from "vitest"
       it("adds", () => expect(3 + 3).toBe(6))
       """
-    Then driving the process is refused with "outside its write access"
+    Then driving the process is refused with "refactor-tests"
 
 
   Scenario: refactorQualityReviews picks the refactor's lenses and qualityReviews does not reach them
@@ -1607,6 +1607,40 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       And ".gtd/REFACTOR.md" contains "src/calc.ts"
       And ".gtd/REFACTOR.md" does not contain "src/calc.test.ts"
 
+    Scenario: the refactor updates an existing test's call sites to the seam's new shape
+      Given step "seam.naive" writes "src/calc.ts" with:
+        """
+        export const add = ({ a, b }: { a: number; b: number }) => a + b
+        export const subtract = ({ a, b }: { a: number; b: number }) => a - b
+        """
+      And step "refactor.deriving" runs its script
+      And step "refactor.building" writes "src/calc.ts" with:
+        """
+        export const add = ({ a, b }: { a: number; b: number }) => a + b
+        """
+      And step "refactor.building" writes "src/calc.test.ts" with:
+        """
+        import { expect, it } from "vitest"
+        import { add } from "./calc"
+        it("adds", () => expect(add({ a: 1, b: 1 })).toBe(2))
+        """
+      When the process is driven
+      Then the process rests at "refactor.health.check"
+
+    Scenario: the refactor may not drop an assertion from an existing test
+      Given step "seam.naive" writes "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        export const subtract = (a: number, b: number) => a - b
+        """
+      And step "refactor.deriving" runs its script
+      And step "refactor.building" writes "src/calc.test.ts" with:
+        """
+        import { it } from "vitest"
+        it("adds", () => {})
+        """
+      Then driving the process is refused with "refactor-tests"
+
     Scenario: a refactor-first whose strays are all test files goes straight to implement
       Given step "seam.naive" writes "src/calc.test.ts" with:
         """

package/src/workflows/feature/refactor.test.ts

@@ -13,6 +13,7 @@ import {
   refactorStrays,
   requireNoNewFlags,
   requireNoTestFiles,
+  requireTestCallSitesOnly,
   requireWithin,
   reviewedRefactor,
   REFACTOR_PACKAGE,
@@ -20,6 +21,15 @@ import {
 
 afterEach(() => installContext(undefined))
 
+const testFileGlobs = [
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*.feature",
+  "**/tests/**",
+  "**/test/**",
+  "**/__tests__/**",
+]
+
 const change = (
   path: string,
   before: string | undefined,
@@ -131,6 +141,137 @@ describe("requireNoTestFiles", () => {
   })
 })
 
+describe("requireTestCallSitesOnly", () => {
+  it("refuses an added or deleted test path, naming it", () => {
+    const list = [
+      change("tests/unit/b.ts", undefined, "x", "added"),
+      change("src/__tests__/c.ts", "a", undefined, "deleted"),
+      change("src/a.test.ts", "expect(a()).toBe(1)", "expect(a(1)).toBe(1)"),
+    ]
+    const message = withChanges(list, () => requireTestCallSitesOnly())
+    expect(message).toMatch(/^gtd land: refactor-tests: /)
+    expect(message).toContain("  - tests/unit/b.ts")
+    expect(message).toContain("  - src/__tests__/c.ts")
+    expect(message).not.toContain("src/a.test.ts")
+  })
+
+  it("passes a modified test file's call site, non-test paths and .gtd/ paths", () => {
+    const list = [
+      change("src/a.test.ts", "expect(a()).toBe(1)", "expect(a(1)).toBe(1)"),
+      change("src/new.ts", undefined, "x", "added"),
+      change(".gtd/tests/x.md", "", "x", "added"),
+    ]
+    expect(withChanges(list, () => requireTestCallSitesOnly())).toBeUndefined()
+  })
+
+  it("refuses a snapshot change and a dropped test or assertion, naming each", () => {
+    const list = [
+      change("src/__snapshots__/a.test.ts.snap", "a", "b"),
+      change("src/b.test.ts", 'it("a", () => {})\nit("b", () => {})', 'it("a", () => {})'),
+      change("src/c.test.ts", "expect(c()).toBe(1)\nexpect(c()).toBe(1)", "expect(c()).toBe(1)"),
+      change(
+        "d.feature",
+        "Feature: d\n  Scenario: d\n    Then it is\n",
+        "Feature: d\n  Scenario: d\n",
+      ),
+    ]
+    const message = withChanges(list, () => requireTestCallSitesOnly())
+    for (const { path } of list) expect(message).toContain(`  - ${path}`)
+  })
+
+  it.each([
+    [
+      "a skipped test",
+      'it("a", () => expect(a()).toBe(1))',
+      'it.skip("a", () => expect(a()).toBe(1))',
+    ],
+    [
+      "an x-prefixed test",
+      'it("a", () => expect(a()).toBe(1))',
+      'xit("a", () => expect(a()).toBe(1))',
+    ],
+    [
+      "a line-commented assertion",
+      'it("a", () => {\n  expect(a()).toBe(1)\n})',
+      'it("a", () => {\n  // expect(a()).toBe(1)\n})',
+    ],
+    [
+      "a block-commented test",
+      'it("a", () => expect(a()).toBe(1))',
+      '/* it("a", () => expect(a()).toBe(1)) */',
+    ],
+    [
+      "a .skip swapped for an .only",
+      'it.skip("a", () => expect(a()).toBe(1))\nit("b", () => expect(b()).toBe(1))',
+      'it.only("a", () => expect(a()).toBe(1))\nit("b", () => expect(b()).toBe(1))',
+    ],
+    [
+      "an assertion dropped after a URL in a test name",
+      'it("GET http://x", () => expect(get()).toBe(1))',
+      'it("GET http://x", () => {})',
+    ],
+    ["fixture data with no test", '{"sum": 2}', '{"sum": 3}'],
+  ])("refuses %s", (_label, before, after) => {
+    const message = withChanges([change("tests/a.test.ts", before, after)], () =>
+      requireTestCallSitesOnly(),
+    )
+    expect(message).toContain("  - tests/a.test.ts")
+  })
+
+  it("refuses a modified test file whose content cannot be read", () => {
+    const message = withChanges([change("tests/a.test.ts", undefined, "expect(a()).toBe(1)")], () =>
+      requireTestCallSitesOnly(),
+    )
+    expect(message).toContain("  - tests/a.test.ts")
+  })
+
+  it("passes a regex .test( call rewritten at a call site", () => {
+    const list = [
+      change(
+        "src/a.test.ts",
+        'it("a", () => expect(/x/.test(s)).toBe(true))',
+        'it("a", () => expect(has(s)).toBe(true))',
+      ),
+    ]
+    expect(withChanges(list, () => requireTestCallSitesOnly())).toBeUndefined()
+  })
+
+  it("passes a call site rewritten inside an assertion", () => {
+    const list = [
+      change(
+        "src/a.test.ts",
+        'it("adds", () => expect(add(1, 1)).toBe(2))',
+        'it("adds", async () => expect(await add({ a: 1, b: 1 })).toBe(2))',
+      ),
+    ]
+    expect(withChanges(list, () => requireTestCallSitesOnly())).toBeUndefined()
+  })
+
+  it("is not narrowed by a narrowed seamAllow", () => {
+    installContext(
+      fixtureContext(
+        { vars: { seamAllow: "docs/**" } },
+        {
+          changes: () => [change("src/a.test.ts", undefined, "b", "added")],
+          matches: globMatches,
+          refuse: (message) => {
+            throw new Error(message)
+          },
+        },
+      ),
+    )
+    expect(refusal(() => requireTestCallSitesOnly())).toContain("src/a.test.ts")
+  })
+
+  it("does not refuse other naming such as _test.go or test_*.py", () => {
+    const list = [
+      change("pkg/a_test.go", undefined, "b", "added"),
+      change("pkg/test_a.py", undefined, "b", "added"),
+    ]
+    expect(withChanges(list, () => requireTestCallSitesOnly())).toBeUndefined()
+  })
+})
+
 describe("refactorStrays", () => {
   it("refactorStrays drops test files, keeps the rest and ignores a narrowed seamAllow", () => {
     installContext(fixtureContext({ vars: { seamAllow: "docs/**" } }, { matches: globMatches }))
@@ -359,7 +500,7 @@ describe("refactorFirst", () => {
     const body = derive?.kind === "run" ? derive.body : ""
     expect(body).toContain("`src/a.ts`") // gtd-path-exempt: fixture paths
     expect(body).not.toContain("a.test.ts")
-    expect(h.scopes[0]?.access).toEqual({ write: ["src/a.ts", ".gtd/**"] })
+    expect(h.scopes[0]?.access).toEqual({ write: ["src/a.ts", ...testFileGlobs, ".gtd/**"] })
   })
 
   it("throws before any step when a stray holds a flag read the pattern matches zero-length", async () => {
@@ -403,10 +544,13 @@ describe("refactorFirst", () => {
     expect(lines).toEqual(["- `src/z.ts`", "- `src/a.ts`", "- `it's.ts`"]) // gtd-path-exempt: fixture paths
   })
 
-  it("runs inside a refactor scope whose write access is the strays plus .gtd/**", async () => {
+  it("runs inside a refactor scope whose write access is the strays, test files and .gtd/**", async () => {
     const h = await drive(shape())
     expect(h.scopes).toEqual([
-      { name: "refactor", access: { write: ["src/a.ts", "src/b.ts", ".gtd/**"] } },
+      {
+        name: "refactor",
+        access: { write: ["src/a.ts", "src/b.ts", ...testFileGlobs, ".gtd/**"] },
+      },
     ])
   })
 
@@ -439,19 +583,38 @@ describe("refactorFirst", () => {
     expect(names(h)).not.toContain("health.check")
   })
 
-  it("refuses a build turn changing a test file even when it is a stray", async () => {
-    const h = await drive(shape({ strays: ["src/a.ts", "src/a.test.ts"] }), {
-      build: [change("src/a.test.ts", "a", "b")],
+  it("lets a build turn update an existing test file's call sites", async () => {
+    const h = await drive(shape(), {
+      build: [
+        change("src/a.ts", "a", "b"),
+        change("tests/a.test.ts", "expect(a()).toBe(1)", "expect(await a()).toBe(1)"),
+      ],
+    })
+    expect(h.result).toBe(true)
+    expect(names(h)).toContain("health.check")
+  })
+
+  it("refuses a build turn adding a test file", async () => {
+    const h = await drive(shape(), {
+      build: [change("src/a.test.ts", undefined, "b", "added")],
     })
     expect((h.result as Error).message).toContain("refactor-tests")
     expect((h.result as Error).message).toContain("src/a.test.ts")
     expect(names(h)).not.toContain("health.check")
   })
 
-  it("says never a test file in the package rules", async () => {
+  it("lets the package rules admit only an existing test file's call sites", async () => {
     const h = await drive(shape())
-    expect(bodyOf(h, 0)).toContain("never a test file")
-    expect(bodyOf(h, 0)).not.toContain("only when it is one of them")
+    expect(bodyOf(h, 0)).toContain("never add or delete a test file")
+    expect(bodyOf(h, 0)).toContain("never add, remove or alter a test or an assertion")
+  })
+
+  it("names the reference's seam as the change to carry, when there is a reference", async () => {
+    const withRef = await drive(shape(), { reference: "abc1234" })
+    expect(bodyOf(withRef, 0)).toMatch(/seam/)
+    expect(buildingPrompt(withRef)).toMatch(/touches none of it/)
+    const bare = await drive(shape())
+    expect(buildingPrompt(bare)).not.toMatch(/touches none of it/)
   })
 
   it("refuses a build turn adding a flag read", async () => {
@@ -734,7 +897,7 @@ describe("reviewedRefactor", () => {
     const body = derive?.kind === "run" ? derive.body : ""
     expect(body).toContain("`src/a.ts`") // gtd-path-exempt: fixture paths
     expect(body).not.toContain("a.test.ts")
-    expect(h.scopes[0]?.access).toEqual({ write: ["src/a.ts", ".gtd/**"] })
+    expect(h.scopes[0]?.access).toEqual({ write: ["src/a.ts", ...testFileGlobs, ".gtd/**"] })
     const collecting = h.steps.find((s) => s.kind === "agent" && s.name === "review.collecting")
     const prompt = collecting?.kind === "agent" ? collecting.prompt : ""
     expect(prompt).toContain("`src/a.ts`") // gtd-path-exempt: fixture paths
@@ -958,14 +1121,18 @@ describe("reviewedRefactor", () => {
       const h = await driveReviewed(shape({ strays: ["src/a.ts", "src/a.test.ts"] }), {
         notes: ["add — typo"],
         answers: { "note-1": { answer: "nit", p: 0.9 } },
-        turns: { "refactor.build.review.fix.nits.fixing": [change("src/a.test.ts", "a", "b")] },
+        turns: {
+          "refactor.build.review.fix.nits.fixing": [
+            change("src/a.test.ts", undefined, "b", "added"),
+          ],
+        },
       })
       expect((h.result as Error).message).toContain("refactor-tests")
       expect(h.names.at(-1)).toBe("refactor.build.review.fix.nits.fixing")
     })
 
-    it("runs the nit-fix turn under the strays plus .gtd/** as its write access", async () => {
-      const write = ["src/a.ts", ".gtd/**"]
+    it("runs the nit-fix turn under the strays, test files and .gtd/** as its write access", async () => {
+      const write = ["src/a.ts", ...testFileGlobs, ".gtd/**"]
       const h = await driveReviewed(shape({ strays: ["src/a.ts", "src/a.test.ts"] }), {
         notes: ["add — typo"],
         answers: { "note-1": { answer: "nit", p: 0.9 } },
@@ -979,7 +1146,7 @@ describe("reviewedRefactor", () => {
         notes: ["add — typo"],
         answers: { "note-1": { answer: "nit", p: 0.9 } },
         reds: 2,
-        turns: { "refactor.build.fix": [change("src/a.test.ts", "x", "y")] },
+        turns: { "refactor.build.fix": [change("src/a.test.ts", "x", undefined, "deleted")] },
       })
       expect(h.names).toContain("refactor.build.fix")
       expect((h.result as Error).message).toContain("refactor-tests")
@@ -1031,11 +1198,11 @@ describe("reviewedRefactor's tail prompts", () => {
     ],
     ["refactor.build.health.describe", { findings: true, reds: 6 }],
   ] as const)(
-    "%s names every stray and bans test files and new flag reads",
+    "%s names every stray and bans new test files and new flag reads",
     async (name, script) => {
       const prompt = await promptAt(name, script as ReviewedScript)
       for (const stray of strays) expect(prompt).toContain(`\`${stray}\``)
-      expect(prompt).toContain("never a test file")
+      expect(prompt).toContain("never add or delete a test file")
       expect(prompt).toContain("no new flag read")
     },
   )

package/src/workflows/feature/refactor.ts

@@ -10,6 +10,7 @@ import {
   run,
   scope,
   vars,
+  type Change,
   type DiffShapeResult,
 } from "../../flows/index.js"
 import { lensesOf } from "../../workflow-kit/index.js"
@@ -43,6 +44,7 @@ export const requireWithin = (allowed: readonly string[]): void => {
 // A fixed list, not `seamAllow`: narrowing that setting must not let a test file through.
 const isTestFile = (path: string): boolean => testFileGlobs.some((glob) => matches(path, glob))
 
+// The bundled refactor uses `requireTestCallSitesOnly`; this stays a public export.
 export const requireNoTestFiles = (): void => {
   const tests = changes()
     .map((c) => c.path)
@@ -53,6 +55,58 @@ export const requireNoTestFiles = (): void => {
   )
 }
 
+// Call sites live in code: a `.feature` file or a snapshot holds only expectations.
+const holdsCallSites = (path: string): boolean =>
+  !path.endsWith(".feature") && !path.endsWith(".snap")
+
+// `//` after a `:` (a URL) and `/*` after `*` or `/` (a glob) sit in strings, not comments.
+const COMMENT = /(?<![*/])\/\*[\s\S]*?\*\/|(?<!:)\/\/.*$/gm
+const ASSERTION = /\b(?:expect|assert\w*)\s*[.(]/g
+const TEST_CASE = /(?<![.\w])x?(?:it|test|describe)\s*[.(]/g
+const MODIFIER =
+  /(?<![.\w])(?:it|test|describe)\.(skip|only|todo|fails|skipIf|runIf)\b|(?<![.\w])(x)(?:it|test|describe)\b/g
+
+// Modifiers count per kind, so swapping a `.skip` for an `.only` shows.
+const counts = (text: string): string => {
+  const live = text.replace(COMMENT, "")
+  const modifiers = [...live.matchAll(MODIFIER)].map((m) => m[1] ?? m[2]).sort()
+  return JSON.stringify([
+    [...live.matchAll(ASSERTION)].length,
+    [...live.matchAll(TEST_CASE)].length,
+    modifiers,
+  ])
+}
+
+const tested = (text: string): boolean => {
+  const live = text.replace(COMMENT, "")
+  return live.search(ASSERTION) >= 0 || live.search(TEST_CASE) >= 0
+}
+
+// A call-shape update keeps every live test and assertion, so the counts hold. A changed
+// expected value keeps every count — that is left to the refactor review.
+const callSitesOnly = ({ path, status, before, after }: Change): boolean =>
+  status === "modified" &&
+  holdsCallSites(path) &&
+  before !== undefined &&
+  after !== undefined &&
+  // A file with no test or assertion is fixture or helper data, never a call site to follow.
+  tested(before) &&
+  counts(before) === counts(after)
+
+/**
+ * The test-file half of the refactor guard: an existing test may follow a changed call shape,
+ * nothing more. Returns the test files it admitted, which the scope check then allows.
+ */
+export const requireTestCallSitesOnly = (): readonly string[] => {
+  const tests = changes().filter((c) => isCode(c.path) && isTestFile(c.path))
+  const refused = tests.filter((c) => !callSitesOnly(c)).map((c) => c.path)
+  if (refused.length > 0)
+    refuse(
+      `gtd land: refactor-tests: the refactor may update an existing test file's call sites only — never add, delete, skip or comment out a test or an assertion, or touch a snapshot, a .feature file or test data; revert these:\n${refused.map((path) => `  - ${path}`).join("\n")}`,
+    )
+  return tests.map((c) => c.path)
+}
+
 const flagExpression = (pattern: string): RegExp => {
   if (pattern.trim() === "") throw new Error("gtd: refactorFlagPattern must not be blank")
   let expression: RegExp
@@ -133,14 +187,18 @@ const packageLines = (
   "## Rules",
   "",
   "- The suite's outcome must not change",
-  "- Change only the paths above, and never a test file",
+  "- Change only the paths above, plus an existing test file where a changed call shape reaches it: never add or delete a test file, and never add, remove or alter a test or an assertion",
   `- Introduce no flag read and add no second read of an existing one (\`${pattern}\`)`,
   "",
   "## Reference",
   "",
-  reference === undefined
-    ? "None."
-    : `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+  ...(reference === undefined
+    ? ["None."]
+    : [
+        `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+        "",
+        "Its changes to the existing code above are the seam this refactor exists to land, minus the feature's own behaviour.",
+      ]),
   "",
 ]
 
@@ -195,9 +253,7 @@ const plan = (shape: DiffShapeResult, options: RefactorOptions): Plan | undefine
 const guardOf =
   ({ pattern, strays }: Plan, entry: string): Guard =>
   () => {
-    // Tests first: a test file is never a stray here, so the scope refusal would mask it.
-    requireNoTestFiles()
-    requireWithin(strays)
+    requireWithin([...strays, ...requireTestCallSitesOnly()])
     requireNoNewFlags(pattern, entry)
   }
 
@@ -241,7 +297,9 @@ const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<vo
   await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" })
 }
 
-const strayAccess = (strays: readonly string[]) => ({ write: [...strays, ".gtd/**"] })
+const strayAccess = (strays: readonly string[]) => ({
+  write: [...strays, ...testFileGlobs, ".gtd/**"],
+})
 
 export const refactorFirst = async (
   shape: DiffShapeResult,

package/src/workflows/shared/text.test.ts

@@ -1066,16 +1066,25 @@ describe("the refactor prompts", () => {
   const strays = ["src/a.ts", "src/b.ts"]
   const pattern = "\\bGTD_FLAG_\\w+"
 
-  it("building and fix rules forbid every test file, with no stray exception", () => {
+  it("building and fix rules admit only call-site updates in existing test files", () => {
     for (const prompt of renderText(() => [
       refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
       refactorFixPrompt(strays, pattern),
     ])) {
-      expect(prompt).toContain("never a test file")
-      expect(prompt).not.toContain("only when it is")
+      expect(prompt).toContain("never add or delete a test file")
+      expect(prompt).toContain("never add, remove or alter a test or an assertion")
     }
   })
 
+  it("building names the reference's seam only when there is a reference", () => {
+    const [bare, ref] = renderText(() => [
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern, reference: "abc1234" }),
+    ])
+    expect(bare).not.toContain("touches none of it")
+    expect(ref).toContain("touches none of it")
+  })
+
   it("building adds the act-on-review-feedback line only when asked", () => {
     const [plain, feedback] = renderText(() => [
       refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
@@ -1096,11 +1105,11 @@ describe("the refactor prompts", () => {
       expect(prompt).toContain("capture-text")
     })
 
-    it("lists the strays and says a non-stray, test-file or flag concern cannot be built", () => {
+    it("lists the strays and says a non-stray, test or flag concern cannot be built", () => {
       expect(prompt).toContain("`src/a.ts`") // gtd-path-exempt: fixture paths
       expect(prompt).toContain("`src/b.ts`") // gtd-path-exempt: fixture paths
       expect(prompt).toMatch(/cannot be built/)
-      expect(prompt).toMatch(/test file/)
+      expect(prompt).toMatch(/test or assertion/)
       expect(prompt).toMatch(/flag/)
       expect(prompt).toMatch(/behaviour/)
       expect(prompt).not.toMatch(/say in the reply/i)
@@ -1231,7 +1240,7 @@ describe("the rules-taking fix prompts", () => {
     (k) => {
       const [bare] = renderText(() => [prompts[k]!()])
       expect(bare).not.toContain("Change only these paths")
-      expect(bare).not.toContain("never a test file")
+      expect(bare).not.toContain("never add or delete a test file")
     },
   )
 
@@ -1242,7 +1251,7 @@ describe("the rules-taking fix prompts", () => {
     })
     expect(prompt).toContain(rules)
     for (const stray of strays) expect(prompt).toContain(`\`${stray}\``)
-    expect(prompt).toContain("never a test file")
+    expect(prompt).toContain("never add or delete a test file")
     expect(prompt).toContain("no new flag read")
   })
 
@@ -1274,6 +1283,15 @@ describe("buildReviewReviewingPrompt lap wording", () => {
   )
 })
 
+it("asks the refactor review, and only it, to flag a test-file hunk that is more than a call site", () => {
+  const [refactor, first] = renderText(() => [
+    buildReviewReviewingPrompt("base", "refactor"),
+    buildReviewReviewingPrompt("base", "first"),
+  ])
+  expect(refactor).toContain("give any test-file hunk its own chunk")
+  expect(first).not.toContain("give any test-file hunk its own chunk")
+})
+
 describe("architectureDecomposePrompt tests rule", () => {
   it("states one rule: write-or-change, relied-on marked (unchanged), no other untouched", () => {
     const prompt = renderText(() => architectureDecomposePrompt()).replace(/\s+/g, " ")

package/src/workflows/shared/text.ts

@@ -465,9 +465,13 @@ ${fixFeedbackPrompt}
 
 export const refactorRules = (strays: readonly string[], pattern: string): string =>
   `- Behaviour-neutral: the suite's outcome must not change
-- Change only these paths, nothing else, and never a test file even
-  when it is one of them:
+- Change only these paths, nothing else:
 ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
+- An existing test file only where a changed call shape reaches it:
+  update its call sites, inside an assertion too;
+  never add or delete a test file,
+  never add, remove or alter a test or an assertion, and never
+  change what an assertion checks, an expected value or a snapshot
 - Introduce no new flag read and add no second read of an existing one:
   every match of \`${pattern}\` may move, never increase in number`
 
@@ -499,8 +503,13 @@ ${
   reference === undefined
     ? ""
     : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
-  earlier attempt at this change. Read it for ideas; never apply,
-  cherry-pick or check it out — write a fresh refactor
+  earlier attempt at this change, and \`git show --stat ${reference}\`
+  lists every file it touched, the test call sites included.
+  Read it; never apply, cherry-pick or check it out
+- Its changes to these paths' existing code are the seam: write that
+  restructuring afresh here, minus the feature's own behaviour. A
+  refactor that touches none of it is wrong, however clean — never
+  swap in an unrelated tidy-up
 `
 }- Leave everything uncommitted and finish your turn — do not commit
 `
@@ -920,11 +929,11 @@ export const buildReviewCollectingPrompt = (
 ): string => {
   const target = refactor ? ".gtd/REFACTOR.md" : ".gtd/REQUIREMENTS.md"
   const fence = refactor
-    ? `- The next refactor may change only these paths, and never a test file
-  or a flag read:
+    ? `- The next refactor may change only these paths, plus an existing test
+  file's call sites, and never a flag read:
 ${refactor.strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
-  A concern needing any other path, a test file, a new or added flag
-  read, or a change in behaviour (that belongs to the feature, not this
+  A concern needing any other path, a new or changed test or assertion,
+  a new or added flag read, or a change in behaviour (that belongs to the feature, not this
   refactor) cannot be built: do not fold it
 `
     : ""
@@ -1048,7 +1057,8 @@ const lapRange: Record<ReviewRange, string> = {
   first: "it covers everything since the base.",
   feedback:
     "it starts at the previous review's boundary, so it covers only what is new since the previous review.",
-  refactor: "it covers the whole refactor since it started, on every round.",
+  refactor:
+    "it covers the whole refactor since it started, on every round. A refactor may update an existing test's call sites only: give any test-file hunk its own chunk, and say so if it changes a test, an assertion or an expected value.",
 }
 
 export const buildReviewReviewingPrompt = (