@opengsd/gsd-core 1.12.0 → 1.13.0

package/agents/gsd-ui-researcher.md

@@ -367,6 +367,35 @@ gsd_run query commit "docs($PHASE): UI design contract" --files "$PHASE_DIR/$PAD
 UI-SPEC complete. Checker can now validate.
 ```
 
+## Revision Conflict
+
+Revision mode only. Emit this INSTEAD OF `## UI-SPEC COMPLETE` when a checker `fix_hint`
+contradicts a locked user answer, active capability guidance, or a constraint this UI-SPEC already
+encodes — or when the `required_property` is unreachable without breaking one. Resolve every
+non-conflicting issue first. This is not a failure: `/gsd:ui-phase` routes it to the user and does
+not spend a revision iteration on it.
+
+```markdown
+## REVISION_CONFLICT
+
+**Conflicts:** {N}  |  **Issues resolved anyway:** {M}
+
+| Issue | required_property | Conflicts with | Why the hint cannot be applied |
+|-------|-------------------|----------------|-------------------------------|
+| Dimension {N} | {property} | {locked answer / CLAUDE.md rule / spec constraint} | {one line} |
+
+### Alternatives Considered
+
+| Issue | Alternative | Satisfies required_property? | Cost of adopting |
+|-------|-------------|------------------------------|------------------|
+| Dimension {N} | {smaller or different mechanism} | {yes / partially — how} | {what it changes} |
+```
+
+**Every field is one line of plain text.** No newlines inside a cell, and never begin a field with
+`#`, `-`, `|` or a code fence. This table is presented directly to the user in ui-phase's revision
+step, not persisted to a shared file; a field that opens a heading, list item, table cell, or
+fence would corrupt that presentation.
+
 ## UI-SPEC Blocked
 
 ```markdown

package/agents/gsd-verifier.md

@@ -42,6 +42,7 @@ Every truth must resolve to VERIFIED, FAILED (BLOCKER), or UNCERTAIN (WARNING wi
 @~/.claude/gsd-core/references/verification-overrides.md
 @~/.claude/gsd-core/references/gates.md
 @~/.claude/gsd-core/references/verifier-phase-gates.md
+@~/.claude/gsd-core/references/verifier-evidence-gate.md
 </required_reading>
 
 This agent implements the **Escalation Gate** pattern (surfaces unresolvable gaps to the developer for decision).
@@ -410,7 +411,9 @@ grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|funct
 
 **Debt marker gate:** Any `TBD`, `FIXME`, or `XXX` marker in a file modified by this phase is a 🛑 BLOCKER unless the same line references formal follow-up work (`issue #123`, `PR #123`, `#123`, or `DEF-*`). Unreferenced markers mean completion is not auditable; set `status: gaps_found` and list each marker under `gaps`.
 
