@opengsd/gsd-core 1.11.0 → 1.12.0

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,79 @@ 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.
+ */
+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 +774,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 +869,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 +890,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 +1105,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 +1208,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 +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> [--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 +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> [--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 +1264,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 +1309,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 +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> [--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 +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> [--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 +1534,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 +1606,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);

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

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

@@ -29,6 +29,7 @@
     "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",
@@ -43,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",
@@ -75,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",

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" }
+]

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

@@ -0,0 +1,20 @@
+#!/bin/sh
+# GENERATED FILE — DO NOT EDIT BY HAND.
+# Source of truth: gsd-core/bin/shared/exit-codes.json. Regenerate with:
+#   node scripts/gen-exit-code-registry.cjs --write
+#
+# One `export EXIT_<NAME>=<code>` per gsd-core/bin/shared/exit-codes.json
+# entry (ADR-3889 §2, #3905/#3906/#3908). POSIX sh, safe under `set -u`:
+# sourcing this file only ever ASSIGNS variables, never reads one, so it
+# cannot trip an unset-variable check regardless of the caller's existing
+# environment.
+#
+# Usage (from a scanner under scripts/):
+#   . "$(dirname "$0")/../gsd-core/bin/shared/exit-codes.sh"
+#   exit "$EXIT_UNAVAILABLE"
+export EXIT_HOOK_DENY=2
+export EXIT_USAGE=64
+export EXIT_NO_INPUT=66
+export EXIT_UNAVAILABLE=69
+export EXIT_INTERNAL=70
+export EXIT_DEGRADED=80

package/gsd-core/bin/shared/model-catalog.json

@@ -112,7 +112,7 @@
     "openai": {
       "opus":   { "low": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" }, "medium": { "model": "gpt-5.6-sol", "reasoning_effort": "high" }, "high": { "model": "gpt-5.6-sol", "reasoning_effort": "xhigh" } },
       "sonnet": { "low": { "model": "gpt-5.6-luna", "reasoning_effort": "low" }, "medium": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.6-sol", "reasoning_effort": "medium" } },
-      "haiku":  { "low": { "model": "gpt-5.6-luna", "reasoning_effort": "minimal" }, "medium": { "model": "gpt-5.6-luna", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" } }
+      "haiku":  { "low": { "model": "gpt-5.6-luna", "reasoning_effort": "low" }, "medium": { "model": "gpt-5.6-luna", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" } }
     },
     "google": {
       "opus":   { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-3-flash" }, "high": { "model": "gemini-3.1-pro-preview" } },
@@ -130,6 +130,12 @@
       "haiku":  { "low": null, "medium": null, "high": null }
     }
   },
+  "codexModelEffort": {
+    "_baseline": ["low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-sol":   ["low", "medium", "high", "xhigh", "max", "ultra"],
+    "gpt-5.6-terra": ["low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-luna":  ["low", "medium", "high", "xhigh", "max"]
+  },
   "agents": {
     "gsd-planner":                { "golden": "opus",   "balanced": "opus",   "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
     "gsd-roadmapper":             { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
@@ -149,6 +155,7 @@
     "gsd-ui-auditor":             { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
     "gsd-doc-writer":             { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "execution",    "routingTier": "standard" },
     "gsd-doc-verifier":           { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-dom-verifier":           { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
 
     "gsd-advisor-researcher":     { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
     "gsd-ai-researcher":          { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },

package/gsd-core/references/agent-contracts.md

@@ -19,8 +19,9 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
 | gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` (unconsumed: blocked-research return — spawners detect failure via the #222 SUMMARY.md-on-disk check, no dispatch branch keys on the marker) | `gsd-core/workflows/new-milestone.md`, `gsd-core/workflows/new-project.md` | sentinel-match |
 | gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED`, `## INVESTIGATION INCONCLUSIVE`, `## TDD CHECKPOINT`, `## FIX REJECTED BY GUARDRAIL` | `agents/gsd-debug-session-manager.md`, `gsd-core/workflows/diagnose-issues.md`, `gsd-core/workflows/plan-phase.md`, `agents/gsd-executor.md` | sentinel-match |
 | gsd-debug-session-manager | Debug checkpoint loop | `## DEBUG SESSION COMPLETE`, `## CONTINUE_REQUIRED` | `gsd-core/workflows/debug.md` | sentinel-match |
-| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED`, `## ROADMAP DRAFT` (unconsumed: draft-presentation format the shipped execution flow never invokes — Step 8 returns `## ROADMAP CREATED`; retained for interactive draft review) | `gsd-core/workflows/new-milestone.md`, `gsd-core/workflows/new-project.md` | sentinel-match |
+| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED` | `gsd-core/workflows/new-milestone.md`, `gsd-core/workflows/new-project.md` | sentinel-match |
 | gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` | `gsd-core/workflows/ui-review.md` | sentinel-match |
+| gsd-dom-verifier | Live-DOM UAT verification | No marker (writes `{phase}-DOM-VERIFY.md` directly; the frontmatter `outcome` / `reason` scalars carry the verdict, and `could_not_look` is never conflated with `nothing_to_report`) | `{phase}-DOM-VERIFY.md` artifact, written by the `live-dom-uat` capability's `execute:wave:post` step dispatched from `gsd-core/workflows/execute-phase.md` | artifact+query |
 | gsd-ui-checker | UI validation | `## ISSUES FOUND`, `## UI-SPEC VERIFIED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-plan-checker.md` | sentinel-match |
 | gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` | `gsd-core/workflows/ui-phase.md` | sentinel-match |
 | gsd-verifier | Post-execution verification | `## Verification Complete` (unconsumed: Marker Rule 2 recorded decision — intentional title-case marker; completion is detected via the artifact route, nothing matches the marker) | `*-VERIFICATION.md` artifact + `gsd_run query verification.status` in `gsd-core/workflows/verify-work.md` | artifact+query |
@@ -56,7 +57,7 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
    - `structured-return` -- the agent has no way to write files (no `Write` tool) or simply doesn't; it returns parseable sections, a table, or JSON inline, and the caller reads that return text directly
 5. Markers must appear as H2 headings (`## `) at the start of a line in the agent's final output
 6. The `Consumed by` / `Kind` columns are machine-enforced by `check:contract-drift` (`scripts/check-contract-drift.cjs`), which cross-checks this table against what each `agents/*.md` file actually emits in-fence and what every `gsd-core/workflows/**`, `commands/**`, and `agents/**` file actually consumes. Update this table whenever an agent's return contract changes -- a stale row is a violation the check will report, not something to leave for later.
-7. A marker entry annotated `(unconsumed: <reason>)` is emitted deliberately but matched by no workflow, command, or agent — e.g. `## ROADMAP DRAFT`, a presentation format a human approves interactively. The check still verifies the marker is declared **and** emitted, and still counts it for case-collision purposes; only the consumer requirement is waived. Use it for display formats, never to silence a real orphan.
+7. A marker entry annotated `(unconsumed: <reason>)` is emitted deliberately but matched by no workflow, command, or agent — a display/presentation format no orchestrator branch consumes (the `## ROADMAP DRAFT` header was the canonical case until #3797 folded its content into `## ROADMAP CREATED`). The check still verifies the marker is declared **and** emitted, and still counts it for case-collision purposes; only the consumer requirement is waived. Use it for display formats, never to silence a real orphan.
 
 ## Key Handoff Contracts
 

package/gsd-core/references/api-coverage.md

@@ -53,7 +53,26 @@ compound modifiers ("Resolver-only API"), and first-party-qualified services
    `capabilities/ai-integration/fragments/api-coverage-plan-pre.md`.
 2. **Seal time (`verify:pre`).** The blocking `api-coverage.verify-pre` gate
    runs `check api-coverage.verify-pre <phase-dir>` and blocks unless a valid
-   matrix exists (or no integration is detected).
+   matrix exists (or no integration is detected in a scope it could actually
+   read).
+
+### Seal-time outcomes
+
+| Condition | Verdict |
+|---|---|
+| Valid `COVERAGE.md` matrix | pass |
+| `No external API integration: <reason>` declaration | pass (the reasoned human overrule) |
+| Malformed / partial matrix | **block** |
+| No matrix, integration signal found | **block** |
+| No matrix, no signal, scope was read | pass |
+| No matrix, **scope could not be established** | **block** — `scope_unavailable: true` (#3909) |
+| Phase token unresolvable | **block** |
+| Plan file exists but unreadable | **block** |
+| No `.planning/phases` tree at all | pass — not a GSD project layout |
+
+The last four are the fail-closed arms: the gate refuses to certify "no
+external-API integration" from scope it did not read. A phase with real plans
+and no API vocabulary is the fifth row, and is unaffected.
 
 ## The coverage matrix format
 
@@ -126,7 +145,10 @@ zero — the matrix is the durable subtraction record.
 
 ```bash
 echo "$PHASE_SCOPE" | node gsd-core/bin/lib/api-coverage.cjs --json
-# exit 0 = integration detected, 1 = none, 2 = startup error
+# exit 0 = integration detected, 1 = none (real input, examined, no signal)
+# NO_INPUT = stdin was empty or whitespace-only (registry code — ADR-3889 Phase 3, #3907)
+# UNAVAILABLE = stdin read failed (registry code)
+# NO_INPUT/UNAVAILABLE emit {"skipped":true,"reason":"no_input"|"stdin_error"} — no `detected` key
 ```
 
 The detector is a pure function (`detectApiIntegration` → `{ detected, signals,

package/gsd-core/references/autonomous-smart-discuss.md

@@ -5,7 +5,7 @@ Smart discuss is the autonomous-optimized variant of `gsd-discuss-phase`. It pro
 **Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
 
 ```bash
-PHASE_STATE=$(gsd-tools query init.phase-op ${PHASE_NUM})
+PHASE_STATE=$(gsd_run query init.phase-op ${PHASE_NUM})
 ```
 
 Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
@@ -94,7 +94,7 @@ Read the 3-5 most relevant files to understand existing patterns.
 **Get phase details:**
 
 ```bash
-DETAIL=$(gsd-tools query roadmap.get-phase ${PHASE_NUM})
+DETAIL=$(gsd_run query roadmap.get-phase ${PHASE_NUM})
 ```
 
 Extract `goal`, `requirements`, `success_criteria` from the JSON response.
@@ -266,7 +266,7 @@ Write the file.
 **Commit:**
 
 ```bash
-gsd-tools query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+gsd_run query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 Display confirmation: