@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/bin/lib/commands.cjs

@@ -625,6 +625,11 @@ function cmdResolveExecution(cwd, agentType, raw, opts) {
  * applies here exactly as everywhere else: an unknown host, a missing axis, or the
  * `undocumented` sentinel all degrade to the safe floor rather than being trusted.
  * Never throws — a lookup failure yields `'none'`, which renders no argument.
+ *
+ * On the module's export surface for #4255: the reviewer-lane effort resolver renders a lane's own
+ * configured level through this same negotiation, so a lane can never emit an argument for a host
+ * whose negotiated surface does not accept one. One negotiation, both channels — a second copy in
+ * the lane path is exactly how the two would drift.
  */
 function effortSurfaceForHost(cwd, host) {
     void cwd;
@@ -1655,12 +1660,232 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     // During a merge, git refuses partial commits — fall back to a bare commit.
     // --amend is left without a pathspec: amending with -- <paths> is a different
     // operation that rewrites the tip with only those paths.
-    if (explicitFiles && stagedPaths.length === 0 && !amend) {
+    const mergeHeadProbe = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { cwd });
+    const isMergeInProgress = mergeHeadProbe.exitCode === 0;
+    // PROVENANCE FOR THIS WHOLE BLOCK: every behavioural claim below was DRIVEN
+    // against git 2.54, not reasoned by analogy. Individual claims state what was
+    // observed and omit the version; where a claim is version-SENSITIVE rather
+    // than merely version-observed, it says so at the claim.
+    //
+    // #3776: git refuses a PARTIAL commit (`git commit -- <paths>`) while a merge
+    // or a cherry-pick is in progress, so in those states the pathspec describes
+    // nothing about what would actually land and the empty-diff decision below
+    // must not be made from it. The three sequencer states do NOT agree:
+    //   MERGE_HEAD        -> `fatal: cannot do a partial commit during a merge.`
+    //   CHERRY_PICK_HEAD  -> `fatal: cannot do a partial commit during a cherry-pick.`
+    //   REVERT_HEAD       -> permitted; behaves like an ordinary commit.
+    // REVERT_HEAD is therefore deliberately absent: including it would suppress
+    // this fix during a revert, reintroducing the very misreport it removes.
+    // `canScope` below keeps its narrower merge-only test on purpose — widening it
+    // would change pre-existing cherry-pick behaviour, which is outside this fix.
+    // Only the scoped, non-amend call can return through the guard below, so the
+    // cherry-pick probe and the guard's own probes are gated on that — an
+    // unscoped commit or an --amend would otherwise pay for git invocations whose
+    // answer it can never use. The MERGE_HEAD probe above predates this fix and
+    // stays unconditional: `canScope` needs it on every path.
+    // A non-zero exit from either sequencer probe means "not in that state" AND
+    // "the probe never answered" — `execGit` surfaces a spawn timeout as
+    // `exitCode: 1` (`_spawnResult`: `result.status ?? 1`), which is the exact
+    // code `rev-parse --verify` returns for a ref that does not exist. Conflating
+    // them is the one path in this fix that does NOT fail toward the old
+    // behaviour: a timeout during a real merge would leave `partialCommitRefused`
+    // false, the guard would decide `nothing_to_commit` from a pathspec git will
+    // not honour, and the merge would be silently abandoned where it previously
+    // reported a loud `commit_failed`. So an unanswered probe is treated as
+    // "assume the partial commit would be refused" — the conservative reading,
+    // which falls through to `git commit` and lets git speak for itself.
+    //
+    // This is deliberately routed into `partialCommitRefused` ONLY, never into
+    // `isMergeInProgress`: that flag also feeds the pre-existing `canScope` below,
+    // where a spurious timeout would convert a scoped commit into a bare one and
+    // record the whole index instead of the named paths. Suppressing a misreport
+    // must not be paid for by committing content the caller never named.
+    const guardApplies = explicitFiles && !amend;
+    const cherryPickProbe = guardApplies
+        ? (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '-q', '--verify', 'CHERRY_PICK_HEAD'], { cwd })
+        : null;
+    const partialCommitRefused = isMergeInProgress
+        || (0, shell_command_projection_cjs_1.isSpawnTimeout)(mergeHeadProbe)
+        || (cherryPickProbe !== null
+            && (cherryPickProbe.exitCode === 0 || (0, shell_command_projection_cjs_1.isSpawnTimeout)(cherryPickProbe)));
+    // `stagedPaths` records paths whose `git add` exited 0 — that is "did
+    // staging succeed", not "is there anything to commit". Staging an
+    // already-committed, unmodified file succeeds while contributing no diff, so
+    // `length === 0` is reachable only when EVERY named path was missing from
+    // disk. For the ordinary empty-diff case control fell through to `git commit`,
+    // and the only thing converting that back to `nothing_to_commit` was the
+    // string match on git's output below — which a rejecting pre-commit hook
+    // pre-empts, because git runs the hook before it decides there is nothing to
+    // commit. The caller was then handed `commit_failed` carrying a gate message
+    // about a commit that had nothing to gate. Ask git whether the named paths
+    // actually differ instead. Three things about that probe are load-bearing:
+    //  - it compares the WORKING TREE to HEAD (`diff HEAD`), not the index
+    //    (`diff --cached`). `git commit -- <paths>` is a partial commit: it takes
+    //    the working-tree content of those paths and ignores what is staged. A
+    //    probe against the index therefore answers a different question than the
+    //    commit asks, and a working-tree write landing between the `git add`
+    //    above and this line — another process in a shared checkout — would make
+    //    the index say "empty" while the commit would still have recorded the new
+    //    content. Driven: `diff --cached` rc 0 and `diff HEAD` rc 1 on the same
+    //    path, with `git commit -- <path>` then committing it.
+    //  - the `length === 0` short-circuit keeps the all-missing-paths case exact.
+    //    Spreading an empty array yields a pathspec-less `diff`, which tests the
+    //    WHOLE tree — unrelated work elsewhere would then suppress the guard and
+    //    regress the skip-missing contract (#2014).
+    //    It is deliberately NOT gated on `partialCommitRefused`, and gating it
+    //    would be a REGRESSION rather than a hardening. With every named path
+    //    missing, `stagedPaths` is empty, so `canScope` is false and the
+    //    fall-through reaches a BARE `git commit` — which git PERMITS during a
+    //    merge, and which then CONCLUDES that merge: rc 0, a two-parent merge
+    //    commit recording the entire index, under a message naming a path that
+    //    does not exist, reported to the caller as `committed: true` (driven).
+    //    Today's answer writes nothing at all. That is the same trade the timeout
+    //    routing above already refuses — a misreport must not be paid for by
+    //    committing content the caller never named — which is why the sequencer
+    //    states gate the DIFF branch only. The behaviour is also PRE-EXISTING and
+    //    unchanged by this fix: before it the identical short-circuit ran ABOVE
+    //    the MERGE_HEAD probe, so it never consulted the sequencer either. The
+    //    residual it leaves — a merge held open behind a `nothing_to_commit`
+    //    report — is offered as a separate issue with the other three, not folded
+    //    in here. Both sequencer shapes are pinned in
+    //    tests/commit-files-pathspec.test.cjs.
+    //  - `!partialCommitRefused`: see above — deciding "nothing to commit" from a
+    //    pathspec git will not honour would abandon an in-progress merge, so those
+    //    states keep their pre-existing behaviour untouched.
+    //  - the probe is pinned against user configuration that would make `git diff`
+    //    answer a DIFFERENT question than `git commit -- <paths>` asks. `git diff`
+    //    is porcelain and honours settings the commit does not, so without these
+    //    flags a caller's config decides whether the guard fires. Each vector
+    //    below was driven with the paired `git commit -- <path>` confirmed to
+    //    record the change the probe reported as absent:
+    //      `diff.ignoreSubmodules=all`   -> a gitlink bump is invisible to the probe
+    //      `.gitmodules` `ignore = all`  -> the same, and it needs NO local config:
+    //                                       it is checked in, so it arrives with a
+    //                                       clone
+    //      `diff=<driver>` + `textconv`  -> two different blobs converge to one
+    //                                       text, so the probe sees no change at
+    //                                       all; no submodule involved
+    //    `--ignore-submodules=dirty` rather than `=none`, because `dirty` is what
+    //    a partial commit of a submodule path actually means: it records the
+    //    GITLINK, and the gitlink moves only when the submodule's HEAD does. Under
+    //    `=none` a merely dirty submodule WORKTREE reports a difference the commit
+    //    would not record, sending an empty call back to `git commit` — the #3776
+    //    misreport, re-entered from the other side. `dirty` still overrides both
+    //    `diff.ignoreSubmodules` and a checked-in `.gitmodules` `ignore`, so the
+    //    gitlink vectors above stay closed (driven: rc 1 under every one of them).
+    //    `--no-ext-diff` is deliberately absent: `--quiet` short-circuits ahead of
+    //    an external diff driver, so an external `diff.<driver>.command` cannot
+    //    invert the probe (driven: rc 1 with and without the flag).
+    // Any other non-zero exit from the probe (a genuine git error, or an unborn
+    // HEAD) leaves the guard shut and falls through to the commit — failing toward
+    // today's path rather than manufacturing a no-op.
+    // THE ONE STATE WHERE `git diff` AND `git commit -- <paths>` GENUINELY DISAGREE.
+    // `--assume-unchanged` tells git to skip the worktree stat for a path, so
+    // `git add` stages nothing and BOTH diff forms report no difference — while
+    // `git commit -- <path>` reads the working tree directly and records it
+    // (driven: probe rc 0, commit rc 0, new content in the tree). Left
+    // to the diff probe alone the guard reports `nothing_to_commit` about content
+    // the caller explicitly named in `--files` and git would have written. #3776
+    // is a purely diagnostic bug — nothing is corrupted and no wrong commit is
+    // made — so suppressing its misreport must not be paid for by dropping named
+    // content. The same rule the timeout routing already follows one block up.
+    //
+    // `git ls-files -v` is the discriminator for the STATE: it tags an
+    // assume-unchanged path with a LOWERCASE letter (`h`), where
+    // `--skip-worktree` is an uppercase `S` and never reaches THIS branch:
+    // `git add` exits 1 under it, so a present-but-modified skip-worktree path
+    // fails closed as `staging_failed` above the guard. (An ABSENT one is skipped
+    // before `git add` runs at all per #2014, and is answered by the
+    // `stagedPaths.length === 0` arm above — correctly, and exactly as it was
+    // pre-fix. Both shapes are pinned.)
+    //
+    // Then ASK GIT, rather than reconstructing its answer. `git commit --dry-run`
+    // is the same decision the real commit makes, and `--no-verify` is what keeps
+    // it a DECISION rather than an execution. git 2.54 already declines to run
+    // `pre-commit` on a dry run (driven: a rejecting one neither fires nor writes
+    // its marker), which is the property that matters here, because a firing
+    // `pre-commit` is the whole of #3776 — but that is an observed behaviour of
+    // one version, and the failure it would produce on a version that differs is
+    // SILENT. A `pre-commit` that fires and rejects exits 1, the same code git
+    // returns for `nothing to record`, so the closure below would read it as a
+    // CONFIRMED empty answer, drop the content the caller named, and report
+    // `nothing_to_commit` — #3776's exact shape, in #3776's exact configuration.
+    // `--no-verify` forecloses that structurally instead of resting on the
+    // version, and is behaviour-neutral where the version already agrees (driven:
+    // rc 0 would-record / rc 1 nothing, identical with and without it). This is
+    // VERSION-SENSITIVE reasoning, hence stated at the claim per the provenance
+    // note above.
+    //
+    // It is still NOT hook-free in general, and `--no-verify` does not widen that
+    // claim: `post-index-change` fires on this call with or without the flag
+    // (driven both ways), so a repo using that hook sees TWO extra invocations
+    // for the probe — git fires it twice per `commit --dry-run`, and twice again
+    // for the real commit (driven: 2/2/2 across flagged probe, unflagged probe
+    // and real commit). Stated rather than claimed away; the narrower
+    // claim is the true one. `--porcelain` keeps the output to a couple
+    // of machine-readable lines instead of a full status listing — the rc is
+    // identical either way (driven: 0 would-record / 1 nothing), but the plain
+    // form prints every untracked path, which on a large tree is output this
+    // probe has no use for and `execGit` would have to buffer. rc 0 means the
+    // commit would record something, so the guard must stand aside.
+    //
+    // Reconstructing it was tried and is WRONG in three measured ways, all of
+    // them silent drops of named content. Comparing `git hash-object` against
+    // `HEAD:<path>` misses a mode-only change (`chmod +x` leaves the blob
+    // identical while `git commit -- <path>` records `100755`); it cannot hash a
+    // submodule path at all (`fatal: Unable to hash sub`, while the commit
+    // advances the gitlink); and the path it needs must be parsed out of
+    // `ls-files` output, which `core.quotePath` renders as `"caf\303\251.md"`
+    // by default, so the probe reads a filename that does not exist. Asking git
+    // needs no path parsed and no case enumerated.
+    //
+    // Scoped to this branch on purpose. The diff probe above answers the ordinary
+    // case cheaply and is pinned against the configuration vectors below; the
+    // dry run is the heavier, exact answer, and it runs only when an
+    // assume-unchanged path is actually present.
+    //
+    // The `ls-files` read is an OPTIMISATION, never a gate — so an unreadable one
+    // must not decide anything. It exists only to keep the dry run off the hot
+    // path when no assume-unchanged entry is present; when it cannot answer, the
+    // dry run simply runs, because the dry run needs nothing from it. Both
+    // failing-closed (drop the content) and failing-open (re-enter #3776) are
+    // wrong answers to a question we can just ask directly.
+    const assumeUnchangedWouldRecord = () => {
+        const listed = (0, shell_command_projection_cjs_1.execGit)(['ls-files', '-v', '--', ...stagedPaths], { cwd });
+        // Only the TAG is read; the path is deliberately never parsed out — see the
+        // `core.quotePath` note above, and the dry run below needs no path anyway.
+        if (listed.exitCode === 0
+            && !listed.stdout.split('\n').some((line) => /^[a-z] /.test(line)))
+            return false;
+        const dryRun = (0, shell_command_projection_cjs_1.execGit)(['commit', '--dry-run', '--porcelain', '--no-verify', '-m', sanitizedMessage, '--', ...stagedPaths], { cwd });
+        // Only a CONFIRMED "nothing to record" closes the path: rc 1 from a git
+        // that actually answered. This is the one probe in the guard whose rc 0
+        // is the REASSURING answer, so it inverts the diff probe's safety: there
+        // a timeout can only yield non-zero and reads as "not clean"; here
+        // `execGit` collapses a spawn timeout (or any spawn error) to
+        // `exitCode: 1` (`_spawnResult`: `result.status ?? 1`), byte-identical to
+        // git's own "nothing to record" — and the guard then reports
+        // `nothing_to_commit` about content it never asked git to write. Same
+        // conflation the sequencer probes above defend against, same remedy: an
+        // unanswered probe falls toward the commit, where git speaks for itself
+        // (and a genuine error there is reported loudly, as it always was). rc 128
+        // is likewise not an answer. Timeout kill of a dry run CAN leave a stale
+        // `index.lock` behind (it refreshes the index); the real commit then
+        // fails on it, loudly — never silently.
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(dryRun) || dryRun.error !== null)
+            return true;
+        return dryRun.exitCode !== 1;
+    };
+    const nothingToCommit = guardApplies
+        && (stagedPaths.length === 0
+            || (!partialCommitRefused
+                && (0, shell_command_projection_cjs_1.execGit)(['diff', '--quiet', '--ignore-submodules=dirty', '--no-textconv', 'HEAD', '--', ...stagedPaths], { cwd }).exitCode === 0
+                && !assumeUnchangedWouldRecord()));
+    if (nothingToCommit) {
         const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
         output(result, raw, 'nothing');
         return;
     }
