@opengsd/gsd-core 1.8.0 → 1.9.0

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,6 +37,7 @@ 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, PHASE_CONTINUATION_SEGMENT_SOURCE, } = phaseIdMod;
@@ -137,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

@@ -41,6 +41,7 @@ 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;
@@ -61,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: {
@@ -77,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',
@@ -89,16 +101,30 @@ 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, '/');
@@ -177,12 +203,12 @@ function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_comma
  * 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, phaseCleanCommitTimesMs = defaultPhaseCleanCommitTimesMs) {
@@ -241,14 +267,25 @@ function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default, phas
  *
  * @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 {
@@ -261,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.
@@ -269,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.
@@ -282,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.
@@ -291,7 +328,7 @@ 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, phaseCleanCommitTimesMs);
@@ -300,7 +337,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
         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
@@ -314,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
@@ -322,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),
     };
 }
 /**
@@ -339,7 +376,7 @@ 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 = {