@opengsd/gsd-core 1.18.0 → 1.20.0

package/commands/gsd/update.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:update
 description: Update GSD to latest version with changelog display
-argument-hint: "[--sync | --reapply | --next | --rc]"
+argument-hint: "[--sync | --reapply | --next | --rc] [--interactive=exceptions|all]"
 allowed-tools:
   - Read
   - Write
@@ -35,14 +35,17 @@ Routes to the update workflow which handles:
 <flags>
 - **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
 - **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+  - **--interactive[=exceptions|all]** (with `--reapply` only): show each user edit next to the stock text with a recommended disposition and wait for a keep / retire / rewrite decision per edit. `all` shows every edit; `exceptions` (bare `--interactive`) shows only edits upstream adopted, partly adopted, reworded around, or orphaned, and keeps the rest. Without it, `--reapply` behaves exactly as before.
 - **--next** (alias **--rc**): Target the `@next` RC dist-tag instead of `@latest` so you can install or refresh a release candidate (e.g. `1.4.0-rc.1`) through the normal update flow — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all still apply. Omitting it keeps targeting `@latest` (no change). See ADR #660 for the RC channel.
 - **(no flag)**: Standard update — check for new version, show changelog, install.
 </flags>
 
 <process>
+If the arguments contain `--interactive` (bare or with a value) but not `--reapply`, STOP with: `--interactive applies only to --reapply (for example: /gsd:update --reapply --interactive=all)`. Do nothing else.
+
 Parse the first token of the `<arguments>` block:
 - If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
-- If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
+- If it is `--reapply`: strip the flag, execute the reapply-patches workflow, passing the remaining arguments (for example `--interactive=all`) to it.
 - Otherwise (including `--next` / `--rc`): execute the update workflow end-to-end, passing the `<arguments>` block through so the workflow's parse_update_channel step can select the release channel.
 
 </process>

package/gsd-core/bin/gsd-tools.cjs