-    const isMergeInProgress = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { cwd }).exitCode === 0;
     const canScope = explicitFiles && stagedPaths.length > 0 && !amend
         && !isMergeInProgress;
     const commitArgs = amend
@@ -1671,10 +1896,45 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     if (canScope) {
         commitArgs.push('--', ...stagedPaths);
     }
+    // #3859 follow-up: on git 2.39.5 (confirmed on the CI Linux bench image,
+    // ghcr.io/open-gsd/gsd-tester-linux:v1.8.0-node24; NOT reproducible on git
+    // 2.50.1) `git commit` itself — not just `git diff` — consults
+    // `diff.ignoreSubmodules` when deciding whether there is anything to
+    // record. With a local `diff.ignoreSubmodules=all` and a submodule gitlink
+    // genuinely bumped, that git version silently REFUSES the commit (prints a
+    // `git status`-style "Changes to be committed" dump and exits 1, having
+    // written nothing) even though the diff probe above (already pinned with
+    // its own `--ignore-submodules=dirty`) correctly reported the change as
+    // present. The result was misclassified as generic `commit_failed` because
+    // git's refusal text does not contain "nothing to commit".
+    // Originally scoped to `canScope` on the assumption that only a
+    // PATHSPEC-LIMITED `git commit -- <paths>` exercises this git internal
+    // path. That assumption was wrong: reproduced directly against the pinned
+    // v1.8.0-node24 tester image, a bare WHOLE-INDEX `git commit -m ...` (no
+    // pathspec at all) is refused identically when the only staged change is a
+    // submodule gitlink and `diff.ignoreSubmodules=all` — git's "nothing to
+    // commit" check is a real diff (HEAD vs. index) honouring
+    // `diff.ignoreSubmodules` regardless of whether a pathspec narrows it.
+    // `--amend` is the one shape confirmed NOT to hit this: it always
+    // recreates the commit from the current index and never runs the
+    // empty-diff refusal a plain `git commit` does, override or not. The
+    // override is therefore applied unconditionally here (not gated on
+    // `canScope`) — it is a documented no-op everywhere it is not needed
+    // (dry-run, git 2.50.1, and `--amend` already behave this way with or
+    // without it; see `#3859 follow-up (canScope gap)` regression tests).
+    // The override rides in via `GIT_CONFIG_*` env vars rather than a `-c`
+    // argv flag so `commitArgs[0]` stays `'commit'` — several #3859 regression
+    // tests assert on the raw argv captured at the `execGit` seam (e.g.
+    // `gitCalls.some((a) => a[0] === 'commit')`), and a leading `-c` would shift
+    // every element and break that pinning. Same override the probe already
+    // carries, so the two can never disagree again.
+    const commitEnv = {
+        GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'diff.ignoreSubmodules', GIT_CONFIG_VALUE_0: 'dirty',
+    };
     // #3886: `git commit` runs pre-commit hooks (husky/lint-staged routinely
     // idles ~4s on Windows before any task) — 10s is too tight, and a timeout
     // kill is NOT an ordinary failure. Same band as the push call below.
