@pmelab/gtd 9.1.0 → 9.1.1

package/README.md

@@ -143,22 +143,28 @@ landing script opens a **review checkout window**: HEAD is rewound to the review
 base with the working tree untouched, so the whole reviewable change shows up as
 ordinary uncommitted changes in your editor's normal git integration (and files
 added during the process show up as ordinary untracked files, so discarding one
-deletes it). The next landing's own script closes the window before it commits.
-Tick a box as you review each hunk (ticking just records "I read this"), and
-leave a **comment** to request changes: a note on a line, an inline
-`// TODO`-style comment in the code, or a direct code edit. Any comment sends a
-build + re-review round — an agent first turns your comments into an explicit
-instruction list, then a build turn implements it (a re-review then covers only
-the follow-through, and a hand-edit is treated as your own fix the agent
-completes without reverting your lines; a comment can't be silently dropped — a
-build turn that addresses nothing is refused). For the simple flow, the build
-turn that follows through on feedback and the turn that drafts the final squash
-message both resume the same session that built the feature in the first place,
-since the review tail is nested inside that build identity rather than sitting
-beside it. Ticking every box with no comment is the sign-off, which collapses
-the whole process into one commit (a **squash finale** whose message an agent
-drafts). Landing with a box still unticked and no comment is refused (finish
-reviewing first), as is deleting `.gtd/REVIEW.md`.
+deletes it — an untracked file you leave alone is not a pending change, and only
+actually removing it from disk counts as a deletion). The next landing's own
+script closes the window before it commits. Tick a box as you review each hunk
+(ticking just records "I read this"), and leave a **comment** to request
+changes: a note on a line, an inline `// TODO`-style comment in the code, or a
+direct code edit. Any comment sends a build + re-review round — an agent first
+turns your comments into an explicit instruction list, then a build turn
+implements it (a re-review then covers only the follow-through, and a hand-edit
+is treated as your own fix the agent completes without reverting your lines; a
+comment can't be silently dropped — a build turn that addresses nothing is
+refused). For the simple flow, the build turn that follows through on feedback
+and the turn that drafts the final squash message both resume the same session
+that built the feature in the first place, since the review tail is nested
+inside that build identity rather than sitting beside it. Ticking every box with
+no comment is the sign-off, which collapses the whole process into one commit (a
+**squash finale** whose message an agent drafts). Landing with a box still
+unticked and no comment is refused (finish reviewing first), as is deleting
+`.gtd/REVIEW.md`. Both refusals hold wherever the review doc lives: repointing
+`reviewFile` out of `.gtd/` (say to `REVIEW.md` at the repo root) changes
+nothing about them — your own edit to the review doc is never mistaken for a
+code comment, and the doc's pre-turn copy is read at the review window's saved
+head rather than at the rewound `HEAD`.
 
 The same review tail also has a direct entry point —
 `gtd --entry review-gate.check --var reviewBase=<commitish>` starts a brand new
@@ -793,6 +799,13 @@ normalizes `[ ]`/`[x]` checkboxes before comparing). If you plug in your own
 — ticking a box, stripping a paragraph — makes the guard's decision and the
 file's actual content disagree, and gtd will not catch that for you.
 
+One case never runs your `format:` (or `validate:`) at all: a step whose diff
+DELETES the state's own `file:`. Deleting it is a legitimate outcome — a review
+sign-off's whole diff is the review doc's deletion — and there is nothing left
+to format. Emitting the command anyway would make such a step unlandable, since
+`format:` is the first line of a `set -euo pipefail` script and a formatter like
+`prettier --write` exits non-zero on a path that is not there.
+
 ### Built-in steering formats are ordinary modes
 
 `qa` and `review` are gtd's two built-in steering-file formats (parsed and
@@ -1098,12 +1111,14 @@ the compiler's job at load time.
 - **Test/build artifacts must be gitignored.** This is **load-bearing**, not a
   style preference: every land decision detects "clean" via
   `git diff --name-status HEAD` (tracked changes) unioned with
