@opengsd/gsd-core 1.7.0 → 1.9.0

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

@@ -66,8 +66,8 @@ function classifyElement(text) {
  */
 exports.UI_TAXONOMY = [
     { id: 'empty', name: 'Empty / no data', elements: ['form', 'list-collection', 'media'], consideration: 'What is shown when there is no data — zero items, an unfilled form, or absent media?' },
-    { id: 'loading', name: 'Loading / in-flight', elements: ['form', 'list-collection', 'media', 'nav'], consideration: 'What is shown while data or content is still loading (skeleton, spinner, progressive reveal)?' },
-    { id: 'error', name: 'Error / failure', elements: ['form', 'list-collection', 'media', 'nav'], consideration: 'What is shown when the load or submit fails (message, retry affordance, partial fallback)?' },
+    { id: 'loading', name: 'Loading / in-flight', elements: ['form', 'list-collection', 'media', 'nav', 'interactive-control'], consideration: 'What is shown while data or content is still loading (skeleton, spinner, progressive reveal)?' },
+    { id: 'error', name: 'Error / failure', elements: ['form', 'list-collection', 'media', 'nav', 'interactive-control'], consideration: 'What is shown when the load or submit fails (message, retry affordance, partial fallback)?' },
     { id: 'populated', name: 'Populated / happy path', elements: ['list-collection', 'media'], consideration: 'What does the normal populated (happy-path) state look like at a typical volume of content?' },
     { id: 'partial', name: 'Partial / incomplete', elements: ['form', 'list-collection'], consideration: 'What is shown for partial or incomplete data — some fields or rows present, others missing?' },
     { id: 'overflow', name: 'Overflow / truncation', elements: ['list-collection', 'nav', 'static-content'], consideration: 'What happens when content exceeds its container — scroll, clip, wrap, or truncate?' },

package/gsd-core/bin/lib/unusable-input.cjs

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Unusable Input Diagnostic — the out-of-band half of ADR-1411's
+ * "corrupt is not absent" amendment (epic #1879).
+ *
+ * ADR-1411 splits the amendment's mechanism in two. Where a read already returns a
+ * provenance envelope, the cause is named *in-band* — that is `ConfigResolution.reason`
+ * (#1880, shipped). Where a read returns a bare sentinel or a plausible default it cannot
+ * extend, the return value is preserved exactly and the cause is surfaced *out-of-band*,
+ * as a deduplicated diagnostic on stderr. This module owns that second mechanism.
+ *
+ * It exists as a shared seam rather than a pattern copied per site because four call sites
+ * across four modules need identical behaviour (#1882 frontmatter, #1881 roadmap-parser,
+ * #1883 planning-workspace/verify, #1884 planning lock). Four hand-rolled copies of one
+ * behaviour is `DEFECT.GENERATIVE-FIX` by construction; one seam with a frozen reason set
+ * is the documented cure.
+ *
+ * Two contracts this module must not break:
+ *
+ *  - **Unconditional.** ADR-1411 diverges deliberately from ADR-227's never-implemented
+ *    `GSD_DEBUG` opt-in: "an opt-in nobody sets is indistinguishable from the silence
+ *    #1879 is about". There is no config gate here, by design.
+ *  - **Never throws.** Callers are leaf readers that promised a total function. A failed
+ *    stderr write (closed stream, EPIPE) must not turn a silent degradation into a crash.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// ─── Reason vocabulary ────────────────────────────────────────────────────────
+/**
+ * Frozen so tests assert a typed surface instead of diagnostic prose
+ * (CONTRIBUTING.md — Prohibited: Raw Text Matching on Test Outputs).
+ *
+ * Adding a reason is three coordinated changes, matching the repo's `REASON`-enum
+ * convention: the entry here, the emitting call site, and the test that locks
+ * `Object.keys(UNUSABLE_REASON).sort()`. Each epic-#1879 phase adds only its own —
+ * pre-declaring the later phases' reasons would be speculative generality and would
+ * leave values no call site emits.
+ */
+const UNUSABLE_REASON = Object.freeze({
+    /**
+     * A file opened a `---` frontmatter fence at byte 0, carried at least one parseable
+     * key, and never closed the fence — a truncated or half-written file, NOT a file that
+     * legitimately has no frontmatter. (#1882)
+     */
+    FRONTMATTER_UNTERMINATED: 'frontmatter_unterminated',
+    /**
+     * A ROADMAP.md exists but could not be read (EACCES/EIO/…). Distinct from a project that
+     * simply has no ROADMAP yet: absence returns the same sentinel, silently. (#1881)
+     */
+    ROADMAP_UNREADABLE: 'roadmap_unreadable',
+});
+/** One human-readable clause per reason. Prose lives here, never in a test assertion. */
+const REASON_PROSE = Object.freeze({
+    [UNUSABLE_REASON.FRONTMATTER_UNTERMINATED]: 'frontmatter opens with "---" but never closes; metadata was NOT applied',
+    [UNUSABLE_REASON.ROADMAP_UNREADABLE]: 'ROADMAP.md exists but could not be read; phase and milestone lookups fell back to defaults',
+});
+// ─── Dedup state ──────────────────────────────────────────────────────────────
+/**
+ * Process-lifetime dedup set. Mirrors `config-loader.cjs`'s `_warnedUnknownConfigKeys`
+ * guard, which ADR-1411 names as the precedent to reuse.
+ */
+const _warnedUnusableInputs = new Set();
+/**
+ * Count of diagnostics actually WRITTEN, which is not the same as the size of the dedup set:
+ * one emission records every key the input could later be identified by, so set size counts
+ * identities while this counts events. Tests assert on this because the behavioural claim is
+ * "how many diagnostics did the operator see", not "how many keys are interned".
+ */
+let _unusableInputEmissions = 0;
+/**
+ * ASCII control characters (including NUL) are stripped from any path before it is used
+ * as a key component or written to a terminal. Two reasons, both real:
+ *
+ *  - the key separator is NUL, so a `sourcePath` containing NUL could otherwise forge a
+ *    collision with a different (path, reason) pair and suppress a genuine second failure;
+ *  - a path carrying ANSI escapes would be replayed verbatim into the operator's terminal.
+ */
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+/**
+ * Strip control characters. Deliberately does NOT normalize path separators.
+ *
+ * An earlier revision folded backslashes to `/` unconditionally, reasoning that `C:\a\b.md`
+ * and `C:/a/b.md` are one file and should not report twice. That is true on Windows, and
+ * false — destructively — everywhere else: `\` is a legal filename character on Linux and
+ * macOS, so `/repo/weird\name/PLAN.md` and `/repo/weird/name/PLAN.md` are two genuinely
+ * different files that collapsed to one key, and the second one's diagnostic was silently
+ * swallowed. ADR-1411 forbids exactly that ("keying too coarsely suppresses a genuine second
+ * failure in a different file"), and this repo targets Linux/macOS/Windows alike.
+ *
+ * The trade is now explicit and one-directional: two spellings of one Windows path may
+ * report twice (mild noise), but two distinct files can never silence each other (lost
+ * signal). Dropping a real diagnostic is the strictly worse failure.
+ */
+function sanitizeSource(source) {
+    return source.replace(CONTROL_CHARS, '');
+}
+/**
+ * Identify the offending input. A path is preferred because it is what an operator can act
+ * on. When the caller has only an in-memory string, fall back to a short content digest so
+ * that *different* bad inputs still produce *different* keys.
+ *
+ * The leading `p`/`d` tag is what keeps the two namespaces disjoint. Without it a caller
+ * whose file is literally named `<unnamed:8efa5269728e7271>` would key identically to a
+ * path-less caller whose content happens to hash to that digest — no brute force required,
+ * since the digest of any predictable content (a shared template, known boilerplate) can
+ * simply be computed and used as a filename to pre-seed suppression. Because control
+ * characters — including NUL — are stripped from `source`, a caller-supplied path can never
+ * contain the separator and so can never forge a key in the other namespace either.
+ *
+ * The digest is computed only on the emission path, which is rare, so it never costs
+ * anything on a healthy read.
+ */
+function sourceKey(source, content) {
+    if (typeof source === 'string' && source.trim() !== '') {
+        return `p\u0000${sanitizeSource(source)}`;
+    }
+    const digest = node_crypto_1.default.createHash('sha256').update(content ?? '').digest('hex').slice(0, 16);
+    return `d\u0000${digest}`;
+}
+/** Human-facing name for the offending input, derived from the same key. */
+function displaySource(key) {
+    return key.startsWith('p\u0000') ? key.slice(2) : `<unnamed:${key.slice(2)}>`;
+}
+/**
+ * Emit a deduplicated diagnostic naming an input that exists but cannot be used.
+ *
+ * The key is `<normalized source>\0<reason>`. ADR-1411 requires the resolved path AND the
+ * distinguishing cause — keying on the path alone would let a second, different fault on
+ * the same file go unreported; keying on the message prose would couple the guard to
+ * wording.
+ *
+ * @returns `true` when this call actually wrote a diagnostic, `false` when it was
+ * deduplicated. Returning the decision is what lets tests assert emission *counts* on a
+ * typed surface rather than scraping stderr.
+ */
+function warnUnusableInput({ reason, source, content }) {
+    // Defensive: an unknown reason must not emit a diagnostic with `undefined` in it.
+    const prose = Object.prototype.hasOwnProperty.call(REASON_PROSE, reason)
+        ? REASON_PROSE[reason]
+        : null;
+    if (prose === null)
+        return false;
+    // The guarantee, stated precisely, because it is not symmetric:
+    //
+    //   * a file reported BY NAME is reported at most once, and
+    //   * an anonymous re-parse of content already reported by name stays silent, and
+    //   * two DIFFERENT files always both report, even when their truncated bytes are identical.
+    //
+    // The asymmetry is the anonymous-FIRST ordering (a path-less parse, then a named parse of the
+    // same content), which emits twice. That is a deliberate limit, not an oversight. A path-less
+    // caller cannot identify its file, so suppressing the later named report would also suppress a
+    // genuine second failure in a DIFFERENT file whenever two files share byte-identical truncated
+    // content — the over-coarse keying ADR-1411 explicitly forbids. Between a duplicate line and a
+    // swallowed diagnostic the ADR ranks the swallow worse, so the duplicate is accepted; and the
+    // second line is the more useful of the two, because it carries the filename.
+    //
+    // Mechanically: check ONLY the key matching what this caller actually knows, but record every
+    // key the input could later be identified by.
+    const identity = sourceKey(source, content);
+    const keys = [`${identity}\u0000${reason}`];
+    if (typeof content === 'string' && identity.startsWith('p\u0000')) {
+        keys.push(`${sourceKey(undefined, content)}\u0000${reason}`);
+    }
+    if (_warnedUnusableInputs.has(keys[0]))
+        return false;
+    for (const k of keys)
+        _warnedUnusableInputs.add(k);
+    try {
+        process.stderr.write(`gsd: warning — ${displaySource(identity)}: ${prose}. (#1879)\n`);
+        // Counted only after a write that actually completed. Incrementing before the try counted
+        // attempts, so on a broken stderr the counter claimed a diagnostic had reached the operator
+        // when nothing had — a seam documented as "written" reporting something else.
+        _unusableInputEmissions += 1;
+    }
+    catch {
+        /* a closed or broken stderr must never escalate a degraded read into a crash */
+    }
+    return true;
+}
+// ─── Test seams ───────────────────────────────────────────────────────────────
+/**
+ * Clear the dedup state between cases.
+ *
+ * This exists because the set is process-global: without it, the second test to use a key
+ * silently observes the first test's suppression. #2674 is the cautionary precedent — a
+ * reset helper that cleared two of three sets was a silent no-op for the very suite that
+ * existed to test it, and the cases only passed because each happened to pick a key no
+ * other case reused.
+ */
+function _resetUnusableInputWarningsForTests() {
+    _warnedUnusableInputs.clear();
+    _unusableInputEmissions = 0;
+}
+/** Number of diagnostics written — the typed surface tests assert on instead of stderr prose. */
+function _unusableInputEmissionCountForTests() {
+    return _unusableInputEmissions;
+}
+/** Size of the dedup set (identities interned, not events). Retained for key-shape assertions. */
+function _unusableInputWarningCountForTests() {
+    return _warnedUnusableInputs.size;
+}
+/** Test seam: the sanitized form of a source, so control-char handling is asserted on a
+ * returned value instead of by scraping what reached stderr. */
+function _sanitizeSourceForTests(source) {
+    return sanitizeSource(source);
+}
+module.exports = {
+    UNUSABLE_REASON,
+    _sanitizeSourceForTests,
+    warnUnusableInput,
+    _resetUnusableInputWarningsForTests,
+    _unusableInputWarningCountForTests,
+    _unusableInputEmissionCountForTests,
+};

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

@@ -37,30 +37,35 @@ exports.canonicalPlanStem = canonicalPlanStem;
 exports.phaseVariants = phaseVariants;
 exports.buildRoadmapPhaseVariants = buildRoadmapPhaseVariants;
 exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
+exports.textEncodingError = textEncodingError;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, PHASE_CONTINUATION_SEGMENT_SOURCE, } = phaseIdMod;
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
 // Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
 // deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
 exports.phaseDirNameRe = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{2,}(?:-\\d+)*(?:\\.\\d+)*-[\\w-]+$`, 'i');
 // Extracts the full phase token from a directory name, including milestone-prefixed
 // multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
-// #2043: a *continuation* sub-phase segment must be zero-padded (≥2 digits), so a
+// #2043: a *continuation* sub-phase segment must be zero-padded, so a
 // single-digit slug word after a phase number (e.g. "46-6-rs-…", slug "6 Rs …") is
-// NOT absorbed — it captures "46", not "46-6". The first component stays "\d+"
+// NOT absorbed — it captures "46", not "46-6". #2232: the continuation width is
+// exactly 2 (PHASE_CONTINUATION_SEGMENT_SOURCE), so a ≥3-digit slug word (a year:
+// "14-2026-photos-…") is not absorbed either — it captures "14", not "14-2026".
+// The first component stays "\d+"
 // (with the "[A-Z]?" suffix) so single-digit letter-suffixed phase ids ("1A") and
 // milestone-prefixed single-digit sub-phases ("M1-2" → prefix "M1-" stripped, then
 // "2") still match. The trailing boundary "(?:-|$)" (was "(?:-[a-z]|$)") lets a slug
 // that starts with a digit terminate the token.
-exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-\\d{2,})*[A-Z]?(?:\\.\\d+)*)(?:-|$)`, 'i');
+exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Z]?(?:\\.\\d+)*)(?:-|$)`, 'i');
 exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
 function canonicalPlanStem(stem) {
-    // #2043: the plan component (after the phase number) must be zero-padded
-    // (≥2 digits), so a digit-leading slug word (e.g. "46-6-rs-…") is not mistaken
-    // for a "46-6" phase/plan pair.
-    const m = stem.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE}-\\d{2,})`, 'i'));
+    // #2043: the plan component (after the phase number) must be zero-padded,
+    // so a digit-leading slug word (e.g. "46-6-rs-…") is not mistaken
+    // for a "46-6" phase/plan pair. #2232: exactly 2 digits, so a year-leading
+    // slug ("14-2026-photos-…") is not mistaken for a "14-2026" pair either.
+    const m = stem.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE}-${PHASE_CONTINUATION_SEGMENT_SOURCE})`, 'i'));
     return m ? m[1] : stem;
 }
 // ── Issue #6: phase variant helpers (W006/W007) ──────────────────────────────
@@ -133,3 +138,34 @@ function buildNotStartedPhaseVariants(roadmapContent) {
     }
     return notStartedPhases;
 }
+/**
+ * Detect binary corruption (embedded NUL bytes) in a text artifact's bytes.
+ *
+ * #2701: the plan/summary/verification/state validators must FAIL LOUD on a
+ * NUL-corrupted file instead of reporting `valid: true`. A NUL byte is the
+ * unambiguous signal — UTF-8 text never contains 0x00 — and a file carrying one
+ * is binary-classified by `file(1)`, then silently OMITTED from recursive /
+ * binary-skipping search results (`rg -l`, `grep -rI`, exit 0), so the corruption
+ * reads downstream as "file absent" rather than "file corrupt." The error message
+ * names that consequence so the next investigator is not misdirected.
+ *
+ * This is a pure, opt-in check called explicitly by each validator at its own
+ * entry point. It is deliberately NOT placed inside the shared `platformReadSync`
+ * read primitive (which dozens of best-effort, tolerant reads flow through and
+ * which must not start hard-failing on encoding). It does NOT strip, sanitize, or
+ * repair the NUL bytes — corruption is a signal of an upstream authoring-tool bug
+ * and must stay visible.
+ *
+ * @param buf   the file bytes (Buffer or string; a string is searched char-wise)
+ * @param relPath  a path/label for the diagnostic message
+ * @returns an error string when NUL is found, or `null` when the bytes are clean text
+ */
+function textEncodingError(buf, relPath) {
+    const nul = typeof buf === 'string' ? buf.indexOf('\0') : buf.indexOf(0x00);
+    if (nul === -1)
+        return null;
+    return (`${relPath}: file contains NUL bytes (first at offset ${nul}). ` +
+        'Artifact files must be UTF-8 text. A NUL-corrupted file is binary-classified ' +
+        'and silently skipped by recursive / binary-skipping search tools (rg, grep -I), ' +
+        'so downstream verification reports its contents as missing rather than corrupt.');
+}

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

@@ -15,6 +15,17 @@
  * inside a fenced code block) is ignored — this is the exact failure mode that
  * issue #586 / PR #650 identified. The shared extractFrontmatter parser anchors
  * its regex at byte 0 of the document, which provides this guarantee.
+ *
+ * #2348 staleness signal: whether a *-VERIFICATION.md is stale (a summary newer
+ * than it) is decided from git commit time when a file is committed AND clean,
+ * and from filesystem mtime otherwise. mtimes are assigned at checkout time and
+ * are not preserved by `git clone` / `cp -R`, and any unrelated `touch` /
+ * reformat / editor-save re-stales a valid report — so a committed phase could
+ * read `passed` on one machine and `stale` on a fresh clone purely from checkout
+ * order. Git commit time is content-tied and clone-stable; mtime is retained
+ * only for uncommitted or working-tree-dirty files, where it is the true
+ * last-changed signal. Both are real wall-clock change times, so the comparison
+ * is sound even when one file uses each.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -29,6 +40,8 @@ const phaseId = require("./phase-id.cjs");
 const frontmatterMod = require("./frontmatter.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const scanPhasePlans = require("./plan-scan.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const { output, error } = io;
 const { extractPhaseToken } = phaseId;
 const { extractFrontmatter } = frontmatterMod;
@@ -49,6 +62,12 @@ const VERIFIER_STATUSES = ['passed', 'gaps_found', 'human_needed'];
  *
  * For 'gaps_found', next_command is built at call time in readVerificationStatus
  * by substituting the phase number — it is NOT stored as a function in the table.
+ *
+ * #2617: `next_command` here holds a BARE command name (`execute-phase`), never a
+ * prefixed one. Every return path projects it through `formatGsdSlash` with the
+ * caller's runtime, so Codex sees `$gsd-execute-phase` and slash-hyphen runtimes
+ * see `/gsd-execute-phase`. Storing a prefixed literal is what leaked the
+ * hard-coded (and deprecated) `/gsd:` colon form to every runtime.
  */
 const VERIFICATION_ROUTING_TABLE = {
     passed: {
@@ -65,7 +84,12 @@ const VERIFICATION_ROUTING_TABLE = {
     human_needed: {
         status: 'human_needed',
         next_action: "Human verification required. Complete the manual tests in the phase's *-UAT.md, then re-run the verify step until status is passed.",
-        next_command: '',
+        // #2617: was '' — next_action told the user to "re-run the verify step" but
+        // named no command, while init.cts's parallel projector emitted
+        // `verify-work <N>` for this same state. The two surfaces disagreed on
+        // whether a next command existed at all; init's answer was the useful one,
+        // and init now delegates here rather than re-deriving it.
+        next_command: 'verify-work',
     },
     stale: {
         status: 'stale',
@@ -77,30 +101,117 @@ const VERIFICATION_ROUTING_TABLE = {
     missing: {
         status: 'missing',
         next_action: 'No verification report found — the verify step never completed. Re-run execute-phase.',
-        next_command: '/gsd:execute-phase',
+        next_command: 'execute-phase',
     },
     // INTERNAL SENTINEL: constructed when the file has a status value not in
     // VERIFIER_STATUSES. Never emitted by the verifier.
     unknown: {
         status: 'unknown',
         next_action: '', // filled in dynamically with the raw value
-        next_command: '/gsd:execute-phase',
+        next_command: 'execute-phase',
     },
 };
+/**
+ * Project a BARE command name (plus optional argument tail) into the surface the
+ * given runtime actually installs (#2617).
+ *
+ * `formatGsdSlash` owns the per-runtime shape (`$gsd-<cmd>` for shell-var
+ * runtimes like Codex, `/gsd-<cmd>` otherwise) and is idempotent, so passing an
+ * already-prefixed string is safe. An empty command stays empty — "no next
+ * command" must not become a bare prefix.
+ */
+function projectNextCommand(bare, runtime, tail = '') {
+    if (!bare)
+        return '';
+    return `${(0, runtime_slash_cjs_1.formatGsdSlash)(bare, runtime)}${tail}`;
+}
+/** Normalize separators to posix (git emits `/`; callers may pass `\` on Windows). */
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Match a git-emitted (repo-root-relative) path back to the caller's
+ * phaseDir-relative request by exact match or `/`-bounded suffix — precise
+ * enough that a root file and a nested `plans/` file can never collide (a plain
+ * basename match could). Returns the original caller-form file string, or null.
+ */
+function matchRequestedFile(gitPath, requested, requestedPosix) {
+    const g = toPosix(gitPath);
+    for (let i = 0; i < requested.length; i++) {
+        const want = requestedPosix[i];
+        if (g === want || g.endsWith('/' + want))
+            return requested[i];
+    }
+    return null;
+}
+/**
+ * Parse `git log --format=%ct --name-only` output into file → most-recent commit
+ * time (ms). Output is reverse-chronological, so a file's FIRST appearance
+ * top-down is its latest commit. `%ct` headers are pure digits; path lines
+ * contain a `.` (the `.md` extension) — so the two are unambiguous.
+ */
+function parseCommitTimes(stdout, requested, requestedPosix) {
+    const out = new Map();
+    let currentCt = null;
+    for (const line of stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        if (/^\d+$/.test(line)) {
+            currentCt = Number.parseInt(line, 10);
+            continue;
+        }
+        if (currentCt === null)
+            continue;
+        const rel = matchRequestedFile(line, requested, requestedPosix);
+        if (rel !== null && !out.has(rel))
+            out.set(rel, currentCt * 1000);
+    }
+    return out;
+}
+function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_command_projection_cjs_1.execGit) {
+    if (files.length === 0)
+        return new Map();
+    const requestedPosix = files.map(toPosix);
+    const logRes = execGitFn(['log', '--first-parent', '--format=%ct', '--name-only', '--', ...files], {
+        cwd: phaseDir,
+    });
+    if (logRes.error || logRes.exitCode !== 0 || logRes.stdout.length === 0)
+        return new Map();
+    const commitTimes = parseCommitTimes(logRes.stdout, files, requestedPosix);
+    if (commitTimes.size === 0)
+        return commitTimes;
+    // Drop dirty files (working tree ≠ HEAD) so their mtime is used instead. If the
+    // dirty-check itself is INCONCLUSIVE (git diff errored / non-zero — as opposed
+    // to "ran and reported no dirty files"), we cannot prove any file is clean, so
+    // fail SAFE: discard the commit times and let every file fall back to mtime,
+    // the same direction as a git-log failure. Trusting possibly-stale commit times
+    // here would silently mask a real edit (false "not stale"). (#2348)
+    const diffRes = execGitFn(['diff', '--name-only', 'HEAD', '--', ...files], { cwd: phaseDir });
+    if (diffRes.error || diffRes.exitCode !== 0)
+        return new Map();
+    for (const line of diffRes.stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const rel = matchRequestedFile(line, files, requestedPosix);
+        if (rel !== null)
+            commitTimes.delete(rel);
+    }
+    return commitTimes;
+}
 /**
  * Build a 'missing' result from the routing table.
  * Used for two early-return paths: no *-VERIFICATION.md file found, and
  * file present but no parseable frontmatter status.
  */
-function missingResult() {
+function missingResult(runtime, phaseArg) {
     const route = VERIFICATION_ROUTING_TABLE['missing'];
     return {
         status: route.status,
         next_action: route.next_action,
-        next_command: route.next_command,
+        next_command: projectNextCommand(route.next_command, runtime, phaseArg),
     };
 }
-function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default) {
+function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default, phaseCleanCommitTimesMs = defaultPhaseCleanCommitTimesMs) {
     // FS errors (TOCTOU: a SUMMARY listed by scanPhasePlans then removed before statSync;
     // unreadable dir; broken symlink; file->dir swap) must degrade to "not stale" rather
     // than throw uncaught into callers that are NOT under the planning lock
@@ -112,23 +223,31 @@ function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default) {
         const verificationFile = phaseFiles.filter((f) => f.endsWith('-VERIFICATION.md')).sort()[0];
         if (!verificationFile)
             return null;
-        const verificationMtimeMs = fsImpl.statSync(node_path_1.default.join(phaseDir, verificationFile)).mtimeMs;
-        let newestStaleSummary = null;
-        const summaryFiles = scanPhasePlans(phaseDir).summaryFiles;
-        for (const summaryFile of summaryFiles.sort()) {
-            const summaryMtimeMs = fsImpl.statSync(node_path_1.default.join(phaseDir, summaryFile)).mtimeMs;
-            if (summaryMtimeMs <= verificationMtimeMs)
-                continue;
-            if (!newestStaleSummary || summaryMtimeMs > newestStaleSummary.mtimeMs) {
-                newestStaleSummary = { summaryFile, mtimeMs: summaryMtimeMs };
+        const summaryFiles = scanPhasePlans(phaseDir).summaryFiles
+            .slice()
+            .sort();
+        // No summary can be newer than the verification → never stale. Return before
+        // touching git so a phase with no summaries costs zero subprocesses. (#2348)
+        if (summaryFiles.length === 0)
+            return null;
+        // Each file's effective "last changed" time = its commit time when committed
+        // AND clean (content-tied and clone-stable), else its filesystem mtime (the
+        // uncommitted working-tree edit). Both are real wall-clock change times, so
+        // comparing a clean file's commit time against a dirty file's mtime is sound.
+        // One resolver call = two git subprocesses for the whole phase. (#2348)
+        const cleanCommitMs = phaseCleanCommitTimesMs(phaseDir, [verificationFile, ...summaryFiles]);
+        const effectiveTimeMs = (file) => cleanCommitMs.has(file)
+            ? cleanCommitMs.get(file)
+            : fsImpl.statSync(node_path_1.default.join(phaseDir, file)).mtimeMs;
+        const verificationTimeMs = effectiveTimeMs(verificationFile);
+        for (const summaryFile of summaryFiles) {
+            // The caller only needs whether the phase is stale, not which summary —
+            // the first stale summary (in sorted order) is enough. Short-circuit.
+            if (effectiveTimeMs(summaryFile) > verificationTimeMs) {
+                return { verificationFile, summaryFile };
             }
         }
-        if (!newestStaleSummary)
-            return null;
-        return {
-            verificationFile,
-            summaryFile: newestStaleSummary.summaryFile,
-        };
+        return null;
     }
     catch {
         return null;
@@ -148,13 +267,25 @@ function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default) {
  *
  * @param phaseDir - Absolute path to the phase directory.
  * @param opts     - Options. `opts.fs` allows test injection (defaults to node:fs).
+ *                   `opts.runtime` selects the command surface `next_command` is
+ *                   projected into (#2617).
  */
 function readVerificationStatus(phaseDir, opts = {}) {
     const fsImpl = opts.fs ?? node_fs_1.default;
+    const phaseCleanCommitTimesMs = opts.phaseCleanCommitTimesMs ?? defaultPhaseCleanCommitTimesMs;
+    const runtime = opts.runtime ?? 'claude';
     // Phase token for the gaps_found command
     const baseName = node_path_1.default.basename(phaseDir);
     const phaseToken = extractPhaseToken(baseName);
-    const phaseNumber = phaseToken.length > 0 ? phaseToken : baseName;
+    const derivedPhaseNumber = phaseToken.length > 0 ? phaseToken : baseName;
+    // #2617: the phase number becomes a COMMAND ARGUMENT, so it is appended only
+    // when it is unambiguously one. extractPhaseToken also returns project-code
+    // forms (`PROJ-07`), which are indistinguishable by shape from an ordinary
+    // directory name — `gsd-651-parent` yields `gsd-651` — and emitting
+    // `execute-phase gsd-651` is worse than emitting no argument at all. Callers
+    // that already know the number (init) pass it explicitly and always get it.
+    const phaseArgSource = opts.phaseNumber ?? (/^\d+(\.\d+)*$/.test(derivedPhaseNumber) ? derivedPhaseNumber : '');
+    const phaseArg = phaseArgSource ? ` ${phaseArgSource}` : '';
     // 1. Find *-VERIFICATION.md
     let verificationFile = null;
     try {
@@ -167,7 +298,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
         verificationFile = null;
     }
     if (!verificationFile) {
-        return missingResult();
+        return missingResult(runtime, phaseArg);
     }
     // 2. Read and parse frontmatter using the shared parser.
     // extractFrontmatter anchors at byte 0, so body `status:` lines are ignored.
@@ -175,7 +306,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
     let rawStatus = null;
     try {
         const content = fsImpl.readFileSync(filePath, 'utf-8');
-        const fm = extractFrontmatter(content);
+        const fm = extractFrontmatter(content, filePath);
         const statusVal = fm['status'];
         // status is always a scalar string in a well-formed VERIFICATION.md frontmatter;
         // only accept string values — arrays and objects are not valid status values.
@@ -188,7 +319,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
         rawStatus = null;
     }
     if (!rawStatus) {
-        return missingResult();
+        return missingResult(runtime, phaseArg);
     }
     // gaps_found takes priority over stale — gap closure is the correct next
     // step regardless of whether summaries are newer than the verification file.
@@ -197,16 +328,16 @@ function readVerificationStatus(phaseDir, opts = {}) {
         return {
             status: entry.status,
             next_action: entry.next_action,
-            next_command: `/gsd:plan-phase ${phaseNumber} --gaps`,
+            next_command: projectNextCommand('plan-phase', runtime, `${phaseArg} --gaps`),
         };
     }
-    const staleVerification = findStaleVerificationSummary(phaseDir, fsImpl);
+    const staleVerification = findStaleVerificationSummary(phaseDir, fsImpl, phaseCleanCommitTimesMs);
     if (staleVerification) {
         const entry = VERIFICATION_ROUTING_TABLE['stale'];
         return {
             status: entry.status,
             next_action: entry.next_action,
-            next_command: `/gsd:verify-work ${phaseNumber}`,
+            next_command: projectNextCommand('verify-work', runtime, phaseArg),
         };
     }
     // 3. Route — exclude internal sentinels from raw-file lookup (they are
@@ -220,7 +351,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
         return {
             status: entry.status,
             next_action: entry.next_action,
-            next_command: entry.next_command,
+            next_command: projectNextCommand(entry.next_command, runtime, phaseArg),
         };
     }
     // Unknown value
@@ -228,7 +359,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
     return {
         status: unknownRoute.status,
         next_action: `Unexpected verification status '${rawStatus}'. Re-run execute-phase verification.`,
-        next_command: unknownRoute.next_command,
+        next_command: projectNextCommand(unknownRoute.next_command, runtime, phaseArg),
     };
 }
 /**
@@ -245,12 +376,13 @@ function cmdVerificationStatus(cwd, phaseDirArg, raw) {
         return;
     }
     const phaseDir = node_path_1.default.resolve(cwd, phaseDirArg);
-    const result = readVerificationStatus(phaseDir);
+    const result = readVerificationStatus(phaseDir, { runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd) });
     output(result, raw);
 }
 module.exports = {
     VERIFIER_STATUSES,
     VERIFICATION_ROUTING_TABLE,
+    defaultPhaseCleanCommitTimesMs,
     findStaleVerificationSummary,
     readVerificationStatus,
     cmdVerificationStatus,