-    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd, timeout: COMMIT_TIMEOUT_MS });
+    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd, env: commitEnv, timeout: COMMIT_TIMEOUT_MS });
     if (commitResult.exitCode !== 0) {
         // #3886: a SIGTERM'd git commit is a timeout, not commit_failed — the
         // partial stderr it flushed (often incidental CRLF warnings) is noise,
@@ -1830,7 +2090,12 @@ function cmdCommitToSubrepo(cwd, message, files, raw) {
         const commitArgs = canScopeSub
             ? ['commit', '-m', message, '--', ...stagedRelPaths]
             : ['commit', '-m', message];
-        const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd, timeout: COMMIT_TIMEOUT_MS });
+        // #3859 follow-up fix as cmdCommit above (line ~2081) — git 2.39.5 needs
+        // this override for pathspec-scoped AND whole-index commits alike.
+        const commitEnvSub = {
+            GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'diff.ignoreSubmodules', GIT_CONFIG_VALUE_0: 'dirty',
+        };
+        const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd, timeout: COMMIT_TIMEOUT_MS, env: commitEnvSub });
         if (commitResult.exitCode !== 0) {
             if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(commitResult)) {
                 // #3886 (subrepo counterpart): timeout ≠ error; surface the stale-lock
@@ -1905,7 +2170,16 @@ function cmdPrSubrepo(cwd, repo, branch, commitMessage, raw) {
     }
     // 1. Collect changed files via porcelain status — explicit, never git add -A.
     //    ?? (untracked) lines are excluded — only stage tracked modifications.
-    const statusResult = (0, shell_command_projection_cjs_1.execGit)(['-c', 'core.quotePath=false', 'status', '--porcelain'], { cwd: repoCwd });
+    // #3859 follow-up: `git status --porcelain` honors `diff.ignoreSubmodules`
+    // the same way the empty-diff probe fixed for cmdCommit did — under a local
+    // `diff.ignoreSubmodules=all`, a genuinely bumped submodule gitlink is
+    // invisible here too, so `changedFiles` comes back empty and the function
+    // reports `nothing_to_commit` before ever reaching the (now-fixed) commit
+    // call. `--ignore-submodules=dirty` pins this the same way, reported
+    // verbatim: `git -C repo status --porcelain` (no flag) shows nothing for a
+    // pure gitlink bump under `diff.ignoreSubmodules=all`, while
+    // `--ignore-submodules=dirty` reports ` M nested` (reproduced directly).
+    const statusResult = (0, shell_command_projection_cjs_1.execGit)(['-c', 'core.quotePath=false', 'status', '--porcelain', '--ignore-submodules=dirty'], { cwd: repoCwd });
     if (statusResult.exitCode !== 0) {
         error(`git status failed in ${repo}: ${statusResult.stderr}`);
     }
@@ -1974,7 +2248,12 @@ function cmdPrSubrepo(cwd, repo, branch, commitMessage, raw) {
     const commitArgs = canScopePr
         ? ['commit', '-m', commitMessage, '--', ...changedFiles]
         : ['commit', '-m', commitMessage];
-    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd, timeout: COMMIT_TIMEOUT_MS });
+    // #3859 follow-up fix as cmdCommit above (line ~2081) — git 2.39.5 needs
+    // this override for pathspec-scoped AND whole-index commits alike.
+    const commitEnvPr = {
+        GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'diff.ignoreSubmodules', GIT_CONFIG_VALUE_0: 'dirty',
+    };
+    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd, timeout: COMMIT_TIMEOUT_MS, env: commitEnvPr });
     if (commitResult.exitCode !== 0) {
         rollback();
         if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(commitResult)) {
@@ -2375,7 +2654,34 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
     matches.sort((a, b) => b.score - a.score);
     output({ phase, matches, todo_count: todos.length }, raw, undefined);
 }