@@ -85,6 +85,14 @@
  *     [--no-archive-phases]          Skip moving phase dirs to milestones/vX.Y-phases/ (archived by default)
  *     [--archive-quick]              Move .planning/quick/* dirs to milestones/vX.Y-quick/ + reset the
  *                                    Quick Tasks Completed table (#2142; opt-in, default OFF)
+ *     [--release-map <file>]         Archive a per-repository release map (JSON array of
+ *                                    {repo, release, reference, environment, status, tag}) as
+ *                                    milestones/vX.Y-RELEASE-MAP.json and record it in MILESTONES.md
+ *                                    (#5706; validated before any write, absent = unchanged)
+ *
+ *   milestone release-tags --map <file.json> [--dry-run]
+ *                                      Preflight, then create annotated tags per sub-repo from a JSON array of
+ *                                      {repo, tag, ref?, message?, skip?}; never pushes, never overwrites (#5705)
  *
  *   milestone archive-quick <version>  Move .planning/quick/* dirs to milestones/vX.Y-quick/ + reset the
  *                                      Quick Tasks Completed table, WITHOUT the milestone complete close-out
@@ -326,6 +334,7 @@ const config = require('./lib/config.cjs');
 const estimateCli = require('./lib/estimate-cli.cjs');
 const template = require('./lib/template.cjs');
 const milestone = require('./lib/milestone.cjs');
+const milestoneReleaseTags = require('./lib/milestone-release-tags.cjs');
 const commands = require('./lib/commands.cjs');
 const runtimeIdentity = require('./lib/runtime-identity.cjs');
 const init = require('./lib/init.cjs');
@@ -848,7 +857,31 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       error,
       output: output,
     });
-    if (!handled) config.cmdConfigNewProject(cwd, args[1], raw);
+    if (handled) return;
+    // #5268: this verb's flag surface is closed, as `todo complete`'s is
+    // (#4096). `--dry-run` is parsed and plumbed, and any OTHER flag fails loudly
+    // instead of being silently ignored: an accepted-but-ignored `--dry-run`
+    // wrote the config it was meant to preview. (`--raw` is spliced by the
+    // dispatcher before routing; it stays in the set as a guard against that
+    // splice ever moving.) The choices JSON is the one positional argument,
+    // wherever the flag sits, and a second one is refused for the same reason.
+    // A flag is a dash followed by a letter: `-1` is a (negative-number) JSON
+    // argument, refused below as choices that are not an object, not a flag.
+    const CONFIG_NEW_PROJECT_KNOWN_FLAGS = new Set(['--dry-run', '--raw']);
+    const positionals = [];
+    for (const a of args.slice(1)) {
+      if (typeof a === 'string' && /^--?[A-Za-z]/.test(a)) {
+        if (!CONFIG_NEW_PROJECT_KNOWN_FLAGS.has(a)) {
+          error(`Unknown flag for config-new-project: ${a}`, ERROR_REASON.USAGE);
+        }
+        continue;
+      }
+      positionals.push(a);
+    }
+    if (positionals.length > 1) {
+      error(`Unexpected argument for config-new-project: ${positionals[1]}. Usage: config-new-project [choices-json] [--dry-run]`, ERROR_REASON.USAGE);
+    }
+    config.cmdConfigNewProject(cwd, positionals[0], raw, { dryRun: args.includes('--dry-run') });
   }
 
   function routeConfigPath({ cwd, raw, workstreamContext }) {
@@ -1598,7 +1631,8 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     const fsx = require('node:fs');
     const os = require('node:os');
     const { REVIEWER_LANES, mergeReviewerLanes } = require('./lib/review-lane-descriptor.cjs');
-    const { resolveLanePlan: resolveLanePlanBase, resolveLaneEffort, resolveLaneBudget, applyPromptOverride } = require('./lib/review-lane-invocation.cjs');
+    const { resolveLanePlan: resolveLanePlanBase, resolveLaneEffort, resolveLaneCap, refuseIfOverCap, renderPromptRefusalStub, artifactPaths, applyPromptOverride } = require('./lib/review-lane-invocation.cjs');
+    const { estimateTokens } = require('./lib/prompt-budget.cjs');
     // OpenCode 2.x argv differs from 1.x (no --variant; effort rides on the model as `#variant`;
     // ADR-5331 D5/D8). The generation is probed lazily, only when the opencode lane is resolved.
     const resolveLanePlan = (laneInput) => {
@@ -1632,8 +1666,9 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     // `plan`/`invoke` are the only subs that need the expensive plan-building path
     // below; `sections`/`flags` return earlier still. Anything else errors here, before
     // any of that work starts.
-    if (!['plan', 'invoke', 'sections', 'flags', 'dispatch-step', 'explicit-from-argv'].includes(sub)) {
-      error("Usage: review-lane <plan|invoke|sections|flags|dispatch-step|explicit-from-argv> [--selected a,b] [--run-dir D] [--repo-root R]");
+    const REVIEW_LANE_USAGE = 'Usage: review-lane <plan|invoke|sections|flags|availability|dispatch-step|explicit-from-argv> [--selected a,b] [--run-dir D] [--repo-root R]';
+    if (!['plan', 'invoke', 'sections', 'flags', 'availability', 'dispatch-step', 'explicit-from-argv'].includes(sub)) {
+      error(REVIEW_LANE_USAGE);
       return;
     }
     const runDir = flag('--run-dir') || '.';
@@ -1709,8 +1744,34 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             method: opts.method,
             headers: opts.body ? { 'Content-Type': 'application/json' } : undefined,
             body: opts.body,
+            // Never follow a redirect: the egress check compares the CONFIGURED host, so a
+            // followed redirect would send the review prompt to a host the user never named (#5433).
+            redirect: 'manual',
             signal: AbortSignal.timeout(opts.timeoutMs),
           });
+          // probe:true marks a reachability probe (returns status only, body ''): the status line is the answer, so do not
+          // let a stalled body turn a replying server into `missing`.
+          if (opts.probe) {
+            res.body?.cancel().catch(() => {});
+            return { ok: res.ok, status: res.status, body: '' };
+          }
+          if (res.status >= 300 && res.status < 400) {
+            res.body?.cancel().catch(() => {});
+            const location = res.headers.get('location');
+            let target = 'without a Location header';
+            if (location) {
+              target = 'to an unparseable Location';
+              try { target = `to ${new URL(location, url).host}`; } catch { /* keep the unparseable wording */ }
+            }
+            // Host and path only: a configured URL may carry credentials that must not reach a review file.
+            const asked = (() => { try { const u = new URL(url); return `${u.host}${u.pathname}`; } catch { return 'the configured URL'; } })();
+            return {
+              ok: false,
+              status: res.status,
+              body: '',
+              error: `${asked} answered HTTP ${res.status}, redirecting ${target}. The lane does not follow redirects; configure the final URL as the lane's host.`,
+            };
+          }
           return { ok: res.ok, status: res.status, body: await res.text() };
         } catch (e) {
           return { ok: false, status: 0, body: '', error: e && e.message ? e.message : String(e) };
@@ -1737,6 +1798,23 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
 
     const selected = (flag('--selected') || '')
       .split(',').map((s) => s.trim()).filter(Boolean);
+    // #5266: `<slug>:available|missing` per openai-http lane. Host + default come from the lane
+    // descriptor (resolveLanePlan), probing is runner.probeLane — review.md keeps no host table.
+    // Prerequisite binaries (jq) are reported separately by the workflow, not folded in here.
+    // First-party lanes only: ADR-2782 D5 requires egress/consent before a third-party lane's host is
+    // contacted; detection has no such check, so installed third-party lanes are never probed here.
+    if (sub === 'availability') {
+      const { rows, warnings } = await runner.probeHttpLanes(
+        REVIEWER_LANES,
+        selected,
+        (lane) => resolveLanePlan({ lane, configGet, runDir, repoRoot }),
+        buildLaneRunnerDeps(),
+      );
+      for (const w of warnings) process.stderr.write(`review-lane availability: ${w}\n`);
+      process.stdout.write(rows.join('\n') + (rows.length ? '\n' : ''));
+      return;
+    }
+
     // ADR-2782 D8 (#2927): the lane map is first-party ∪ INSTALLED overlay
     // `reviewer` bodies, first-party winning on slug collision. Before this merge
     // the map was built from the frozen REVIEWER_LANES array alone, so an installed,
@@ -1838,11 +1916,11 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     };
     const effortFor = (lane) => resolveLaneEffort(lane, configGet, renderLaneEffort);
 
