@opengsd/gsd-core 1.18.0 → 1.19.0

package/gsd-core/bin/lib/task-content-resolution.cjs

@@ -43,6 +43,8 @@ const node_child_process_1 = __importDefault(require("node:child_process"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { formatDiagnosticToken } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityLoaderMod = require("./capability-loader.cjs");
 // ─── Result taxonomy ──────────────────────────────────────────────────────────
 /**
  * The four non-throwing outcomes of `resolveTaskContent`. Frozen because the
@@ -102,6 +104,17 @@ class ResolverFailedError extends Error {
         this.stderrTail = stderrTail;
     }
 }
+/**
+ * The tracker-id's id segment cannot safely be one argv element: a leading `-`
+ * reads as an option to the resolver binary, and control characters are never
+ * legitimate. Thrown before any spawn.
+ */
+class ResolverUnsafeIdError extends Error {
+    constructor() {
+        super('tracker-id rejected: id must not start with "-" or contain control characters');
+        this.name = 'ResolverUnsafeIdError';
+    }
+}
 /** The resolver subprocess exceeded its declared `invoke.timeoutMs` bound. */
 class ResolverTimeoutError extends Error {
     timeoutMs;
@@ -312,6 +325,9 @@ function resolveTaskContent(input) {
     const split = splitTrackerId(input.trackerId);
     if (split === null)
         return { kind: TASK_CONTENT_RESULT.NOT_APPLICABLE };
+    if (split.id.trimStart().startsWith('-') || /[\u0000-\u001f\u007f]/.test(input.trackerId ?? '')) {
+        throw new ResolverUnsafeIdError();
+    }
     const resolver = findResolver(split.prefix, input.capabilities ?? []);
     if (resolver === null)
         return { kind: TASK_CONTENT_RESULT.NO_RESOLVER };
@@ -327,7 +343,7 @@ function resolveTaskContent(input) {
         throw new ResolverAmbiguousError(split.prefix, ids);
     }
     const invocation = buildInvocation(resolver, split.id);
-    const timeoutMs = input.timeoutOverrideMs ?? invocation.timeoutMs;
+    const timeoutMs = Math.floor(Math.min(input.timeoutOverrideMs ?? invocation.timeoutMs, invocation.timeoutMs));
     const execFn = input.execFn ?? realExec;
     const result = execFn(invocation.binary, invocation.args, { timeout: timeoutMs });
     if (isExecTimeout(result)) {
@@ -354,12 +370,41 @@ function resolveTaskContent(input) {
     }
     return { kind: TASK_CONTENT_RESULT.RESOLVED, content };
 }
+/**
+ * Production capability loader for tracker-id resolution: the merged
+ * first-party + validated-installed-overlay registry (ADR-1244 D2), the
+ * established runtime read path for "installed capabilities including
+ * third-party" — as opposed to `capability-loader.cts`'s heavier build-time
+ * validation entry points or the static `capability-registry.cjs` alone
+ * (first-party only, would miss a third-party capability's
+ * `taskContentResolver` declaration entirely).
+ */
+function loadResolverCapabilities(cwd) {
+    const registry = capabilityLoaderMod.loadRegistry({ includeInstalled: true, cwd });
+    return Object.values(registry.capabilities ?? {});
+}
+/** True for every error `resolveTaskContent` throws as a hard halt (the one classifier all consumers share). */
+function isResolverFailure(err) {
+    return (err instanceof ResolverAmbiguousError ||
+        err instanceof ResolverFailedError ||
+        err instanceof ResolverTimeoutError ||
+        err instanceof ResolverMalformedOutputError ||
+        err instanceof ResolverUnsafeIdError);
+}
+/** Every text field of resolved content, so a consumer scanning for text cannot miss one when the shape grows. */
+function contentTexts(c) {
+    return [c.action, c.verify, ...c.acceptanceCriteria, ...c.readFirst, c.done].filter((v) => v !== null);
+}
 const taskContentResolution = {
     TASK_CONTENT_RESULT,
     splitTrackerId,
     findResolver,
     buildInvocation,
     resolveTaskContent,
+    loadResolverCapabilities,
+    isResolverFailure,
+    contentTexts,
+    ResolverUnsafeIdError,
     ResolverAmbiguousError,
     ResolverFailedError,
     ResolverTimeoutError,

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

@@ -47,6 +47,8 @@ const coreUtilsMod = require("./core-utils.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
 const planningScopeMod = require("./planning-scope.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const text_lines_cjs_1 = require("./text-lines.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const security_cjs_1 = require("./security.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
@@ -607,17 +609,19 @@ function phaseArtifactPaths(phaseDir, projectRoot) {
  *                `.planning/<project>/workstreams/<ws>`), covering a
  *                per-project/per-workstream store symlink (amendment 1,
  *                revised R7).
+ *   v4 (#5351) — v3 with each CRLF byte pair hashed as LF. Every other
+ *                byte, including a lone CR and non-UTF-8 input, is preserved.
  *
  * A stored digest names its own version (`v<N>:sha256:…`), and
  * `readVerificationStatus` recomputes under the STORED version rather than
  * this constant — so bumping it does not flip every already-verified phase
- * to `stale` on upgrade. A legacy v1/v2 report keeps its own semantics
- * (shared documents included for v1; no report filter or artifact union for
- * either) until it is re-fingerprinted; only a version outside
+ * to `stale` on upgrade. A legacy v1/v2/v3 report keeps its own raw-byte
+ * semantics (shared documents included for v1; no report filter or artifact
+ * union for v1/v2) until it is re-fingerprinted; only a version outside
  * `KNOWN_FINGERPRINT_VERSIONS` is unrecomputable and fails closed.
  */
-const FINGERPRINT_VERSION = 3;
-const KNOWN_FINGERPRINT_VERSIONS = new Set([1, 2, 3]);
+const FINGERPRINT_VERSION = 4;
+const KNOWN_FINGERPRINT_VERSIONS = new Set([1, 2, 3, 4]);
 /**
  * #4623: the planning roots whose DIRECT children are repo-wide planning
  * documents, as project-root-relative posix paths. Always `.planning`; plus
@@ -815,7 +819,22 @@ function deriveCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_VE
         catch {
             return { ok: true, digest: null, files: declared, mappedPhaseDir: artifactMappedPhaseDir };
         }
-        const fileHash = node_crypto_1.default.createHash('sha256').update(bytes).digest('hex');
+        const hash = node_crypto_1.default.createHash('sha256');
+        if (version >= 4) {
+            // #5351: drop only the CR in each CRLF pair without decoding the
+            // covered input — binary files and lone CR bytes keep their meaning.
+            // Hash Buffer slices directly, retaining the LF at each new start.
+            let start = 0;
+            for (let crlf = bytes.indexOf('\r\n'); crlf !== -1; crlf = bytes.indexOf('\r\n', start)) {
+                hash.update(bytes.subarray(start, crlf));
+                start = crlf + 1;
+            }
+            hash.update(bytes.subarray(start));
+        }
+        else {
+            hash.update(bytes);
+        }
+        const fileHash = hash.digest('hex');
         parts.push(`${rel}\n${fileHash}\n`);
         hashed++;
     }
@@ -1175,6 +1194,72 @@ function findVerificationStatusError(phaseDirs, deps = {}) {
     }
     return null;
 }
+/**
+ * #5291: legacy report statuses `validate health --repair` may rewrite, and the
+ * closed-set status each becomes. Deliberately minimal — only the value the
+ * maintainer ruled on (`pass_with_caveats` -> `passed`). Every other status
+ * outside the closed set (`pending`, `partial`, …) has NO mapping: it stays
+ * refused and its W030 stays advise-only (fail closed; only `passed` satisfies
+ * the gate). The original value is preserved in `legacy_status`.
+ */
+const LEGACY_STATUS_REPAIRS = Object.freeze({
+    pass_with_caveats: VERIFICATION_STATUS.PASSED,
+});
+/** The closed-set status a known legacy `raw` status repairs to, or `null` when it has no mapping. */
+function legacyStatusRepairTarget(raw) {
+    return typeof raw === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_STATUS_REPAIRS, raw)
+        ? LEGACY_STATUS_REPAIRS[raw]
+        : null;
+}
+/**
+ * #5291: rewrite one report's frontmatter `status:` from a known legacy value
+ * to its closed-set equivalent and record the original as `legacy_status:`
+ * right after it. Touches only those lines — every other byte (body, other
+ * keys, line endings) is preserved — and never overwrites an existing
+ * `legacy_status`. Refuses (writes nothing) for a path that is not a report
+ * contained in its own phase directory, a report with no frontmatter `status`,
+ * and any status without a mapping.
+ */
+function repairLegacyVerificationStatus(filePath) {
+    if (!isReportContained(node_path_1.default.dirname(filePath), filePath)) {
+        return { ok: false, reason: 'the report is not contained in its phase directory' };
+    }
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+    // The fence owner (`locateFrontmatterFence`) is the one place that knows where
+    // the frontmatter body starts and ends (BOM, CRLF, lenient closing fence).
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence || !fence.closed)
+        return { ok: false, reason: 'the report has no closed frontmatter' };
+    const lines = (0, text_lines_cjs_1.splitLines)(content.slice(fence.openEnd, fence.bodyEnd));
+    // The YAML reader keeps the LAST of duplicate keys, so the line the repair
+    // edits is the last `status:` line — the very value the refusal named. A
+    // trailing comment (`status: pass_with_caveats # x`) is not part of the value.
+    let statusAt = -1;
+    lines.forEach((l, i) => { if (/^status:/.test(l))
+        statusAt = i; });
+    if (statusAt === -1)
+        return { ok: false, reason: 'the report frontmatter has no status' };
+    const raw = lines[statusAt]
+        .replace(/^status:\s*/, '')
+        .replace(/\s+#.*$/, '')
+        .replace(/\s+$/, '')
+        .replace(/^(["'])(.*)\1$/, '$2');
+    const to = legacyStatusRepairTarget(raw);
+    if (to === null)
+        return { ok: false, reason: `${describeRawStatus(raw)} has no known repair` };
+    const legacyStatusKept = lines.some((l) => /^legacy_status:/.test(l));
+    lines[statusAt] = `status: ${to}`;
+    if (!legacyStatusKept)
+        lines.splice(statusAt + 1, 0, `legacy_status: ${raw}`);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(filePath, content.slice(0, fence.openEnd) + (0, text_lines_cjs_1.joinLines)(lines, fence.eol) + content.slice(fence.bodyEnd), { verbatim: true });
+    return { ok: true, from: raw, to, legacyStatusKept };
+}
 /**
  * #3518: the shared phase-pinned artifact-selection core BOTH single-pick
  * resolvers (`resolveVerificationFile` for `*-VERIFICATION.md`,
@@ -1499,11 +1584,11 @@ function readVerificationStatus(phaseDir, opts = {}) {
             isStale = true;
         }
         else if (storedVersion >= 3) {
-            // #5095 (R1): v3's digest is computed over the declared set UNIONED
+            // #5095 (R1): the v3+ digest is computed over the declared set UNIONED
             // with the phase's own live artifacts — a plan/summary added after
             // fingerprinting already moves the digest itself, so the separate
             // live-directory re-scan (`uncoveredCurrentArtifacts`) is redundant
-            // for v3 and is not run.
+            // for v3+ and is not run.
             isStale =
                 computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal;
             if (isStale) {
@@ -1784,7 +1869,7 @@ function parseFingerprintFileArgs(tokens) {
  *                       directly assignable. #5095 (ADR-5057 Phase 2): `raw`
  *                       returning only the digest is safe even though the
  *                       emitted `covered_files` is a SUPERSET of the caller's
- *                       declared list — the v3 digest is computed over
+ *                       declared list — the v3+ digest is computed over
  *                       `canonicalize(declared ∪ phaseArtifactPaths)` on BOTH
  *                       the emit side (here) and the check side
  *                       (`readVerificationStatus`), so a `--raw` caller that
@@ -2134,6 +2219,8 @@ const verificationModule = {
     isReportContained,
     routeResult,
     findVerificationStatusError,
+    legacyStatusRepairTarget,
+    repairLegacyVerificationStatus,
     defaultPhaseCleanCommitTimesMs,
     resolvePhaseArtifactFile,
     resolveVerificationFile,

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

@@ -1809,6 +1809,8 @@ function repairFixText(slash, action) {
             return `Run ${slash('health')} --repair to add key`;
         case REMEDY_ACTION.BACKFILL_MILESTONES:
             return `Run ${slash('health')} --backfill to synthesize missing entries from archive snapshots`;
+        case REMEDY_ACTION.REPAIR_VERIFICATION_STATUS:
+            return `Run ${slash('health')} --repair to rewrite the legacy status (original kept as legacy_status)`;
         default:
             return '';
     }

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -176,7 +176,28 @@ function resolveWorktreeContext(cwd, deps = {}) {
             reason: 'has_local_planning',
         };
     }
-    return resolveWorktreeLinkage(cwd, deps);
+    const linkage = resolveWorktreeLinkage(cwd, deps);
+    if (linkage.reason !== 'linked_worktree')
+        return linkage;
+    // #4885: from a SUBDIRECTORY of a LINKED worktree the cwd has no .planning of its own, but the
+    // worktree's own top-level may. That checkout is the project the caller means; remapping to the
+    // main checkout would make `commit` and every planning write land in the wrong repository. A linked
+    // worktree with no .planning anywhere still remaps to the main checkout, and the main checkout's own
+    // subdirectories are untouched.
+    const execGit = deps.execGit || execGitDefault;
+    const top = execGit(['rev-parse', '--show-toplevel'], { cwd });
+    const topText = String(top.stdout || '').trim();
+    if (!top.timedOut && top.exitCode === 0 && topText !== '') {
+        const topLevel = node_path_1.default.resolve(cwd, topText);
+        if (existsSync(node_path_1.default.join(topLevel, '.planning'))) {
+            return {
+                effectiveRoot: topLevel,
+                mode: 'current_directory',
+                reason: 'has_local_planning',
+            };
+        }
+    }
+    return linkage;
 }
 function planWorktreePrune(repoRoot, options = {}, deps = {}) {
     const parsePorcelain = deps.parseWorktreePorcelain || parseWorktreePorcelain;

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -22,6 +22,7 @@
   "git": {
     "branching_strategy": "none",
     "create_tag": true,
+    "repo_tagging": "single",
     "base_branch": null,
     "phase_branch_template": "gsd/phase-{phase}-{slug}",
     "milestone_branch_template": "gsd/{milestone}-{slug}",

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -51,6 +51,7 @@
     "git.protected_branches",
     "git.allow_default_branch_commits",
     "git.create_tag",
+    "git.repo_tagging",
     "git.phase_branch_template",
     "git.milestone_branch_template",
     "git.quick_branch_template",

package/gsd-core/references/git-integration.md

@@ -295,4 +295,15 @@ This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, a
 
 Files that don't match any configured sub-repo are reported as unmatched.
 
+### Milestone Tagging Across Sub-Repos
+
+A GSD milestone version names planned work in `.planning/`; it is not any repository's release version. With `git.repo_tagging: "per_repo"` and a non-empty `sub_repos`, `/gsd:complete-milestone` records one release map entry per repository (status, release, reference, environment, tag choice) instead of creating one `v[X.Y]` tag in the current directory:
+
+1. `gsd_run query milestone release-tags --map <tags.json> --dry-run` checks every requested tag (repository listed in `sub_repos`, ref resolves, tag name valid, no tag at a different commit) before anything is written.
+2. After one consolidated confirmation, `gsd_run query milestone release-tags --map <tags.json>` creates the annotated tags, each with the target repository as its working directory. Re-running the same map is idempotent (`already_tagged`).
+3. `milestone complete <version> --release-map <file>` archives the map by recorded value.
+4. Nothing is pushed by default. Each repository's tag has its own confirmation naming the repository and its remote.
+
+With `git.create_tag: false` the map is still recorded and no tag is created. See [How to tag a multi-repository milestone](../../docs/how-to/tag-a-multi-repo-milestone.md).
+
 </sub_repos_support>

package/gsd-core/references/loop-hook-dispatch.md

@@ -91,12 +91,19 @@ not one shape of one.
 capability manifest, which may be third-party — and `gates[].check` is **not** one of the
 executable surfaces the install consent prompt discloses (`hooks`, command modules,
 `mcpServers`, reviewer lanes), so a capability can be consented to as declarative-only and
-still reach a shell through a gate. Check the query value you read from `activeHooks` against
-`^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself, IN-CONTEXT — **never** by pasting it into a
-shell command to be tested there, because a value carrying a quote, `;`, a `` ` ``, `$(`, or a
-newline would terminate the assignment and run as its own statement before any shell-side
-check could execute. A value that fails is a malformed manifest: record a warning, route it
-per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
+still reach a shell through a gate. Normalize first, then validate: the registry declares query
+ids in dotted form (`ui.plan-gate`, `verify.codebase-drift`) and `gsd_run check` accepts them by
+turning each `.` into `-`, so replace every `.` with `-` in the query value you read from
+`activeHooks`, then check that normalized value against
+`^[a-z][a-z0-9]*(-[a-z0-9]+)*( [a-z][a-z0-9]*(-[a-z0-9]+)*)*$` yourself, IN-CONTEXT — **never** by
+pasting it into a shell command to be tested there, because a value carrying a quote, `;`, a
+`` ` ``, `$(`, or a newline would terminate the assignment and run as its own statement before
+any shell-side check could execute. The normalized value is the one value you validate and the
+one value you pass: wherever a workflow shows `${hook.check.query}`, write the normalized value.
+A leading dot, a trailing dot or consecutive dots become a leading, trailing or doubled hyphen,
+which the pattern rejects. A value that fails — or that passes but names no known check, which
+`gsd_run check` rejects as an unknown check subcommand — is a malformed manifest: record a
+warning, route it per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
 element** for the same reason — never re-quote it into a shell string, where an apostrophe
 would close the literal. This is the identical requirement `step` → `ref.command` carries
 above; it was stated there and omitted here, which is the gap #3559 closed.

package/gsd-core/references/planning-config.md

@@ -35,6 +35,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.base_branch` | `null` (auto-detect) | Target branch for PRs and merges (e.g. `"master"`, `"develop"`). When `null`, auto-detects from `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `"main"`. |
 | `git.protected_branches` | (none) | Optional array of non-empty strings naming additional shared branches that should trigger protected-branch warnings |
 | `git.create_tag` | `true` | Create git tags on milestone completion |
+| `git.repo_tagging` | `"single"` | Milestone tagging mode: `"single"` (existing behavior) or `"per_repo"` (record one release per configured repository; each tag is pushed only after a per-repository confirmation) |
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
@@ -340,6 +341,7 @@ Set via `git.*` namespace (e.g., `"git": { "branching_strategy": "phase" }`).
 | `git.base_branch` | string\|null | `null` (auto-detect) | Any branch name | Target branch for PRs and merges; auto-detects from `origin/HEAD` when `null` |
 | `git.protected_branches` | array of non-empty strings | (none) | Non-empty branch names | Optional protected names added to the resolved base branch for execute-phase and ship warnings |
 | `git.create_tag` | boolean | `true` | `true`, `false` | Create git tags on milestone completion |
+| `git.repo_tagging` | string | `"single"` | `"single"`, `"per_repo"` | Milestone tagging mode; `"per_repo"` opts a multi-repo project into per-repository release records |
 | `git.phase_branch_template` | string | `"gsd/phase-{phase}-{slug}"` | Template with `{phase}`, `{slug}` | Branch naming template for `phase` strategy |
 | `git.milestone_branch_template` | string | `"gsd/{milestone}-{slug}"` | Template with `{milestone}`, `{slug}` | Branch naming template for `milestone` strategy |
 | `git.quick_branch_template` | string\|null | `null` | Template with `{slug}` | Optional branch template for quick-task runs |

package/gsd-core/references/tdd.md

@@ -316,7 +316,7 @@ git log --oneline -E --grep="^feat\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 git log --oneline -E --grep="^refactor\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 ```
 
-If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
+If RED or GREEN gate commits are missing, or no GREEN commit follows a RED commit (#5275), add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
 </gate_enforcement>
 
 <end_of_phase_review>
@@ -342,7 +342,7 @@ TDD Plans: {count} | Gate violations: {count}
 
 ### What the Review Checks
 
-1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order. A plan is scored on its own `test(<plan>):` / `feat(<plan>):` commits, with one exception (#4867): a RED-only probe plan is satisfied by a `feat(...)` commit under a plan that declares it in `depends_on`, directly or through a chain. That is the gap-closure shape (probe plan, then the fix plan that depends on it). The plan's own RED is still required, a plan nothing depends on is scored alone, and the report names the plan that supplied the GREEN (`Plan {id} GREEN is supplied by dependent plan {id}.`).
+1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order (#5275). Order is commit ancestry, not log position or commit date: a GREEN counts only when it descends from a RED commit of the plan, so a history merged from worktree branches is judged by what each commit descends from. A plan with both commit kinds but no GREEN after a RED fails with `reason: green_before_red` and the line `Plan {id} GREEN precedes RED: no feat(...) commit descends from a test(...) commit.`, distinct from the `missing` row for a plan without a RED or GREEN commit. If git cannot answer the ancestry question, the GREEN keeps its credit rather than becoming a violation. A plan is scored on its own `test(<plan>):` / `feat(<plan>):` commits, with one exception (#4867): a RED-only probe plan is satisfied by a `feat(...)` commit under a plan that declares it in `depends_on`, directly or through a chain. That is the gap-closure shape (probe plan, then the fix plan that depends on it). The plan's own RED is still required, a plan nothing depends on is scored alone, and the report names the plan that supplied the GREEN (`Plan {id} GREEN is supplied by dependent plan {id}.`).
 2. **Test quality:** RED phase tests fail for the right reason (not import errors or syntax)
 3. **Minimal GREEN:** Implementation is minimal — no premature optimization in GREEN phase
 4. **Refactor discipline:** If REFACTOR commit exists, tests still pass

package/gsd-core/templates/DEBUG.md

@@ -25,6 +25,17 @@ bug_class: null  <!-- assigned at Phase 1.75 — bohrbug|heisenbug-mandelbug|con
 reasoning_checkpoint: null  <!-- populated before every fix attempt — see structured_returns -->
 tdd_checkpoint: null  <!-- populated when tdd_mode is active after root cause confirmed -->
 
+## Session Loop
+<!-- Read and written only by the checkpoint loop that drives gsd-debugger (on Pi, the top-level session); gsd-debugger never edits it. OVERWRITE on each dispatch and each wait -->
+
+goal: find_and_fix | find_root_cause_only
+tdd_mode: false
+tdd_phase: none | green
+resume_count: 0
+awaiting: none | [header of the return whose question is open]
+question: none | [checkpoint type and the full question text shown to the user]
+last_next_action: [next_action seen before the last re-dispatch]
+
 ## Symptoms
 <!-- Written during gathering, then immutable -->
 
@@ -78,6 +89,11 @@ files_changed: []
 - `reasoning_checkpoint`: OVERWRITE before every fix_and_verify — seven-field structured reasoning record (hypothesis, confirming_evidence, falsification_test, fix_rationale, blind_spots, candidate_causes, and_gate) — see `gsd-debugger.md` Structured Reasoning Checkpoint
 - `tdd_checkpoint`: OVERWRITE during TDD red/green phases — test file, name, status, failure output
 
+**Session Loop:**
+- Owned by the checkpoint loop that drives `gsd-debugger`; on Pi that loop is the top-level session, which holds no state in memory between turns (#5638)
+- OVERWRITE on each dispatch and each wait; the debugger never edits it and `## Current Focus` rewrites never touch it
+- Fields: goal, tdd_mode, tdd_phase, resume_count, awaiting, question, last_next_action
+
 **Symptoms:**
 - Written during initial gathering phase
 - IMMUTABLE after gathering complete

package/gsd-core/templates/config.json

@@ -30,7 +30,8 @@
     "sub_repos": []
   },
   "git": {
-    "create_tag": true
+    "create_tag": true,
+    "repo_tagging": "single"
   },
   "parallelization": {
     "enabled": true,

package/gsd-core/templates/verification-report.md

@@ -16,7 +16,7 @@ covered_files: # #4155 — see agents/gsd-verifier.md's "Create VERIFICATION.md"
   - .planning/phases/XX-name/{phase_num}-{plan}-PLAN.md
   - .planning/phases/XX-name/{phase_num}-{plan}-SUMMARY.md
   - src/{changed-file}.cts
-covered_digest: "v3:sha256:{digest from verification.fingerprint}"
+covered_digest: "v4:sha256:{digest from verification.fingerprint}"
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised)
 behavior_unverified_items: # Only if behavior_unverified > 0 — the truths above as structured items; emitted regardless of overall status
   - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"

package/gsd-core/workflows/audit-fix.md

@@ -128,7 +128,8 @@ if [ -z "$AUDIT_TEST_CMD" ]; then
   elif [ -f "Justfile" ] || [ -f "justfile" ]; then
     AUDIT_TEST_CMD="just test"
   elif [ -f "package.json" ]; then
-    AUDIT_TEST_CMD="npm test"
+    AUDIT_TEST_CMD=$(gsd_run query resolve-package-manager test --cwd . 2>/dev/null || echo "npm test")
+    [ -n "$AUDIT_TEST_CMD" ] || AUDIT_TEST_CMD="npm test"
   elif [ -f "Cargo.toml" ]; then
     AUDIT_TEST_CMD="cargo test"
   elif [ -f "go.mod" ]; then

package/gsd-core/workflows/code-review/steps/structural-pre-pass.md

@@ -2,8 +2,17 @@ When `FALLOW_ENABLED=true`:
 
 1) Resolve binary via `node_modules/.bin/fallow` first, then PATH.
 ```bash
+# gsd-resolve-lib begin fallow-runner.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="fallow-runner.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: fallow-runner.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 FALLOW_BIN=$(FALLOW_CWD="$(pwd)" node -e "
-const { resolveFallowBinary } = require('./gsd-core/bin/lib/fallow-runner.cjs');
+const { resolveFallowBinary } = require(require('path').join(process.env.GSD_LIB_DIR, 'fallow-runner.cjs'));
 const resolved = resolveFallowBinary({ cwd: process.env.FALLOW_CWD });
 if (resolved) process.stdout.write(resolved);
 ")

package/gsd-core/workflows/code-review.md

@@ -32,8 +32,20 @@ PHASE_ARG="${1}"
 # logic (e.g., --all and --auto imply --fix). Resolved BEFORE the init call below so
 # the section-manifest gate forwards the RESOLVED (post-implication) fix decision, not
 # just a literal --fix token check.
+# gsd-resolve-lib begin code-review-flags.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="code-review-flags.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+[ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: code-review-flags.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 FLAGS_JSON=$(node -e "
-  const { parseCodeReviewFlags } = require('./gsd-core/bin/lib/code-review-flags.cjs');
+  const { parseCodeReviewFlags } = require(require('path').join(process.env.GSD_LIB_DIR, 'code-review-flags.cjs'));
   const flags = parseCodeReviewFlags(process.argv.slice(1));
   process.stdout.write(JSON.stringify(flags));
 " -- "$@" 2>/dev/null)
@@ -125,12 +137,25 @@ If FILES_OVERRIDE is set (from --files flag):
 ```bash
 if [ -n "$FILES_OVERRIDE" ]; then
   REVIEW_FILES=()
-  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+  # #5519: compare the repository root and each resolved path in ONE form. On Windows Git Bash,
+  # `git rev-parse --show-toplevel` (a native program) reports a mixed path (C:/Users/..) while
+  # GNU `realpath` reports an MSYS POSIX path (/c/Users/..); the two never share a prefix, so
+  # every entry looked "outside". `cygpath -m` exists exactly where the forms differ and maps both
+  # to the mixed form; elsewhere the value passes through unchanged.
+  _gsd_norm_path() {
+    if command -v cygpath >/dev/null 2>&1; then cygpath -m "$1"; else printf '%s' "$1"; fi
+  }
+  REPO_ROOT=$(_gsd_norm_path "$(git rev-parse --show-toplevel 2>/dev/null)")
   
   for file_path in "${FILES_ARRAY[@]}"; do
-    # Security: validate path is within repository (prevent path traversal)
-    ABS_PATH=$(realpath -m "${file_path}" 2>/dev/null || echo "${file_path}")
-    if [[ "$ABS_PATH" != "$REPO_ROOT"* ]]; then
+    # Security: validate path is within repository (prevent path traversal). Compare on a path
+    # boundary: the root itself or anything under "<root>/" — a sibling such as "<root>-other"
+    # shares the prefix but is not inside.
+    ABS_PATH=$(_gsd_norm_path "$(realpath -m "${file_path}" 2>/dev/null || echo "${file_path}")")
+    # Fail closed on two shapes that cannot be trusted: an empty root (git failed, so nothing can be
+    # "inside" it) and a path that still holds ".." segments (a resolved path never does, so it was
+    # not resolved — no GNU realpath).
+    if [ -z "$REPO_ROOT" ] || [[ "$ABS_PATH" == */../* || "$ABS_PATH" == */.. ]] || [[ "$ABS_PATH" != "$REPO_ROOT" && "$ABS_PATH" != "$REPO_ROOT"/* ]]; then
       echo "Error: File path outside repository, skipping: ${file_path}"
       continue
     fi
@@ -437,8 +462,20 @@ DEPTH_PAYLOAD=$(printf '%s\n' "${REVIEW_FILES[@]}" | FLAG_DEPTH="$DEPTH_OVERRIDE
   }));
 ")
 
+# gsd-resolve-lib begin code-review-depth.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="code-review-depth.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+[ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: code-review-depth.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 DEPTH_JSON=$(echo "$DEPTH_PAYLOAD" | node -e "
-  const { resolveCodeReviewDepth } = require('./gsd-core/bin/lib/code-review-depth.cjs');
+  const { resolveCodeReviewDepth } = require(require('path').join(process.env.GSD_LIB_DIR, 'code-review-depth.cjs'));
   const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf-8'));
   process.stdout.write(JSON.stringify(resolveCodeReviewDepth(input)));
 ")
@@ -737,9 +774,21 @@ if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
   # Normalize fallow's raw report into the compact {summary, findings[]} contract
   # the reviewer consumes (real fallow schema -> normalized findings).
   FALLOW_NORMALIZED_PATH="${PHASE_DIR}/FALLOW-normalized.json"
+  # gsd-resolve-lib begin fallow-runner.cjs (#5640): load helpers from the installed runtime, not the cwd
+  _gsd_lib_probe="fallow-runner.cjs"
+  _gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  _gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+  case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+  [ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+  GSD_LIB_DIR=""
+  _gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+  _gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+  if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: fallow-runner.cjs not found in the GSD runtime (looked in ${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib); continuing without it." >&2; fi
+  export GSD_LIB_DIR
+  # gsd-resolve-lib end
   FALLOW_SRC="$FALLOW_JSON_PATH" FALLOW_OUT="$FALLOW_NORMALIZED_PATH" node -e "
     const fs = require('fs');
-    const { normalizeFallowReportFile } = require('./gsd-core/bin/lib/fallow-runner.cjs');
+    const { normalizeFallowReportFile } = require(require('path').join(process.env.GSD_LIB_DIR, 'fallow-runner.cjs'));
     const n = normalizeFallowReportFile(process.env.FALLOW_SRC);
     fs.writeFileSync(process.env.FALLOW_OUT, JSON.stringify(n, null, 2));
   " 2>/dev/null && FALLOW_EMBED_PATH="$FALLOW_NORMALIZED_PATH" || FALLOW_EMBED_PATH="$FALLOW_JSON_PATH"
@@ -943,6 +992,11 @@ grep -A 3 "^### CR-\|^### BL-\|^### WR-" "${REVIEW_PATH}" | head -n 12
 **Windows:** This workflow uses bash features (arrays, process substitution). On Windows, it requires
 Git Bash or WSL. Native PowerShell is not supported. The CI matrix (Ubuntu/macOS/Windows)
 runs under Git Bash on Windows runners, which provides bash compatibility.
+The `--files` containment check compares the repository root with each resolved path, and Git Bash
+reports them in different forms (`git rev-parse` returns `C:/Users/...`, GNU `realpath` returns
+`/c/Users/...`), so both are normalized with `cygpath -m` (shipped with Git Bash) before the
+comparison. Relative paths and absolute paths in either form are accepted when they are inside the
+repository (#5519).
 
 **macOS:** macOS ships with bash 3.2 (GPL licensing). This workflow does NOT use `mapfile` (bash 4+
 only) — all array construction uses portable `while IFS= read -r` loops compatible with bash 3.2.