-  `git ls-files --others --exclude-standard` (untracked files), which silently
-  omits anything matched by `.gitignore`. If a `script` state's command (or the
-  build it triggers) writes output — a `dist/`, a coverage report, a log file —
-  into the working tree, the tree never goes clean after a green run, and the
-  check's `"C"` pattern never fires. Gitignore every path your scripts write
-  before wiring gtd into a repo.
+  `git ls-files --others --exclude-standard` (untracked files, classified by
+  content against the base — one that is already there with the same bytes is
+  not a change, and a file that exists on disk is never reported as a deletion,
+  however the index sees it), which silently omits anything matched by
+  `.gitignore`. If a `script` state's command (or the build it triggers) writes
+  output — a `dist/`, a coverage report, a log file — into the working tree, the
+  tree never goes clean after a green run, and the check's `"C"` pattern never
+  fires. Gitignore every path your scripts write before wiring gtd into a repo.
 - **Repository root invocation.** Every state subcommand must run from the git
   repository root. `--help`/`--version` (and the `help`/`version` subcommands),
   `lsp`, `init`, `visualize`, `check`, and `install` skip this guard entirely

package/dist/gtd.bundle.mjs

@@ -192745,6 +192745,87 @@ const parseNameStatus = (out) => {
 	}
 	return result;
 };
+/** Split a `-z` git output into its entries, dropping the trailing empty one. */
+const splitNul = (out) => out.split("\0").filter((s) => s.length > 0);
+/**
+* `git ls-tree` the given paths at `ref` → `path → blob object id`; a path
+* absent from the map does not exist at `ref`. Pathspec-limited, so the cost
+* tracks the candidate list rather than the size of the tree. An unresolvable
+* `ref` (an empty repo has no `HEAD`) yields an empty map — every candidate
+* then reads as "not at `ref`", exactly the pre-`base` behaviour.
+*/
+const blobsAtRef = (exec, ref, paths) => exec("git", "ls-tree", "-r", "-z", ref, "--", ...paths).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")), map$4((out) => {
+	const blobs = /* @__PURE__ */ new Map();
+	for (const entry of splitNul(out)) {
+		const tab = entry.indexOf("	");
+		if (tab === -1) continue;
+		const [, type, oid] = entry.slice(0, tab).split(" ");
+		if (type === "blob" && oid !== void 0) blobs.set(entry.slice(tab + 1), oid);
+	}
+	return blobs;
+}));
+/**
+* `git hash-object` every path's CURRENT bytes in ONE call → `path → object id`
+* (git prints one id per path, in argument order). An empty map when the call
+* fails at all (an unreadable file): every candidate then reads as "differs",
+* which is the safe direction — a file that EXISTS must never be reported
+* deleted.
+*
+* These ids are directly comparable with the ones `git ls-tree` reports because
+* hash-object applies the repo's own CLEAN FILTERS, looking each file's
+* attributes up from its own path — so in a `text=auto`/`core.autocrlf` repo an
+* untouched CRLF working-tree file hashes to the same LF-normalized blob git
+* stored, and is correctly read as unchanged. Never add `--no-filters` (nor
+* `--path=<other>`) here: that would report every such file `M`, i.e. a
+* spurious "the human edited something real" (`StepGuards`'s `hasCodeChange`),
+* which walks the review-signoff guard past its unticked-box check, plus a
+* spurious change for any `on` pattern to match. Both tiers of the
+* `changedPaths` contract pin this (`src/testing/GitTiers.ts`).
+*
+* A symlink is the one residual inexactness: hash-object reads through it, so it
+* hashes the target's content rather than the link text git stores, and reads as
+* `M`. Still never `D`.
+*/
+const hashObjects = (exec, paths) => exec("git", "hash-object", "--", ...paths).pipe(map$4((out) => new Map(out.trim().split("\n").map((oid, i) => [paths[i] ?? "", oid.trim()]))), catchIf((e) => !isIndexLockError(e), () => succeed$3(/* @__PURE__ */ new Map())));
+/**
+* Classify every untracked path against `ref`'s tree, by CONTENT:
+*
+* - not at `ref` → `A`, an ordinary untracked addition
+* - at `ref` with different bytes → `M`
+* - at `ref` with identical bytes → no entry at all
+*
+* The last two exist because "untracked" does not mean "new": the review
+* checkout window's `git reset --mixed <base>` moves the index to the review
+* base, so every file the reviewed range ADDED is untracked while being
+* perfectly present (and usually unchanged) at the window's saved head. Read
+* from the worktree rather than the index, this is the same tree-vs-worktree
+* comparison the in-memory double has always done (`InMemRepo`'s
+* `changedPathsWorktree`) — production used to disagree with it here.
+*
+* "Different bytes" is decided the way GIT decides it — `hashObjects` hashes
+* through the repo's own clean filters, so a `text=auto` repo's untouched CRLF
+* file matches the LF blob it was stored as. Over-reporting `M` for an untouched
+* file would not be cosmetic: it is a spurious "the human edited something real"
+* (`StepGuards`'s `hasCodeChange`), which sends the review-signoff guard down
+* its it-is-a-comment branch and past the unticked-box check, plus a spurious
+* change for any `on` pattern to match.
+*/
+const classifyUntracked = (exec, ref, untrackedPaths) => gen(function* () {
+	const atRef = yield* blobsAtRef(exec, ref, untrackedPaths);
+	const candidates = untrackedPaths.filter((path) => atRef.has(path));
+	const onDisk = candidates.length === 0 ? /* @__PURE__ */ new Map() : yield* hashObjects(exec, candidates);
+	return untrackedPaths.flatMap((path) => {
+		const at = atRef.get(path);
+		if (at === void 0) return [{
+			path,
+			status: "A"
+		}];
+		return onDisk.get(path) === at ? [] : [{
+			path,
+			status: "M"
+		}];
+	});
+});
 /**
 * True when `error` is git's `index.lock` contention failure — another process
 * held the index lock when git tried to take it. gtd shares one worktree index
@@ -192811,17 +192892,17 @@ const makeGitImpl = (executor, root) => {
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
 		changedPathsSince: (ref) => exec("git", "diff", "--name-status", ref, "HEAD").pipe(map$4(parseNameStatus)),
 		changedPaths: (base) => gen(function* () {
-			const nameStatusOut = yield* exec("git", "diff", "--name-status", base ?? "HEAD").pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
+			const ref = base ?? "HEAD";
+			const nameStatusOut = yield* exec("git", "diff", "--name-status", ref).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
 			const trackedPaths = parseNameStatus(nameStatusOut);
-			const untrackedAll = (yield* exec("git", "ls-files", "--others", "--exclude-standard", "-z")).split("\0").filter((s) => s.length > 0).map((path) => ({
-				path,
-				status: "A"
-			}));
-			const atBase = base === void 0 ? /* @__PURE__ */ new Set() : new Set((yield* exec("git", "ls-tree", "-r", "--name-only", "-z", base)).split("\0").filter((s) => s.length > 0));
-			const untracked = untrackedAll.filter((entry) => !atBase.has(entry.path));
+			const untrackedRaw = yield* exec("git", "ls-files", "--others", "--exclude-standard", "-z");
+			const untrackedPaths = splitNul(untrackedRaw);
+			if (untrackedPaths.length === 0) return trackedPaths;
+			const untrackedChanges = yield* classifyUntracked(exec, ref, untrackedPaths);
+			const untrackedSet = new Set(untrackedPaths);
 			const seen = /* @__PURE__ */ new Set();
 			const all = [];
