@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/tdd-red-evidence.cjs

@@ -34,6 +34,52 @@ const prohibition_enforcement_cjs_1 = require("./prohibition-enforcement.cjs");
 function baseOf(p) {
     return typeof p === 'string' ? (p.split(/[\\/]/).pop() ?? p) : '';
 }
+/**
+ * #4724 — Surefire/Failsafe XML summary parsed by TAG-BOUNDARY scanning, NOT
+ * by a lazy `(.*?)<\/testcase>` regex: Surefire writes PASSING cases as
+ * self-closing `<testcase … />` elements, so a lazy span from a green case to
+ * the next closing tag swallows every case between and misreports names beside
+ * the right failure message. The scanner walks `<testcase` start tags; each
+ * case's extent is its own tag (self-closing) or the segment up to its
+ * `</testcase>` closer (testcases never nest). A `<failure` or `<error` child
+ * marks the case failing; the reported name is `classname#name`. Any parse
+ * anomaly degrades to "case not failing" — the module stays fail-closed.
+ */
+function parseSurefireSummary(output) {
+    let tests = 0;
+    let fail = 0;
+    const failing_tests = [];
+    let idx = output.indexOf('<testcase');
+    while (idx !== -1) {
+        const tagEnd = output.indexOf('>', idx);
+        // #4724 review (HIGH): a `<testcase` with no `>` (truncated/stream-cut
+        // output) must terminate the scan — resuming the search at -1 clamps to 0
+        // and re-finds the same tag forever. Degrade to what was scanned so far
+        // (fail-closed: an incomplete report proves nothing).
+        if (tagEnd === -1)
+            break;
+        tests++;
+        const tagText = output.slice(idx, tagEnd + 1);
+        // Self-closing (`/>`): the case has NO body — a failing sibling after it
+        // must never be attributed to this case (the #4724 spanning trap).
+        const selfClosing = output[tagEnd - 1] === '/';
+        const closeIdx = selfClosing ? -1 : output.indexOf('</testcase>', tagEnd);
+        // CDATA sections are verbatim captured output (e.g. System.out echoing
+        // test source) — their content must never be scanned for failure tags
+        // (#4724 review: CDATA phantom failures).
+        const body = (selfClosing
+            ? ''
+            : output.slice(tagEnd + 1, closeIdx === -1 ? output.length : closeIdx)).replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+        const name = /name="([^"]*)"/.exec(tagText)?.[1] ?? '';
+        const classname = /classname="([^"]*)"/.exec(tagText)?.[1] ?? '';
+        if (body.includes('<failure') || body.includes('<error')) {
+            fail++;
+            failing_tests.push(classname ? `${classname}#${name}` : name);
+        }
+        idx = output.indexOf('<testcase', closeIdx === -1 ? tagEnd : closeIdx);
+    }
+    return { tests, pass: tests - fail, fail, failing_tests };
+}
 /** Coerce and validate the raw record's scalar fields. Returns null exit_code only when absent/non-numeric. */
 function readInput(input) {
     const command = typeof input?.command === 'string' ? input.command : '';
@@ -69,8 +115,34 @@ function classifyRedEvidence(input) {
         };
     }
     const { command, exitCode, output, targetTest } = parsed;
