@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -63,7 +63,19 @@ function countRoadmapPhases(roadmapPath, fallbackCount, cwd, ws, versionOverride
             return fallbackCount;
         if (!cwd)
             return fallbackCount;
-        const filter = getMilestonePhaseFilter(cwd, versionOverride ?? null, null, ws ?? null);
+        // #2761 B1 (trek-e review): `undefined`, NOT `null`. The third argument
+        // discriminates "not resolved yet — resolve it from this workstream's
+        // config" (`undefined`) from "resolved, and it is not bracket" (`null`).
+        // This site meant the former and spelled the latter, so a workstream that
+        // opted into `phase_id_convention: "bracket"` had its ROADMAP scanned with
+        // the LEGACY grammar: the heading set came back empty, `phaseCount` was 0,
+        // and the count silently fell back to the on-disk directory count — the
+        // very degrade the #3185 rewrite of this function existed to remove.
+        // Measured on a bracket workstream whose milestone declares 3 phases:
+        // `null` -> 0 (fallback), `undefined` -> 3. A non-bracket workstream
+        // resolves to a value that compiles the same base grammar `null` did, so
+        // its count is unchanged (verified against a legacy control).
+        const filter = getMilestonePhaseFilter(cwd, versionOverride ?? null, undefined, ws ?? null);
         // A pass-all degrade (phaseCount 0) means the window declared no phases —
         // fall back rather than reporting a confident zero.
         return filter.phaseCount > 0 ? filter.phaseCount : fallbackCount;
@@ -437,7 +449,13 @@ function inspectWorkstream(cwd, name, options = {}) {
     // filtering. Consulted only when it is genuinely scoped to a single milestone
     // (`versionScoped`); the unversioned whole-roadmap shape spans the project's
     // lifetime and would re-admit prior-milestone phases — the very defect here.
-    const headingFilter = getMilestonePhaseFilter(cwd, currentVersion, null, name);
+    //
+    // #2761 B1 (trek-e review): `undefined`, not `null` — same discriminator fix
+    // as `countRoadmapPhases` above. This site iterates workstreams by NAME, so
+    // it is exactly the caller that cannot set `GSD_WORKSTREAM`; spelling `null`
+    // pinned every workstream to the legacy grammar and made `headingScoped`
+    // unreachable (`phaseCount > 0` never held) on a bracket workstream.
+    const headingFilter = getMilestonePhaseFilter(cwd, currentVersion, undefined, name);
     const headingScoped = headingFilter.versionScoped && headingFilter.phaseCount > 0;
     // Phase keys the ROADMAP attributes to some OTHER milestone. A row carrying an
     // explicit version that is not the current one is a positive claim by a prior

package/gsd-core/bin/lib/workstream-name-policy.cjs

@@ -6,6 +6,24 @@
  * byte-for-behaviour from the prior hand-written .cjs; only types are added.
  *
  * Used by active-workstream-store.cjs, planning-workspace.cjs, workstream.cjs.
+ *
+ * #3883 (ADR-3473 §8.3): toWorkstreamSlug delegates to core-utils.cjs's
+ * generateSlugInternal (the canonical slug formula), passing `maxLen: null`
+ * to preserve this site's pre-migration untruncated contract — the 60-char
+ * default collided distinct >60-char workstream names onto the same slug
+ * (verified: `"a".repeat(60)+"alpha"` and `"a".repeat(60)+"beta"` truncated
+ * identically). core-utils.cjs already
+ * requires (transitively, at module-init time) THIS module:
+ * core-utils.cjs -> planning-workspace.cjs -> active-workstream-store.cjs ->
+ * workstream-name-policy.cjs. A top-level require of core-utils.cjs here
+ * would therefore close that cycle and — per this codebase's compiled-.cjs
+ * convention of a single `module.exports = {...}` reassignment at the bottom
+ * of core-utils.cjs — capture a stale, still-empty exports object forever
+ * (verified live: "generateSlugInternal is not a function" whichever module
+ * loads first). The require is deferred (lazy, inside toWorkstreamSlug's
+ * body) instead, mirroring the same cycle-break already used by
+ * core-utils.cts's own getPhaseFileStats/plan-scan.cjs seam and by
+ * phase-id.cts's toDir/getPhaseDirFromPhaseId.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
@@ -68,10 +86,13 @@ function validateWorkstreamName(name) {
  * Lowercases, collapses non-alphanumeric runs to hyphens, strips leading/trailing hyphens.
  */
 function toWorkstreamSlug(name) {
-    return String(name ?? '')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
+    // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+    // (generateSlugInternal, core-utils.cts) rather than re-implementing it —
+    // this call site previously diverged from it (no transliteration, no
+    // 60-char truncation). Lazy require to break the core-utils.cjs cycle
+    // (see the module dependency doc comment above).
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+    return require('./core-utils.cjs').generateSlugInternal(String(name ?? ''), null) ?? '';
 }
 /**
  * Returns true when `name` is a valid active workstream name:

package/gsd-core/bin/lib/worktree-base-ref.cjs

@@ -94,10 +94,13 @@ function parseJsonc(text) {
 }
 // ─── Message constants (verbatim — downstream docs/tests depend on these) ─────
 function buildMsgDiverged(headSha, forkRef, forkSha) {
-    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
+    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. Parallel worktrees return once HEAD is merged/pushed so ${forkRef} matches it. (worktree.baseRef:"head" applies only where GSD itself creates the worktree — the runtime harness does not read it; #48, #3659.)`;
 }
-const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
-const MSG_HEAD_UNRESOLVABLE = `⚠ Cannot determine the worktree base (git rev-parse HEAD did not return a definitive answer). Running this phase sequentially on the main working tree to avoid an unverified base mismatch. Note: worktree.baseRef:"head" would silence this check without verifying the base — it skips the comparison rather than resolving it. Retry; if it persists, check for a stalled filesystem mount or a stale git index lock (.git/index.lock). See #683, #3050.`;
+const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. Parallel worktrees return once origin/HEAD resolves and matches HEAD. See #683, #3659.`;
+function buildMsgBaserefHeadIgnored(headSha, forkRef, forkSha) {
+    return `⚠ Worktree base mismatch: worktree.baseRef:"head" is set, but the runtime harness does not honor it for isolated dispatch — the fork base stays ${forkRef} (${shortSha(forkSha)}) while HEAD is ${shortSha(headSha)} (#48; upstream claude-code#44965). Running this phase sequentially on the main working tree. Parallel worktrees return once HEAD is merged/pushed so ${forkRef} matches it, or on runtimes where GSD itself manages worktree creation. See #3659.`;
+}
+const MSG_HEAD_UNRESOLVABLE = `⚠ Cannot determine the worktree base (git rev-parse HEAD did not return a definitive answer). Running this phase sequentially on the main working tree to avoid an unverified base mismatch. Note: worktree.baseRef:"head" silences this check only where GSD itself creates the worktree (orchestrator-managed runtimes) — in harness mode it never applied (#48, #3659). Retry; if it persists, check for a stalled filesystem mount or a stale git index lock (.git/index.lock). See #683, #3050.`;
 /**
  * Returns true when an execGit result indicates the subprocess was killed by
  * a timeout. A timeout means the command genuinely could not complete — it
@@ -228,7 +231,20 @@ function resolveEffectiveBaseRef(claudeDir, deps, userClaudeDir) {
  * deps.userClaudeDir overrides the user/global config directory resolution
  * (default: getGlobalConfigDir('claude'), which honours CLAUDE_CONFIG_DIR).
  */
-function cmdWorktreeBaseCheck(cwd, _args, deps) {
+function cmdWorktreeBaseCheck(cwd, args, deps) {
+    // --mode threads the dispatch isolation mode through to the evaluation
+    // (#3659): 'harness-worktree' (default) or 'orchestrator-worktree'. Invalid
+    // or missing values after --mode fail closed — a silently defaulted typo
+    // would re-open the hole the flag exists to close.
+    let isolationMode = 'harness-worktree';
+    const modeIdx = args.indexOf('--mode');
+    if (modeIdx !== -1) {
+        const value = args[modeIdx + 1];
+        if (value !== 'harness-worktree' && value !== 'orchestrator-worktree') {
+            throw new Error(`worktree base-check: --mode must be harness-worktree or orchestrator-worktree, got ${JSON.stringify(value ?? null)}`);
+        }
+        isolationMode = value;
+    }
     const claudeDir = node_path_1.default.join(cwd, '.claude');
     const userClaudeDir = Object.prototype.hasOwnProperty.call(deps ?? {}, 'userClaudeDir')
         ? deps.userClaudeDir
@@ -238,8 +254,22 @@ function cmdWorktreeBaseCheck(cwd, _args, deps) {
         cwd,
         effectiveBaseRef,
         execGit: deps?.execGit,
+        isolationMode,
+    });
+    // Default emit goes through fs.writeSync(1, …), NOT process.stdout.write:
+    // the CLI's --pick capture intercepts writeSync, and command substitution
+    // is a pipe — via process.stdout.write a `$(gsd-tools … --pick x)` capture
+    // received the full JSON instead of the picked field, so the workflow
+    // auto-degrade guards never matched (#3659 review). Short-count loop per
+    // io.cjs writeAllSync's rationale (a non-blocking pipe can accept partial
+    // writes).
+    const write = deps?.write ?? ((s) => {
+        const buf = Buffer.from(s, 'utf8');
+        let offset = 0;
+        while (offset < buf.length) {
+            offset += node_fs_1.default.writeSync(1, buf, offset, buf.length - offset);
+        }
     });
-    const write = deps?.write ?? ((s) => process.stdout.write(s));
     write(JSON.stringify(result, null, 2) + '\n');
     return result;
 }
@@ -295,7 +325,20 @@ function cmdWorktreeSetBaseRef(cwd, _args, deps) {
         baseRef: 'head',
         file,
     };
-    const write = deps?.write ?? ((s) => process.stdout.write(s));
+    // Default emit goes through fs.writeSync(1, …), NOT process.stdout.write:
+    // the CLI's --pick capture intercepts writeSync, and command substitution
+    // is a pipe — via process.stdout.write a `$(gsd-tools … --pick x)` capture
+    // received the full JSON instead of the picked field, so the workflow
+    // auto-degrade guards never matched (#3659 review). Short-count loop per
+    // io.cjs writeAllSync's rationale (a non-blocking pipe can accept partial
+    // writes).
+    const write = deps?.write ?? ((s) => {
+        const buf = Buffer.from(s, 'utf8');
+        let offset = 0;
+        while (offset < buf.length) {
+            offset += node_fs_1.default.writeSync(1, buf, offset, buf.length - offset);
+        }
+    });
     write(JSON.stringify(output, null, 2) + '\n');
     return output;
 }
@@ -311,12 +354,19 @@ function evaluateWorktreeBaseDegrade(deps) {
     const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     const cwd = deps?.cwd;
     const cwdOpts = cwd ? { cwd } : {};
-    // a. If baseRef is explicitly 'head' the harness forks from HEAD — no mismatch possible.
-    // Claude Code's worktree.baseRef accepts only "fresh" (= origin/HEAD, the default) or "head".
-    // Therefore special-casing "head" here and otherwise comparing HEAD against origin/HEAD is
-    // complete: any non-"head" value (including "fresh" and absent/null) has fresh/origin-HEAD
-    // semantics and must be evaluated against origin/HEAD. (Reference: Claude Code worktrees docs, #683.)
-    if (deps?.effectiveBaseRef === 'head') {
+    // a. baseRef 'head' suppresses ONLY where GSD controls the fork start-point
+    // (#3659). The former unconditional suppress trusted the harness to honor the
+    // setting; #48 verified 5/5 that the Agent-isolation dispatch path never
+    // routes through project settings (upstream claude-code#44965), so in
+    // harness mode the fork base is always origin/HEAD and 'head' must fall
+    // through to the same comparison the fresh path runs. In
+    // orchestrator-worktree mode GSD itself runs `git worktree add <path>
+    // <start-point>` with the orchestrator HEAD — 'head' is honored by
+    // construction there and the suppress is correct. Any non-"head" value
+    // (including "fresh" and absent/null) has fresh/origin-HEAD semantics and is
+    // evaluated against origin/HEAD as before. (Reference: #683, #48, #3659.)
+    const headIgnoredByHarness = deps?.effectiveBaseRef === 'head';
+    if (headIgnoredByHarness && (deps?.isolationMode ?? 'harness-worktree') === 'orchestrator-worktree') {
         return { shouldDegrade: false, reason: 'baseref-head', message: null, headSha: null, forkRef: null, forkSha: null, headAbsenceVerified: null };
     }
     // b. Resolve HEAD sha.
@@ -389,6 +439,10 @@ function evaluateWorktreeBaseDegrade(deps) {
     if (forkSha === headSha) {
         return { shouldDegrade: false, reason: 'head-matches-fork', message: null, headSha, forkRef, forkSha, headAbsenceVerified: null };
     }
+    if (headIgnoredByHarness) {
+        const message = buildMsgBaserefHeadIgnored(headSha, forkRef, forkSha);
+        return { shouldDegrade: true, reason: 'baseref-head-ignored-by-harness', message, headSha, forkRef, forkSha, headAbsenceVerified: null };
+    }
     const message = buildMsgDiverged(headSha, forkRef, forkSha);
     return { shouldDegrade: true, reason: 'head-diverged-from-fork', message, headSha, forkRef, forkSha, headAbsenceVerified: null };
 }

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

@@ -374,6 +374,12 @@ function normalizeCleanupManifestEntry(entry) {
     // would make an unrecorded plan look 100% out of scope.
     const filesModified = (Array.isArray(e.files_modified) ? e.files_modified : [])
         .filter((f) => typeof f === 'string' && f.trim().length > 0);
+    // #3003: same liberal-in-what-we-accept rule as `files_modified` above — non-array,
+    // or non-string / empty elements, are dropped rather than coerced, and an EMPTY
+    // result omits the field entirely so "declares nothing" stays indistinguishable
+    // from "not recorded" (the guard's own absence-check already treats both as unknown).
+    const declaredDeletions = (Array.isArray(e.declared_deletions) ? e.declared_deletions : [])
+        .filter((f) => typeof f === 'string' && f.trim().length > 0);
     const normalized = {
         agent_id: typeof e.agent_id === 'string' ? e.agent_id : null,
         worktree_path: worktreePath,
@@ -383,6 +389,8 @@ function normalizeCleanupManifestEntry(entry) {
     };
     if (filesModified.length > 0)
         normalized.files_modified = filesModified;
+    if (declaredDeletions.length > 0)
+        normalized.declared_deletions = declaredDeletions;
     return normalized;
 }
 function normalizeCleanupManifest(manifest) {
@@ -480,16 +488,84 @@ function repoRootStillMidMerge(execGit, repoRoot) {
 // advisory fire on essentially every wave.
 const SUMMARY_ARTIFACT_DIR = '.planning';
 const SUMMARY_ARTIFACT_SUFFIX = 'SUMMARY.md';
+/**
+ * Decode a git-quoted path. With `core.quotepath` left at its default (`true`)
+ * git wraps any path containing non-ASCII or special bytes in double quotes
+ * and C-escapes it — e.g. `tests/é.ts` is emitted as the literal
+ * `"tests/\303\251.ts"`. Both sides of the deletion/scope comparison
+ * (a declared path and a git-reported path) must agree on the same decoded
+ * shape, and decoding it here — rather than passing `-c core.quotepath=false`
+ * on the `execGit` call — keeps the git argv, and therefore every existing
+ * test fixture that asserts on exact argv, unchanged. It also works
+ * regardless of the user's own `core.quotepath` config.
+ *
+ * A value that is not wrapped in a leading and trailing `"` is returned
+ * completely untouched — this is the overwhelmingly common (plain ASCII)
+ * case and must not be altered in any way.
+ *
+ * Escapes decode to BYTES, collected into a Buffer and decoded as UTF-8 only
+ * at the end: `\303\251` is two bytes that together form one character (é),
+ * so decoding them one at a time would produce mojibake. Malformed input
+ * (a trailing lone backslash, or an octal escape with fewer than three
+ * digits) never throws — it degrades to treating the character literally, so
+ * a single bad path can never take down the whole cleanup wave.
+ *
+ * Exported (#4081) so the codebase-drift gate's `--name-status` parser can
+ * decode the identical C-quoted form before classifying paths — the gate's
+ * `execGit` call sets no `core.quotepath` config, so it receives the same
+ * quoting and must decode it with the same single owner of this seam.
+ */
+function decodeGitQuotedPath(raw) {
+    if (raw.length < 2 || !raw.startsWith('"') || !raw.endsWith('"'))
+        return raw;
+    const body = raw.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch !== '\\' || i === body.length - 1) {
+            // UTF-8 bytes, not the code unit: a DECLARED path may be quoted while
+            // still holding a literal `é`, and pushing 0xE9 alone is invalid UTF-8.
+            // codePointAt keeps a surrogate pair together.
+            const codePoint = body.codePointAt(i);
+            const char = codePoint === undefined ? ch : String.fromCodePoint(codePoint);
+            bytes.push(...Buffer.from(char, 'utf8'));
+            i += char.length - 1;
+            continue;
+        }
+        const rest = body.slice(i + 1);
+        const octalMatch = /^([0-3][0-7][0-7])/.exec(rest);
+        if (octalMatch) {
+            bytes.push(parseInt(octalMatch[1], 8));
+            i += 3;
+            continue;
+        }
+        const next = body[i + 1];
+        const CONTROL_ESCAPES = {
+            a: 0x07, b: 0x08, f: 0x0c, n: 0x0a, r: 0x0d, t: 0x09, v: 0x0b,
+            '\\': 0x5c, '"': 0x22,
+        };
+        if (Object.prototype.hasOwnProperty.call(CONTROL_ESCAPES, next)) {
+            bytes.push(CONTROL_ESCAPES[next]);
+        }
+        else {
+            bytes.push(next.charCodeAt(0));
+        }
+        i += 1;
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
 /**
  * Normalize one path for scope comparison. Applied to BOTH sides so a declared
- * path and a git-reported path meet in the same shape: backslashes become
- * slashes unconditionally (a backslash path is not a Windows-only input),
- * a leading `./` and any trailing `/` are stripped. This is the single
- * normalizer shared by the SUMMARY-artifact predicate and the scope advisory,
- * so the two can never disagree about what `./a\b/` means.
+ * path and a git-reported path meet in the same shape: any git C-quoting is
+ * decoded first (order matters — the backslash-to-slash conversion below
+ * would destroy the escape sequences if it ran first), then backslashes
+ * become slashes unconditionally (a backslash path is not a Windows-only
+ * input), and a leading `./` and any trailing `/` are stripped. This is the
+ * single normalizer shared by the SUMMARY-artifact predicate and the scope
+ * advisory, so the two can never disagree about what `./a\b/` means.
  */
 function normalizeScopePath(raw) {
-    return String(raw || '')
+    return decodeGitQuotedPath(String(raw || '').trim())
         .replace(/\\/g, '/')
         .trim()
         .replace(/^\.\//, '')
@@ -703,6 +779,42 @@ function planWaveScopeConformance(changedPaths, declaredFiles, branch) {
     }
     return warnings;
 }
+/**
+ * #3003: split git's reported deletions into declared and undeclared.
+ *
+ * EXACT match after `normalizeScopePath` — the same normalizer both other path
+ * comparisons in this file use, so a declared path and a git-reported path meet in the
+ * same shape (`a\b` and `./a/b/` both become `a/b`).
+ *
+ * Deliberately NOT `declaredScopePrefix`. That helper returns `null` for a glob-leading
+ * pattern meaning "matches everything", which is right for the ADVISORY it serves — a
+ * false alarm there costs more than a miss — and exactly wrong for a GATE, where it would
+ * let `["*.ts"]` disarm the guard. A glob here is simply a literal path that matches
+ * nothing. Prefix matching is likewise refused: `["tests"]` must not authorize deleting
+ * everything under tests/.
+ *
+ * Pure — no git, no IO. Returns the undeclared residue in the order git reported it.
+ */
+function partitionDeclaredDeletions(deletedPaths, declared) {
+    const allowed = new Set((Array.isArray(declared) ? declared : [])
+        .filter((p) => typeof p === 'string')
+        .map((p) => normalizeScopePath(p))
+        .filter((p) => p.length > 0));
+    const undeclared = [];
+    const seen = new Set();
+    for (const raw of Array.isArray(deletedPaths) ? deletedPaths : []) {
+        if (typeof raw !== 'string')
+            continue;
+        const normalized = normalizeScopePath(raw);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        if (allowed.has(normalized))
+            continue;
+        undeclared.push(normalized);
+    }
+    return undeclared;
+}
 function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
     const execGit = deps.execGit || execGitDefault;
     const entries = Array.isArray(plan?.entries) ? plan.entries : [];
@@ -762,13 +874,17 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             continue; // #2852: isolate
         }
         if (deletions.stdout) {
-            // Unconditional: any deletion in this entry's branch blocks THIS entry. Whether
-            // that guard should have an opt-in for intentional deletions is a deferred
-            // product decision (issue #2852's own triage scoped it out — tracked in #3003);
-            // this fix only isolates the block to this one entry (#2852) instead of aborting
-            // the rest of the wave, same as every other block reason below.
-            blockEntry(result, 'branch_contains_deletions', deletions.stdout);
-            continue; // #2852: isolate
+            // #3003: a deletion the PLAN declared is authorized; anything else still blocks.
+            // Only a SUCCESSFUL check reaches here — a failed one blocked above on its own
+            // reason, so a broken check can never be filtered into a pass.
+            //
+            // The block detail carries ONLY the undeclared residue. Listing declared paths
+            // there would misdirect the operator toward paths that were fine.
+            const undeclaredDeletions = partitionDeclaredDeletions(deletions.stdout.split('\n'), entry.declared_deletions);
+            if (undeclaredDeletions.length > 0) {
+                blockEntry(result, 'branch_contains_deletions', undeclaredDeletions.join('\n'));
+                continue; // #2852: isolate
+            }
         }
         // #2596: advisory scope conformance — does the branch's ACTUAL committed
         // diff stay inside the scope the plan declared? Gated on a declared scope
@@ -779,13 +895,34 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
         // ADVISORY ONLY. Unlike the deletions check above, a finding here does NOT
         // call blockEntry and does NOT touch `ok` — the merge proceeds. Promotion
         // to a hard gate is a separate, disclosed change.
-        if (Array.isArray(entry.files_modified) && entry.files_modified.length > 0) {
+        // #3003: a declared deletion is in scope by construction — `git diff --name-only`
+        // includes deleted paths, so without accounting for the declaration, authorizing a
+        // deletion would immediately warn that the same path is out of declared scope.
+        //
+        // It is SUBTRACTED from the findings rather than UNIONED into the declared scope,
+        // and the difference is not cosmetic. `planWaveScopeConformance` reads its scope
+        // list with prefix-and-glob semantics, so unioning would silently hand
+        // `declared_deletions` a second, WIDER matching rule than the gate gives it:
+        // `["*.md"]` (inert at the gate) would yield a null prefix meaning "matches
+        // everything" and mute the advisory entirely, and `["src"]` would mute all of
+        // `src/`. One field with two matching rules is a trap. Subtracting keeps the
+        // field exact-match-only on every surface it touches.
+        //
+        // Gating stays on `files_modified` alone for the same reason: a plan that declares
+        // only deletions has still declared no modification scope, so the advisory stays
+        // exactly as silent as it was before this change instead of warning on every
+        // modified path.
+        const declaredFiles = Array.isArray(entry.files_modified) ? entry.files_modified : [];
+        if (declaredFiles.length > 0) {
             const scopeDiff = execGit(['diff', '--name-only', `HEAD...${entry.branch}`], { cwd: plan.repoRoot });
             const scopeWarnings = !gitResultOk(scopeDiff)
                 // A broken advisory must never become a gate: record that conformance
                 // is unknown rather than blocking (or, worse, silently passing).
                 ? [{ code: WAVE_CLEANUP_WARNING.SCOPE_CHECK_UNAVAILABLE, branch: entry.branch, path: null }]
-                : planWaveScopeConformance((scopeDiff.stdout || '').split('\n'), entry.files_modified, entry.branch);
+                : planWaveScopeConformance((scopeDiff.stdout || '').split('\n'), declaredFiles, entry.branch)
+                    // A path-less warning (SCOPE_CHECK_UNAVAILABLE) is never subtracted.
+                    .filter((w) => w.path === null
+                    || partitionDeclaredDeletions([w.path], entry.declared_deletions).length > 0);
             result.warnings.push(...scopeWarnings);
             allWarnings.push(...scopeWarnings);
         }
@@ -973,12 +1110,16 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
     // 2. Shared validation: run the candidate through the reader's normalizer.
     //    If it returns null the reader would drop this entry on read — reject now.
     const declaredScope = parseDeclaredScopeFlag(fields.files);
+    // #3003: reuse parseDeclaredScopeFlag — a blank/absent --deletions leaves the
+    // entry shape untouched, mirroring the --files rule directly above.
+    const declaredDeletions = parseDeclaredScopeFlag(fields.deletions);
     const candidate = {
         agent_id: agentId,
         worktree_path: worktreePath,
         branch,
         expected_base: base,
         ...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
+        ...(declaredDeletions.length > 0 ? { declared_deletions: declaredDeletions } : {}),
     };
     const entry = normalizeCleanupManifestEntry(candidate);
     if (!entry) {
@@ -1072,6 +1213,11 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
     if (entry.files_modified && entry.files_modified.length > 0) {
         recorded.files_modified = entry.files_modified;
     }
+    // #3003: same conservative rule as --files above — a blank --deletions
+    // leaves the entry shape untouched.
+    if (entry.declared_deletions && entry.declared_deletions.length > 0) {
+        recorded.declared_deletions = entry.declared_deletions;
+    }
     worktrees.push(recorded);
     return {
         ok: true,
@@ -1083,7 +1229,7 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
 /**
  * CLI command: append a validated per-agent entry to a wave cleanup manifest.
  *
- * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"]
+ * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"] [--deletions "<space-separated paths>"]
  *
  * Fails loudly (non-zero exit + recovery hint on stderr) when a field is
  * missing/garbled or the manifest is absent/malformed, rather than appending an
@@ -1092,13 +1238,15 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
 function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
     const flag = (name) => {
         const i = args.indexOf(name);
-        return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
+        if (i < 0 || i + 1 >= args.length)
+            return '';
+        return args[i + 1];
     };
     const write = deps.write || ((s) => process.stdout.write(s));
     const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
     const manifestPath = flag('--manifest');
     if (!manifestPath) {
-        writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"]\n');
+        writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"] [--deletions "<space-separated paths>"]\n');
         process.exitCode = 2;
         return { ok: false, reason: 'usage', entry: null };
     }
@@ -1121,6 +1269,7 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
         branch: flag('--branch'),
         base: flag('--base'),
         files: flag('--files'),
+        deletions: flag('--deletions'),
     });
     if (!plan.ok || plan.manifest === null) {
         writeErr(`[gsd] worktree.record-agent: ${plan.reason} — ${plan.hint || ''}\n`);
@@ -1165,12 +1314,16 @@ function planWorktreeCreate(fields) {
         };
     }
     const declaredScope = parseDeclaredScopeFlag(fields.files);
+    // #3003: reuse parseDeclaredScopeFlag — a blank/absent --deletions leaves the
+    // entry shape untouched, mirroring the --files rule directly above.
+    const declaredDeletions = parseDeclaredScopeFlag(fields.deletions);
     const candidate = {
         agent_id: agentId,
         worktree_path: worktreePath,
         branch,
         expected_base: base,
         ...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
+        ...(declaredDeletions.length > 0 ? { declared_deletions: declaredDeletions } : {}),
     };
     const entry = normalizeCleanupManifestEntry(candidate);
     if (!entry) {
@@ -1298,7 +1451,7 @@ function executeWorktreeCreatePlan(plan, repoRoot, deps = {}) {
  * validated manifest entry so the worktree is immediately manageable by
  * `worktree cleanup-wave` / `worktree reap-orphans`.
  *
- * Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"]
+ * Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"] [--deletions "<space-separated paths>"]
  *
  * #2584 FIX 1 — ORDERING CONTRACT: every manifest read/parse/shape-validate/
  * plan step runs BEFORE the git side effect (step 5). The ONLY manifest
@@ -1312,13 +1465,15 @@ function executeWorktreeCreatePlan(plan, repoRoot, deps = {}) {
 function cmdWorktreeCreate(cwd, args = [], deps = {}) {
     const flag = (name) => {
         const i = args.indexOf(name);
-        return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
+        if (i < 0 || i + 1 >= args.length)
+            return '';
+        return args[i + 1];
     };
     const write = deps.write || ((s) => process.stdout.write(s));
     const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
     const manifestPath = flag('--manifest');
     if (!manifestPath) {
-        writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"]\n');
+        writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"] [--deletions "<space-separated paths>"]\n');
         process.exitCode = 2;
         return { ok: false, reason: 'usage' };
     }
@@ -1384,6 +1539,7 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         branch: flag('--branch'),
         base: flag('--base'),
         files: flag('--files'),
+        deletions: flag('--deletions'),
     });
     if (!plan.ok || !plan.entry) {
         writeErr(`[gsd] worktree.create: ${plan.reason} — ${plan.hint || ''}\n`);
@@ -1455,6 +1611,11 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
     if (Array.isArray(plan.entry.files_modified) && plan.entry.files_modified.length > 0) {
         recorded.files_modified = plan.entry.files_modified;
     }
+    // #3003: same conservative rule as --files above — a blank --deletions
+    // leaves the entry shape untouched.
+    if (Array.isArray(plan.entry.declared_deletions) && plan.entry.declared_deletions.length > 0) {
+        recorded.declared_deletions = plan.entry.declared_deletions;
+    }
     const dedupeKey = `${recorded.worktree_path}\0${recorded.branch}`;
     const alreadyPresent = worktrees.some((existing) => {
         const normalized = normalizeCleanupManifestEntry(existing);
@@ -1830,6 +1991,9 @@ function pruneOrphanedWorktrees(repoRoot, deps = {}) {
     return [];
 }
 module.exports = {
+    // Re-exported for the codebase-drift gate's --name-status parser (#4081):
+    // single owner of git C-quoted-path decoding.
+    decodeGitQuotedPath,
     resolveWorktreeContext,
     resolveWorktreeLinkage,
     parseWorktreePorcelain,

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

@@ -1,5 +1,5 @@
 {
-  "_comment": "Canonical CONFIG_DEFAULTS for the Configuration Module. Nested shape is canonical. CJS flat projection (branching_strategy, sub_repos, etc.) is handled by consumers at the boundary. Security keys (security_enforcement, security_asvs_level, security_block_on) and post_planning_gaps live in workflow.* as their canonical location. resolve_model_ids, context_window, phase_naming are CJS-originated top-level keys included here. brave_search, firecrawl, exa_search default to false in the manifest; at runtime buildNewProjectConfig detects API keys. The plan_checker (CJS flat) → workflow.plan_check (canonical nested) divergence is resolved: canonical name is workflow.plan_check. _auto_chain_active is a runtime-state field included for completeness.",
+  "_comment": "Canonical CONFIG_DEFAULTS for the Configuration Module. Nested shape is canonical. CJS flat projection (branching_strategy, sub_repos, etc.) is handled by consumers at the boundary. Security keys (security_enforcement, security_asvs_level, security_block_on) and post_planning_gaps live in workflow.* as their canonical location. resolve_model_ids, context_window, phase_naming are CJS-originated top-level keys included here. brave_search, firecrawl, exa_search default to false in the manifest; at runtime buildNewProjectConfig detects API keys. The plan_checker (CJS flat) \u2192 workflow.plan_check (canonical nested) divergence is resolved: canonical name is workflow.plan_check. _auto_chain_active is a runtime-state field included for completeness.",
   "model_profile": "balanced",
   "commit_docs": true,
   "parallelization": true,
@@ -46,11 +46,13 @@
     "context_coverage_gate": true,
     "code_review": true,
     "code_review_depth": "standard",
+    "code_review_depth_overrides": [],
     "code_review_command": null,
     "pattern_mapper": true,
     "plan_bounce": false,
     "plan_bounce_script": null,
     "plan_bounce_passes": 2,
+    "inline_plan_threshold": 2,
     "auto_prune_state": false,
     "post_planning_gaps": true,
     "security_enforcement": true,
@@ -60,6 +62,7 @@
   },
   "planning": {
     "commit_docs": true,
+    "pr_strict": false,
     "search_gitignored": false,
     "sub_repos": [],
     "granularity": "standard"
@@ -97,6 +100,9 @@
     "source_grounding": true,
     "source_grounding_authority": "grep"
   },
+  "review": {
+    "max_prompt_tokens": null
+  },
   "capabilities": {
     "strict_known_registries": null,
     "auto_update": false