-    // Per-lane prompt budget: `resolveLaneBudget` (review-lane-invocation.cjs) owns the #2797
+    // Per-lane prompt cap: `resolveLaneCap` (review-lane-invocation.cjs) owns the #2797 + #4559
     // resolution semantics (shared with src/reviewer-step-dispatch.cts, #4209 R3 — was two
-    // verbatim copies). Only the budget VALUE is resolved here; assembly/trimming stay in
-    // `prompt-budget`, which the workflow calls, handing the trimmed file back via `--prompt-file`.
-    const budgetFor = (lane) => resolveLaneBudget(lane, configGet);
+    // verbatim copies). `plan` reports it; `invoke` REFUSES a lane whose prompt is over it
+    // (#4559) rather than trimming — the prompt is never edited on the way to a lane.
+    const capFor = (lane) => resolveLaneCap(lane, configGet);
 
     // #4209 (ADR-2782 seam) — the ONE interpreter route for a step that declared
     // `supportsReviewerLanes: true`. Wires `dispatchReviewerLanes` (src/reviewer-step-dispatch.cts)
@@ -1982,17 +2060,19 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       } catch (e) {
         return { slug, ok: false, reason: 'malformed_lane', detail: `resolver threw: ${e && e.message ? e.message : String(e)}` };
       }
-      return r.ok
-        ? {
-            slug,
-            ok: true,
-            section: lane.reviewsSection,
-            transport: r.plan.transport,
-            promptBudget: budgetFor(lane),
-            promptPath: r.plan.transport === 'spawn' ? r.plan.stdin : r.plan.promptPath,
-            plan: r.plan,
-          }
-        : { slug, ok: false, reason: r.reason, detail: r.detail };
+      if (!r.ok) return { slug, ok: false, reason: r.reason, detail: r.detail };
+      const laneCap = capFor(lane);
+      return {
+        slug,
+        ok: true,
+        section: lane.reviewsSection,
+        transport: r.plan.transport,
+        promptBudget: laneCap.cap,
+        promptCapSource: laneCap.source,
+        contextWindowTokens: laneCap.contextWindowTokens,
+        promptPath: r.plan.transport === 'spawn' ? r.plan.stdin : r.plan.promptPath,
+        plan: r.plan,
+      };
     });
 
     if (sub === 'plan') {
@@ -2001,7 +2081,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     }
 
     if (sub !== 'invoke') {
-      error("Usage: review-lane <plan|invoke|sections|flags|dispatch-step|explicit-from-argv> [--selected a,b] [--run-dir D] [--repo-root R]");
+      error(REVIEW_LANE_USAGE);
       return;
     }
 
@@ -2101,14 +2181,61 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       ];
     }
 
