@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/quick-batch-command-router.cjs

@@ -35,9 +35,19 @@ const commandRoutingHub = require("./command-routing-hub.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
 const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const nodeFs = require("node:fs");
+// #5118: the writer set is owned by src/verification.cts.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verificationMod = require("./verification.cjs");
 const { output, ERROR_REASON } = io;
+const { VERIFIER_STATUSES } = verificationMod;
 const { makeInvalidArgs } = commandRoutingHub;
 const { routeHubCommandFamily } = cjsCommandRouterAdapter;
+/** Default stdin reader for `parse-args --stdin` (fd 0, UTF-8, whole stream). */
+function readProcessStdin() {
+    return nodeFs.readFileSync(0, 'utf8');
+}
 // ─── Small arg-parsing helpers (local — no new shared convention needed) ────
 /** `--flag value` lookup; undefined when the flag is absent. */
 function argValue(args, flag) {
@@ -57,7 +67,7 @@ function parseJsonArg(raw, label) {
     return { ok: true, value: parsed.value };
 }
 // ─── Implementation ───────────────────────────────────────────────────────────
-function routeQuickBatchCommand({ args, cwd, raw, error, _quickBatch, _quickBatchDispatch }) {
+function routeQuickBatchCommand({ args, cwd, raw, error, _quickBatch, _quickBatchDispatch, _readStdin }) {
     const qb = _quickBatch ?? quickBatch;
     const dispatch = _quickBatchDispatch ?? quickBatchDispatch;
     /** Forward a `Result<T>` from either module straight to output()/error(). */
@@ -211,7 +221,7 @@ function routeQuickBatchCommand({ args, cwd, raw, error, _quickBatch, _quickBatc
             // `quick-batch verification-routing --status <passed|gaps_found|human_needed>`
             'verification-routing': () => {
                 const status = argValue(args, '--status');
-                if (status !== 'passed' && status !== 'gaps_found' && status !== 'human_needed') {
+                if (typeof status !== 'string' || !VERIFIER_STATUSES.has(status)) {
                     return makeInvalidArgs('--status', 'Usage: gsd-tools quick-batch verification-routing --status <passed|gaps_found|human_needed>', ERROR_REASON.USAGE);
                 }
                 output(dispatch.routeVerificationOutcome(status), raw);
@@ -252,17 +262,33 @@ function routeQuickBatchCommand({ args, cwd, raw, error, _quickBatch, _quickBatc
                     planContent,
                 }), raw);
             },
-            // `quick-batch parse-args --text "<raw $ARGUMENTS string>"` (preferred —
-            // callers pass the ENTIRE, still-quoted $ARGUMENTS as ONE argv element;
-            // this handler does the whitespace split itself, in Node, so shell
-            // pathname expansion (globbing) on attacker-influenced task text never
-            // happens before this parser sees it — quoting `"$ARGUMENTS"` at the
-            // call site is what closes that off; splitting it here is what keeps
-            // the caller from having to word-split it unsafely beforehand).
+            // `quick-batch parse-args --stdin` (preferred, #4780 — the caller feeds
+            // the typed text through a QUOTED heredoc, so the shell never parses it:
+            // quotes, `$(...)`, backticks and newlines in attacker-influenced task
+            // text cannot break out of any shell position, because there is no
+            // shell position for the text to occupy).
+            // `quick-batch parse-args --text "<raw string>"` (still supported for a
+            // caller that already holds the text as ONE real argv element with no
+            // shell quoting involved, e.g. a test harness; it is NOT safe to build
+            // that argument by splicing user text into a shell command line).
+            // In both forms this handler does the whitespace split itself, in Node,
+            // so shell pathname expansion (globbing) never happens.
             // `quick-batch parse-args -- <already-tokenized args>` (legacy/direct
             // form — still supported for a caller that already has a real argv
             // array with no shell splitting involved, e.g. a test harness).
             'parse-args': () => {
+                if (args.includes('--stdin')) {
+                    let stdinText;
+                    try {
+                        stdinText = (_readStdin ?? readProcessStdin)();
+                    }
+                    catch (readError) {
+                        return makeInvalidArgs('--stdin', `could not read standard input: ${readError instanceof Error ? readError.message : String(readError)}`, ERROR_REASON.USAGE);
+                    }
+                    const stdinTokens = stdinText.trim().length === 0 ? [] : stdinText.trim().split(/\s+/);
+                    emit(dispatch.parseQuickBatchArgs(stdinTokens));
+                    return;
+                }
                 const textArg = argValue(args, '--text');
                 if (textArg !== undefined) {
                     const rawArgs = textArg.trim().length === 0 ? [] : textArg.trim().split(/\s+/);

package/gsd-core/bin/lib/quick-batch-dispatch.cjs

@@ -140,6 +140,16 @@ function computeSpawnPlan(input) {
     }
     return { spawn, pending };
 }
+/**
+ * #5118: one routing entry per writer-set status, keyed by the owner's type —
+ * no status literal is compared (local/no-verification-status-literal's
+ * type-aware arm), and `Record<VerifierStatus, …>` makes the table total.
+ */
+const VERIFICATION_OUTCOME_ROUTES = Object.freeze({
+    passed: { action: 'complete' },
+    human_needed: { action: 'human_needed' },
+    gaps_found: { action: 'fail', failureReason: 'verification reported gaps_found (no automatic gap-fix retry in v1)' },
+});
 /**
  * Route a verifier's status to an item action. `human_needed` is terminal
  * for the item — the caller must NOT call `completeQuickItem` (row 30, no
@@ -147,14 +157,7 @@ function computeSpawnPlan(input) {
  * WITHOUT an automatic gap-fix retry (row 31,34). `passed` completes it.
  */
 function routeVerificationOutcome(status) {
-    switch (status) {
-        case 'passed':
-            return { action: 'complete' };
-        case 'human_needed':
-            return { action: 'human_needed' };
-        case 'gaps_found':
-            return { action: 'fail', failureReason: 'verification reported gaps_found (no automatic gap-fix retry in v1)' };
-    }
+    return VERIFICATION_OUTCOME_ROUTES[status];
 }
 /**
  * Route a merge attempt's outcome to an item action. Both `merge_failed`

package/gsd-core/bin/lib/real-home-guard.cjs

@@ -105,6 +105,14 @@ const SANDBOX_MARKER = 'GSD_TEST_HOME_SANDBOX';
  * `statSync` follows symlinks and reports the inode itself, so a case-variant
  * HOME, a symlinked HOME, and a bind-mounted HOME all compare equal.
  *
+ * `identify` calls `fs.statSync(p, { bigint: true })`, not the plain numeric
+ * form. Node documents that the default numeric `dev`/`ino` lose precision past
+ * `Number.MAX_SAFE_INTEGER` (2^53), and NTFS/ReFS file IDs routinely exceed
+ * that — so on Windows two DISTINCT directories can round to the same numeric
+ * `ino` and compare equal here, which is a fail-OPEN in a module whose whole
+ * job is refusing writes into the real home. `{ bigint: true }` reports the
+ * true 64-bit values with no precision loss.
+ *
  * Fails CLOSED, and "closed" here means returning FALSE. The sole caller is the
  * passwd-less marker branch, which READS a true as permission to proceed:
  *
@@ -130,7 +138,7 @@ function sameDirectory(a, b) {
 }
 function identify(p) {
     try {
-        const st = node_fs_1.default.statSync(p);
+        const st = node_fs_1.default.statSync(p, { bigint: true });
         return { kind: 'ok', dev: st.dev, ino: st.ino };
     }
     catch (err) {

package/gsd-core/bin/lib/report-parser.cjs

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestStatus = exports.ReportFormat = void 0;
+exports.parseTestReport = parseTestReport;
+/** Format adapters for RED evidence. Parsing never depends on the runner command. */
+const tap_parser_cjs_1 = require("./vendor/tap-parser.cjs");
+const saxes_cjs_1 = require("./vendor/saxes.cjs");
+exports.ReportFormat = {
+    Tap: 'tap', Junit: 'junit', SwiftTesting: 'swift-testing', Unittest: 'unittest', Unknown: 'unknown',
+};
+exports.TestStatus = { Passed: 'passed', Failed: 'failed', Skipped: 'skipped', Todo: 'todo' };
+function parseTap(output) {
+    const report = { format: exports.ReportFormat.Tap, valid: true, tests: [], issues: [] };
+    const parser = new tap_parser_cjs_1.Parser({ strict: true });
+    const assertions = [];
+    const openBuffered = new Map();
+    let completed = false;
+    const watch = (p) => {
+        p.on('child', (child) => {
+            if (child.buffered)
+                openBuffered.set(p, (openBuffered.get(p) ?? 0) + 1);
+            watch(child);
+        });
+        // tap-parser finalizes buffered children at EOF even without their closing
+        // brace. Track its child/line events so that truncation cannot prove RED.
+        p.on('line', (line) => {
+            if (line === '}\n')
+                openBuffered.set(p, (openBuffered.get(p) ?? 0) - 1);
+        });
+        p.on('assert', (result) => {
+            if (!result.closingTestPoint)
+                assertions.push({ result, owner: p });
+            if (result.buffered && !result.closingTestPoint)
+                report.issues.push('Missing buffered TAP subtest');
+            const diag = result.diag;
+            if (diag && ['cancelledByParent', 'hookFailed', 'testTimeoutFailure'].includes(String(diag['failureType']))) {
+                report.issues.push('Test run interrupted by cancellation, hook failure, or timeout');
+            }
+        });
+        p.on('extra', (extra) => { if (extra.trim())
+            report.issues.push('Non-TAP data in report'); });
+        p.on('complete', (summary) => {
+            if (p === parser)
+                completed = true;
+            const { start, end } = summary.plan;
+            if (start !== 1 || end === null || summary.count !== end)
+                report.issues.push('Missing or incomplete TAP plan');
+            if (summary.bailout)
+                report.issues.push('TAP bailout');
+            if (summary.failures.some((failure) => failure.tapError))
+                report.issues.push('Malformed TAP');
+        });
+    };
+    watch(parser);
+    parser.end(output);
+    if ([...openBuffered.values()].some((count) => count !== 0))
+        report.issues.push('Unclosed buffered TAP subtest');
+    for (const { result, owner } of assertions) {
+        let skipped = Boolean(result.skip);
+        let todo = Boolean(result.todo);
+        for (let parent = owner; parent; parent = parent.parent) {
+            skipped ||= Boolean(parent.closingTestPoint?.skip);
+            todo ||= Boolean(parent.closingTestPoint?.todo);
+        }
+        report.tests.push({
+            name: result.name,
+            identities: [...new Set([result.name, result.fullname])],
+            group: null,
+            groupIdentities: [],
+            status: skipped ? exports.TestStatus.Skipped : todo ? exports.TestStatus.Todo : result.ok ? exports.TestStatus.Passed : exports.TestStatus.Failed,
+        });
+    }
+    if (!completed)
+        report.issues.push('Incomplete TAP stream');
+    report.valid = report.issues.length === 0;
+    return report;
+}
+/** Surefire and Failsafe share the JUnit XML report shape. */
+function parseJunit(output) {
+    const report = { format: exports.ReportFormat.Junit, valid: true, tests: [], issues: [] };
+    const parser = new saxes_cjs_1.SaxesParser({ xmlns: false });
+    const elements = [];
+    const suites = [];
+    let current = null;
+    parser.on('error', () => { report.issues.push('Malformed XML'); });
+    parser.on('doctype', () => { report.issues.push('JUnit reports must not declare a DTD'); });
+    parser.on('opentag', (tag) => {
+        const parent = elements.at(-1);
+        if (!parent && tag.name !== 'testsuite' && tag.name !== 'testsuites')
+            report.issues.push('Not a JUnit report');
+        if (tag.name === 'testsuite' || tag.name === 'testsuites') {
+            if (parent && parent !== 'testsuite' && parent !== 'testsuites')
+                report.issues.push('Misplaced test suite');
+            const count = tag.attributes['tests'];
+            const planned = count === undefined ? null : Number(count);
+            if (count !== undefined && (!/^\d+$/.test(count) || !Number.isSafeInteger(planned)))
+                report.issues.push('Invalid JUnit test count');
+            suites.push({ firstTest: report.tests.length, planned });
+        }
+        else if (tag.name === 'testcase') {
+            if (parent !== 'testsuite' || current)
+                report.issues.push('Misplaced test case');
+            const name = tag.attributes['name'] ?? '';
+            const className = tag.attributes['classname'] ?? '';
+            const qualified = className ? `${className}#${name}` : name;
+            if (!name)
+                report.issues.push('Unnamed test case');
+            current = {
+                name: qualified,
+                identities: [...new Set([name, qualified])],
+                group: className || null,
+                groupIdentities: className ? [className, className.split('.').at(-1)] : [],
+                status: exports.TestStatus.Passed,
+            };
+        }
+        else if (current && parent === 'testcase') {
+            if (tag.name === 'failure' || tag.name === 'error') {
+                if (current.status === exports.TestStatus.Skipped)
+                    report.issues.push('Contradictory JUnit status');
+                current.status = exports.TestStatus.Failed;
+            }
+            if (tag.name === 'skipped') {
+                if (current.status === exports.TestStatus.Failed)
+                    report.issues.push('Contradictory JUnit status');
+                current.status = exports.TestStatus.Skipped;
+            }
+        }
+        elements.push(tag.name);
+    });
+    parser.on('closetag', (tag) => {
+        if (tag.name === 'testcase' && current) {
+            report.tests.push(current);
+            current = null;
+        }
+        else if (tag.name === 'testsuite' || tag.name === 'testsuites') {
+            const suite = suites.pop();
+            if (!suite || (suite.planned !== null && suite.planned !== report.tests.length - suite.firstTest)) {
+                report.issues.push('Incomplete JUnit test suite');
+            }
+        }
+        elements.pop();
+    });
+    parser.write(output).close();
+    report.valid = report.issues.length === 0;
+    return report;
+}
+/**
+ * swift-testing console output (#4957). Only the anchored aggregate line marks
+ * the format; every declared test must have its own result line. The aggregate
+ * counts skipped tests too, and a parameterized test names its case count.
+ * A test is named by its quoted display name (with `(aka 'function()')` under
+ * --verbose) or, without one, by its bare function name. Windows consoles
+ * print √ × - in place of ✔ ✘ ━. swift-testing 6.1 omits the suite count from
+ * the aggregate and marks skipped tests with ✘ (later sources add the count
+ * and use ➜).
+ */
+const SWIFT_AGGREGATE = /^[ \t]*[✘✔━×√-][ \t]*Test run with (\d+) tests?(?: in \d+ suites?)? (passed|failed)\b/gm;
+const SWIFT_RESULT = /^[ \t]*[✘✔━➜×√-][ \t]*Test (?:"([^"]+)"(?: \(aka '([^']+)'\))?|([^\s"]\S*\)))(?: with \d+ test cases?)? (?:(failed|passed|was cancelled) after [\d.]+ seconds?(?: with \d+ [^\n]*?)?(?:\.|: "[^\n]*")|(skipped)(?:\.|: "[^\n]*"))$/gm;
+function parseSwiftTesting(output) {
+    const report = { format: exports.ReportFormat.SwiftTesting, valid: true, tests: [], issues: [] };
+    let declared = 0;
+    let runPassed = true;
+    for (const match of output.matchAll(SWIFT_AGGREGATE)) {
+        declared += Number(match[1]);
+        runPassed &&= match[2] === 'passed';
+    }
+    for (const match of output.matchAll(SWIFT_RESULT)) {
+        const fn = match[2] ?? match[3];
+        report.tests.push({
+            name: match[1] ?? match[3],
+            identities: [...new Set([match[1], fn, fn?.replace(/\(.*\)$/, '')].filter((id) => Boolean(id)))],
+            group: null,
+            groupIdentities: [],
+            status: match[4] === 'failed' ? exports.TestStatus.Failed : match[4] === 'passed' ? exports.TestStatus.Passed : exports.TestStatus.Skipped,
+        });
+    }
+    if (report.tests.length !== declared)
+        report.issues.push('Incomplete swift-testing report');
+    if (runPassed && report.tests.some((test) => test.status === exports.TestStatus.Failed)) {
+        report.issues.push('Contradictory swift-testing status');
+    }
+    report.valid = report.issues.length === 0;
+    return report;
+}
+/**
+ * Python stdlib unittest text output (#4970). Passing tests are unnamed unless
+ * verbose, so they are counted from the summary; failures are named by their
+ * FAIL:/ERROR: headers, which must account for every counted failure. Each
+ * failing subTest repeats its method's header and counts as a failure, while
+ * Ran counts methods, so identical headers collapse into one failed test. An
+ * unexpected success fails the run but is a test that passed.
+ */
+const UNITTEST_RAN = /^Ran (\d+) tests? in [\d.]+s$/gm;
+const UNITTEST_HEADER = /^(?:FAIL|ERROR): (\S+)(?: \(([^)]*)\))?/gm;
+function parseUnittest(output) {
+    const report = { format: exports.ReportFormat.Unittest, valid: true, tests: [], issues: [] };
+    const runs = [...output.matchAll(UNITTEST_RAN)];
+    if (runs.length !== 1) {
+        report.issues.push('Expected exactly one unittest summary');
+        report.valid = false;
+        return report;
+    }
+    const ran = Number(runs[0][1]);
+    const outcome = /^(OK|FAILED)(?: \(([^)]*)\))?$/m.exec(output.slice(runs[0].index + runs[0][0].length));
+    const counts = {};
+    for (const part of outcome?.[2]?.split(', ') ?? []) {
+        const [key, value] = part.split('=');
+        counts[key] = Number(value);
+    }
+    if (!outcome || Object.keys(counts).some((key) => !['failures', 'errors', 'skipped', 'expected failures', 'unexpected successes'].includes(key))) {
+        report.issues.push('Unsupported unittest outcome');
+    }
+    let headers = 0;
+    const failedIds = new Set();
+    for (const match of output.matchAll(UNITTEST_HEADER)) {
+        headers++;
+        const id = match[2] ?? '';
+        const key = `${match[1]} ${id}`;
+        if (failedIds.has(key))
+            continue;
+        failedIds.add(key);
+        // unittest synthesizes _FailedTest for an import/collection crash; its
+        // method name can equal the target, so it is a load failure, never RED.
+        if (id.includes('_FailedTest')) {
+            report.issues.push('unittest module failed to load');
+            continue;
+        }
+        report.tests.push({
+            name: match[1],
+            identities: [...new Set([match[1], id].filter(Boolean))],
+            group: null,
+            groupIdentities: [],
+            status: exports.TestStatus.Failed,
+        });
+    }
+    const failed = (counts['failures'] ?? 0) + (counts['errors'] ?? 0);
+    const skipped = counts['skipped'] ?? 0;
+    const runFailed = failed > 0 || (counts['unexpected successes'] ?? 0) > 0;
+    if (headers !== failed || (outcome?.[1] === 'FAILED') !== runFailed || failedIds.size + skipped > ran) {
+        report.issues.push('Incomplete unittest report');
+    }
+    const unnamed = (status) => ({ name: '', identities: [], group: null, groupIdentities: [], status });
+    for (let i = 0; i < skipped; i++)
+        report.tests.push(unnamed(exports.TestStatus.Skipped));
+    for (let i = Math.max(ran - failedIds.size - skipped, 0); i > 0; i--)
+        report.tests.push(unnamed(exports.TestStatus.Passed));
+    report.valid = report.issues.length === 0;
+    return report;
+}
+const adapters = [
+    { matches: (output) => /^(?:TAP version \d+|(?:not )?ok\b|1\.\.\d+|#)/.test(output.trimStart()), parse: parseTap },
+    { matches: (output) => output.trimStart().startsWith('<'), parse: parseJunit },
+    { matches: (output) => new RegExp(SWIFT_AGGREGATE.source, 'm').test(output), parse: parseSwiftTesting },
+    { matches: (output) => new RegExp(UNITTEST_RAN.source, 'm').test(output), parse: parseUnittest },
+];
+/** Parse supported reports into one result contract; unknown/malformed input fails closed. */
+function parseTestReport(output) {
+    const adapter = adapters.find((candidate) => candidate.matches(output));
+    if (!adapter)
+        return { format: exports.ReportFormat.Unknown, valid: false, tests: [], issues: ['Unsupported report format'] };
+    try {
+        const report = adapter.parse(output);
+        // One entry per problem: a long run of bad lines must not amplify the payload.
+        return { ...report, issues: [...new Set(report.issues)] };
+    }
+    catch {
+        return { format: exports.ReportFormat.Unknown, valid: false, tests: [], issues: ['Malformed report'] };
+    }
+}

package/gsd-core/bin/lib/review-lane-descriptor.cjs

@@ -64,7 +64,7 @@ exports.checkReviewerDocsParity = checkReviewerDocsParity;
  * `args` is an argv TEMPLATE, not a prefix. The injected pieces — model, effort, output file,
  * argv-borne prompt — do not all go in the same place, and no positional rule expresses that:
  * `codex` injects the model in the MIDDLE (after the `exec --ephemeral` subcommand) and the output
- * file later still, while `gemini` injects the model first and five lanes end with a bare `-` that
+ * file later still, while `kimi-code` injects the model first and five lanes end with a bare `-` that
  * must stay last. Splicing by position silently produced
  * `codex --model M -o F exec --ephemeral …`, which is not a valid codex invocation.
  *
@@ -94,36 +94,16 @@ const SPAWN_STDIN_STDOUT = {
     outputChannel: 'stdout',
 };
 /**
- * The twelve declared lanes, in `write_reviews` order.
+ * The eleven declared lanes, in `write_reviews` order.
+ *
+ * The `gemini` lane was retired by #4709: Google sunset Gemini CLI on 2026-06-18 (the same
+ * sunset that removed the gemini RUNTIME in #1928/1.8.0), so the lane spawned a binary that no
+ * longer serves the free/Pro/Ultra tiers that are GSD's audience.
  *
  * `kimi-code` joined in Phase 5b (#2799, closes #2718) — ADR-2782's phase table lands it here
  * rather than in 5a precisely so it arrives together with the iteration that can invoke it.
  */
 exports.REVIEWER_LANES = Object.freeze([
-    {
-        slug: 'gemini',
-        flags: ['--gemini'],
-        transport: 'spawn',
-        probe: { kind: 'command-exists', binary: 'gemini' },
-        invoke: {
-            binary: 'gemini',
-            args: ['{{model}}', '-p', '-'],
-            ...SPAWN_STDIN_STDOUT,
-            modelArg: '-m',
-            effortChannel: 'none',
-        },
-        timeoutFloorMs: 900_000,
-        timeoutConfigKey: 'review.timeouts.gemini',
-        emptyOutput: 'stub-with-stderr',
-        reviewsSection: 'Gemini',
-        evidenceClass: 'source-grounded',
-        requiresBinaries: [],
-        promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.gemini',
-        modelConfigKey: 'review.models.gemini',
-        effortConfigKey: null,
-        defaultEffort: null,
-        handler: null,
-    },
     {
         // 1_200_000 rather than the 900_000 floor: headless Claude measured ~525 s
         // on a large plan set (review.md:304).
@@ -139,8 +119,8 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'argv',
             // #2483: without these the claude leg is the only reviewer that additionally inherits the
             // invoking user's global CLAUDE.md, the project CLAUDE.md, and Claude Code auto-memory —
-            // a context asymmetry against the independent-review premise (gemini sees only the
-            // assembled prompt; codex runs --ephemeral). Both flags, not just the first: CLAUDE.md
+            // a context asymmetry against the independent-review premise (codex sees only the
+            // assembled prompt and runs --ephemeral). Both flags, not just the first: CLAUDE.md
             // loading and auto-memory are independently-toggled mechanisms, and an environment
             // exporting CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 forces auto-memory back ON — the explicit
             // pair is robust against that. Applies when /gsd:review runs from a non-Claude-Code host;
@@ -796,7 +776,7 @@ const NON_LANE_SIGNATURE_FLAGS = new Set(['--all']);
 /**
  * Is `flag` documented in `text` under one of the two structural shapes docs actually use?
  *
- * Backticked is the `COMMANDS.md` table-cell shape; bracketed (`[--gemini]`) is the
+ * Backticked is the `COMMANDS.md` table-cell shape; bracketed (`[--codex]`) is the
  * `FEATURES.md` signature shape. Requiring one of those two delimiters — rather than a bare
  * substring — is what keeps prose and fenced examples from satisfying the gate, and it bounds the
  * token for free: a backticked `--claude` demands its closing backtick, so a backticked
@@ -889,7 +869,7 @@ const BRACKETED_FLAG_RE = /\[(--[a-z0-9][a-z0-9-]*)\]/g;
  * cell 3. A file-scoped check is therefore satisfied by the forwarding row alone, so deleting a
  * lane's actual table row — the exact #2781 regression — passes. Keying on cell 1 separates the
  * two: `| `--agy` / `--antigravity` | … |` is one lane row declaring two flags, while
- * `| Reviewer flags | No | … `--gemini`, `--claude` … |` is not a lane row at all.
+ * `| Reviewer flags | No | … `--codex`, `--claude` … |` is not a lane row at all.
  */
 function flagsInFirstTableCell(lines, declared) {
     const found = new Set();

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -20,7 +20,7 @@
  * `reviewer` bodies in the capability registry, not a hand-maintained tail.
  * A capability of EITHER `role: "runtime"` (the six dual-purpose hosts —
  * antigravity/claude/codex/cursor/opencode/qwen) or the lane-only
- * `role: "reviewer"` (gemini/coderabbit/ollama/lm_studio/llama_cpp) may carry
+ * `role: "reviewer"` (coderabbit/ollama/lm_studio/llama_cpp) may carry
  * a `reviewer` body, and it is the body's `reviewer.slug` — NOT the capability
  * id — that becomes the roster entry: the two differ for `lm-studio` (id) /
  * `lm_studio` (slug) and `llama-cpp` (id) / `llama_cpp` (slug), ADR-2782's
@@ -229,7 +229,7 @@ function resolveReviewerSelection(input) {
         // ADR-2782 D4: absent-safe governs DISCOVERY, never explicit selection.
         // Not finding a lane nobody asked for is normal; failing to run a lane
         // somebody asked for is an error. Every miss used to be an `info`, so a
-        // PARTIAL miss (`--gemini --qwen` with qwen absent) ran the review with a
+        // PARTIAL miss (`--codex --qwen` with qwen absent) ran the review with a
         // thinner reviewer set while present_results reported success — "a cross-AI
         // review that silently drops a lane is blind in one eye" (review.md).
         // A total miss already errored, but only as a side effect of the selected

package/gsd-core/bin/lib/roadmap-command-router.cjs

@@ -13,12 +13,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const command_aliases_cjs_1 = require("./command-aliases.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
 const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapUpgrade = require("./roadmap-upgrade.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdCardMod = require("./phase-id-card.cjs");
+const { phaseIdCard } = phaseIdCardMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -142,14 +146,13 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                 if (roadmapContent.trim() === '') {
                     warnings.push({ code: 'V002', message: 'ROADMAP.md is empty' });
                 }
-                // Malformed frontmatter — a `---` opener with no matching closer.
-                // Tolerate a leading BOM (#3057) before the fence.
-                const contentAfterBom = roadmapContent.replace(/^\uFEFF/, '');
-                if (contentAfterBom.startsWith('---')) {
-                    const closeMatch = contentAfterBom.slice(3).match(/\r?\n---\s*(\r?\n|$)/);
-                    if (!closeMatch) {
-                        warnings.push({ code: 'V003', message: 'ROADMAP.md frontmatter is malformed (unterminated --- fence)' });
-                    }
+                // Malformed frontmatter — a `---` opener with no matching closer, as the one fence
+                // owner reads it (a leading BOM, #3057, is tolerated there).
+                const roadmapFence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(roadmapContent);
+                // The milestone-window read below sees the document without its leading BOM (#3057).
+                const contentAfterBom = roadmapContent.charCodeAt(0) === 0xFEFF ? roadmapContent.slice(1) : roadmapContent;
+                if (roadmapFence && !roadmapFence.closed) {
+                    warnings.push({ code: 'V003', message: 'ROADMAP.md frontmatter is malformed (unterminated --- fence)' });
                 }
                 // #3641: resolve phase_id_convention ONCE, ahead of every consumer in
                 // this validate pass — V004's entry check and V005's scope classifier
@@ -166,13 +169,11 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                     convention = undefined;
                 }
                 if (convention === undefined || convention === null) {
-                    // Fallback: read from ROADMAP.md frontmatter. Bounded to match
-                    // cmdRoadmapMilestoneScope's copy exactly (#3641 review NEW-1: an
-                    // unbounded capture here read past 4KB frontmatters the probe's
-                    // bounded copy could not, diverging validate from the probe).
-                    const fmMatch = roadmapContent.match(/^---\r?\n([\s\S]{0,4000}?)\r?\n---/);
-                    if (fmMatch) {
-                        const kvMatch = fmMatch[1].match(/^phase_id_convention:\s*(.*)$/m);
+                    // Fallback: read from ROADMAP.md frontmatter — the block the one fence owner finds,
+                    // exactly as cmdRoadmapMilestoneScope reads it (#3641 review NEW-1: two copies of
+                    // this read disagreed on long frontmatter, diverging validate from the probe).
+                    if (roadmapFence?.closed) {
+                        const kvMatch = roadmapContent.slice(roadmapFence.openEnd, roadmapFence.bodyEnd).match(/^phase_id_convention:\s*(.*)$/m);
                         if (kvMatch) {
                             const val = kvMatch[1].trim();
                             if (val !== 'null' && val !== '') {
@@ -234,7 +235,7 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
             'upgrade': () => {
                 const dryRun = !args.includes('--apply');
                 // Parse `--convention <value>` and `--convention=<value>`. When the flag is
-                // absent entirely, default to the only supported convention; when present
+                // absent entirely, default to the legacy supported convention; when present
                 // with a missing/unsupported value, fall through to the rejection below
                 // (fail-closed — never silently run a migration the user did not request).
                 let convention = 'milestone-prefixed';
@@ -245,13 +246,18 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                         ? token.slice(token.indexOf('=') + 1)
                         : (args[conventionFlagIdx + 1] ?? '');
                 }
-                if (convention !== 'milestone-prefixed') {
+                if (convention !== 'milestone-prefixed' && convention !== 'bracket') {
                     // No-throw hub contract (ADR-0012): a hub-dispatched handler must not call
                     // process.exit. Throw instead — the hub converts this to HandlerFailure and
                     // the adapter routes it through the injected error() boundary.
-                    throw new Error('Only --convention milestone-prefixed is supported');
+                    throw new Error('Only --convention milestone-prefixed or bracket is supported');
+                }
+                if (convention === 'bracket') {
+                    // Keep stdout machine-readable for the dry-run JSON plan. The card is
+                    // human guidance emitted at command start for both dry-run and apply.
+                    process.stderr.write(`${phaseIdCard({ title: 'Bracket phase-ID convention' })}\n`);
                 }
-                const plan = roadmapUpgrade.computeMigrationPlan(cwd);
+                const plan = roadmapUpgrade.computeMigrationPlan(cwd, { convention });
                 roadmapUpgrade.applyMigration(cwd, plan, { dryRun });
             },
         },