-function cmdTodoComplete(cwd, filename, raw) {
+// #4096: upsert completion keys INSIDE the leading frontmatter block. Never a
+// bare prefix line above the opening `---` (that displaces the fence to line 2
+// and breaks every fence-locating reader). A file with no well-formed block
+// (absent, or an unterminated opening fence) gains a complete block.
+function upsertTodoCompletionFields(content, today) {
+    const lines = content.split('\n');
+    const fields = [`completed: ${today}`, 'status: completed'];
+    const hasOpeningFence = lines[0] !== undefined && lines[0].trim() === '---';
+    const closeIdx = hasOpeningFence ? lines.findIndex((l, i) => i > 0 && l.trim() === '---') : -1;
+    if (!hasOpeningFence || closeIdx === -1) {
+        // No parseable frontmatter: wrap the whole content in a complete block
+        // rather than prefixing bare keys (#4096 fix 2).
+        return `---\n${fields.join('\n')}\n---\n\n${content}`;
+    }
+    const block = lines.slice(1, closeIdx);
+    for (const field of fields) {
+        const key = `${field.slice(0, field.indexOf(':'))}:`;
+        const idx = block.findIndex(l => l.startsWith(key));
+        if (idx === -1) {
+            block.push(field);
+        }
+        else {
+            block[idx] = field;
+        }
+    }
+    return [...lines.slice(0, 1), ...block, ...lines.slice(closeIdx)].join('\n');
+}
+function cmdTodoComplete(cwd, filename, options, raw) {
     if (!filename) {
         error('filename required for todo complete');
     }
@@ -2385,13 +2691,30 @@ function cmdTodoComplete(cwd, filename, raw) {
     if (!node_fs_1.default.existsSync(sourcePath)) {
         error(`Todo not found: ${filename}`);
     }
-    // Ensure completed directory exists
-    (0, shell_command_projection_cjs_1.platformEnsureDir)(completedDir);
-    // Read, add completion timestamp, move
-    let content = node_fs_1.default.readFileSync(sourcePath, 'utf-8');
+    const content = node_fs_1.default.readFileSync(sourcePath, 'utf-8');
     const today = clock_cjs_1.realClock.localToday();
-    content = `completed: ${today}\n` + content;
-    (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(completedDir, filename), content);
+    // #4096: --dry-run mirrors `milestone complete --dry-run` (#2118) — every
+    // existence check above still runs, nothing below mutates, and the payload
+    // is preview-shaped (`dry_run`/`would_*`), never `completed: true`.
+    if (options.dryRun) {
+        output({
+            dry_run: true,
+            would_complete: true,
+            file: filename,
+            date: today,
+            would_move: {
+                source: node_path_1.default.relative(cwd, sourcePath).split(node_path_1.default.sep).join('/'),
+                target: node_path_1.default.relative(cwd, node_path_1.default.join(completedDir, filename)).split(node_path_1.default.sep).join('/'),
+            },
+            would_set: { completed: today, status: 'completed' },
+        }, raw);
+        return;
+    }
+    // Ensure completed directory exists (only on the real run — a dry run
+    // creates nothing).
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(completedDir);
+    const completedContent = upsertTodoCompletionFields(content, today);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(completedDir, filename), completedContent);
     node_fs_1.default.unlinkSync(sourcePath);
     output({ completed: true, file: filename, date: today }, raw, 'completed');
 }
@@ -2865,6 +3188,7 @@ function cmdCommitDocsGuardDisable(cwd, raw) {
     output({ disabled: true, action: 'removed', path: hookPath }, raw, 'disabled');
 }
 module.exports = {
+    effortSurfaceForHost,
     groupFilesBySubrepo,
     determinePhaseStatus,
     foldPhaseStatus,

package/gsd-core/bin/lib/config-loader.cjs

@@ -831,6 +831,7 @@ function loadConfigResolved(cwd, options = {}) {
             branching_strategy: get('branching_strategy', { section: 'git', field: 'branching_strategy' }) ?? defaults.branching_strategy,
             base_branch: get('base_branch', { section: 'git', field: 'base_branch' }),
             protected_branches: getNested('git', 'protected_branches'),
+            allow_default_branch_commits: getNested('git', 'allow_default_branch_commits'),
             phase_branch_template: get('phase_branch_template', { section: 'git', field: 'phase_branch_template' }) ?? defaults.phase_branch_template,
             milestone_branch_template: get('milestone_branch_template', { section: 'git', field: 'milestone_branch_template' }) ?? defaults.milestone_branch_template,
             quick_branch_template: get('quick_branch_template', { section: 'git', field: 'quick_branch_template' }) ?? defaults.quick_branch_template,
@@ -844,6 +845,7 @@ function loadConfigResolved(cwd, options = {}) {
             firecrawl: get('firecrawl') ?? defaults.firecrawl,
             exa_search: get('exa_search') ?? defaults.exa_search,
             mvp_mode: get('mvp_mode', { section: 'workflow', field: 'mvp_mode' }) ?? false,
+            tdd_mode: getNested('workflow', 'tdd_mode') ?? false,
             text_mode: get('text_mode', { section: 'workflow', field: 'text_mode' }) ?? defaults.text_mode,
             auto_advance: get('auto_advance', { section: 'workflow', field: 'auto_advance' }) ?? false,
             _auto_chain_active: get('_auto_chain_active', { section: 'workflow', field: '_auto_chain_active' }) ?? false,
@@ -856,6 +858,7 @@ function loadConfigResolved(cwd, options = {}) {
             project_code: get('project_code') ?? defaults.project_code,
             subagent_timeout: get('subagent_timeout', { section: 'workflow', field: 'subagent_timeout' }) ?? defaults.subagent_timeout,
             model_overrides: (parsed['model_overrides']) || null,
+            agent_tools: (parsed['agent_tools']) || null,
             models: (parsed['models']) || null,
             granularity: parsed['granularity'] !== undefined ? parsed['granularity'] : null,
             granularities: (parsed['granularities']) || null,

package/gsd-core/bin/lib/core-utils.cjs

@@ -43,6 +43,11 @@ const phaseIdModule = require("./phase-id.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCommandProjection = require("./shell-command-projection.cjs");
+// planning-scope.cjs is a leaf module (no imports of its own — see its file
+// header), so importing it here directly cannot introduce a cycle.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 // ─── Line-ending normalization ─────────────────────────────────────────────────
 /**
  * Normalize every line ending in `content` to a bare `\n`, ONCE — the shared
@@ -271,16 +276,38 @@ function transliterateForSlug(text) {
  * Degrades on an unreadable directory instead of throwing: empty arrays,
  * every flag false, scope UNREADABLE (mirroring scanPhasePlans's own
  * degrade path).
+ *
+ * #4014 (epic #3473 B4-unreadable): this function's OWN readdirSync used to
+ * catch its own failure and then return `scope: scan.scope` — the scope of
+ * the UNRELATED, already-successful scanPhasePlans call — silently dropping
+ * that THIS read failed. The own-readdirSync is now routed through
+ * findContextMdIn's directory-string form (which never throws and reports
+ * its own SCOPE.UNREADABLE), and the two independently-scoped answers are
+ * combined into the worse of the two below — never letting a successful
+ * scan.scope mask this function's own failed read.
+ *
+ * The combination is written out as a two-value comparison rather than
+ * calling planning-snapshot.cts's `worstScope` directly: that module
+ * requires core-utils.cjs (for `findOrphanSummaries`) at its own top level,
+ * so importing it back here would create a tight, direct
+ * core-utils.cjs <-> planning-snapshot.cjs cycle — a materially different
+ * (and riskier) shape than this file's existing, documented lazy-access
+ * cyclic partners (planning-workspace.cjs, phase-id.cjs), which
+ * planning-snapshot.cts sits *above* in the dependency graph, not beside.
+ * `findContextMdIn`'s directory-string form can only ever report
+ * SCOPE.COMPLETE or SCOPE.UNREADABLE (a single readdirSync is binary — see
+ * its own doc comment), so per planning-snapshot.cts's SCOPE_SEVERITY
+ * ordering (UNREADABLE is maximal), `worstScope(scan.scope, ownScope)` is
+ * exactly `ownScope === UNREADABLE ? UNREADABLE : scan.scope` — the
+ * expression below is that identity, not a re-derivation of the ordering.
  */
 function getPhaseFileStats(phaseDir) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
     const scanPhasePlans = require('./plan-scan.cjs');
     const scan = scanPhasePlans(phaseDir);
-    let files;
-    try {
-        files = node_fs_1.default.readdirSync(phaseDir);
-    }
-    catch {
+    const { files, scope: ownScope } = planningWorkspace.findContextMdIn(phaseDir);
+    const scope = ownScope === SCOPE.UNREADABLE ? SCOPE.UNREADABLE : scan.scope;
+    if (ownScope === SCOPE.UNREADABLE) {
         return {
             plans: scan.planFiles,
             summaries: scan.summaryFiles,
@@ -288,7 +315,7 @@ function getPhaseFileStats(phaseDir) {
             hasContext: false,
             hasVerification: false,
             hasReviews: false,
-            scope: scan.scope,
+            scope,
         };
     }
     const scopedFiles = phaseIdModule.scopeToPhase(files, node_path_1.default.basename(phaseDir));
@@ -299,7 +326,7 @@ function getPhaseFileStats(phaseDir) {
         hasContext: planningWorkspace.findContextMdIn(scopedFiles) !== null,
         hasVerification: scopedFiles.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
         hasReviews: scopedFiles.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
-        scope: scan.scope,
+        scope,
     };
 }
 /**