-    // `--prompt-file` lets the caller substitute a budget-trimmed prompt. Applied to whichever
-    // channel this lane actually reads from (stdin, argv, an argv-embedded file reference, or the
-    // http promptPath), so one flag serves every lane (#5049).
+    // `--prompt-file` lets the caller substitute a different prompt (a section subset, say). Applied
+    // to whichever channel this lane actually reads from (stdin, argv, an argv-embedded file
+    // reference, or the http promptPath), so one flag serves every lane (#5049). It is no longer a
+    // trim hand-off: nothing in review.md trims a prompt to fit a lane since #4559.
     const promptOverride = flag('--prompt-file');
     if (promptOverride) {
       entry.plan = applyPromptOverride(entry.plan, promptOverride, repoRoot);
     }
 
+    // #4559: refuse, never trim. Measure the prompt this lane would actually receive — the file
+    // the RESOLVED plan reads (stdin file, or the plan's prompt path for argv / argv-file-ref /
+    // http lanes; `--prompt-file` already retargeted the plan above) — against its cap BEFORE any
+    // consent lookup, probe or spawn. An unreadable file is not a refusal: the runner reports its
+    // own error for it. The decision itself lives in `refuseIfOverCap`; this only does the IO.
+    {
+      const plannedPrompt = entry.plan.transport === 'spawn' && entry.plan.stdin
+        ? entry.plan.stdin
+        : entry.plan.promptPath;
+      let promptText = null;
+      try {
+        promptText = fs.readFileSync(plannedPrompt || artifactPaths(runDir, entry.slug).promptPath, 'utf8');
+      } catch { promptText = null; }
+      if (promptText !== null) {
+        const refused = refuseIfOverCap({
+          lane: laneBySlug.get(entry.slug),
+          estimatedTokens: estimateTokens(promptText),
+          configGet,
+        });
+        if (refused) {
+          const reviewPath = entry.plan.reviewPath;
+          let stubWritten = true;
+          try {
+            fs.mkdirSync(path.dirname(reviewPath), { recursive: true });
+            fs.writeFileSync(reviewPath, renderPromptRefusalStub(entry.slug, refused.detail), 'utf8');
+          } catch (e) {
+            stubWritten = false;
+            process.stderr.write(
+              `review-lane invoke: could not write the refusal stub to ${reviewPath}: ` +
+              `${e && e.message ? e.message : String(e)}\n`,
+            );
+          }
+          output({
+            slug: entry.slug,
+            ok: false,
+            reason: refused.reason,
+            detail: refused.detail,
+            reviewPath,
+            stubWritten,
+            refusal: refused.refusal,
+          }, raw);
+          return;
+        }
+      }
+    }
+
     // ADR-2782 D5 rule 4: re-resolve the consented destination at INVOCATION. `undefined` (no
     // consent record, or a record predating rule 1) means "nothing to compare" and ALLOWS — a
     // first-party lane ships inside the SHA-pinned distribution and is never consent-gated, so
@@ -2141,6 +2268,13 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           testCommandNormalizer.cmdNormalizeTestCommand(cwd, args[1]);
   }
 
+  function routeResolvePackageManager({ args, cwd }) {
+    // #5346: the gates' no-configured-command fallback asks here for the
+    // project's package manager (packageManager field, then lockfile, else npm).
+    // args[1] is the script name; --cwd (already parsed into `cwd`) locates package.json.
+    require('./lib/normalize-test-command.cjs').cmdResolvePackageManager(cwd, args[1]);
+  }
+
   function routeDispatchShouldFlatten({ args, cwd, raw, error }) {
     // #1708 / #853: typed query replacing the `RUNTIME === 'codex'` prose rule.
           //
@@ -3142,7 +3276,18 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             // --dry-run) the command refuses before touching anything. Distinct
             // from --force, which bypasses the narrow scope guards only.
             const confirm = args.includes('--confirm');
-            milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force, dryRun, archiveQuick, confirm }, raw);
+            // #5706 (epic #3628): optional caller-supplied release map file.
+            // A flag with no usable value fails loud rather than being dropped.
+            let releaseMap = null;
+            const releaseMapIdx = args.indexOf('--release-map');
+            if (releaseMapIdx !== -1) {
+              const releaseMapValue = args[releaseMapIdx + 1];
+              if (typeof releaseMapValue !== 'string' || releaseMapValue.startsWith('--') || releaseMapValue.trim() === '') {
+                error('--release-map requires a file path (a JSON array of release-map entries)');
+              }
+              releaseMap = releaseMapValue;
+            }
+            milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force, dryRun, archiveQuick, confirm, releaseMap }, raw);
           } else if (subcommand === 'archive-quick') {
             // #2142 escalation: narrow archival-only entry point (does NOT
             // touch ROADMAP/REQUIREMENTS/MILESTONES.md, runs no completion
@@ -3150,8 +3295,11 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             // unlike `milestone complete --archive-quick`.
             const dryRun = args.includes('--dry-run');
             milestone.cmdQuickArchive(cwd, args[2], { dryRun }, raw);
+          } else if (subcommand === 'release-tags') {
+            // #5705 (epic #3628 Phase 1): repository-scoped annotated release tags.
+            milestoneReleaseTags.cmdMilestoneReleaseTags(cwd, args, raw);
           } else {
-            error('Unknown milestone subcommand. Available: complete, archive-quick', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+            error('Unknown milestone subcommand. Available: complete, archive-quick, release-tags', ERROR_REASON.SDK_UNKNOWN_COMMAND);
           }
   }
 
