@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/install-engine.cjs

@@ -55,7 +55,7 @@ const install_scope_cjs_1 = require("./install-scope.cjs");
 const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
-const { getDirName } = runtimeNamePolicy;
+const { getDirName, hostBehaviorsFor } = runtimeNamePolicy;
 function withInstallerPackageSource(configDir, fn) {
     // Reuse the existing compatibility-marker contract through the existing fs
     // seam. The marker exists only in this synchronous call tree: no disk state,
@@ -181,7 +181,7 @@ function provisionRuntimeSurfaceCorpus(layout, configDir, scope) {
         const destination = node_path_1.default.join(corpusRoot, 'agents');
         syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/agents/');
     }
-    const markerFile = _hostBehaviors(layout.runtime).sourceMarkerFile;
+    const markerFile = hostBehaviorsFor(layout.runtime).sourceMarkerFile;
     if (typeof markerFile === 'string' && markerFile !== '' && required.has('commands')) {
         try {
             const markerPath = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, markerFile);
@@ -220,25 +220,6 @@ function executingPackageRoot() { return node_path_1.default.dirname(node_path_1
  */
 const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];
 // ---------------------------------------------------------------------------
-// Host-behavior helpers
-// ---------------------------------------------------------------------------
-/**
- * Host-specific install behaviors declared on the runtime descriptor
- * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors).
- * Mirrors bin/install.js's `_hostBehaviors` (ADR-1239 / #2086/#2087). Returns
- * {} for runtimes that declare none or if the registry fails to load, so
- * every behavior branch degrades to the generic path by default.
- */
-function _hostBehaviors(runtime) {
-    try {
-        const reg = require('./capability-registry.cjs');
-        return (reg && reg.runtimes && reg.runtimes[runtime] && reg.runtimes[runtime].runtime && reg.runtimes[runtime].runtime.hostBehaviors) || {};
-    }
-    catch {
-        return {};
-    }
-}
-// ---------------------------------------------------------------------------
 // Conversion helpers
 // ---------------------------------------------------------------------------
 /**
@@ -730,6 +711,17 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
             continue;
         if (!entry.name.endsWith('.md'))
             continue;
+        // #4782: compact agent variants are consumed ONLY through the non-claude
+        // gate in init.cts's agent-skills persona fallback (`runtime !== 'claude'`
+        // — claude's contract is a skills-injection path, never a persona
+        // fallback). Staging them into Claude's agents directory shipped 29 dead
+        // files whose `name:` frontmatter is identical to their canonical
+        // sibling's, leaving the harness resolution unstated. Claude never
+        // selects compact, so claude is the one runtime whose agents kind skips
+        // them; every other runtime's emission is byte-identical. #5169: the
+        // descriptor declares this (`hostBehaviors.skipCompactAgents`), not a name test.
+        if (kind.kind === 'agents' && hostBehaviorsFor(runtime).skipCompactAgents && entry.name.endsWith('.compact.md'))
+            continue;
         const stem = entry.name.slice(0, -3); // strip .md
         let destName;
         if (kind.kind === 'agents') {
@@ -738,7 +730,7 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
             // hardcoded `runtime === 'copilot'`). copilot declares '.agent.md';
             // every other runtime's descriptor leaves this unset, so destName falls
             // back to entry.name unchanged (byte-parity, #1575 origin comment).
-            const _agentExt = runtime ? _hostBehaviors(runtime).agentFileExtension : undefined;
+            const _agentExt = runtime ? hostBehaviorsFor(runtime).agentFileExtension : undefined;
             destName = _agentExt
                 ? entry.name.replace(/\.md$/, _agentExt)
                 : entry.name;
@@ -877,7 +869,7 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
     // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
     // created skills/gsd-dev-preferences/ skill dir.
     let stagedLegacyArtifacts = null;
-    if (_hostBehaviors(runtime).legacyCommandsGsdInstallMigration) {
+    if (hostBehaviorsFor(runtime).legacyCommandsGsdInstallMigration) {
         if (installFs().existsSync(legacyCommandsGsd)) {
             // #2875: staging root resolved lazily, only when there is actually
             // something to stage — reused below by every other call site sharing
@@ -901,8 +893,8 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
         }
     }
     // Hermes: remove pre-#2841 flat skills/gsd-*/ entries that lived alongside
-    // the new skills/gsd/ nested layout.
-    if (runtime === 'hermes') {
+    // the new skills/gsd/ nested layout. (#5169: `hostBehaviors.legacyFlatSkillsCleanup`.)
+    if (hostBehaviorsFor(runtime).legacyFlatSkillsCleanup) {
         const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
         if (installFs().existsSync(flatSkillsDir)) {
             for (const entry of installFs().readdirSync(flatSkillsDir, { withFileTypes: true })) {
@@ -1040,7 +1032,7 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
     // commands/gsd/ for claude local, preserving dev-preferences.md by restoring it
     // to the same location (#1423). Using migrateLegacyDevPreferencesToSkill here
     // (which would redirect to skills/) conflicts with the test contract for local installs.
-    const _lu = _hostBehaviors(runtime).legacyCommandsGsdUninstall;
+    const _lu = hostBehaviorsFor(runtime).legacyCommandsGsdUninstall;
     // #2870: `scope` keeps its exported `string = 'global'` signature (no
     // signature change), but every real caller — `uninstallRuntimeArtifacts`'s
     // own required `scope` param, always fed a validated 'global' | 'local'
@@ -1065,8 +1057,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
             }
         }
     }
-    // Hermes: pre-#2841 flat skills/gsd-*/ entries
-    if (runtime === 'hermes') {
+    // Hermes: pre-#2841 flat skills/gsd-*/ entries (#5169: `legacyFlatSkillsCleanup`)
+    if (hostBehaviorsFor(runtime).legacyFlatSkillsCleanup) {
         const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
         if (node_fs_1.default.existsSync(flatSkillsDir)) {
             for (const entry of node_fs_1.default.readdirSync(flatSkillsDir, { withFileTypes: true })) {
@@ -1075,6 +1067,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
                 }
             }
         }
+    }
+    if (hostBehaviorsFor(runtime).bareStemSkillsCleanup) {
         // Hermes: pre-#947 bare-stem skills/gsd/<stem>/ entries (dirs that do NOT
         // start with 'gsd-') — the #3664 layout used prefix='' so GSD-owned skills
         // had bare names (e.g. skills/gsd/help/). These are stale on uninstall.
@@ -1132,7 +1126,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // the dedicated combined commands+skills+plugin orchestrator instead of the
         // generic layout-driven loop below, mirroring the bespoke install path that
         // previously lived inline in bin/install.js.
-        const behaviors = _hostBehaviors(runtime);
+        const behaviors = hostBehaviorsFor(runtime);
         const projectDir = scope === 'global' ? process.cwd() : configDir;
         if (behaviors.combinedFamilyInstall) {
             // #2329: combined-family runtimes (OpenCode/Kilo) bypass
@@ -1326,7 +1320,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // with the same prefix). User-owned bare dirs with no gsd-<stem> counterpart
         // are untouched.
         let hermesBareStemCleanup = false;
-        if (runtime === 'hermes') {
+        if (hostBehaviorsFor(runtime).bareStemSkillsCleanup) {
             const nestedGsdDirForCleanup = node_path_1.default.join(configDir, 'skills', 'gsd');
             _removeHermesBareStemDirs(nestedGsdDirForCleanup);
             hermesBareStemCleanup = true;
@@ -1678,7 +1672,7 @@ function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, res
             // already satisfies the fold-to-descriptor requirement. Only the SKILLS
             // converter site above (installOpencodeFamilySkills) has a real
             // `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
-            content = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
+            content = hostBehaviorsFor(runtime).frontmatterDialect === 'kilo'
                 ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
                 : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
             installFs().writeFileSync(node_path_1.default.join(destDir, destName), content);
@@ -1881,6 +1875,9 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
         isWindowsHost: process.platform === 'win32',
         resolvedTarget: (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(configDir)),
         homeDir: (0, shell_command_projection_cjs_1.posixNormalize)(node_os_1.default.homedir()),
+        // #4377: the runtime's own localConfigDir, so an opted-in local install
+        // emits `<dir>/...` instead of this checkout's absolute path.
+        localDirName: runtimeArtifactConversion._localIncludeDirName(runtime),
     });
     // #2329: destDir is derived from the SAME hostBehaviors.flatCommandDir
     // descriptor value read by writeManifest's manifest-key prefix and by
@@ -1958,7 +1955,8 @@ function uninstallRuntimeArtifacts(runtime, configDir, scope, deps = {}) {
     // the GSD-managed DESCRIPTION.md and then the category dir itself if it
     // contains no user content (#947). _removeGsdEntries removed gsd-* dirs
     // but left the category container and DESCRIPTION.md intact.
-    if (runtime === 'hermes') {
+    // (#5169: `hostBehaviors.categoryContainerCleanup`.)
+    if (hostBehaviorsFor(runtime).categoryContainerCleanup) {
         const nestedGsdDir = node_path_1.default.join(configDir, 'skills', 'gsd');
         if (node_fs_1.default.existsSync(nestedGsdDir)) {
             // Remove GSD-owned DESCRIPTION.md (written by writeHermesCategoryDescription)
@@ -2016,7 +2014,6 @@ module.exports = {
     installAgentsKindStandalone,
     installOpencodeFamilyArtifacts,
     _installNativePluginIfDeclared,
-    _hostBehaviors,
     _copyStaged,
     hasExistingSymlinkBetween,
     isSymlinkedDestOptIn,

package/gsd-core/bin/lib/install-profiles.cjs

@@ -27,6 +27,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const installFsAdapter = require("./install-fs-adapter.cjs");
 const { installFs, mkInstallTempDir } = installFsAdapter;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // #2322: reuse the existing pure path-containment seam (ADR-1239 Phase C-2)
 // instead of hand-rolling a new traversal check for capability skill stems.
 const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
@@ -95,13 +96,15 @@ const PROFILES = Object.freeze({
  * Returns string[] — empty array if no requires: field.
  *
  * No external YAML parser dependency — hand-parse the single line
- * since GSD enforces flow-style arrays for requires:.
+ * since GSD enforces flow-style arrays for requires:. The block is the one the
+ * one fence owner (`locateFrontmatterFence`) finds — a `---` pair later in the
+ * body (a thematic break, a YAML example) is never frontmatter.
  */
 function parseRequires(content) {
-    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/m);
-    if (!fmMatch)
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return [];
-    const fm = fmMatch[1];
+    const fm = content.slice(fence.openEnd, fence.bodyEnd);
     const line = fm.match(/^requires:\s*(.+)$/m);
     if (!line)
         return [];

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -280,7 +280,14 @@ function readInstallManifest(configDir) {
         version: typeof m.version === 'string' ? m.version : null,
         timestamp: typeof m.timestamp === 'string' ? m.timestamp : null,
         mode: typeof m.mode === 'string' ? m.mode : null,
-        files: m.files && typeof m.files === 'object' ? m.files : {},
+        // #4544 (review): `typeof [] === 'object'` — a manifest whose `files` is a
+        // JSON array passed the object-shape guard, and Object.keys() then yielded
+        // "0","1",... as install-relative file paths. Consumers iterate these keys,
+        // so an array shape must degrade to the empty set exactly like a
+        // non-object shape does.
+        files: m.files && typeof m.files === 'object' && !Array.isArray(m.files)
+            ? m.files
+            : {},
         manifestVersion: normalizeManifestVersion(m.manifestVersion),
         runtime: normalizeReportedRuntime(rawRuntime),
         scope: (0, install_scope_cjs_1.isInstallScopeId)(m.scope) ? m.scope : null,

package/gsd-core/bin/lib/io.cjs

@@ -121,6 +121,84 @@ function writeAllSync(fd, data) {
         }
     }
 }
+/**
+ * Temporarily patch `fs.writeSync` so everything written to fd 1 (stdout) is
+ * captured into a string instead of reaching the real stdout, run `run`, then
+ * restore the original `fs.writeSync` and resolve with what was captured.
+ *
+ * The ONE shared helper (#5105 S9) for "run a nested command and read its own
+ * JSON envelope back as data instead of letting it reach the real stdout" —
+ * used by gsd-tools.cjs's `--pick`/`@file:` resolution and by `uat.cts`'s
+ * `cmdUatCompleteSession` (which needs `cmdCommit`'s result object without
+ * emitting cmdCommit's own envelope as a second line of output). A single
+ * definition means both callers see the same Buffer/string/encoding handling
+ * and the same throw-mid-write flush behavior, rather than two hand-rolled
+ * monkeypatches drifting apart.
+ *
+ * On a throw from `run`, whatever was captured before the throw is flushed to
+ * the REAL stdout — the wrapped command may have already written its own
+ * JSON envelope and THEN thrown to set a non-zero exit code (e.g. a
+ * capability set/disable on an unknown id); without this flush that output
+ * would be silently discarded, since the success-path flush at the call site
+ * never runs on a throw. The error still propagates so the exit code is
+ * preserved.
+ */
+function captureStdoutSyncWrites(run) {
+    const originalWriteSync = node_fs_1.default.writeSync;
+    let captured = '';
+    node_fs_1.default.writeSync = ((fd, data, ...rest) => {
+        if (fd === 1) {
+            if (Buffer.isBuffer(data)) {
+                captured += data.toString('utf-8');
+                return data.length;
+            }
+            const text = String(data);
+            captured += text;
+            let encoding = 'utf-8';
+            if (typeof rest[1] === 'string')
+                encoding = rest[1];
+            return Buffer.byteLength(text, encoding);
+        }
+        return originalWriteSync.call(node_fs_1.default, fd, data, ...rest);
+    });
+    const restore = () => {
+        node_fs_1.default.writeSync = originalWriteSync;
+    };
+    return Promise.resolve()
+        .then(() => run())
+        .then(() => {
+        restore();
+        return captured;
+    }, (err) => {
+        restore();
+        if (captured) {
+            try {
+                originalWriteSync.call(node_fs_1.default, 1, captured);
+            }
+            catch { /* best-effort flush */ }
+        }
+        throw err;
+    });
+}
+/**
+ * Resolve `output()`'s `@file:<path>` redirection (emitted for a >50KB JSON
+ * payload) back to the real content, or return `captured` unchanged when it
+ * is not that shape.
+ *
+ * #5105 review finding 7: the ONE definition, shared by gsd-tools.cjs's
+ * `--pick`/CLI-passthrough resolution and by `uat.cts`'s
+ * `cmdUatCompleteSession` (which reads `cmdCommit`'s captured result back
+ * without emitting cmdCommit's own envelope as a second stdout line) — same
+ * reasoning as `captureStdoutSyncWrites` just below: one definition means
+ * both callers agree on the trailing-newline-free prefix and the read
+ * encoding, rather than two hand-rolled `startsWith('@file:')` checks
+ * drifting apart.
+ */
+function resolveAtFileOutput(captured) {
+    if (!captured.startsWith('@file:'))
+        return captured;
+    return node_fs_1.default.readFileSync(captured.slice('@file:'.length), 'utf-8');
+}
 /**
  * The wire form of a JSON result: the exact bytes `output()` emits for it.
  *
@@ -290,6 +368,16 @@ const ERROR_REASON = Object.freeze({
     // exit 0. See .gsd/phase/feat-3884-failure-is-a-value/40-design.md.
     PICK_FIELD_ABSENT: 'pick_field_absent',
     PICK_OUTPUT_NOT_JSON: 'pick_output_not_json',
+    // summary-extract (#5013): the SUMMARY's frontmatter fence exists but failed
+    // to parse (extractFrontmatter's FRONTMATTER_UNPARSEABLE marker) — a
+    // distinct failure from "no frontmatter"/"field absent", never a silent
+    // demotion to empty fields at exit 0.
+    SUMMARY_EXTRACT_UNPARSEABLE: 'summary_extract_unparseable',
+    // verification (#5118, ADR-5057 Phase 4): a *-VERIFICATION.md frontmatter
+    // `status` outside the closed writer set (`passed | gaps_found |
+    // human_needed`) — verification.cts's VerificationStatusError, translated
+    // once, centrally, by gsd-tools.cjs. Never read as "no result" at exit 0.
+    VERIFICATION_STATUS_INVALID: 'verification_status_invalid',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',
@@ -334,14 +422,35 @@ const ERROR_REASON = Object.freeze({
  * more than one line or introduce an unescaped `"`. Callers embedding the
  * result MUST NOT add their own surrounding quotes — that would
  * double-quote it.
+ *
+ * #5118 security review: `JSON.stringify` leaves characters that render
+ * invisibly or reorder the text around them untouched — DEL and the C1
+ * controls (U+007F–U+009F), the line/paragraph separators (U+2028–U+2029),
+ * zero-width and directional marks (U+200B–U+200F), the bidi embeddings and
+ * overrides (U+202A–U+202E), the bidi isolates (U+2066–U+2069) and the BOM
+ * (U+FEFF). Each is escaped as `\uXXXX` so the token reads exactly as its
+ * code points are, whoever renders it.
  */
+const INVISIBLE_OR_BIDI_RANGES = [
+    [0x7f, 0x9f],
+    [0x2028, 0x2029],
+    [0x200b, 0x200f],
+    [0x202a, 0x202e],
+    [0x2066, 0x2069],
+    [0xfeff, 0xfeff],
+];
+/** Code points as `\uXXXX` escape text (source stays ASCII; no literal invisible characters). */
+function toUnicodeEscape(codePoint) {
+    return `\\u${codePoint.toString(16).padStart(4, '0')}`;
+}
+const INVISIBLE_OR_BIDI_RE = new RegExp(`[${INVISIBLE_OR_BIDI_RANGES.map(([lo, hi]) => `${toUnicodeEscape(lo)}-${toUnicodeEscape(hi)}`).join('')}]`, 'g');
 function formatDiagnosticToken(value) {
-    return JSON.stringify(value);
+    return JSON.stringify(value).replace(INVISIBLE_OR_BIDI_RE, (ch) => toUnicodeEscape(ch.charCodeAt(0)));
 }
 /**
  * Map an ERROR_REASON wire value onto a declared outcome name (#3912,
- * ADR-3889 §4). Closed over the 25-member enum: every reason gets an
- * explicit entry below, so a 26th member added without a mapping falls
+ * ADR-3889 §4). Closed over the 27-member enum: every reason gets an
+ * explicit entry below, so a 28th member added without a mapping falls
  * through to the `?? 'FAIL'` default rather than silently mis-projecting —
  * and tests/A1 iterates `Object.values(ERROR_REASON)`, so that default is
  * exactly what makes an unmapped addition visible instead of invisible.
@@ -389,6 +498,14 @@ const REASON_TO_OUTCOME = Object.freeze({
     // supposed to be there and was not; a prerequisite of the query failed.
     [ERROR_REASON.PICK_FIELD_ABSENT]: 'UNAVAILABLE',
     [ERROR_REASON.PICK_OUTPUT_NOT_JSON]: 'UNAVAILABLE',
+    // #5013: the SUMMARY's frontmatter fence exists but failed to parse — the
+    // prerequisite of the query (readable frontmatter) is what's broken, same
+    // shape as PICK_FIELD_ABSENT/PICK_OUTPUT_NOT_JSON just above.
+    [ERROR_REASON.SUMMARY_EXTRACT_UNPARSEABLE]: 'UNAVAILABLE',
+    // #5118: the verification report exists but its `status` is not a verdict
+    // the reader accepts — a broken prerequisite of the query, the same shape
+    // as SUMMARY_EXTRACT_UNPARSEABLE just above.
+    [ERROR_REASON.VERIFICATION_STATUS_INVALID]: 'UNAVAILABLE',
     // Self-failure: the run itself broke, not its inputs.
     [ERROR_REASON.SDK_FAIL_FAST]: 'INTERNAL',
     [ERROR_REASON.SECURITY_SCAN_FAILED]: 'INTERNAL',
@@ -433,4 +550,6 @@ module.exports = {
     getJsonErrorMode,
     error,
     formatDiagnosticToken,
+    captureStdoutSyncWrites,
+    resolveAtFileOutput,
 };

package/gsd-core/bin/lib/loop-resolver.cjs

@@ -28,10 +28,19 @@
  *   - capability-registry.cjs (byLoopPoint, consumed at call time)
  *   - capability-state.cjs (resolveCapabilityRuntimeState — for capabilities list)
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output: coreOutput, error: coreError } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const verificationMod = require("./verification.cjs");
+const { resolvePhaseArtifactFile } = verificationMod;
+const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderModule = require("./config-loader.cjs");
 const { loadConfig } = configLoaderModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -528,6 +537,56 @@ function resolveActiveHooksForPoint(cwd, point, options = {}) {
     const combinedWarnings = [...(state.warnings || []), ...loadFailWarnings];
     return { point: resolved.point, activeHooks: resolved.activeHooks, warnings: combinedWarnings };
 }
+/**
+ * #5105 R2: a `produces` entry `p` "exists" in `phaseDir` when it resolves via
+ * the SAME phase-artifact selection core `resolveVerificationFile`/
+ * `resolveUatFile` delegate to (`resolvePhaseArtifactFile`, `verification.cts`)
+ * — no second derivation of "which file counts as this phase's artifact"
+ * (#3473 F2's generative-divergence class). That core is pure and takes an
+ * already-read directory listing of REGULAR-file names only, so a directory
+ * of the same name, or a suffixed near-miss (`p.bak`, `p.tmp`), never counts,
+ * and `phaseDirName` scoping rejects a stray cross-phase file (`02-SECURITY.md`
+ * inside a `01-foo` phase dir) exactly as the aggregate scans do.
+ */
+function producesEntryPresent(fileNames, phaseDirName, p) {
+    return resolvePhaseArtifactFile([...fileNames], p, { phaseDirName, allowBare: true }) !== null;
+}
+/**
+ * #5105 R2: partition `activeHooks` by whether every one of a `kind:"step"`
+ * hook's declared `produces` artifacts already exists (as a regular file)
+ * directly in `phaseDir`. A hook with `produces: []` (e.g. mempalace-capture),
+ * and every gate/contribution, passes through unchanged in `activeHooks`.
+ *
+ * Throws when `phaseDir` cannot be read (fail closed — the caller converts
+ * this to a `coreError` exit, never a silent pass-everything-through).
+ */
+function partitionHooksByFingerprint(activeHooks, phaseDir) {
+    const entries = node_fs_1.default.readdirSync(phaseDir, { withFileTypes: true });
+    const fileNames = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const phaseDirName = node_path_1.default.basename(phaseDir);
+    const kept = [];
+    const skipped = [];
+    for (const hook of activeHooks) {
+        if (hook.kind !== 'step' || !hook.produces || hook.produces.length === 0) {
+            kept.push(hook);
+            continue;
+        }
+        const everyProduced = hook.produces.every((p) => producesEntryPresent(fileNames, phaseDirName, p));
+        if (everyProduced) {
+            skipped.push({
+                capId: hook.capId,
+                kind: 'step',
+                ref: hook.ref,
+                reason: 'produces-present',
+                artifacts: [...hook.produces],
+            });
+        }
+        else {
+            kept.push(hook);
+        }
+    }
+    return { activeHooks: kept, skippedHooks: skipped };
+}
 function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (!point) {
         coreError('loop render-hooks requires a <point> argument. Valid points: ' + CANONICAL_POINTS.join(', '));
@@ -548,6 +607,38 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         coreError(msg);
         return;
     }
+    // #5105 R2: --after-fingerprint <phaseDir> — gate out verify:post steps
+    // whose declared artifact(s) already exist in phaseDir (execute-phase
+    // already dispatched them before its own fingerprint; a re-dispatch here
+    // would write a post-fingerprint covered path for no reason, #4981/#4887).
+    const afterFingerprintDir = typeof options['afterFingerprint'] === 'string' ? options['afterFingerprint'] : undefined;
+    let skippedHooks;
+    if (afterFingerprintDir !== undefined) {
+        // #5105 S10: resolve relative to the handler's own cwd (never the
+        // process cwd) and fail closed if it escapes the project root — the same
+        // `requireSafePath` seam `uat.cts`'s `cmdUatCompleteSession` uses for its
+        // own path argument.
+        let safePhaseDir;
+        try {
+            safePhaseDir = (0, security_cjs_1.requireSafePath)(afterFingerprintDir, cwd, '--after-fingerprint directory', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+        }
+        catch (err) {
+            const msg = (err instanceof Error) ? err.message : String(err);
+            coreError(`--after-fingerprint directory is unsafe: ${msg}`);
+            return;
+        }
+        let partition;
+        try {
+            partition = partitionHooksByFingerprint(result.activeHooks, safePhaseDir);
+        }
+        catch (err) {
+            const msg = (err instanceof Error) ? err.message : String(err);
+            coreError(`--after-fingerprint phase directory not found or unreadable: ${afterFingerprintDir} (${msg})`);
+            return;
+        }
+        result = { point: result.point, activeHooks: partition.activeHooks, warnings: result.warnings };
+        skippedHooks = partition.skippedHooks;
+    }
     if (activeCapId !== undefined) {
         const isActive = result.activeHooks.some((h) => h.capId === activeCapId);
         process.stdout.write(isActive ? 'true\n' : 'false\n');
@@ -562,6 +653,9 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (result.warnings.length > 0) {
         envelope.warnings = result.warnings;
     }
+    if (skippedHooks !== undefined) {
+        envelope.skippedHooks = skippedHooks;
+    }
     coreOutput(envelope, raw);
 }
 module.exports = {
@@ -569,6 +663,7 @@ module.exports = {
     renderLoopHooks,
     cmdLoopRenderHooks,
     resolveActiveHooksForPoint,
+    partitionHooksByFingerprint,
     // Exported for tests
     _getNestedConfigValue,
     _resolveActivationValue,

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -11,6 +11,7 @@
  * ADR-457 build-at-publish: compiled by tsc to gsd-core/bin/lib/markdown-sectionizer.cjs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.XML_DECISION_TAG_NAMES = void 0;
 exports.stripFencedCode = stripFencedCode;
 exports.stripInlineCode = stripInlineCode;
 exports.scanInlineCodeSpans = scanInlineCodeSpans;
@@ -21,11 +22,13 @@ exports.collectSections = collectSections;
 exports.collectSection = collectSection;
 exports.iterateBullets = iterateBullets;
 exports.updateBullet = updateBullet;
+exports.updateHeading = updateHeading;
 exports.extractTaggedBlocks = extractTaggedBlocks;
 exports.stripTaggedBlocks = stripTaggedBlocks;
 exports.replaceSection = replaceSection;
 exports.withSection = withSection;
 exports.deleteSection = deleteSection;
+exports.extractXmlTagBodies = extractXmlTagBodies;
 const pattern_cjs_1 = require("./pattern.cjs");
 // ─── stripFencedCode ──────────────────────────────────────────────────────────
 /**
@@ -722,7 +725,7 @@ function updateBullet(content, match, transform) {
                     bulletText = nm[2];
             }
         }
-        if (bulletText !== null && match(bulletText, rawLine)) {
+        if (bulletText !== null && match(bulletText, rawLine, i)) {
             const newLine = transform(rawLine);
             if (typeof newLine !== 'string')
                 return content;
@@ -732,6 +735,40 @@ function updateBullet(content, match, transform) {
     }
     return content;
 }
+// ─── updateHeading ────────────────────────────────────────────────────────────
+/**
+ * Rewrite the physical line of the FIRST ATX heading (outside fenced code)
+ * accepted by `match` — the heading analogue of `updateBullet` (ADR-5057 §6,
+ * Phase 13, #5217). Heading discovery is `tokenizeHeadings`' (the one fence
+ * state machine for headings); this function adds only the splice.
+ *
+ * `rawLine` (second argument to `match`, the only argument to `transform`) is
+ * the UNMODIFIED physical line between `\n` separators, so on a CRLF document
+ * its trailing `\r` is included and every untouched byte — including every
+ * other line's own terminator — is copied from `content` verbatim. `lineIndex`
+ * is the 0-based physical line index, the same indexing as
+ * `content.split('\n')`, so a caller holding a pre-computed line-indexed plan
+ * can disambiguate two headings with identical text.
+ *
+ * Bounded no-op: no accepted heading, or `transform` returning a non-string,
+ * returns `content` unchanged.
+ */
+function updateHeading(content, match, transform) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    for (const heading of tokenizeHeadings(content)) {
+        const newlineAt = content.indexOf('\n', heading.offset);
+        const lineEnd = newlineAt === -1 ? content.length : newlineAt;
+        const rawLine = content.slice(heading.offset, lineEnd);
+        if (!match(heading, rawLine, heading.line - 1))
+            continue;
+        const newLine = transform(rawLine);
+        if (typeof newLine !== 'string')
+            return content;
+        return content.slice(0, heading.offset) + newLine + content.slice(lineEnd);
+    }
+    return content;
+}
 // ─── extractTaggedBlocks ──────────────────────────────────────────────────────
 /**
  * Return the inner text of every `<tagName>…</tagName>` block in `content`,
@@ -962,5 +999,42 @@ function deleteSection(content, headingPredicate, opts = {}) {
     const collapsedBefore = before.replace(/(?:\r\n|\n){3,}$/, (m) => (m.includes('\r\n') ? '\r\n\r\n' : '\n\n'));
     return collapsedBefore + after;
 }
+// ─── extractXmlTagBodies ──────────────────────────────────────────────────────
+// #2372: scanned-tag set must match the planner-canonical surfaces where a D-NN citation
+// is meaningful. `<objective>`/`<tasks>`/`<task>`/`<action>` are the historical core. The
+// planner is also explicitly told (plan-phase.md) to cite decisions in `<read_first>`,
+// `<behavior>`, `<verify>`, `<acceptance_criteria>`, and `<done>` — those are scanned too,
+// so the decision-coverage gate does not report a false gap when a decision is cited in any of them.
+//
+// Implementation: per-tag matching, NOT a single wide alternation. A single alternation
+// like `<(?:a|b|c)>...<\/(?:a|b|c)>` halts the outer tag's body capture at any inner tag
+// in the set, dropping any citation in the outer tag's prefix prose — e.g.
+// `<action>per D-05 <verify>npm test</verify></action>` would lose D-05 because `<verify>`
+// halts the `<action>` body before the citation. Per-tag matching avoids this: each tag's
+// body terminates only at its OWN closing tag, so `<verify>` inside `<action>` is absorbed
+// into `<action>`'s body (D-05 caught) AND `<verify>` is matched separately on its own pass.
+// Each per-tag regex keeps the ReDoS-safe negative-lookahead tempering (#2128).
+exports.XML_DECISION_TAG_NAMES = ['objective', 'tasks', 'task', 'action', 'read_first', 'behavior', 'verify', 'acceptance_criteria', 'done'];
+function buildXmlDecisionTagRegex(tagName) {
+    // Per-tag: body tempering stops only at the SAME tag's reopening or closing — other
+    // scanned tags pass through as text into this body. Non-greedy `*?` to first close.
+    return new RegExp(`<${tagName}(?:\\s[^>]{0,1000})?>((?:(?!<${tagName}[\\s>])[\\s\\S])*?)<\\/${tagName}>`, 'gi');
+}
+/**
+ * The bodies of every planner-canonical XML tag (`XML_DECISION_TAG_NAMES`) in `text`,
+ * joined by `\n`. Each tag's body ends only at its OWN closing tag, so an inner scanned tag
+ * is absorbed into the outer body AND matched on its own pass.
+ */
+function extractXmlTagBodies(text) {
+    const parts = [];
+    for (const tagName of exports.XML_DECISION_TAG_NAMES) {
+        const re = buildXmlDecisionTagRegex(tagName);
+        for (const match of text.matchAll(re)) {
+            if (match[1])
+                parts.push(match[1]);
+        }
+    }
+    return parts.join('\n');
+}
 // Consumers: require('../gsd-core/bin/lib/markdown-sectionizer.cjs')
 // Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).