-Categorize: 🛑 Blocker (prevents goal or unresolved debt marker) | ⚠️ Warning (incomplete) | ℹ️ Info (notable)
+**Re-verification evidence gate (#3304):** in re-verification mode, a 🛑 Blocker other than an unresolved debt marker (always self-evidencing) blocks unconditionally only if it is a carried-forward gap (Step 0's `gaps:`) or the flagged file was git-modified since the prior `verified:` timestamp (fail closed: unresolvable history counts as modified). Otherwise it predates the gap-closure round unflagged and needs deterministic evidence — a named test run red, or another concrete reproducible artifact — to stay blocking. Full algorithm: @gsd-core/references/verifier-evidence-gate.md. Unevidenced → 📋 Advisory: record in `advisory:` frontmatter, exclude from Step 9 Rule 1, never revert a completed must-have.
+
+Categorize: 🛑 Blocker (prevents goal or unresolved debt marker) | ⚠️ Warning (incomplete) | ℹ️ Info (notable) | 📋 Advisory (re-verification only — new-scope, unevidenced; see above)
 
 ## Step 7b: Behavioral Spot-Checks
 
@@ -665,6 +668,8 @@ If `valid != true`, refuse to verify. Surface the discrepancy and ask the user t
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
+**#4155:** `covered_files`: every phase PLAN/SUMMARY (+superseded, nested `plans/`), mapped requirement, changed impl file — ROOT-relative. `gsd_run query verification.fingerprint {phaseDir} {file}...`, copy output — never hand-write `covered_digest`.
+
 Create `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`:
 
 ```markdown
@@ -673,6 +678,8 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+covered_files: [...]
+covered_digest: "v1:sha256:..."
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised); each is detailed in behavior_unverified_items below (and in human_verification when status is human_needed)
 overrides_applied: 0 # Count of PASSED (override) items included in score
 overrides: # Only if overrides exist — carried forward or newly added
@@ -700,6 +707,11 @@ deferred: # Only if deferred items exist (Step 9b)
   - truth: "Observable truth addressed in a later phase"
     addressed_in: "Phase N"
     evidence: "Matching goal or success criteria text"
+advisory: # Only if unevidenced new-scope findings exist (Step 7, re-verification only)
+  - finding: "Short description of the new-scope concern"
+    category: architectural | security | other
+    reason: "Why raised; what would resolve it"
+    evidence_status: "none provided"
 behavior_unverified_items: # Only if behavior_unverified > 0 — emitted regardless of overall status, so these survive a gaps_found phase
   - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"
     test: "What to trigger"
@@ -744,6 +756,15 @@ Only include this section if deferred items exist (from Step 9b).
 |---|------|-------------|----------|
 | 1 | {truth} | Phase {N} | {matching goal or success criteria} |
 
+### Advisory (New Scope, Unevidenced)
+
+New-scope findings from Step 7 with no deterministic evidence — reported,
+not blocking. Include this section (even "None") whenever re-verification ran.
+
+| # | Finding | Category | Why Advisory |
+|---|---------|----------|--------------|
+| 1 | {finding} | {category} | new-scope, no deterministic evidence |
+
 ### Required Artifacts
 
 | Artifact | Expected    | Status | Details |
@@ -918,6 +939,7 @@ return <div>No messages</div>  // Always shows "no messages"
 - [ ] Gaps structured in YAML frontmatter (if gaps_found)
 - [ ] Deferred items structured in YAML frontmatter (if deferred items exist)
 - [ ] Re-verification metadata included (if previous existed)
+- [ ] fingerprint fields written via verification.fingerprint (#4155)
 - [ ] VERIFICATION.md created with complete report
 - [ ] Results returned to orchestrator (NOT committed)
 </success_criteria>

package/bin/install.js

@@ -183,10 +183,11 @@ function isCodexHooksFeatureKey(key) {
   return CODEX_HOOKS_FEATURE_ALL_KEYS.includes(key);
 }
 
-// #768 \u2014 Claude Code permissions.allow / permissions.deny entries.
+// #768 \u2014 Claude Code permissions.allow entries.
 // Pre-populated during Claude installs to eliminate first-run approval friction
-// for gsd-core's own known-safe tool calls, and to add defense-in-depth deny
-// entries for common credential files.
+// for gsd-core's own known-safe tool calls. (The defense-in-depth deny entries
+// for credential files that #768 also wrote are retired \u2014 see
+// GSD_CLAUDE_LEGACY_DENY_PERMISSIONS below.)
 //
 // Format: each string uses Claude Code's documented permission rule syntax \u2014
 //   "Tool(pattern)"  e.g. "Bash(npx gsd-core *)", "Read(.planning/*)"
@@ -204,7 +205,20 @@ const GSD_CLAUDE_ALLOW_PERMISSIONS = Object.freeze([
   'Read(STATE.md)',
   'Edit(STATE.md)',
 ]);
-const GSD_CLAUDE_DENY_PERMISSIONS = Object.freeze([
+// #4221 \u2014 Retired deny rules. #768 wrote these three `Read()` deny rules
+// into settings.json; Claude Code 2.1.259 hardened the Bash-side enforcement
+// of Read() deny rules so that ANY such rule makes every
+// `cd DIR && grep/cat relative-path` compound prompt for approval, even in
+// `auto` permission mode \u2014 and GSD subagents emit hundreds of those per
+// session. The same protection now ships as the managed PreToolUse hook
+// hooks/gsd-secret-read-guard.js (a hook denial is not a permission rule and
+// never arms that check). Unlike the #2278 allow-side migration, there is no
+// surviving "current" deny list: the constant is RENAMED to its legacy role
+// and only ever filtered, never added. Byte-equal strings only \u2014 a user's
+// own hand-written identical rule is indistinguishable and is removed too
+// (the install manifest never recorded permission strings, so a
+// manifest-gated cleanup is not possible).
+const GSD_CLAUDE_LEGACY_DENY_PERMISSIONS = Object.freeze([
   'Read(.env)',
   'Read(.env.*)',
   'Read(.secrets)',
@@ -236,6 +250,13 @@ const GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS = Object.freeze([
  * so existing installs end up with the working `Edit(...)` forms instead of
  * both the dead legacy entry and its replacement sitting side by side.
  *
+ * Migration (#4221): the retired GSD_CLAUDE_LEGACY_DENY_PERMISSIONS entries
+ * are removed from permissions.deny (byte-equal only). Nothing is added to
+ * deny any more: an absent `deny` key is left absent (never created as an
+ * empty array), and a `deny` array emptied BY THIS FILTER is deleted so the
+ * retirement leaves no `"deny": []` residue; a user's pre-existing empty
+ * `deny: []` is untouched.
+ *
  * Defensive: if settings is not a plain object, returns immediately without
  * throwing. If permissions.allow / permissions.deny exist but are not arrays
  * (malformed settings), they are replaced with valid arrays.
@@ -252,7 +273,7 @@ function mergeClaudePermissions(settings) {
   if (!Array.isArray(settings.permissions.allow)) {
     settings.permissions.allow = [];
   }
-  if (!Array.isArray(settings.permissions.deny)) {
+  if (settings.permissions.deny !== undefined && !Array.isArray(settings.permissions.deny)) {
     settings.permissions.deny = [];
   }
 
@@ -265,9 +286,13 @@ function mergeClaudePermissions(settings) {
       settings.permissions.allow.push(entry);
     }
   }
-  for (const entry of GSD_CLAUDE_DENY_PERMISSIONS) {
-    if (!settings.permissions.deny.includes(entry)) {
-      settings.permissions.deny.push(entry);
+  if (Array.isArray(settings.permissions.deny)) {
+    const before = settings.permissions.deny.length;
+    settings.permissions.deny = settings.permissions.deny.filter(
+      (e) => !GSD_CLAUDE_LEGACY_DENY_PERMISSIONS.includes(e)
+    );
+    if (settings.permissions.deny.length === 0 && before > 0) {
+      delete settings.permissions.deny;
     }
   }
 }
@@ -411,7 +436,7 @@ const GSD_CHANGESET_FILES = [
   'github-release-notes.cjs', 'lint.cjs', 'new.cjs',
   'README.md', // documentation only — not user-authored
 ];
-const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs', 'drift-scan.cjs', 'alias-drift-families.cjs', 'exit-code-registry.cjs', 'ndjson-reporter.cjs', 'ci-job-timing.cjs'];
+const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs', 'drift-scan.cjs', 'alias-drift-families.cjs', 'exit-code-registry.cjs', 'ndjson-reporter.cjs', 'ci-job-timing.cjs', 'shellcheck-fetch.cjs'];
 
 /**
  * Resolve a runtime's shared-hooks directory name from its descriptor.
@@ -790,6 +815,10 @@ const {
 const {
   resolveRuntimeArtifactLayout,
 } = require(path.join(_gsdLibDir, 'runtime-artifact-layout.cjs'));
+const {
+  readSurface,
+  resolveSurface,
+} = require(path.join(_gsdLibDir, 'surface.cjs'));
 const {
   assertDestWithinConfigHome,
   createRuntimeArtifactInstallPlan,
@@ -1796,8 +1825,20 @@ const kiloAgentPermissionOrder = [
   'lsp',
 ];
 
+const kiloMcpPermissionPattern = /^mcp__([A-Za-z0-9_-]+)__((?:[A-Za-z0-9_-]+)|\*)$/;
+
+// Derives Kilo's native `{server}_{tool}` MCP permission key (kilo.ai/docs —
+// external, fixed format). Not injective: both capture groups allow `_`, so
+// e.g. `mcp__a_b__c` and `mcp__a__b_c` derive the same key. The `Set` below
+// resolves any such collision deterministically to first-seen-wins — see
+// src/runtime-artifact-conversion.cts's regression test. Mirrors that file's
+// convertClaudeToKiloPermissionTool exactly (#4032).
 function convertClaudeToKiloPermissionTool(claudeTool) {
-  return claudeToKiloAgentPermissions[claudeTool] || null;
+  const builtinPermission = claudeToKiloAgentPermissions[claudeTool];
+  if (builtinPermission) return builtinPermission;
+
+  const mcpPermission = kiloMcpPermissionPattern.exec(claudeTool);
+  return mcpPermission ? `${mcpPermission[1]}_${mcpPermission[2]}` : null;
 }
 
 function buildKiloAgentPermissionBlock(claudeTools) {
@@ -1814,6 +1855,10 @@ function buildKiloAgentPermissionBlock(claudeTools) {
   for (const permission of kiloAgentPermissionOrder) {
     lines.push(`  ${permission}: ${allowedPermissions.has(permission) ? 'allow' : 'deny'}`);
   }
+  for (const permission of allowedPermissions) {
+    if (kiloAgentPermissionOrder.includes(permission)) continue;
+    lines.push(`  ${permission}: allow`);
+  }
 
   return lines;
 }
@@ -3849,26 +3894,37 @@ Execute mode fallback:
 ## C. Task() → spawn_agent Mapping
 GSD workflows use \`Task(...)\` (Claude Code syntax). Translate to Codex collaboration tools:
 
-**Schema detection (required first step):** Codex exposes two \`spawn_agent\` schemas:
-- **agent_type-capable schema** (e.g. \`multi_agent_v2\`): \`spawn_agent\` accepts \`agent_type\`, \`message\`, \`reasoning_effort\`, \`fork_context\`, etc. — typed GSD agent dispatch is available.
-- **Generic schema** (\`multi_agent_v1\`): \`spawn_agent\` accepts only \`message\`, \`items\`, \`fork_context\` — there is **no \`agent_type\` field**. Typed GSD agent dispatch is unavailable in this session.
+**Schema detection (required first step):** Before spawning, inspect the \`spawn_agent\`
+tool's visible parameter schema (via \`tool_search\` or the tool list). Use the presence
+of \`agent_type\` only to choose typed dispatch versus the generic-agent workaround.
+Detect optional fields independently: \`model\`, \`reasoning_effort\`, \`task_name\`,
+\`fork_turns\`, and \`fork_context\` may be added or removed without \`agent_type\` changing.
+Never infer one field from a schema/version label or from the presence of another field.
 
-Before spawning, inspect the \`spawn_agent\` tool's visible parameter schema (via \`tool_search\` or the tool list) to determine which form is active.
+- **agent_type-capable schema:** \`spawn_agent\` advertises \`agent_type\` — typed GSD agent dispatch is available.
+- **Generic schema:** \`spawn_agent\` does not advertise \`agent_type\` — typed GSD agent dispatch is unavailable in this session, even if other optional fields are present.
 
 Typed mapping (agent_type-capable schema only):
 - \`Task(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
 - \`Agent(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
-- \`Task(model="...")\` → omit. \`spawn_agent\` has no inline \`model\` parameter;
-  GSD embeds the resolved per-agent model directly into each agent's \`.toml\`
-  at install time so \`model_overrides\` from \`.planning/config.json\` and
-  \`~/.gsd/defaults.json\` are honored automatically by Codex's agent router.
-- Resolved \`reasoning_effort="low|medium|high|xhigh"\` (\`xhigh\` is a GSD/Codex tier, not a generic runtime enum) → pass \`reasoning_effort\`
-  to \`spawn_agent\` when the runtime/tool supports it. Omit missing, empty,
-  inherited, or unsupported values; do not invent one-off effort literals in
-  workflow prose.
+- \`Task(model="{resolved_model}")\` → pass \`model="{resolved_model}"\` when the
+  visible \`spawn_agent\` schema advertises \`model\` and the resolved value is explicit.
+  This is how \`model_profile\` tier routing, including \`adaptive\`, reaches the child agent.
+  Omit \`model\` only when the schema does not advertise \`model\`, or when the value is
+  missing, empty, or \`"inherit"\`; omission deliberately inherits the session/static agent
+  configuration. Explicit \`model_overrides\` may also be embedded in agent \`.toml\` files,
+  but ordinary profile-resolved models are not, so a TOML file is not a reason to discard
+  an available inline value.
+- Before each typed spawn, obtain the paired effort for its role with
+  \`gsd_run query resolve-model <subagent_type> --pick effort\` when the workflow has not
+  already exposed it. The resolver's unified \`effort\` field maps to the Codex spawn argument
+  \`reasoning_effort\`; do not look for a resolver field named \`reasoning_effort\`.
+  Pass it when the visible \`spawn_agent\` schema advertises \`reasoning_effort\`. Omit the
+  field when it is not advertised, or when the value is missing, empty, \`"inherit"\`, or
+  unsupported; do not invent one-off effort literals in workflow prose.
 - \`fork_context: false\` by default — GSD agents load their own context via \`<required_reading>\` blocks
-- \`task_name\` — required by the collaboration schema; provide a descriptive name for each spawned task
-- \`fork_turns\` — optional parameter controlling turn-forking depth; coexists with \`fork_context\` (not a replacement)
+- \`task_name\` — when advertised, provide a descriptive name for each spawned task
+- \`fork_turns\` — when advertised, controls turn-forking depth; coexists with \`fork_context\` (not a replacement)
 - \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct \`spawn_agent\` mapping,
   but Codex declares \`dispatch.isolation: orchestrator-worktree\` (#2584). Codex
   \`spawn_agent\` still does not create or bind a git worktree; instead GSD itself
@@ -7372,7 +7428,8 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
 
     if (isAgent && inAgentTools) {
       if (trimmed.startsWith('- ')) {
-        agentTools.push(trimmed.substring(2).trim());
+        const tool = runtimeArtifactConversion._decodeToolScalar(trimmed.substring(2));
+        if (tool !== null) agentTools.push(tool);
         continue;
       }
       if (trimmed && !trimmed.startsWith('-')) {
@@ -7384,8 +7441,12 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
     if (trimmed.startsWith('tools:')) {
       if (isAgent) {
         const toolsValue = trimmed.substring(6).trim();
-        if (toolsValue) {
-          const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
+        // A comment-only value (`tools: # note`) is not real inline content —
+        // fall through to the block-list scan instead of decoding the
+        // comment as a bogus tool name and dropping the list (mirrors
+        // src/runtime-artifact-conversion.cts's convertClaudeToKiloFrontmatter, #4032).
+        if (toolsValue && !toolsValue.startsWith('#')) {
+          const tools = runtimeArtifactConversion._splitToolScalars(toolsValue).map(runtimeArtifactConversion._decodeToolScalar).filter(tool => tool !== null);
           agentTools.push(...tools);
         } else {
           inAgentTools = true;
@@ -7451,7 +7512,8 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
       if (trimmed.startsWith('- ')) {
         const tool = trimmed.substring(2).trim();
         if (isAgent) {
-          agentTools.push(tool);
+          const decoded = runtimeArtifactConversion._decodeToolScalar(tool);
+          if (decoded !== null) agentTools.push(decoded);
         } else {
           allowedTools.push(tool);
         }
@@ -9039,17 +9101,29 @@ function uninstall(isGlobal, runtime = DEFAULT_RUNTIME) {
         );
         if (settings.permissions.allow.length !== before) {
           permissionsModified = true;
+          // #4221: an array this filter emptied was GSD-only \u2014 remove the
+          // key rather than leave an empty array behind (Antigravity symmetry).
+          if (settings.permissions.allow.length === 0) {
+            delete settings.permissions.allow;
+          }
         }
       }
       if (Array.isArray(settings.permissions.deny)) {
         const before = settings.permissions.deny.length;
+        // #4221: the deny rules are retired, so this is a legacy-only filter.
         settings.permissions.deny = settings.permissions.deny.filter(
-          (e) => !GSD_CLAUDE_DENY_PERMISSIONS.includes(e)
+          (e) => !GSD_CLAUDE_LEGACY_DENY_PERMISSIONS.includes(e)
         );
         if (settings.permissions.deny.length !== before) {
           permissionsModified = true;
+          if (settings.permissions.deny.length === 0) {
+            delete settings.permissions.deny;
+          }
         }
       }
+      if (permissionsModified && Object.keys(settings.permissions).length === 0) {
+        delete settings.permissions;
+      }
       if (permissionsModified) {
         settingsModified = true;
         console.log(`  ${green}✓${reset} Removed GSD permissions from settings.json`);
@@ -10111,19 +10185,57 @@ function saveLocalPatches(configDir, pristineCtx) {
   const modified = [];
   const pristineHashes = {};
 
+  // #4086: skills/ manifest keys may live OUTSIDE configDir at the runtime's
+  // ACTUAL skills root — codex global installs to $HOME/.agents/skills (the
+  // ADR-1239 skills-kind `home` override), which writeManifest() already
+  // hashes from via _resolveSkillsRootDir (#2088/#3738). Resolving every key
+  // against configDir alone made every skills/ key miss here, so user
+  // modifications to Codex skills were never hash-compared, never backed up,
+  // and were silently overwritten by the next update. configDir stays FIRST
+  // (Postel: runtimes whose skills genuinely live under configDir resolve
+  // byte-identically to before); the skills root is a fallback, only for keys
+  // under the SAME descriptor-driven manifest prefix writeManifest uses, and
+  // only when that root resolves outside configDir. Containment + symlink
+  // guards apply to the alternate root too (resolveInstallRelativePath).
+  const patchRuntime = (pristineCtx && pristineCtx.runtime) || manifest.runtime || null;
+  const patchScope = manifest.scope === 'local' ? 'local' : 'global';
+  let skillsRedirect = null;
+  if (patchRuntime) {
+    const skillsRoot = _resolveSkillsRootDir(patchRuntime, configDir, patchScope);
+    const resolvedConfig = path.resolve(configDir);
+    if (
+      skillsRoot &&
+      skillsRoot !== resolvedConfig &&
+      !skillsRoot.startsWith(resolvedConfig + path.sep)
+    ) {
+      const prefix = _hostBehaviors(patchRuntime).skillsManifestPrefix || 'skills/';
+      skillsRedirect = { root: skillsRoot, prefix };
+    }
+  }
+
   for (const [relPath, originalHash] of Object.entries(manifest.files || {})) {
     const safeRef = resolveInstallRelativePath(configDir, relPath);
     if (!safeRef) continue;
     const { relPath: safeRelPath, fullPath } = safeRef;
-    if (!fs.existsSync(fullPath)) continue;
-    const currentHash = fileHash(fullPath);
+    let installedPath = fullPath;
+    if (!fs.existsSync(installedPath) && skillsRedirect && safeRelPath.startsWith(skillsRedirect.prefix)) {
+      const altRef = resolveInstallRelativePath(
+        skillsRedirect.root,
+        safeRelPath.slice(skillsRedirect.prefix.length)
+      );
+      if (altRef && fs.existsSync(altRef.fullPath)) {
+        installedPath = altRef.fullPath;
+      }
+    }
+    if (!fs.existsSync(installedPath)) continue;
+    const currentHash = fileHash(installedPath);
     if (currentHash !== originalHash) {
       // Back up the user's modified version
       const backupRef = resolveInstallRelativePath(patchesDir, safeRelPath);
       if (!backupRef) continue;
       const backupPath = backupRef.fullPath;
       fs.mkdirSync(path.dirname(backupPath), { recursive: true });
-      fs.copyFileSync(fullPath, backupPath);
+      fs.copyFileSync(installedPath, backupPath);
       modified.push(safeRelPath);
       pristineHashes[safeRelPath] = originalHash;
     }
@@ -10512,7 +10624,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // one) is honored on every profile, `full` included (#2322 blocker 2).
   const _commandsDir = path.join(src, 'commands', 'gsd');
   const _skillsManifest = _isCoreProfileAlias ? new Map() : loadSkillsManifest(_commandsDir);
-  const _resolvedProfile = resolveProfile({
+  let _resolvedProfile = resolveProfile({
     modes: [_activeProfileName],
     manifest: _skillsManifest,
     registry: _installedCapabilityRegistry,
@@ -10863,6 +10975,28 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     return Array.isArray(scopeLayout) && scopeLayout.length > 0;
   })();
 
+  // Install the distribution-owned gsd-core tree before layout materialization.
+  // installRuntimeArtifacts then provisions the durable Runtime Surface corpus
+  // exactly once into this final tree instead of having that corpus overwritten
+  // by a later whole-tree copy and needing a second provisioning pass.
+  const skillSrc = path.join(src, 'gsd-core');
+  const skillDest = path.join(targetDir, 'gsd-core');
+  const _gsdArtifactsStagingRoot = _tryResolveUserArtifactStagingRoot(targetDir);
+  if (_gsdArtifactsStagingRoot === null) {
+    console.warn(`  ${yellow}!${reset} Skipping gsd-core/${USER_OWNED_ARTIFACTS.join(', gsd-core/')} preservation (staging unavailable) — it will be lost if present.`);
+    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
+  } else {
+    const stagedGsdArtifacts = stageUserArtifacts(skillDest, USER_OWNED_ARTIFACTS, _gsdArtifactsStagingRoot);
+    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
+    restoreStagedUserArtifacts(skillDest, stagedGsdArtifacts);
+    discardStagedUserArtifacts(stagedGsdArtifacts);
+  }
+  if (verifyInstalled(skillDest, 'gsd-core')) {
+    console.log(`  ${green}✓${reset} Installed workflow assets`);
+  } else {
+    failures.push('gsd-core');
+  }
+
   // #2624: write the .gsd-source marker. Extracted from its former late position so it can be
   // called BEFORE staging reads the marker (see the call site below). Scoped to the Claude-global
   // layout (issue #1477) — the only install path that ships the skills layout without a
@@ -10879,6 +11013,9 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           // ADR-1239 Phase B write-confinement: the descriptor-sourced marker filename
           // must resolve under targetDir (parity with the other descriptor-driven writes).
           const _markerPath = assertDestWithinConfigHome(targetDir, _hostBehaviors(runtime).sourceMarkerFile);
+          if (hasExistingSymlinkBetween(path.resolve(targetDir), _markerPath, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+            throw new Error(`compatibility marker "${_markerPath}" contains an untrusted symlink`);
+          }
           fs.writeFileSync(_markerPath, gsdSourceCommands + '\n', 'utf8');
         } catch (err) {
           // Non-fatal: install proceeds. But on the Claude-global layout walk-up
@@ -10905,6 +11042,19 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   if (_isSkillsRuntime) {
     // Layout-driven install for skills-based runtimes (full and minimal modes)
     const scope = _installScopeId;
+    // Preserve an existing Runtime Surface selection during upgrades. The
+    // installer refreshes the source corpus first, then emits exactly the
+    // already-committed selection instead of widening it to the base profile.
+    const _committedSurface = readSurface(targetDir);
+    if (_committedSurface) {
+      _resolvedProfile = resolveSurface(
+        targetDir,
+        loadSkillsManifest(_commandsDir),
+        undefined,
+        _installedCapabilityRegistry,
+        _committedSurface,
+      );
+    }
     // ADR-1239 upgrade 3 / #2088: a kind may declare an alternate install `home`
     // (e.g. Codex skills -> $HOME/.agents/skills) instead of the runtime's normal
     // configDir. Resolve the ACTUAL on-disk skills root here, descriptor-driven
@@ -11197,36 +11347,6 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     _installNativePluginIfDeclared(runtime, targetDir, _hostBehaviors(runtime), src);
   }
 
-  // Copy gsd-core skill with path replacement
-  // Stage user-generated files DURABLY to disk before the wipe-and-copy so
-  // they survive re-install even if the process dies mid-copy (#2875 /
-  // #1874-F19) — copyWithPathReplacement wipes and recursively re-copies the
-  // entire gsd-core/ tree, the single longest operation in the install, on
-  // the path every user takes (40-design.md "Site 4 is far worse...").
-  const skillSrc = path.join(src, 'gsd-core');
-  const skillDest = path.join(targetDir, 'gsd-core');
-  // #2875 defect fix: this IS the mainline install step (installing
-  // gsd-core/ itself) — unlike the optional legacy-cleanup blocks above,
-  // install must still be able to proceed and actually write gsd-core/ even
-  // when the staging root cannot be resolved. Degrade by skipping ONLY the
-  // USER_OWNED_ARTIFACTS preserve/restore wrapper around the copy (warn),
-  // never the copy itself.
-  const _gsdArtifactsStagingRoot = _tryResolveUserArtifactStagingRoot(targetDir);
-  if (_gsdArtifactsStagingRoot === null) {
-    console.warn(`  ${yellow}!${reset} Skipping gsd-core/${USER_OWNED_ARTIFACTS.join(', gsd-core/')} preservation (staging unavailable) — it will be lost if present.`);
-    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
-  } else {
-    const stagedGsdArtifacts = stageUserArtifacts(skillDest, USER_OWNED_ARTIFACTS, _gsdArtifactsStagingRoot);
-    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
-    restoreStagedUserArtifacts(skillDest, stagedGsdArtifacts);
-    discardStagedUserArtifacts(stagedGsdArtifacts);
-  }
-  if (verifyInstalled(skillDest, 'gsd-core')) {
-    console.log(`  ${green}✓${reset} Installed workflow assets`);
-  } else {
-    failures.push('gsd-core');
-  }
-
   // #2624: the .gsd-source marker is now written by _writeGsdSourceMarker()
   // BEFORE staging reads it (see the early call above the _isSkillsRuntime
   // block). The former write lived here — AFTER staging — which on an upgrade
@@ -11314,7 +11434,8 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   } else if (_isSkillsRuntime) {
     console.log(`  ${dim}↳${reset} Agents installed via descriptor-driven layout (${runtime})`);
   } else {
-    const _standaloneAgentsResult = installAgentsKindStandalone(runtime, targetDir, _installScopeId, _resolvedProfile, pathPrefix, getCommitAttribution, _installedCapabilityRegistry);
+    const _standaloneProjectDir = isGlobal ? process.cwd() : targetDir;
+    const _standaloneAgentsResult = installAgentsKindStandalone(runtime, targetDir, _installScopeId, _resolvedProfile, pathPrefix, getCommitAttribution, _installedCapabilityRegistry, _standaloneProjectDir);
     if (_standaloneAgentsResult) {
       // #2875 defect fix: installAgentsKindStandalone now returns `null`
       // (rather than a truthy result pointing at an empty destDir) whenever a
@@ -12064,8 +12185,18 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     //   require()s managed-hooks-registry.cjs for MANAGED_HOOKS — so all four must be
     //   installed/refreshed together for every profile, or Codex is wired to a dependency
     //   chain the same installer never delivers.
-    // We deliberately do *not* copy gsd-graphify-update.sh or hooks/lib/ for Codex
-    // in this change (graphify auto-update support for Codex is out of scope for #3579).
+    // We deliberately do *not* copy gsd-graphify-update.sh for Codex in this
+    // change (graphify auto-update support for Codex is out of scope for #3579).
+    // hooks/lib/ WAS excluded here for the same reason, and that stopped being
+    // correct when #3911 (2ea5efc15) gave gsd-context-monitor.js a real
+    // `require('./lib/hook-exit.js')`: the allowlist below is flat and never
+    // recursed, so the hook shipped without its helper and died with
+    // MODULE_NOT_FOUND at load, before its own try/catch, on every registered
+    // event (#4087, #4098). The libs are now derived from what the staged
+    // scripts actually require rather than hand-listed — see the
+    // stageTransitiveHookLibs call after the copy loop. The #3579 boundary is
+    // preserved: helpers no staged Codex hook requires (graphify tooling among
+    // them) are still not shipped.
     const CODEX_HOOKS_TO_COPY = [
       'gsd-check-update.js',
       'gsd-check-update-worker.js',
@@ -12081,6 +12212,12 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       // is not the same as an allowlisted file landing in it — see the marker
       // gate below.
       let codexStagedHooks = false;
+      // The entries THIS invocation actually staged. Seeding the lib scan from
+      // `existsSync` over the destination instead would also pick up a file
+      // left by a PREVIOUS install whose source is no longer staged — e.g. a
+      // name dropped from the allowlist — and derive helpers for a hook that is
+      // no longer shipped (review of #4087).
+      const codexStagedEntries = [];
       for (const entry of fs.readdirSync(codexHooksSrc)) {
         if (!CODEX_HOOKS_TO_COPY.includes(entry)) continue;
         const srcFile = path.join(codexHooksSrc, entry);
@@ -12115,8 +12252,43 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
         }
         codexStagedHooks = true;
+        codexStagedEntries.push(entry);
+      }
+      // Stage the hooks/lib/ helpers the staged scripts require, transitively
+      // (#4087, #4098). Shares writeCursorHooksJson's walker rather than a
+      // second copy: both reduced bundles hand-pick SCRIPTS, and the identical
+      // MODULE_NOT_FOUND was already fixed once for Cursor in 704859e9c. A flat
+      // list of today's three helpers would re-break the next time a
+      // Codex-bundled hook grows a lib dependency, which is exactly how this
+      // regressed. Gated on codexStagedHooks for the same reason the CommonJS
+      // marker below is: hooks/ is shared space, and staging nothing must not
+      // leave a GSD-owned lib/ behind in a directory GSD created but did not
+      // fill (#2544). Seeded from the copies staged by THIS invocation, so the
+      // scan sees the same bytes Node will load and never derives helpers for a
+      // hook left behind by an earlier install.
+      let codexStagedLibs = [];
+      if (codexStagedHooks) {
+        codexStagedLibs = hooksSurface.stageTransitiveHookLibs({
+          seedSources: codexStagedEntries
+            .map((entry) => fs.readFileSync(path.join(codexHooksDest, entry), 'utf8')),
+          srcLibDir: path.join(codexHooksSrc, 'lib'),
+          destLibDir: path.join(codexHooksDest, 'lib'),
+          runtimeLabel: 'Codex',
+          // Same substitutions the .js branch above applies to hook scripts, so
+          // a helper that ever gains a runtime path or version token is
+          // rewritten identically instead of shipping a Claude-shaped path.
+          // No-ops on today's helpers, which carry neither.
+          transform: (content) => content
+            .replace(/'\.claude'/g, configDirReplacement)
+            .replace(/\/\.claude\//g, `/${getDirName(runtime)}/`)
+            .replace(/\.claude\//g, `${getDirName(runtime)}/`)
+            .replace(/\{\{GSD_VERSION\}\}/g, pkg.version),
+        });
       }
       console.log(`  ${green}✓${reset} Installed hooks (Codex)`);
+      if (codexStagedLibs.length > 0) {
+        console.log(`  ${green}✓${reset} Installed hooks/lib/ helpers (${codexStagedLibs.join(', ')})`);
+      }
       // #2717: write the CommonJS marker into hooks/ alongside the staged .js
       // scripts. Codex is excluded from installSharedHooksBundle by the
       // !isCodex gate, so it never received the marker the shared-bundle path
@@ -13881,7 +14053,7 @@ module.exports = {
     mergeClaudePermissions,
     GSD_CLAUDE_ALLOW_PERMISSIONS,
     GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS,
-    GSD_CLAUDE_DENY_PERMISSIONS,
+    GSD_CLAUDE_LEGACY_DENY_PERMISSIONS,
     GSD_CODEX_MARKER,
     // #3897 rung 3 (ADR-3473 §8.3, HALT.md option 2)
     CODEX_SANDBOX_HOLDS,

package/commands/gsd/execute-phase.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:execute-phase
-description: Execute all plans in a phase with wave-based parallelization
+description: SDD phase execution — execute all plans in a phase with dependency-aware wave parallelization
 argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
 effort: max
 allowed-tools:

package/commands/gsd/ns-workflow.md

@@ -5,7 +5,7 @@ argument-hint: ""
 allowed-tools:
   - Read
   - Skill
-requires: [discuss-phase, spec-phase, plan-phase, execute-phase, verify-work, phase, progress, next, ultraplan-phase, plan-review-convergence, add-tests, ai-integration-phase, autonomous, fast, mvp-phase, quick]
+requires: [discuss-phase, spec-phase, plan-phase, execute-phase, verify-work, phase, progress, next, ultraplan-phase, plan-review-convergence, add-tests, ai-integration-phase, autonomous, fast, mvp-phase, quick, quick-batch]
 ---
 
 Route to the appropriate phase-pipeline skill based on the user's intent.
@@ -33,5 +33,6 @@ workflow-advance command.
 | Execute a trivial task inline | gsd-fast |
 | Plan a phase as a vertical MVP slice | gsd-mvp-phase |
 | Execute a quick task with GSD guarantees | gsd-quick |
+| Batch several quick-shaped tasks together | gsd-quick-batch |
 
 Invoke the matched skill directly using the Skill tool.