@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -366,13 +366,32 @@ function normalizeCleanupManifestEntry(entry) {
         return null;
     const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
     const allowedBases = Array.from(new Set([expectedBase, ...rawAllowedBases.filter((base) => typeof base === 'string' && base.length > 0)]));
-    return {
+    // #2596: liberal in what we accept — non-array, or non-string / empty
+    // elements, are dropped rather than coerced. An EMPTY result omits the field
+    // entirely, so "declared nothing" is indistinguishable from "not recorded":
+    // that ambiguity is already resolved as *unknown* by the per-plan submodule
+    // gate's own `[ -z "$PLAN_FILES" ]` rule, and inventing a second rule here
+    // 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,
         branch,
         expected_base: expectedBase,
         allowed_bases: allowedBases,
     };
+    if (filesModified.length > 0)
+        normalized.files_modified = filesModified;
+    if (declaredDeletions.length > 0)
+        normalized.declared_deletions = declaredDeletions;
+    return normalized;
 }
 function normalizeCleanupManifest(manifest) {
     let parsed = manifest;
@@ -461,6 +480,102 @@ function repoRootStillMidMerge(execGit, repoRoot) {
         return false; // ref not found — repoRoot is not mid-merge
     return true; // any other exit code (e.g. a fatal git error) — fail closed
 }
+// #2596: the single definition of "this file is an executor-written SUMMARY
+// artifact". Shared by `defaultFindSummaryFiles` (which walks for them to
+// rescue) and the scope advisory below (which must never flag them) — a plan's
+// declared `files_modified` never lists a SUMMARY, because the executor writes
+// it by orchestration contract, so a second copy of this rule would make the
+// 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.
+ */
+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: 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 decodeGitQuotedPath(String(raw || '').trim())
+        .replace(/\\/g, '/')
+        .trim()
+        .replace(/^\.\//, '')
+        .replace(/\/+$/, '');
+}
+/**
+ * True when a worktree-relative path is a SUMMARY artifact. Input may use
+ * either separator; normalization to POSIX is unconditional (backslash paths
+ * reach Linux too).
+ */
+function isSummaryArtifactRelPath(relPath) {
+    const normalized = normalizeScopePath(relPath);
+    return normalized.startsWith(`${SUMMARY_ARTIFACT_DIR}/`)
+        && normalized.endsWith(SUMMARY_ARTIFACT_SUFFIX);
+}
 /**
  * Walk <worktreePath>/.planning/ recursively and collect absolute paths of
  * all files whose names match *SUMMARY.md.  Returns [] when the directory
@@ -470,7 +585,7 @@ function repoRootStillMidMerge(execGit, repoRoot) {
  *   find "$WT/.planning" -name "*SUMMARY.md"
  */
 function defaultFindSummaryFiles(worktreePath) {
-    const planningDir = node_path_1.default.join(worktreePath, '.planning');
+    const planningDir = node_path_1.default.join(worktreePath, SUMMARY_ARTIFACT_DIR);
     const results = [];
     function walk(dir) {
         let entries;
@@ -485,7 +600,7 @@ function defaultFindSummaryFiles(worktreePath) {
             if (entry.isDirectory()) {
                 walk(full);
             }
-            else if (entry.isFile() && entry.name.endsWith('SUMMARY.md')) {
+            else if (entry.isFile() && entry.name.endsWith(SUMMARY_ARTIFACT_SUFFIX)) {
                 results.push(full);
             }
         }
@@ -588,6 +703,113 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
     }
     return { rescuedRelPaths, failures };
 }
+/**
+ * #2596: advisory codes emitted by the wave-cleanup gauntlet. Frozen and
+ * exported so tests assert on a code rather than on rendered prose (this repo
+ * forbids raw-text matching on test output).
+ */
+const WAVE_CLEANUP_WARNING = Object.freeze({
+    /** A committed path fell outside the plan's declared `files_modified`. */
+    SCOPE_OUT_OF_DECLARED: 'scope_out_of_declared',
+    /** The scope diff could not be computed, so conformance is unknown. */
+    SCOPE_CHECK_UNAVAILABLE: 'scope_check_unavailable',
+});
+/**
+ * The literal directory prefix a declared path covers, or `null` when the
+ * pattern begins with a glob metacharacter and therefore has no usable prefix.
+ *
+ * Deliberately literal-prefix only — NOT a glob engine. A hand-rolled
+ * `**`/`*`/`?` matcher inside a worktree-lifecycle module is an informal,
+ * undocumented pattern language living where no language belongs, and this
+ * repo forbids external deps in core. The submodule-intersection gate
+ * (`workflows/execute-phase/steps/per-plan-worktree-gate.md`) already ships
+ * exactly this glob-prefix rule; reusing it beats inventing a second one.
+ *
+ * `null` (no literal prefix, e.g. `*.md`) means "matches everything": for an
+ * ADVISORY, a false alarm costs more than a miss, so the ambiguous case
+ * suppresses rather than shouts.
+ */
+function declaredScopePrefix(declared) {
+    const globAt = declared.search(/[*?[]/);
+    if (globAt < 0)
+        return declared;
+    const literal = declared.slice(0, globAt).replace(/\/+$/, '');
+    return literal.length > 0 ? literal : null;
+}
+/**
+ * #2596: compare a branch's actual committed paths against the plan's declared
+ * scope. Pure — no git, no IO. Returns one warning per out-of-scope path, in
+ * the order the paths were given. Returns [] when nothing usable was declared:
+ * absence of data is not evidence of over-reach.
+ */
+function planWaveScopeConformance(changedPaths, declaredFiles, branch) {
+    if (!Array.isArray(declaredFiles))
+        return [];
+    const prefixes = [];
+    for (const declared of declaredFiles) {
+        if (typeof declared !== 'string')
+            continue;
+        const normalized = normalizeScopePath(declared);
+        if (!normalized)
+            continue;
+        prefixes.push(declaredScopePrefix(normalized));
+    }
+    if (prefixes.length === 0)
+        return [];
+    const warnings = [];
+    const seen = new Set();
+    for (const raw of Array.isArray(changedPaths) ? changedPaths : []) {
+        if (typeof raw !== 'string')
+            continue;
+        const changed = normalizeScopePath(raw);
+        if (!changed || seen.has(changed))
+            continue;
+        seen.add(changed);
+        if (isSummaryArtifactRelPath(changed))
+            continue;
+        const covered = prefixes.some((prefix) => (prefix === null || changed === prefix || changed.startsWith(`${prefix}/`)));
+        if (covered)
+            continue;
+        warnings.push({ code: WAVE_CLEANUP_WARNING.SCOPE_OUT_OF_DECLARED, branch, path: changed });
+    }
+    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 : [];
@@ -598,10 +820,12 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             reason: plan ? (plan.reason || 'missing_entries') : 'missing_plan',
             entries: [],
             pending: entries,
+            warnings: [],
         };
     }
     const results = [];
     const pending = [];
+    const allWarnings = [];
     let ok = true;
     // #2852: every per-entry failure site marks the SAME shape — status='blocked',
     // a reason code, the captured stderr, push to results, flip the overall `ok`
@@ -622,6 +846,7 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             status: 'pending',
             reason: null,
             stderr: '',
+            warnings: [],
         };
         const branchCheck = execGit(['-C', entry.worktree_path, 'rev-parse', '--abbrev-ref', 'HEAD'], { cwd: plan.repoRoot });
         if (!gitResultOk(branchCheck) || branchCheck.stdout.trim() !== entry.branch) {
@@ -644,13 +869,57 @@ 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
+        // being present: with nothing declared there is nothing to compare, so no
+        // git subprocess is spent at all (and every pre-#2596 fixture, none of
+        // which declares one, issues exactly the git calls it always did).
+        //
+        // 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.
+        // #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'), 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);
         }
         // Safety net: rescue uncommitted SUMMARY.md artifacts before the dirty check.
         // The executor leaves <quick_id>-SUMMARY.md uncommitted by contract — the
@@ -737,6 +1006,7 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
         reason: ok ? 'ok' : 'cleanup_blocked',
         entries: results,
         pending,
+        warnings: allWarnings,
     };
 }
 function cmdWorktreeCleanupWave(cwd, args = []) {
@@ -777,6 +1047,15 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
         process.exitCode = 1;
     }
 }
+/**
+ * #2596: split a `--files` value into declared paths. Whitespace-separated,
+ * matching the `PLAN_FILES` shape the per-plan worktree gate already builds
+ * with `jq -r '.files_modified // [] | join(" ")'`. Values are DATA compared
+ * against a diff — never opened, never passed to a shell.
+ */
+function parseDeclaredScopeFlag(raw) {
+    return String(raw || '').split(/\s+/).filter((token) => token.length > 0);
+}
 /**
  * Pure planner for the per-agent wave-manifest append.
  *
@@ -793,8 +1072,9 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
  * rejected loudly — the reader dedups on that key, so a re-record would be
  * silently dropped (the failure mode this verb exists to eliminate). The
  * on-disk shape stays the existing 4-field entry (`agent_id`, `worktree_path`,
- * `branch`, `expected_base`) — no schema change; the reader re-derives
- * `allowed_bases`.
+ * `branch`, `expected_base`) unless `--files` declares a scope, in which case
+ * an optional `files_modified` is appended (#2596); the reader still
+ * re-derives `allowed_bases`.
  */
 function planWorktreeRecordAgent(manifestRaw, fields) {
     // 1. Write-strict required-field check (loud, with which flag is missing).
@@ -824,11 +1104,17 @@ 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) {
@@ -917,6 +1203,16 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
         branch: entry.branch,
         expected_base: entry.expected_base,
     };