-    const summary = (0, prohibition_enforcement_cjs_1.parseNodeTestSummary)(output);
-    const failing = (0, prohibition_enforcement_cjs_1.tapFailedTestNames)(output);
+    // #4724: format detection. Surefire/Failsafe XML (a `<testsuite>` element) is
+    // parsed by tag-boundary scanning; everything else stays on the proven TAP
+    // primitives. Unknown formats keep the TAP parse — which finds nothing — and
+    // fail closed below.
+    // #4724 review: BOTH element names must appear — a TAP error message that
+    // merely quotes "<testsuite>" (e.g. "expected <testsuite> was 2") must not
+    // flip a genuine TAP red into the XML path.
+    const isSurefireXml = output.includes('<testsuite') && output.includes('<testcase');
+    let summary;
+    let failing;
+    if (isSurefireXml) {
+        const sf = parseSurefireSummary(output);
+        summary = { tests: sf.tests, pass: sf.pass, fail: sf.fail };
+        failing = sf.failing_tests;
+    }
+    else {
+        summary = (0, prohibition_enforcement_cjs_1.parseNodeTestSummary)(output);
+        failing = (0, prohibition_enforcement_cjs_1.tapFailedTestNames)(output);
+    }
+    // Surefire target matching is class-level (the plan names the class); the
+    // entry's last classname segment or its test name must carry the target.
+    const surefireTargetMatches = isSurefireXml
+        ? failing.some((entry) => {
+            const cls = entry.split('#')[0] ?? '';
+            const nm = entry.split('#')[1] ?? '';
+            return cls === targetTest || cls.endsWith(`.${targetTest}`) || nm === targetTest;
+        })
+        : failing.includes(targetTest);
     const evidence = {
         command,
         exit_code: exitCode,
@@ -90,14 +162,15 @@ function classifyRedEvidence(input) {
     if (summary.tests === 0) {
         return { verdict: 'INVALID_RED', reason: 'zero_tests_discovered', evidence };
     }
-    // Nonzero exit but TAP reports no failing test: harness/setup/parser crash
-    // whose failure never reached a test assertion (or unparseable output).
+    // Nonzero exit but the report shows no failing test: harness/setup/parser
+    // crash whose failure never reached a test assertion (or unparseable output).
     if (summary.fail === 0 || failing.length === 0) {
         return { verdict: 'INVALID_RED', reason: 'nonzero_exit_without_test_failure', evidence };
     }
     // Fixture/load failure: every failing entry is named like the target FILE —
     // node reports a load-time crash (throw-on-require, syntax error, ENOENT
     // fixture) as a file-named `not ok 1 - <file>`, never the target test.
+    // (TAP-only shape: Surefire failures carry class#method names.)
     const targetBase = baseOf(input?.targetFile ?? '');
     const distinctlyNamed = failing.filter((n) => (targetBase ? baseOf(n) !== targetBase : true));
     if (distinctlyNamed.length === 0) {
@@ -105,7 +178,7 @@ function classifyRedEvidence(input) {
     }
     // Unrelated failure: real tests ran and failed, but none is the target test
     // the plan named — an unrelated assertion must not authorize GREEN.
-    if (!distinctlyNamed.includes(targetTest)) {
+    if (!(isSurefireXml ? surefireTargetMatches : distinctlyNamed.includes(targetTest))) {
         return { verdict: 'INVALID_RED', reason: 'no_target_test_failure', evidence };
     }
     return { verdict: 'RED_EVIDENCE_OK', reason: 'target_test_failed', evidence };

package/gsd-core/bin/lib/uat-predicate.cjs

@@ -47,6 +47,22 @@ const BLOCKING_VERIFICATION_FM_STATUSES = new Set([
 ]);
 // UAT test-item `result` values that count as passing
 const PASSING_RESULTS = new Set(['passed', 'pass']);
+// #4546 — a `skipped` test-item whose reason carries the verify-work writer's
+// deferral template prefix ("Deferred follow-up: …", #1921) is a deliberately
+// deferred follow-up: non-blocking. Quote-tolerant (the writer wraps the value
+// in double quotes) and case-insensitive (human-edited files vary). Anything
+// else — a reasonless skip, a non-deferral reason — still blocks. PARITY: this
+// matcher and the writer template in gsd-core/workflows/verify-work.md
+// (process_response) are two halves of one contract, pinned together by
+// tests/verify-work-deferred-promotion.test.cjs.
+const DEFERRED_REASON_RE = /^["']?deferred follow-up\b/i;
+// Trust note (#4546 review): the reason line is user-authored state — an
+// author could equally write `result: passed` — so this prefix is an
+// AUTHORING contract with the verify-work writer, not a security boundary.
+// A hand-written deferral that skips the UAT file's ## Deferred Follow-Ups
+// section also bypasses the complete_session promotion offer; the section is
+// the durable project-level record. Variant spellings that do not match
+// ("Deferred follow-ups:", "followup") block — fail-closed by design.
 // ─── stripFalsePositiveContexts ───────────────────────────────────────────────
 /**
  * Remove contexts that can contain `result: ...` lines that are NOT real test results:
@@ -166,16 +182,28 @@ function parseUatResultItems(cleanContent) {
         // ambiguity counting, matching src/uat.cts's contract.
         // Uses [ \t]* (not \s*) so the captured value must sit on the SAME line as result:.
         // A result: key with the value on a subsequent line yields no match → 'missing' (blocker).
+        // #4546: the `reason:` line is captured with the same frame and FIRST-match
+        // rule — it is the deferral signal the evaluator needs (a `skipped` item
+        // whose reason is the verify-work writer's "Deferred follow-up:" template
+        // is non-blocking). Quoted values are captured with their quotes so the
+        // evaluator's matcher can tolerate them exactly as written.
         const RESULT_LINE_RE = /^result:[ \t]*\[?([\w-]+)\]?/i;
         const resultMatch = blockContent
             .split('\n')
             .map((line) => line.match(RESULT_LINE_RE))
             .find((m) => m !== null) ?? null;
+        const REASON_LINE_RE = /^reason:[ \t]*(.*)$/i;
+        const reasonMatch = blockContent
+            .split('\n')
+            .map((line) => line.match(REASON_LINE_RE))
+            .find((m) => m !== null) ?? null;
+        const reason = reasonMatch ? reasonMatch[1].trim() : '';
         if (resultMatch) {
             items.push({
                 test: h.test,
                 name: h.name,
                 result: resultMatch[1].toLowerCase(),
+                reason,
             });
         }
         else {
@@ -184,6 +212,7 @@ function parseUatResultItems(cleanContent) {
                 test: h.test,
                 name: h.name,
                 result: 'missing',
+                reason,
             });
         }
     }
@@ -198,7 +227,13 @@ function parseUatResultItems(cleanContent) {
  * Pass requires at least one real passing check AND no blockers.
  */
 function evaluateUatPassed(phaseFullDir, opts) {
-    const requireVerification = opts?.policy?.requireVerification === true;
+    // uatOnly (#4663) takes precedence: it evaluates the UAT rows ONLY, skipping
+    // the VERIFICATION-file blockers entirely. The verify-work canonicalize
+    // pre-check needs exactly that — it runs while the report still reads
+    // `human_needed`, which is itself a blocking verification status, so the
+    // full predicate could never pass there and the flip would deadlock.
+    const uatOnly = opts?.policy?.uatOnly === true;
+    const requireVerification = !uatOnly && opts?.policy?.requireVerification === true;
     const blockers = [];
     const checks = [];
     const uatFiles = [];
@@ -221,7 +256,7 @@ function evaluateUatPassed(phaseFullDir, opts) {
             checks: [],
             blockers,
             no_uat_artifacts,
-            policy: { require_verification: requireVerification },
+            policy: { require_verification: requireVerification, uat_only: uatOnly },
             // readVerificationStatus was never reached on this early-return path.
             verification_stale_check_indeterminate: false,
         };
@@ -269,13 +304,20 @@ function evaluateUatPassed(phaseFullDir, opts) {
         const cleanContent = stripFalsePositiveContexts(raw);
         const items = parseUatResultItems(cleanContent);
         for (const item of items) {
-            const passing = PASSING_RESULTS.has(item.result);
+            // #4546: a `skipped` item whose reason matches the verify-work writer's
+            // "Deferred follow-up:" template is a deliberately deferred follow-up
+            // (#1921) — non-blocking. Quote-tolerant because the writer emits the
+            // reason WITH its wrapping quotes. Everything else — pending, blocked,
+            // issue, missing, and a plain or non-deferral skipped — still blocks.
+            const deferred = item.result === 'skipped' && DEFERRED_REASON_RE.test(item.reason);
+            const passing = PASSING_RESULTS.has(item.result) || deferred;
             checks.push({
                 file,
                 test: item.test,
                 name: item.name,
                 result: item.result,
                 passing,
+                deferred,
             });
             if (!passing) {
                 blockers.push(`${file}: test ${item.test} (${item.result})`);
@@ -284,7 +326,7 @@ function evaluateUatPassed(phaseFullDir, opts) {
     }
     // ── Process VERIFICATION files ─────────────────────────────────────────────
     let hasPassingVerification = false;
-    for (const file of verFileNames) {
+    for (const file of uatOnly ? [] : verFileNames) {
         verificationFiles.push(file);
         const verificationFilePath = node_path_1.default.join(phaseFullDir, file);
         let raw = '';
@@ -340,6 +382,7 @@ function evaluateUatPassed(phaseFullDir, opts) {
         no_uat_artifacts,
         policy: {
             require_verification: requireVerification,
+            uat_only: uatOnly,
         },
         verification_stale_check_indeterminate: verificationStaleCheckIndeterminate,
     };

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

@@ -322,7 +322,7 @@ function cmdRenderCheckpoint(cwd, options = {}, raw) {
     if (!filePath) {
         error('UAT file required: use uat render-checkpoint --file <path>');
     }
-    const resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'UAT file', { allowAbsolute: true });
+    const resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'UAT file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
     if (!node_fs_1.default.existsSync(resolvedPath)) {
         error(`UAT file not found: ${filePath}`);
     }
@@ -3579,6 +3579,14 @@ function categorizeItem(rawResult, reason, blockedBy) {
         return 'blocked';
     }
     if (result === 'skipped') {
+        // #4546 — a deliberately deferred follow-up (the verify-work writer's
+        // "Deferred follow-up:" template, #1921) is its own category, checked
+        // BEFORE the keyword families so e.g. "…on the release build next
+        // version" is not misfiled as build_needed. Must agree with
+        // uat-predicate.cts's DEFERRED_REASON_RE (gate/audit agreement,
+        // #3078-CR), pinned by tests/uat-predicate.test.cjs.
+        if (reason && /^["']?deferred follow-up\b/i.test(reason))
+            return 'deferred';
         if (reason) {
             if (/server|not running|not available/i.test(reason))
                 return 'server_blocked';

package/gsd-core/bin/lib/ui-consideration-probe.cjs

@@ -117,6 +117,15 @@ function validateRequirement(element) {
     if (r.elements == null && !(typeof r.text === 'string' && r.text.trim())) {
         throw new Error(`element ${element.id} text must be a non-empty string when no elements override is provided`);
     }
+    // text_en (#4657) is optional, but when present it must be a non-empty string. An empty
+    // string is NOT caught by `??` (only null/undefined are), so an unvalidated `text_en: ''`
+    // would silently win `text_en ?? text` and classify against '' — the same fail-open shape
+    // #1110/#2773 already exist to eliminate, just moved one field over. Validated
+    // unconditionally (not gated on whether `elements` will make it unused) so bad data fails
+    // closed even when it happens to be dead for this particular call.
+    if (r.text_en != null && !(typeof r.text_en === 'string' && r.text_en.trim())) {
+        throw new Error(`element ${element.id} text_en must be a non-empty string when present`);
+    }
 }
 /** Validate a UI-consideration resolution against the UI verification vocabulary (delegated, D-06). */
 function validateResolution(resolution) {
@@ -143,7 +152,11 @@ function proposeConsiderations(element) {
         kinds = element.elements;
     }
     else {
-        kinds = classifyElement(element.text);
+        // #4657: prefer the English translation when present — UI_CUES are English-only
+        // word-boundary patterns, so a non-English `text` (e.g. response_language projects)
+        // would otherwise classify to zero kinds. validateRequirement (called above) has
+        // already guaranteed text_en, if present, is a non-empty string.
+        kinds = classifyElement((element.text_en ?? element.text));
         if (kinds.length === 0) {
             // Prose present but no element cue matched. Do NOT silently drop it (#1110): a UI element
             // whose phrasing missed every cue would otherwise vanish from coverage with no signal — the
@@ -210,7 +223,7 @@ function proposeElements(elements) {
         const considerations = proposeConsiderations(el);
         const kinds = Array.isArray(el.elements)
             ? el.elements // already validated inside proposeConsiderations
-            : classifyElement(el.text);
+            : classifyElement((el.text_en ?? el.text)); // #4657: text_en ?? text
         const unclassified = !Array.isArray(el.elements) && kinds.length === 0;
         const categories = unclassified ? [] : applicableCategories(kinds);
         return { id: el.id, kinds, categories, considerations, unclassified };

package/gsd-core/bin/lib/ui-frontend-evidence.cjs

@@ -23,6 +23,19 @@
  *       html, ...) are deliberately NOT static evidence: docs sites and
  *       markdown/bash/config repos routinely carry stray `.html`/`.css`, which
  *       is precisely the false-positive class #3312 reports.
+ *   (c) any `*.xaml` file, or a `*.swift` / `*.kt` / `*.dart` file whose
+ *       content carries its ecosystem's UI-framework import marker
+ *       (`import SwiftUI` / `import UIKit`, `androidx.compose`,
+ *       `package:flutter`) (#4658). Native UI projects (SwiftUI, Jetpack
+ *       Compose, Flutter, .NET MAUI) carry neither (a) nor (b), which made the
+ *       gate structurally unreachable for them. Source files match on the
+ *       IMPORT, not the extension alone — the same unambiguity bar that
+ *       justifies (b)'s subset and excludes (css, scss, html): a non-UI Swift
+ *       package (a CLI, a server) imports Foundation, not SwiftUI, and must
+ *       stay silent. `.xaml` is extension-alone for the same reason `.tsx` is —
+ *       the extension itself is unambiguous. Marker matching is case-sensitive
+ *       (imports are case-sensitive in all four ecosystems); extension
+ *       matching is case-insensitive, mirroring `UI_COMPONENT_FILE_RE`.
  *
  * All I/O failures degrade to `false` (no evidence) — never throw.
  */
@@ -30,12 +43,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UI_COMPONENT_FILE_RE = void 0;
+exports.NATIVE_UI_CONTENT_MARKERS = exports.NATIVE_UI_XAML_RE = exports.NATIVE_UI_SOURCE_RE = exports.UI_COMPONENT_FILE_RE = void 0;
 exports.hasStaticFrontendEvidence = hasStaticFrontendEvidence;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 /** Component-framework file extensions — the static-evidence subset of UI_FILE_EXTENSIONS_RE. */
 exports.UI_COMPONENT_FILE_RE = /\.(tsx|jsx|vue|svelte)$/i;
+/** Native UI source files whose CONTENT is scanned for an import marker (#4658). */
+exports.NATIVE_UI_SOURCE_RE = /\.(swift|kt|dart)$/i;
+/** Native UI files that are evidence by extension alone — `.xaml`, the `.tsx` analogue. */
+exports.NATIVE_UI_XAML_RE = /\.xaml$/i;
+/**
+ * Per-extension UI-framework import markers for `NATIVE_UI_SOURCE_RE` files
+ * (#4658). Every marker embeds its ecosystem's import keyword, so a bare
+ * framework-name mention in prose or a comment is not evidence; the Dart
+ * marker carries both legal quote styles. Case-sensitive: imports are
+ * case-sensitive in Swift, Kotlin and Dart.
+ */
+exports.NATIVE_UI_CONTENT_MARKERS = {
+    '.swift': ['import SwiftUI', 'import UIKit'],
+    '.kt': ['import androidx.compose'],
+    '.dart': ["import 'package:flutter", 'import "package:flutter'],
+};
 /**
  * UI-framework package.json dependencies (dependencies OR devDependencies).
  * Component frameworks/renderers only — deliberately excludes meta tooling
@@ -111,9 +140,16 @@ function packageJsonHasUiFramework(projectDir) {
     }
     return false;
 }
-function treeHasComponentFile(projectDir) {
-    // Iterative BFS — bounded by MAX_WALK_ENTRIES so a pathological tree cannot
-    // stall the gate. Symlinks are never followed (withFileTypes + isDirectory).
+/**
+ * Shared bounded BFS over the project tree — the single home of the walk
+ * semantics both evidence walks depend on: SKIP_DIRS pruning, the
+ * MAX_WALK_ENTRIES entry cap (cap-hit → `false`: the tree is treated as
+ * scanned and evidence stays undecided), symlinks never followed
+ * (withFileTypes Dirents), unreadable directories skipped. `visit` is called
+ * for every regular file with its name and full path; returning `true` stops
+ * the walk with `true` (evidence found).
+ */
+function walkProjectFiles(projectDir, visit) {
     const queue = [projectDir];
     let visited = 0;
     while (queue.length > 0 && visited < MAX_WALK_ENTRIES) {
@@ -133,25 +169,80 @@ function treeHasComponentFile(projectDir) {
                 if (!SKIP_DIRS.has(entry.name))
                     queue.push(node_path_1.default.join(dir, entry.name));
             }
-            else if (entry.isFile() && exports.UI_COMPONENT_FILE_RE.test(entry.name)) {
+            else if (entry.isFile() && visit(entry.name, node_path_1.default.join(dir, entry.name))) {
                 return true;
             }
         }
     }
     return false;
 }
+function treeHasComponentFile(projectDir) {
+    return walkProjectFiles(projectDir, (name) => exports.UI_COMPONENT_FILE_RE.test(name));
+}
+/**
+ * Read at most the first 64 KiB of `file` and report whether any of `markers`
+ * occurs in it (#4658). Import sections live at the top of a source file, so a
+ * bounded prefix read keeps the gate's plan-time cost profile without reading
+ * generated monsters in full. Any I/O failure degrades to false — never throw.
+ */
+function fileHasAnyMarker(file, markers) {
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(file, 'r');
+    }
+    catch {
+        return false;
+    }
+    try {
+        const bytes = Buffer.alloc(64 * 1024);
+        const read = node_fs_1.default.readSync(fd, bytes, 0, bytes.length, 0);
+        const prefix = bytes.toString('utf8', 0, read);
+        return markers.some((m) => prefix.includes(m));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            node_fs_1.default.closeSync(fd);
+        }
+        catch {
+            // already closed — nothing to degrade
+        }
+    }
+}
+/**
+ * Native-UI walk over the shared bounded BFS (#4658): `.xaml` is evidence by
+ * extension alone; `.swift`/`.kt`/`.dart` are evidence only when the file's
+ * content carries its ecosystem's import marker.
+ */
+function treeHasNativeUiFile(projectDir) {
+    return walkProjectFiles(projectDir, (name, fullPath) => {
+        if (exports.NATIVE_UI_XAML_RE.test(name))
+            return true;
+        if (exports.NATIVE_UI_SOURCE_RE.test(name)) {
+            const markers = exports.NATIVE_UI_CONTENT_MARKERS[node_path_1.default.extname(name).toLowerCase()];
+            return markers != null && fileHasAnyMarker(fullPath, markers);
+        }
+        return false;
+    });
+}
 /**
  * Does the project tree carry static evidence of a frontend?
  *
  * @param projectDir - Absolute path to the project root (the gate's cwd).
- * @returns true when package.json declares a UI-framework dependency or the
- *          tree contains a component-framework file; false otherwise (including
- *          on any I/O failure — evidence must be affirmative).
+ * @returns true when package.json declares a UI-framework dependency, the tree
+ *          contains a component-framework file, or the tree contains native UI
+ *          evidence (a `.xaml` file, or a `.swift`/`.kt`/`.dart` file carrying
+ *          its ecosystem's UI import marker — #4658); false otherwise
+ *          (including on any I/O failure — evidence must be affirmative).
  */
 function hasStaticFrontendEvidence(projectDir) {
     if (typeof projectDir !== 'string' || projectDir === '')
         return false;
     if (packageJsonHasUiFramework(projectDir))
         return true;
-    return treeHasComponentFile(projectDir);
+    if (treeHasComponentFile(projectDir))
+        return true;
+    return treeHasNativeUiFile(projectDir);
 }

package/gsd-core/bin/lib/undo-commit-selection.cjs

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Undo Commit Selection — issue #4661 (absorbed into epic #4906, Phase 5).
+ *
+ * Pure scope-matching logic for `/gsd:undo --phase N` / `--plan N-M`, replacing
+ * the two hand-rolled `git log --oneline | grep -E ...` pipelines that used to
+ * live in `gsd-core/workflows/undo.md`. Those greps were unanchored substring
+ * matches against a live regex built from unvalidated user input — four
+ * documented bug classes (see #4661):
+ *
+ *   1. The id was interpolated raw into an ERE: `.` and `+` are live
+ *      metacharacters there, so a malformed or merely differently-shaped id
+ *      silently matched the WRONG phase.
+ *   2. The grep was unanchored, so a commit that only MENTIONS a scope
+ *      (`docs(99-01): explain feat(03-01): commit convention`) was wrongly
+ *      selected as a DECLARATION of it.
+ *   3. Phase-mode's `\):` suffix and plan-mode's missing suffix disagreed on
+ *      the same commit (`feat(03-01)!: breaking change`).
+ *   4. The "obvious" fix — anchoring `git log --oneline`'s record start —
+ *      is a trap: it silently drops `fixup! ...` / `Revert "..."` wrapper
+ *      commits (a worse failure, a silent partial revert) and returns zero
+ *      matches under `color.ui=always` (ANSI codes precede the sha).
+ *
+ * This module closes all four by parsing each commit subject through the
+ * SAME anchored conventional-commit grammar the changelog/PR-title gate uses
+ * (`HEADER_RE`, reused verbatim from `scripts/release-notes/conventional-title.cjs`
+ * — see the require() below), then comparing the extracted scope to the
+ * caller-supplied target id by exact STRING EQUALITY. No regex is built from
+ * user input at any point past `validatePhaseNumber` (src/security.cts),
+ * which the CLI caller (`gsd-tools.cjs query select-revert-commits`) runs
+ * BEFORE this module ever sees the id.
+ *
+ * Deliberately no `fs`/`child_process` in this file: it operates purely on
+ * `{sha, subject}` records the caller already fetched (e.g. via `git log
+ * --format=%H%x00%s`), so it is unit-testable without touching git or the
+ * filesystem.
+ *
+ * KNOWN LIMIT (documented, not a defect): `unwrapSubject` unwraps ONE level
+ * of a `fixup! `/`squash! `/`Revert "..."` wrapper. A doubly-wrapped subject
+ * (e.g. `Revert "fixup! feat(03-01): work"`) is treated as unparseable (no
+ * declared scope) after that single unwrap — it is NOT selected, never
+ * mis-selected. This bounds the module to the wrapper shapes git itself
+ * produces (`fixup!`/`squash!` from `--fixup`/`--squash`, `Revert "..."` from
+ * `git revert`), each of which wraps a single ordinary commit subject, not
+ * another wrapper.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectCommitsByDeclaredScope = selectCommitsByDeclaredScope;
+const node_path_1 = __importDefault(require("node:path"));
+// Reuse the exact HEADER_RE the changelog classifier and PR-title CI gate
+// already depend on (#1549) — never fork a second copy of this grammar. A
+// bare `require()` (not a TS `import ... = require(...)`) is used
+// deliberately: `scripts/` sits outside this build's `rootDir` ("src", see
+// tsconfig.build.json) and carries no `.d.ts`, so a type-checked import-equals
+// would fail module resolution (TS7016) under `strict`/`noImplicitAny`. A
+// plain `require()` resolves through Node's ambient `NodeRequire` type
+// (`(id: string) => any`) instead, sidestepping that check entirely — the
+// cast below is the only place the resulting shape is asserted.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const conventionalTitle = require(node_path_1.default.resolve(__dirname, '..', '..', '..', 'scripts', 'release-notes', 'conventional-title.cjs'));
+const { HEADER_RE } = conventionalTitle;
+// ─── Subject unwrapping (Known limit: exactly ONE level) ──────────────────
+const FIXUP_PREFIX = 'fixup! ';
+const SQUASH_PREFIX = 'squash! ';
+const REVERT_RE = /^Revert "(.*)"$/;
+/**
+ * Strip exactly one `fixup! `/`squash! `/`Revert "..."` wrapper layer off a
+ * commit subject, returning the (possibly) unwrapped remainder. Never
+ * recurses — a doubly-wrapped subject is returned with only its outermost
+ * layer removed, which is intentionally still unparseable by `HEADER_RE` (see
+ * module doc comment).
+ */
+function unwrapSubject(subject) {
+    if (subject.startsWith(FIXUP_PREFIX))
+        return subject.slice(FIXUP_PREFIX.length);
+    if (subject.startsWith(SQUASH_PREFIX))
+        return subject.slice(SQUASH_PREFIX.length);
+    const revertMatch = REVERT_RE.exec(subject);
+    if (revertMatch)
+        return revertMatch[1];
+    return subject;
+}
+/**
+ * Parse a (possibly wrapped) commit subject into its declared conventional-
+ * commit scope, or `null` when the subject carries no parseable scope: no
+ * clean `type[(scope)][!]:` header at all, or a header with no `(scope)`
+ * group. Never regex-matches against untrusted `targetId` — this function
+ * only ever consumes the commit's OWN subject text.
+ */
+function parseDeclaredScope(subject) {
+    const unwrapped = unwrapSubject(subject);
+    const m = HEADER_RE.exec(unwrapped);
+    if (!m)
+        return null;
+    const scopeWithParens = m[2]; // e.g. "(03-01)" — includes parens, or undefined
+    if (!scopeWithParens)
+        return null;
+    // HEADER_RE's scope group is `\([^)]*\)` — always at least the two paren
+    // characters when present, so slicing them off is safe unconditionally.
+    return scopeWithParens.slice(1, -1);
+}
+/**
+ * Select commits whose DECLARED conventional-commit scope identifies
+ * `targetId`, by exact string equality (`'plan'` mode) or exact-or-phase-
+ * prefixed equality (`'phase'` mode). `targetId` is assumed ALREADY
+ * VALIDATED/NORMALIZED by the caller (e.g. via `validatePhaseNumber` from
+ * `src/security.cts`) — this function performs no validation of its own, and
+ * never builds a regex from it (string equality / `startsWith` only), so a
+ * malformed or metacharacter-laden `targetId` cannot cause a wildcard-style
+ * over-match the way the retired grep pipelines could.
+ */
+function selectCommitsByDeclaredScope(commits, targetId, mode = 'plan') {
+    const phasePrefix = `${targetId}-`;
+    const classified = commits.map(({ sha, subject }) => {
+        const parsedScope = parseDeclaredScope(subject);
+        let matched = false;
+        if (parsedScope !== null) {
+            matched = mode === 'phase'
+                ? parsedScope === targetId || parsedScope.startsWith(phasePrefix)
+                : parsedScope === targetId;
+        }
+        return { sha, subject, parsedScope, matched };
+    });
+    const selected = classified
+        .filter((c) => c.matched)
+        .map(({ sha, subject }) => ({ sha, subject }));
+    return { selected, classified };
+}