@opengsd/gsd-core 1.11.0 → 1.13.0

package/scripts/lint-phase-id-drift.cjs

@@ -53,6 +53,35 @@ const TOKEN_DRIFT_RE = /(?:\\{1,2}d|\[0-9\])\+\[A-Z(?:a-z)?\]\??\(\?:(?:\\{1,2}\
 const OWNER_RE = /^\s*\/\/.*phase-id-owner:/;
 const CANON_REF = 'PHASE_NUMBER_TOKEN_SOURCE';
 
+// #2761 M3 (trek-e review): the SECOND grammar this seam owns — the BRACKET
+// project-code class of `[CODE.MM]`, spelled `[A-Z][A-Z0-9_]*` (with its
+// case-widened `[A-Za-z]`/`[A-Za-z0-9_]` variant tolerated so a trivial rewrite
+// does not evade the rule). The token guard above only ever knew the phase-
+// NUMBER grammar, so three files re-typed this class verbatim — roadmap-parser's
+// bracket-fallback selector, state's `isMilestoneBounded`, verify's
+// `checkBracketCoherence` — and `check:phase-id-drift` reported clean the whole
+// time. That is the blind spot which let #2761's own "no token literal outside
+// src/phase-id.cts" gate pass while being violated. Build from
+// `BRACKET_PROJECT_CODE_SRC`, `BRACKET_ID_SRC`, `bracketMilestoneIntroSrcFor`
+// or `BRACKET_MILESTONE_INTRO_CAPTURING_SRC` instead.
+const BRACKET_CODE_DRIFT_RE = /\[A-Z(?:a-z)?\]\[A-Z(?:a-z)?0-9_\]\*/;
+
+// This rule has NO counterpart to the token rule's `line.includes(CANON_REF)`
+// escape, and that omission is the point.
+//
+// That escape is LINE-level: a line naming the canonical source anywhere on it
+// is taken as built-from-the-owner. verify.cts's copy read
+//
+//   new RegExp(`^\\[[A-Z][A-Z0-9_]*\\.(${BRACKET_MILESTONE_NUMERIC_SRC})\\]`, 'i')
+//
+// — an owner reference for the MILESTONE field sharing a line with a re-typed
+// PROJECT-CODE class. A line-level escape waves that through, so a bracket rule
+// that copied it would have kept reporting clean on the very site under review.
+// Partial ownership IS the drift. Only a `// phase-id-owner:` sanction
+// suppresses this rule, and a sanction has to state which half is deliberate.
+const BRACKET_OWNER_HINT =
+  'BRACKET_PROJECT_CODE_SRC / BRACKET_ID_SRC / bracketMilestoneIntroSrcFor / BRACKET_MILESTONE_INTRO_CAPTURING_SRC';
+
 /**
  * Pure: find every literal re-derivation of the canonical phase-number token in
  * `text` that is NOT sanctioned. A site is sanctioned when the nearest preceding
@@ -79,6 +108,28 @@ function findPhaseIdRegexDrift(text) {
   return out;
 }
 
+/**
+ * Pure: find every literal re-derivation of the BRACKET project-code grammar in
+ * `text` that is NOT sanctioned. Same sanction mechanism as the token rule — a
+ * dedicated `// phase-id-owner:` comment on the nearest preceding non-blank
+ * line — but deliberately WITHOUT its line-level owner-reference escape, so a
+ * site that references the owner for one field while re-typing the other is
+ * still reported (see BRACKET_CODE_DRIFT_RE's note). Returns [{ line, found }].
+ */
+function findBracketGrammarDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = BRACKET_CODE_DRIFT_RE.exec(lines[i]);
+    if (!m) continue;
+    let j = i - 1;
+    while (j >= 0 && lines[j].trim() === '') j--; // nearest preceding non-blank line
+    if (j >= 0 && OWNER_RE.test(lines[j])) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
 // Authored TypeScript source only (the generated bin/lib/*.cjs mirror it).
 const SCAN_DIRS = ['src'];
 const SCAN_EXT = new Set(['.cts', '.ts', '.mts']);
@@ -104,6 +155,67 @@ function walk(dir, acc) {
   return acc;
 }
 
+// ─── #2761 M4: the heading-baseline selector census ────────────────────────
+//
+// `phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.<MODE>)` is the other half
+// of this seam: it decides which intro grammar a call site compiles, and the
+// MODE argument is a fact about that site's history that no behavioural test
+// can recover — flipping verify's milestone-complete site from LABEL_ONLY to
+// ANY_BRACKET grants a tolerance it has never had, and every behavioural test
+// still passes. Pinning it therefore requires reading the authored source.
+//
+// That reading lives HERE, not in the test suite. `tests/**` runs
+// `local/no-source-grep` at ERROR, and its documented exemption
+// (CONTEXT.md: RULESET.TESTS.no-source-grep.exemption) is reserved for tests
+// whose subject is a runtime CONTRACT FILE — STATE.md, config.toml,
+// hooks.json, agent .md — which `src/*.cts` is not. The suite had claimed that
+// exemption anyway. Scripts are the sanctioned home for source scanning (the
+// rule runs at `warn` in `scripts/**`, and this file already scans src/ for the
+// grammar rules above), so the scan is exported as structured data and the test
+// asserts on the returned census instead of on file text.
+const SELECTOR_CALL_RE = /phaseHeadingPrefixSrcFor\(/g;
+const SELECTOR_BASELINE_RE = /phaseHeadingPrefixSrcFor\(\s*PHASE_HEADING_BASELINE\.(ANY_BRACKET|LABEL_ONLY)/g;
+
+/**
+ * Pure: census the heading-baseline selector calls in `text`.
+ *
+ * `total` counts EVERY invocation, so a call that does not name a
+ * `PHASE_HEADING_BASELINE` member shows up as `total > ANY_BRACKET +
+ * LABEL_ONLY` — a hole in the pin rather than a silently uncounted site.
+ * Returns { ANY_BRACKET, LABEL_ONLY, total }.
+ */
+function countSelectorBaselines(text) {
+  const out = { ANY_BRACKET: 0, LABEL_ONLY: 0, total: 0 };
+  for (const m of text.matchAll(SELECTOR_BASELINE_RE)) out[m[1]] += 1;
+  out.total = (text.match(SELECTOR_CALL_RE) || []).length;
+  return out;
+}
+
+/**
+ * Scan the authored source tree and return the selector census keyed by
+ * repo-relative path, for every file that consumes the selector at least once.
+ * `phase-id.cts` is excluded: it DEFINES the selector, so its own occurrences
+ * are the declaration, not a consumer's choice of baseline.
+ */
+function scanSelectorBaselines(root) {
+  const census = {};
+  for (const dir of SCAN_DIRS) {
+    for (const file of walk(path.join(root, dir), [])) {
+      const rel = path.relative(root, file);
+      if (EXEMPT.has(rel)) continue;
+      let text;
+      try {
+        text = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const counts = countSelectorBaselines(text);
+      if (counts.total > 0) census[path.basename(file)] = counts;
+    }
+  }
+  return census;
+}
+
 /**
  * Scan the authored source tree and return every unsanctioned phase-token
  * re-derivation, each annotated with the repo-relative file path.
@@ -121,7 +233,11 @@ function scanRepo(root) {
         continue;
       }
       for (const d of findPhaseIdRegexDrift(text)) {
-        violations.push({ file: rel, ...d });
+        violations.push({ file: rel, kind: 'token', ...d });
+      }
+      // #2761 M3: the bracket grammar is the second thing this seam owns.
+      for (const d of findBracketGrammarDrift(text)) {
+        violations.push({ file: rel, kind: 'bracket', ...d });
       }
     }
   }
@@ -132,19 +248,28 @@ function main() {
   const root = path.join(__dirname, '..');
   const violations = scanRepo(root);
   if (violations.length === 0) {
-    process.stdout.write('ok phase-id-drift: no unsanctioned phase-token re-derivations outside phase-id.cts\n');
+    process.stdout.write('ok phase-id-drift: no unsanctioned phase-token or bracket-grammar re-derivations outside phase-id.cts\n');
     return;
   }
-  process.stderr.write('phase-id-drift: literal re-derivation(s) of the canonical phase-number token found.\n');
-  process.stderr.write('Build the regex from phase-id.cjs `PHASE_NUMBER_TOKEN_SOURCE` (or phaseMarkdownRegexSource for a\n');
-  process.stderr.write('known number), or sanction the site with a dedicated `// phase-id-owner: <reason>`\n');
-  process.stderr.write('comment on the line directly above the regex:\n');
+  process.stderr.write('phase-id-drift: literal re-derivation(s) of a canonical grammar found.\n');
+  process.stderr.write(`Build the regex from phase-id.cjs \`${CANON_REF}\` (or phaseMarkdownRegexSource for a\n`);
+  process.stderr.write(`known number) for the phase-number token, or from ${BRACKET_OWNER_HINT}\n`);
+  process.stderr.write('for the bracket grammar — or sanction the site with a dedicated\n');
+  process.stderr.write('`// phase-id-owner: <reason>` comment on the line directly above the regex:\n');
   for (const d of violations) {
-    process.stderr.write(`  ${d.file}:${d.line}  ${d.found}\n`);
+    process.stderr.write(`  [${d.kind}] ${d.file}:${d.line}  ${d.found}\n`);
   }
   process.exitCode = 1;
 }
 
 if (require.main === module) main();
 
-module.exports = { findPhaseIdRegexDrift, scanRepo, TOKEN_DRIFT_RE };
+module.exports = {
+  findPhaseIdRegexDrift,
+  findBracketGrammarDrift,
+  scanRepo,
+  countSelectorBaselines,
+  scanSelectorBaselines,
+  TOKEN_DRIFT_RE,
+  BRACKET_CODE_DRIFT_RE,
+};

package/scripts/lint-planning-prompt-drift.cjs

@@ -370,8 +370,45 @@ function writeBaseline(root, violations) {
   return entries;
 }
 
+/**
+ * Resolve the scan root for a CLI run. Default: this repo — exactly what
+ * `lint:ci` invokes. `--root <dir>` overrides it (#3640) so the CLI
+ * end-to-end test can prove the guard's FAIL path against an isolated temp
+ * tree instead of writing its fixture into the shared `gsd-core/workflows/`
+ * that parallel test chunks observe mid-lifecycle (the emitted-provenance
+ * manifest build copies the transient file into all 19 runtime manifests;
+ * the #3333 TOCTOU ENOENT crash was the same writer's first symptom).
+ *
+ * Usage errors exit 2 — a code distinct from the guard's own findings exit
+ * (1), so tests and CI can tell "bad invocation" from "drift found" without
+ * parsing stderr. Fail-closed on every bad shape, because a wrong root is
+ * not harmless: `--root --update` would otherwise resolve the flag itself
+ * into a cwd-relative path and --update would happily `mkdir -p` a stray
+ * baseline tree inside the shared source directory (#3640's write class).
+ * A value that starts with `-` (another flag) or does not name an existing
+ * directory is therefore a usage error, never a scan root. With repeated
+ * `--root` flags the first wins (same first-match convention as the boolean
+ * `--update` parse).
+ */
+function resolveScanRoot() {
+  const rootIdx = process.argv.indexOf('--root');
+  if (rootIdx === -1) return path.join(__dirname, '..');
+  const value = process.argv[rootIdx + 1];
+  const isDir = value !== undefined
+    && !value.startsWith('-')
+    && fs.existsSync(value)
+    && fs.statSync(value).isDirectory();
+  if (!isDir) {
+    process.stderr.write('planning-prompt-drift: --root requires an existing directory argument (usage: --root <dir>)\n');
+    process.exitCode = 2;
+    return null;
+  }
+  return path.resolve(value);
+}
+
 function main() {
-  const root = path.join(__dirname, '..');
+  const root = resolveScanRoot();
+  if (root === null) return;
   const update = process.argv.includes('--update');
   const violations = scanRepo(root);
 

package/scripts/lint-portable-grep.cjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-portable-grep.cjs — ban GNU-only `grep -P`/`--perl-regexp` in gsd
+ * workflow / agent / reference / command markdown (#4112 macOS regression).
+ *
+ * ## Why
+ *
+ * `-P`/`--perl-regexp` selects GNU grep's PCRE engine. Stock macOS ships BSD
+ * grep, which does not implement `-P` at all — the call errors out ("grep:
+ * invalid option -- P" or "unknown option") on that host, and a pipeline like
+ * `... | grep -oP '...' || true` swallows that error and silently resolves to
+ * an empty string instead of failing loudly.
+ *
+ * This is exactly what happened in `gsd-core/workflows/pause-work.md`'s
+ * Context Detection step (#4112, merged as #4140): the fix for the `$((`
+ * shell-syntax bug left `grep -oP 'phases/\K[^/]+'` in place. That construct
+ * had never been exercised on macOS before (the syntax error masked it), so
+ * fixing the syntax bug newly exposed a second, pre-existing macOS-only
+ * defect — phase/spike/sketch detection silently resolving to "" on macOS —
+ * which the PR's own new regression test then caught, but only in the
+ * post-merge `full test (macos-latest, ...)` matrix. That lane runs on push
+ * to the base branch, not on the pull_request event, so nothing pre-merge
+ * (gsd-test's Linux-only benches included) could have caught it before `next`
+ * went red.
+ *
+ * This is the same class of defect `lint-portable-timeout.cjs` (#2351) exists
+ * for: a GNU-coreutils assumption baked into workflow markdown that every
+ * pre-merge gate is blind to because none of them run on macOS. The fix here
+ * is the same shape — a static ratchet that catches the assumption in the
+ * markdown itself, before a shell ever executes it on the platform that lacks
+ * the flag.
+ *
+ * ## What PASSES
+ *
+ * - `grep -o '...'`, `grep -E '...'`, `egrep`/`fgrep` without `-P`.
+ * - `-P` appearing as part of an unrelated long option (`--path`, `--perl`) —
+ *   only a `-P`/short-cluster-containing-`P` token or the literal
+ *   `--perl-regexp` counts.
+ * - Prose that merely mentions "grep -P" outside of a fenced command context
+ *   is still flagged (this lint does not parse fences) — the roots below are
+ *   restricted to directive markdown where a `grep -P` mention is always
+ *   either a real invocation or a specimen to fix, never neutral prose.
+ *
+ * ## What FAILS
+ *
+ * A `grep`/`egrep`/`fgrep` invocation whose flag cluster includes `P`
+ * (`-P`, `-oP`, `-Po`, `-iP`, ...) or the long form `--perl-regexp`.
+ *
+ * ## Portable replacements
+ *
+ * - Extracting a path component: `basename "$(dirname "$path")")` instead of
+ *   `grep -oP 'seam/\K[^/]+'`.
+ * - Extracting a token after a flag: `sed -E 's#.*--flag[[:space:]]+([^[:space:]]+).*#\1#'`
+ *   instead of `grep -oP '(?<=--flag )\S+'` — POSIX ERE (`-E`) has no
+ *   lookbehind, so capture the group and let `sed` emit just it. `-E` (not
+ *   GNU-only `-r`) is supported by both BSD and GNU `sed`. (A `/`-delimited
+ *   sed command ending in a star-quantifier would place a star immediately
+ *   before a slash, closing this very JSDoc block comment early — hence the
+ *   `#`-delimited form used above.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+
+// Surfaces whose markdown carries agent-executed bash. Mirrors
+// lint-portable-timeout.cjs's roots — the same files that can ship shell
+// snippets which a bash/zsh host on macOS actually executes.
+const DEFAULT_ROOTS = ['gsd-core/workflows', 'gsd-core/references', 'agents', 'commands'];
+
+// A `grep`/`egrep`/`fgrep` token, anchored to a command position (line start,
+// right after `| & ; ( \` {`, or right after a shell keyword that opens a new
+// command — `then`/`do`/`else`/`elif`) so prose mentioning "grep -P" in
+// running text is still caught in these directive-markdown roots (see file
+// header) without also matching an unrelated word ending in "grep". The
+// keyword alternative is `\b`-bounded on both sides, so a bare mention of the
+// word "then"/"do"/etc. with no following grep never matches on its own.
+const GREP_INVOCATION_RE = /(?:^|[|&;(`{]|\b(?:then|do|else|elif)\b)[ \t]*(?:e|f)?grep\b/g;
+
+// A `-P` short-flag cluster (e.g. `-P`, `-oP`, `-Po`, `-iP`) or the long form
+// `--perl-regexp`, as a standalone token.
+const PERL_FLAG_RE = /(?:^|\s)-[a-zA-Z]*P[a-zA-Z]*(?=\s|$)|--perl-regexp\b/;
+
+/**
+ * Locate `grep -P`/`--perl-regexp` invocations in a block of text.
+ *
+ * Pure (no I/O): callers pass file contents; the caller reads files. For each
+ * `grep`-family invocation on a line, inspects only the segment from that
+ * invocation to the next `|`/`;`/end-of-line, so a `-P`-bearing token in a
+ * later, unrelated command on the same line is never mistaken for a grep flag.
+ *
+ * @param {string} text  file contents
+ * @returns {{ line: number, snippet: string }[]}  findings (empty array = clean)
+ */
+function findPerlGrepInvocations(text) {
+  const findings = [];
+  const lines = String(text).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    GREP_INVOCATION_RE.lastIndex = 0;
+    let match;
+    while ((match = GREP_INVOCATION_RE.exec(line)) !== null) {
+      const startAt = match.index + match[0].length;
+      const rest = line.slice(startAt);
+      const nextPipe = rest.search(/[|;`]/);
+      const segment = nextPipe === -1 ? rest : rest.slice(0, nextPipe);
+      if (PERL_FLAG_RE.test(segment)) {
+        findings.push({ line: i + 1, snippet: line.trim() });
+        break; // one finding per line is enough context to fix it
+      }
+    }
+  }
+  return findings;
+}
+
+function walkMarkdown(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // a missing root is not an error — some surfaces are optional
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Scan the given roots (repo-relative) for `grep -P`/`--perl-regexp` invocations.
+ * @param {string[]} roots
+ * @returns {{ file: string, line: number, snippet: string }[]}
+ */
+function scan(roots = DEFAULT_ROOTS) {
+  const offenders = [];
+  for (const rel of roots) {
+    const abs = path.isAbsolute(rel) ? rel : path.join(ROOT, rel);
+    for (const file of walkMarkdown(abs)) {
+      const findings = findPerlGrepInvocations(fs.readFileSync(file, 'utf8'));
+      for (const f of findings) {
+        offenders.push({ file: path.relative(ROOT, file), line: f.line, snippet: f.snippet });
+      }
+    }
+  }
+  return offenders;
+}
+
+function main() {
+  const rootsEnv = process.env.GSD_LINT_PORTABLE_GREP_ROOTS;
+  const roots = rootsEnv ? rootsEnv.split(path.delimiter).filter(Boolean) : DEFAULT_ROOTS;
+  const offenders = scan(roots);
+  if (offenders.length > 0) {
+    const detail = offenders.map((o) => `  ${o.file}:${o.line}  ${o.snippet}`).join('\n');
+    throw new ExitError(
+      1,
+      'lint-portable-grep: `grep -P`/`--perl-regexp` is not portable — stock macOS ships\n' +
+        'BSD grep, which has no `-P`, so the call errors and a `|| true`/`$(...)` fallback\n' +
+        'silently resolves to empty output instead of failing loudly (#4112). Use\n' +
+        '`basename "$(dirname "$path")")` for path-component extraction, or\n' +
+        '`sed -E \'s/.../\\1/\'` (POSIX ERE, no lookbehind needed) for token extraction:\n' +
+        detail,
+    );
+  }
+  console.log(`ok lint-portable-grep: no GNU-only grep -P invocations in ${roots.length} root(s)`);
+}
+
+module.exports = { findPerlGrepInvocations, scan, DEFAULT_ROOTS };
+
+if (require.main === module) runMain(main);