@@ -4506,7 +4654,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             // #1956: deterministic STATE.md-vs-ROADMAP.md phase-status drift.
             const { planningDir } = require('./lib/planning-workspace.cjs');
             const { stateExtractField, stateCurrentPositionSlice } = require('./lib/state-document.cjs');
-            const { findRoadmapProgressTable } = require('./lib/roadmap-parser.cjs');
+            const { locateRoadmapProgress } = require('./lib/roadmap-progress.cjs');
             const { phaseKeyFromProse } = require('./lib/phase-id.cjs');
             // STATE.md's YAML frontmatter carries its own lowercase `status:`
             // scalar ahead of the body's `## Current Position` prose "Status:"
@@ -4604,9 +4752,9 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
 
             const stateStatus = stateExtractField(currentPositionBody, 'Status');
 
-            // #1956/#2012: scoped to `## Progress` first (decoy-avoidance) —
-            // see findRoadmapProgressTable's doc comment (roadmap-parser.cts).
-            const table = findRoadmapProgressTable(roadmapContent);
+            // #1956/#2012: scoped to `## Progress` first (decoy-avoidance) — the
+            // Progress owner's rule (roadmap-progress.cts), shared with every reader and writer (#5762).
+            const { table } = locateRoadmapProgress(roadmapContent);
             const matchedRow = table
               ? table.rows.find((row) => phaseKeyFromProse(row.Phase) === phase && phase !== null)
               : undefined;