-			for (const entry of [...trackedPaths, ...untracked]) if (!seen.has(entry.path)) {
+			for (const entry of [...trackedPaths.filter((e) => !untrackedSet.has(e.path)), ...untrackedChanges]) if (!seen.has(entry.path)) {
 				seen.add(entry.path);
 				all.push(entry);
 			}
@@ -194595,6 +194676,7 @@ const restAt = (ref) => gen(function* () {
 		on,
 		stepDef,
 		changes,
+		windowHead,
 		memory,
 		memoryResumed,
 		hints,
@@ -195173,6 +195255,20 @@ const decideOpenWindow = (def, target, run, head) => {
 * Idempotent under re-entry: `updateRef`/`mixedResetTo` re-pointing at the
 * same target is a no-op, and `restoreStagedFrom` re-pinning an already-pinned
 * path is a no-op.
+*
+* `".gtd"` stays a LITERAL, deliberately, rather than being derived from the
+* workflow's own `stateDir`/`file:` declarations. The pin exists to keep gtd's
+* PLUMBING out of the reviewer's editor, and `.gtd/` is the conventional
+* directory it lives in — including the parts no state declares (a check
+* script's temp output), which a `file:`-derived list would miss. A steering
+* file a workflow repoints outside it (`vars: { reviewFile: REVIEW.md }`)
+* simply stays untracked in the window, which is harmless: `changedPaths`
+* classifies untracked paths by content (`src/Git.ts`), so an unedited one is
+* not a pending change and never a phantom deletion. Making the list dynamic
+* would also cost the in-memory tier its trust property — the recognizer
+* (`src/testing/EmittedScriptRecognizer.ts`'s `recognizeReviewWindowOpen`)
+* re-derives this exact string and compares, which only works while the paths
+* are fixed. Don't trade that for cosmetics.
 */
 const buildOpenWindowScript = (decision) => [
 	updateRef(REVIEW_BASE_REF, decision.base),
@@ -206949,6 +207045,15 @@ const openInBrowser = (url) => {
 };
 //#endregion
 //#region src/StepGuards.ts
+/**
+* True when `changes` deletes `file` — the one question BOTH this registry's
+* `GuardContext.fileDeleted` and `program.ts`'s `steeringModeSteps` ask about a
+* state's `file:`, so they ask it in exactly one place. A deletion is a
+* legitimate step outcome at some states (a review sign-off's bare REVIEW.md
+* deletion) and a refusal at others (see `reviewSignoffGuard`), but either way
+* there is no file left to format or validate.
+*/
+const deletesFile = (changes, file) => changes.some((c) => c.path === file && c.status === "D");
 /** Normalize every markdown checkbox to a single placeholder so a pure `[ ]`→`[x]` tick is invisible to a text comparison; any surviving difference is a human note. */
 const normalizeCheckboxes = (content) => content.replace(/\[[ xX]\]/g, "[_]");
 /** The `mode:` name of gtd's built-in REVIEW.md checkbox validator — the only mode the sign-off guard understands. */
@@ -207010,8 +207115,8 @@ const enforceStepGuards = (input) => gen(function* () {
 	if (file === void 0) return;
 	const applicable = stepGuards.filter((g) => g.appliesTo(input.rest));
 	if (applicable.length === 0) return;
-	const fileDeleted = input.changes.some((c) => c.path === file && c.status === "D");
-	const hasCodeChange = input.changes.some((c) => !c.path.startsWith(".gtd/"));
+	const fileDeleted = deletesFile(input.changes, file);
+	const hasCodeChange = input.changes.some((c) => !c.path.startsWith(".gtd/") && c.path !== file);
 	const base = {
 		rest: input.rest,
 		file,
@@ -207021,7 +207126,7 @@ const enforceStepGuards = (input) => gen(function* () {
 		template: input.context
 	};
 	const files = yield* RepoFiles;
-	const head = yield* cached(files.committed(file));
+	const head = yield* cached(files.committed(file, input.windowHead));
 	const worktree = yield* cached(try_(() => files.working(file)));
 	const ctx = {
 		...base,
@@ -207456,11 +207561,22 @@ const headPreconditions = (currentCommit) => ({ expectedHead: currentCommit });
 * of gtd running it in process (see `src/StepGuards.ts`'s shrunk registry).
 * Empty for a state declaring no `file:`+`mode:` pair; an unknown mode name
 * is a refusal, exactly as it was when gtd ran the commands itself.
+*
+* Also empty when the step DELETES that file (`deletesFile`). A deletion is a
+* legitimate outcome at some states — `build.review.deciding`'s sign-off diff
+* is a bare REVIEW.md deletion — and there is nothing left to format or
+* validate either way. Emitting the mode's `format:` anyway made the step
+* UNLANDABLE for any formatter that treats a missing path as an error
+* (`prettier --write` exits non-zero with "No files matching the pattern were
+* found"): it is the first command in a `set -euo pipefail` script, so it
+* aborted the whole thing — window close, commit and all — before anything
+* could land, and a driver saw only a non-zero exit.
 */
 const steeringModeSteps = (rest) => gen(function* () {
 	const file = rest.hints.file;
 	const mode = rest.stateDef.mode;
 	if (file === void 0 || mode === void 0) return [];
+	if (deletesFile(rest.changes, file)) return [];
 	const resolved = resolveSteeringMode(rest.def, mode);
 	if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(rest.def, rest.state, mode)));
 	return (yield* renderSteeringCommands(resolved, file, rest.context)).map((command) => ({
@@ -207508,8 +207624,10 @@ const previewSubject = (decision, rest) => decision.kind === "commit" ? succeed$
 * (decision 6): there is nothing to format/validate in an empty diff, and a
 * `format:` command running ahead of the commit could dirty the tree and
 * turn an "empty" attempt non-empty, breaking the derivation `stalledAt`
-* relies on (`Edge.ts`). The review-window close still runs regardless —
-* committing with a window open would land the attempt on the review base.
+* relies on (`Edge.ts`). It is skipped for a step that DELETES the state's
+* own `file:` too — see `steeringModeSteps`. The review-window close still
+* runs regardless — committing with a window open would land the attempt on
+* the review base.
 */
 const buildRequiredScript = (rest, decision, cost, model) => gen(function* () {
 	const git = yield* GitService;
@@ -207571,6 +207689,7 @@ const planLanding = (opts = {}) => gen(function* () {
 		context: rest.context,
 		file: rest.hints.file,
 		changes: rest.changes,
+		windowHead: rest.windowHead,
 		kind: decision.kind,
 		attempt: isAttemptDecision(decision)
 	});

package/package.json

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