+    // #2596: only written when a scope was actually declared — conservative in
+    // what we send, so a blank --files leaves the 4-field shape untouched.
+    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,
@@ -928,7 +1224,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>
+ * 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
@@ -937,13 +1233,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>\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 };
     }
@@ -965,6 +1263,8 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
         worktreePath: flag('--path'),
         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`);
@@ -1008,11 +1308,17 @@ function planWorktreeCreate(fields) {
             entry: null,
         };
     }
+    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) {
@@ -1140,7 +1446,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>
+ * 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
@@ -1154,13 +1460,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>\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' };
     }
@@ -1225,6 +1533,8 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         worktreePath: flag('--path'),
         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`);
@@ -1291,6 +1601,16 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         branch: plan.entry.branch,
         expected_base: plan.entry.expected_base,
     };
+    // #2596: only written when a scope was actually declared — conservative in
+    // what we send, so a blank --files leaves the 4-field shape untouched.
+    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);
@@ -1677,6 +1997,9 @@ module.exports = {
     normalizeCleanupManifest,
     planWorktreeWaveCleanup,
     executeWorktreeWaveCleanupPlan,
+    WAVE_CLEANUP_WARNING,
+    planWaveScopeConformance,
+    isSummaryArtifactRelPath,
     cmdWorktreeCleanupWave,
     planWorktreeRecordAgent,
     cmdWorktreeRecordAgent,

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,
@@ -28,6 +28,7 @@
     "verifier": true,
     "nyquist_validation": true,
     "ai_integration_phase": true,
+    "agent_hint_routing": true,
     "human_verify_mode": "end-of-phase",
     "auto_advance": false,
     "_auto_chain_active": false,
@@ -45,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,
@@ -59,6 +62,7 @@
   },
   "planning": {
     "commit_docs": true,
+    "pr_strict": false,
     "search_gitignored": false,
     "sub_repos": [],
     "granularity": "standard"
@@ -96,6 +100,9 @@
     "source_grounding": true,
     "source_grounding_authority": "grep"
   },