@@ -4809,6 +4957,7 @@ const HOST_COMMAND_ROUTERS = {
     // #3676 (Phase 4, epic #3344): quick-batch coordination verbs.
     'quick-batch': routeQuickBatchCommand,
     'normalize-test-command': routeNormalizeTestCommand,
+    'resolve-package-manager': routeResolvePackageManager,
     'dispatch-should-flatten': routeDispatchShouldFlatten,
     'dispatch-isolation': routeDispatchIsolation,
     'dispatch-capacity': routeDispatchCapacity,
@@ -5114,7 +5263,7 @@ function runWithTimeout(argv) {
 // drifting apart when a query command was added to only one or two.
 const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--project-dir <path>] [--ws <name>] [--json-errors] [--exit-contract=<v>]\n' +
   'Commands: agent, agent-skills, assumption-delta, audit-open, audit-uat, check, check-commit, commit, commit-docs-guard, commit-to-subrepo, pr-subrepo, ' +
-  'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, ' +
+  'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, resolve-package-manager, ' +
   'context-predicates, current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
   'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
   'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +

package/gsd-core/bin/lib/agent-install-check.cjs

@@ -328,8 +328,33 @@ function checkCodexModelPosture(runtime, projectRoot) {
 // derives its sandbox_mode from actually lives, in every install shape
 // (repo-dev tree or npm-global package, where the package still ships its
 // own agents/ alongside bin/ and gsd-core/).
-function _canonicalAgentSourceDir() {
-    return node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
+//
+// #5496: "install-relative" has three shapes. This module compiles to
+// `<root>/gsd-core/bin/lib/`, so `<root>` is three parents up. In the repository
+// and the npm package the canonical sources are `<root>/agents`. In an INSTALLED
+// config dir `<root>/agents` holds the CONVERTED runtime copies (no `tools:`
+// declaration — every role then derived `read-only`, 26 false violations on a
+// clean Codex install) and the canonical sources are `<root>/gsd-core/agents`.
+// Prefer the nested directory when it actually holds agent sources; fall back to
+// `<root>/agents`. `root` is a parameter so each layout is testable.
+//
+// #5636: "holds agent sources" is a recognized agent file, `gsd-<name>.md` (every file in the shipped
+// roster) that is not a `.compact.md` variant. Any markdown would let a stray README in the nested
+// directory hide the real sources, so the posture check found no role's canonical file and skipped all.
+const CANONICAL_AGENT_SOURCE_FILE = /^gsd-.+\.md$/;
+function isCanonicalAgentSourceFile(entry) {
+    return CANONICAL_AGENT_SOURCE_FILE.test(entry) && !entry.endsWith('.compact.md');
+}
+function canonicalAgentSourceDir(root = node_path_1.default.join(__dirname, '..', '..', '..')) {
+    const nested = node_path_1.default.join(root, 'gsd-core', 'agents');
+    try {
+        if (node_fs_1.default.readdirSync(nested).some(isCanonicalAgentSourceFile))
+            return nested;
+    }
+    catch {
+        // Absent or unreadable: not this layout.
+    }
+    return node_path_1.default.join(root, 'agents');
 }
 /**
  * Validate installed Codex `.toml` agents' `sandbox_mode` against what each
@@ -384,7 +409,7 @@ function checkCodexSandboxPosture(runtime, projectRoot) {
             reason: POSTURE_REASON.AGENTS_DIR_MISSING,
         };
     }
-    const canonicalAgentsDir = _canonicalAgentSourceDir();
+    const canonicalAgentsDir = canonicalAgentSourceDir();
     // Same symlink guard as checkCodexModelPosture, same reason (never follow
     // an agents-dir symlink into an arbitrary file's content).
     const tomlFiles = node_fs_1.default
@@ -533,6 +558,7 @@ module.exports = {
     checkAgentsInstalled,
     checkCodexModelPosture,
     checkCodexSandboxPosture,
+    canonicalAgentSourceDir,
     POSTURE_REASON,
     resolveAgentHint,
 };

package/gsd-core/bin/lib/args-terminator.cjs

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Per-install terminators for the typed-text capture heredocs (#5637).
+ *
+ * Every workflow that reads the typed text opens with
+ *
+ *   IFS= read -rd '' GSD_ARGS <<'GSD_ARGS_END' || true
+ *   $ARGUMENTS
+ *   GSD_ARGS_END
+ *
+ * and `/gsd-quick-batch` feeds `parse-args` through the same shape with `GSD_QUICK_BATCH_ARGS_END`.
+ * The harness replaces `$ARGUMENTS` with the typed text before the shell parses the fence, so typed
+ * text with a terminator line of its own closes the heredoc early and the lines after it run as
+ * shell. A literal in a shipped file cannot be made unforgeable, so each install replaces it with
+ * `<TERMINATOR>_<nonce>`, a nonce the typed text has no way to know. The shipped source keeps the
+ * canonical tokens; only the files an install writes carry the nonce.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARGS_NONCE_RE = exports.ARGS_TERMINATOR = exports.ARGS_TERMINATORS = void 0;
+exports.generateArgsNonce = generateArgsNonce;
+exports.stampArgsTerminator = stampArgsTerminator;
+exports.readInstalledNonce = readInstalledNonce;
+exports.armArgsNonce = armArgsNonce;
+exports.disarmArgsNonce = disarmArgsNonce;
+exports.stampInstalledContent = stampInstalledContent;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** The canonical terminators the shipped workflows and commands carry. */
+exports.ARGS_TERMINATORS = Object.freeze(['GSD_ARGS_END', 'GSD_QUICK_BATCH_ARGS_END']);
+/** The terminator every workflow carries. */
+exports.ARGS_TERMINATOR = 'GSD_ARGS_END';
+/** A nonce is 128 random bits as 32 lowercase hex characters. */
+exports.ARGS_NONCE_RE = /^[0-9a-f]{32}$/;
+const OPENER_RE = new RegExp(`<<'(${exports.ARGS_TERMINATORS.join('|')})'`, 'g');
+const CLOSER_RE = new RegExp(`^(${exports.ARGS_TERMINATORS.join('|')})(?=\\r?$)`, 'gm');
+/** A fresh nonce. `randomBytes` is a seam for tests. */
+function generateArgsNonce(randomBytes = node_crypto_1.randomBytes) {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * `content` with each canonical terminator replaced by the stamped one: the heredoc opener tag and
+ * the closing line. A terminator that is already stamped does not match and is left alone, and so
+ * is prose that names a token inside a line.
+ *
+ * @throws {TypeError} when `nonce` is not 32 lowercase hex characters
+ */
+function stampArgsTerminator(content, nonce) {
+    if (typeof nonce !== 'string' || !exports.ARGS_NONCE_RE.test(nonce)) {
+        throw new TypeError('stampArgsTerminator: nonce must be 32 lowercase hex characters');
+    }
+    return content
+        .replace(OPENER_RE, (_m, token) => `<<'${token}_${nonce}'`)
+        .replace(CLOSER_RE, (_m, token) => `${token}_${nonce}`);
+}
+let armedNonce = null;
+const INSTALLED_NONCE_RE = /^GSD_ARGS_END_([0-9a-f]{32})\r?$/m;
+/** A workflow is tens of KiB; anything near this is not one, and is not read. */
+const MAX_WORKFLOW_BYTES = 2 * 1024 * 1024;
+/**
+ * The nonce a previous install left in `configDir`, read from the first installed workflow that
+ * carries one; null when there is none. Entries that are not regular files (a directory, a FIFO,
+ * a symlink) and files over MAX_WORKFLOW_BYTES are skipped, and one unreadable entry does not end
+ * the scan.
+ */
+function readInstalledNonce(configDir) {
+    let dir;
+    let names;
+    try {
+        dir = (0, node_path_1.join)(configDir, 'gsd-core', 'workflows');
+        names = (0, node_fs_1.readdirSync)(dir).sort();
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.md'))
+            continue;
+        try {
+            const full = (0, node_path_1.join)(dir, name);
+            const stat = (0, node_fs_1.lstatSync)(full);
+            if (!stat.isFile() || stat.size > MAX_WORKFLOW_BYTES)
+                continue;
+            const match = INSTALLED_NONCE_RE.exec((0, node_fs_1.readFileSync)(full, 'utf8'));
+            if (match)
+                return match[1];
+        }
+        catch {
+            // This entry is unreadable; the next one may still carry the nonce.
+        }
+    }
+    return null;
+}
+/**
+ * Arm stamping for the install into `configDir`, before it writes anything. When `reuse` is true
+ * the directory's installed nonce is kept, so a reinstall changes nothing; otherwise, or when
+ * there is none, a fresh one is minted. Only a global install (a directory under the user's home,
+ * which a cloned repository cannot seed) may reuse: a project-local directory is often committed,
+ * and a nonce planted there would be adopted. Generators never arm it, so the committed generated
+ * skills stay canonical and deterministic.
+ */
+function armArgsNonce(configDir, reuse = false) {
+    const prior = reuse && configDir !== undefined ? readInstalledNonce(configDir) : null;
+    armedNonce = prior ?? generateArgsNonce();
+    return armedNonce;
+}
+/** Stop stamping: the process is no longer writing for an install that has a nonce. */
+function disarmArgsNonce() {
+    armedNonce = null;
+}
+/** `content` stamped with the armed nonce, or untouched when this process is not an installer. */
+function stampInstalledContent(content) {
+    return armedNonce === null ? content : stampArgsTerminator(content, armedNonce);
+}

package/gsd-core/bin/lib/broken-windows.cjs

@@ -504,6 +504,63 @@ function validateEntryShape(e, i) {
         ...('milestone' in o ? { milestone: typeof o.milestone === 'string' ? o.milestone : null } : {}),
     };
 }
+/**
+ * #5418: when the frontmatter counts disagree with the parsed entries, the usual
+ * cause is a hand-edited table: a row added to the rendered table (and the counts
+ * bumped to match) while the fenced JSON block, the sole source of entries, was left
+ * behind. Names the row ids the table and the JSON block disagree about so the
+ * counts message does not point at the (correct) frontmatter. Returns '' when there
+ * is nothing to add. Best-effort by design: it runs while a WindowsError is already
+ * on its way out, so it must never throw and replace that error.
+ */
+/** Row ids spelled out in the divergence note; the rest are counted. */
+const ROW_ID_LIST_LIMIT = 20;
+function describeTableJsonDivergence(raw, entries) {
+    try {
+        // The hint is the PARSED entry count, not frontmatter total_count: the latter
+        // is the number that is wrong here.
+        const table = extractTableRegion(raw, entries.length);
+        if (table === null)
+            return '';
+        const rowId = (line) => (line.split('|')[1] ?? '').trim();
+        // Ids are positive integers (the JSON side enforces it), so a first cell that is
+        // not one — the `_(none)_` empty-ledger placeholder, a continuation line of a
+        // multi-line description, control characters — is not a row id and is never
+        // echoed into the message.
+        const tableIds = new Set();
+        const tableLines = table.split('\n');
+        for (let i = 2; i < tableLines.length; i++) {
+            if (!tableLines[i].startsWith('|'))
+                continue;
+            const id = rowId(tableLines[i]);
+            if (/^\d{1,15}$/.test(id))
+                tableIds.add(id);
+        }
+        const jsonIds = new Set(entries.map((e) => String(e.id)));
+        const byNumber = (a, b) => Number(a) - Number(b);
+        const list = (ids) => {
+            const shown = ids.slice(0, ROW_ID_LIST_LIMIT).join(', ');
+            return ids.length > ROW_ID_LIST_LIMIT ? `${shown} and ${ids.length - ROW_ID_LIST_LIMIT} more` : shown;
+        };
+        const tableOnly = [...tableIds].filter((id) => !jsonIds.has(id)).sort(byNumber);
+        const jsonOnly = [...jsonIds].filter((id) => !tableIds.has(id)).sort(byNumber);
+        const parts = [];
+        if (tableOnly.length > 0) {
+            parts.push(`row id(s) in the table but not in the fenced JSON block: ${list(tableOnly)}`);
+        }
+        if (jsonOnly.length > 0) {
+            parts.push(`row id(s) in the fenced JSON block but not in the table: ${list(jsonOnly)}`);
+        }
+        if (parts.length === 0)
+            return '';
+        return ` The table and the fenced JSON block disagree (${parts.join('; ')}). The JSON block is the ` +
+            'authoritative entries source: add the missing entries there (or remove the stray table rows) ' +
+            'and keep the frontmatter counts in step with it.';
+    }
+    catch {
+        return '';
+    }
+}
 function parseLedger(raw) {
     const fm = parseFrontmatterStrict(raw);
     if (fm.schema_version !== exports.SCHEMA_VERSION) {
@@ -537,7 +594,8 @@ function parseLedger(raw) {
         recomputed.total_count !== ledger.total_count) {
         throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger counts disagree with entries: frontmatter open/waived/fixed/total=` +
             `${ledger.open_count}/${ledger.waived_count}/${ledger.fixed_count}/${ledger.total_count}` +
-            ` but entries yield ${recomputed.open_count}/${recomputed.waived_count}/${recomputed.fixed_count}/${recomputed.total_count}.`);
+            ` but entries yield ${recomputed.open_count}/${recomputed.waived_count}/${recomputed.fixed_count}/${recomputed.total_count}.` +
+            describeTableJsonDivergence(raw, entries));
     }
     return ledger;
 }

package/gsd-core/bin/lib/capability-lifecycle.cjs

@@ -34,7 +34,7 @@ const consentMod = require('./capability-consent.cjs');
 const projectRootMod = require('./project-root.cjs');
 // #1459 finding 4: the SHARED hardened lock primitive (single source of truth for lifecycle + consent).
 const lockMod = require('./capability-lock.cjs');
-const { platformWriteSync, retryRenameSync } = require('./shell-command-projection.cjs');
+const { platformWriteSync, retryRenameSync, shellSingleQuote } = require('./shell-command-projection.cjs');
 // #1463: numeric major.minor.patch comparison for the outdated check (the SAME compare the resolver
 // and capability list use). -1 (a<b), 0 (equal), 1 (a>b).
 const semverMod = require('./semver-compare.cjs');
@@ -308,17 +308,6 @@ function isSafeHookScriptPath(script) {
         return false;
     return true;
 }
-/**
- * #1460 (R) HIGH: POSIX single-quote an arbitrary string for safe inclusion in a shell command.
- * The emitted hook `command` is the ABSOLUTE confined script path, which begins with the
- * (non-manifest) install-prefix — commonly a home dir containing spaces/special chars (e.g.
- * "/Users/Bob Smith/.claude/..."). Written unquoted it would word-split (and, with a hostile
- * prefix, could inject). Wrapping in single quotes — with each embedded `'` escaped as `'\''` —
- * makes the whole path a single shell token that no metacharacter inside it can break.
- */
-function shellSingleQuote(value) {
-    return "'" + value.replace(/'/g, "'\\''") + "'";
-}
 /**
  * #1634: build the emitted hook `command` for an ABSOLUTE confined script path. For `.js`-family
  * hooks (`.js`/`.cjs`/`.mjs`) prefix with `node` so the hook runs regardless of the source's