+  "review": {
+    "max_prompt_tokens": null
+  },
   "capabilities": {
     "strict_known_registries": null,
     "auto_update": false

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

@@ -29,12 +29,14 @@
     "workflow.use_worktrees",
     "workflow.worktree_skip_hooks",
     "workflow.code_review_command",
+    "workflow.code_review_depth_overrides",
     "workflow.plan_bounce",
     "workflow.plan_bounce_script",
     "workflow.plan_bounce_passes",
     "workflow.plan_chunked",
     "workflow.specless_probe_fallback",
     "workflow.plan_review_convergence",
+    "workflow.agent_hint_routing",
     "code_quality.fallow.enabled",
     "code_quality.fallow.scope",
     "code_quality.fallow.profile",
@@ -42,16 +44,19 @@
     "ship.pr_body_sections",
     "git.branching_strategy",
     "git.base_branch",
+    "git.protected_branches",
     "git.create_tag",
     "git.phase_branch_template",
     "git.milestone_branch_template",
     "git.quick_branch_template",
     "planning.commit_docs",
+    "planning.pr_strict",
     "planning.search_gitignored",
     "planning.sub_repos",
     "review.default_reviewers",
     "review.max_prompt_tokens",
     "review.max_prompt_tokens_per_reviewer",
+    "review.parallel_lanes",
     "workflow.cross_ai_execution",
     "workflow.cross_ai_command",
     "workflow.cross_ai_timeout",
@@ -74,6 +79,7 @@
     "statusline.show_context_tokens",
     "statusline.state_format",
     "statusline.show_git",
+    "statusline.show_state_freshness",
     "workflow.max_discuss_passes",
     "features.thinking_partner",
     "context",
@@ -180,7 +186,12 @@
     {
       "topLevel": "model_policy",
       "source": "^model_policy\\.runtime_tiers\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",
-      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku>"
+      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku> (#3587)"
+    },
+    {
+      "topLevel": "phase_commit_docs",
+      "source": "^phase_commit_docs\\.\\d+[A-Z]?(?:\\.\\d+)*$",
+      "description": "phase_commit_docs.<phase-id> — per-phase commit_docs override (#3587). The <phase-id> segment is a hand-copy of the canonical PHASE_NUMBER_TOKEN_SOURCE grammar owned by src/phase-id.cts (#2128); this manifest is hand-maintained JSON so it cannot import that constant. Pinned against drift by the behavioral parity test in tests/commit-docs-bypass.test.cjs (folded 'phase-commit-docs' block, describe block 'E', #3587) — do not hand-edit this pattern without updating that test."
     }
   ]
 }

package/gsd-core/bin/shared/exit-codes.json

@@ -0,0 +1,8 @@
+[
+  { "code": 2,  "name": "HOOK_DENY",   "meaning": "Hook protocol deny — the harness blocks the tool call", "owner": "hook-adapter", "authorizedBy": "ADR-3889" },
+  { "code": 64, "name": "USAGE",       "meaning": "Caller error — bad argv, unknown subcommand, missing argument", "owner": "generic", "authorizedBy": "ADR-3889" },
+  { "code": 66, "name": "NO_INPUT",    "meaning": "Ran; zero units were in scope, and that emptiness is known to be genuine", "owner": "generic", "authorizedBy": "ADR-3889" },
+  { "code": 69, "name": "UNAVAILABLE", "meaning": "Could not run — prerequisite absent, input unreadable, scope unestablished", "owner": "generic", "authorizedBy": "ADR-3889" },
+  { "code": 70, "name": "INTERNAL",    "meaning": "Self-failure — crash, timeout, killed subprocess", "owner": "generic", "authorizedBy": "ADR-3889" },
+  { "code": 80, "name": "DEGRADED",    "meaning": "Ran to completion and is reporting a condition through its result payload rather than as a process failure", "owner": "gsd-tools", "authorizedBy": "ADR-3889 + ADR-2980" }
+]