@opengsd/gsd-core 1.11.0 → 1.13.0

package/scripts/lint-test-file-count.allowlist.json

@@ -1,17 +1,47 @@
 {
   "_doc": "Baseline of modules currently exceeding the 2-test-file limit. Each entry locks in TODAY's exact test filenames as the allowlisted set (identity ratchet). Adding a NEW test file to a capped module fails (novel). Removing one requires pruning this list (stale, ratchet-down). When a cluster drops to \u2264 2, remove its entry entirely. New entries require justification in PR description.",
   "modules": {
+    "adr-parser": {
+      "files": [
+        "adr-parser.property.test.cjs",
+        "adr-parser.test.cjs",
+        "adr-parser.unit.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
     "config": {
       "files": [
         "config-defaults-runtime-exclusion.test.cjs",
         "config-field-docs.test.cjs",
         "config-get-default.test.cjs",
-        "config-schema.property.test.cjs",
+        "config-get-raw-guard.test.cjs",
         "config-validation.test.cjs",
         "config.test.cjs"
       ],
       "issue": "TBD"
     },
+    "context-predicates": {
+      "files": [
+        "context-predicates-query.test.cjs",
+        "context-predicates.property.test.cjs",
+        "context-predicates.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "frontmatter": {
+      "files": [
+        "frontmatter-cli.test.cjs",
+        "frontmatter-golden-parity.test.cjs",
+        "frontmatter-roundtrip.property.test.cjs",
+        "frontmatter.property.test.cjs",
+        "frontmatter.test.cjs",
+        "frontmatter.unit.test.cjs"
+      ],
+      "issue": "3881",
+      "justification": "Grandfathered by #3227 for the original 4-file cluster (pre-existing over-cap, not new sprawl). #3881 (ADR-3473 \u00a78.1, the js-yaml parser migration) adds two more: frontmatter-golden-parity.test.cjs (D-series golden-corpus diff against the legacy parser, ~900 real documents \u2014 cannot be folded into an existing file without losing its independent-of-current-parser provenance) and frontmatter-roundtrip.property.test.cjs (fast-check property coverage the migration's bijective-contract rule requires). Both are migration-specific, not incidental sprawl."
+    },
     "graphify": {
       "files": [
         "graphify-auto-update.slow.test.cjs",
@@ -51,6 +81,7 @@
         "phase-dependency-levels.test.cjs",
         "phase-resolution-parity.test.cjs",
         "phase-structure.test.cjs",
+        "phase-tdd-applicable.test.cjs",
         "phase.test.cjs"
       ],
       "issue": "3186"
@@ -99,6 +130,7 @@
     },
     "verify": {
       "files": [
+        "verify-archive-dirs-live-path.test.cjs",
         "verify-health.test.cjs",
         "verify-mvp-uat.test.cjs",
         "verify-npm-publish.test.cjs",
@@ -106,20 +138,22 @@
         "verify-work-auto-transition.test.cjs",
         "verify.test.cjs"
       ],
-      "issue": "3767"
+      "issue": "#3813 \u2014 the live-path #1883 suite drives buildPlanningSnapshot in-process with an fs fault; the verify module suites are CLI-driving and cannot host an fs monkeypatch",
+      "justification": "verify-command-grounding added by #2401/#3678; allowlist follow-up landed with #3606 (base was red on this lane)."
     },
     "install": {
       "files": [
         "install-minimal-hooks.test.cjs",
         "install-nested-layout.test.cjs",
         "install-path-detection.test.cjs",
+        "install-profile-workflow-spawns.test.cjs",
         "install-regressions.test.cjs",
         "install-runtime-artifacts.test.cjs",
         "install-update-marker.test.cjs",
         "install-write-confinement.test.cjs",
         "install.test.cjs"
       ],
-      "issue": "1679"
+      "issue": "#3798 \u2014 the profile-closure spawn test reads the real repo surface (commands+workflows+agents); consolidating it into install.test.cjs would put a whole-repo scan behind the suite's heaviest file"
     },
     "edge-probe": {
       "files": [
@@ -150,9 +184,95 @@
       "files": [
         "prompt-budget-cli.test.cjs",
         "prompt-budget-parity.test.cjs",
-        "prompt-budget.test.cjs"
+        "prompt-budget.property.test.cjs",
+        "prompt-budget.test.cjs",
+        "prompt-budget.unit.test.cjs"
       ],
       "issue": "2929"
+    },
+    "mcp-catalog": {
+      "files": [
+        "mcp-catalog-parity.install.test.cjs",
+        "mcp-catalog.property.test.cjs",
+        "mcp-catalog.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "model-catalog": {
+      "files": [
+        "model-catalog-runtime-defaults.test.cjs",
+        "model-catalog-valid-tiers.test.cjs",
+        "model-catalog.unit.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "package-legitimacy": {
+      "files": [
+        "package-legitimacy-gate.test.cjs",
+        "package-legitimacy.property.test.cjs",
+        "package-legitimacy.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "runtime-homes": {
+      "files": [
+        "runtime-homes-descriptor-drive.test.cjs",
+        "runtime-homes-legacy-ids-drift-guard.test.cjs",
+        "runtime-homes.property.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "section-manifest": {
+      "files": [
+        "section-manifest-init-facts.test.cjs",
+        "section-manifest.property.test.cjs",
+        "section-manifest.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "workflow-fragments": {
+      "files": [
+        "workflow-fragments-emission.install.test.cjs",
+        "workflow-fragments.property.test.cjs",
+        "workflow-fragments.test.cjs"
+      ],
+      "issue": "3227",
+      "justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
+    },
+    "docs": {
+      "files": [
+        "docs-hooks-table-parity.test.cjs",
+        "docs-parity-live-registry.test.cjs",
+        "docs-state-md-locale-parity.test.cjs",
+        "docs-update.test.cjs"
+      ],
+      "issue": "3873 | #3839 \u2014 the hook-event parity suite cross-checks the four docs hook tables against src/runtime-hooks-surface.cts registrations; a generated-docs concern distinct from content freshness and registry parity",
+      "justification": "ADR-3473 \u00a78.8 makes docs/reference/state-md.md and its four locale siblings generated-and-committed and adds the repo's first locale-parity check (verified: no locale-parity lint precedent exists here). That check is a distinct concern from docs-update (content freshness) and docs-parity-live-registry (registry parity); folding it into either would place an unrelated subject inside them purely to satisfy a count. The section it guards is absent from all four translations today and documents the status enum behind #3853."
+    },
+    "audit": {
+      "files": [
+        "audit-command-cutover.test.cjs",
+        "audit-fix-command.test.cjs",
+        "audit-milestone-filename-guard.test.cjs",
+        "audit-open-remainder-count.test.cjs",
+        "audit-uat-acknowledged.test.cjs",
+        "audit-uat-summary-segmentation.test.cjs",
+        "audit-workstream-layouts.test.cjs"
+      ],
+      "issue": "#3804/#3805 \u2014 audit-layout and acknowledged-marker suites drive the real audit-uat CLI against on-disk fixtures | #3817 \u2014 regression suite proving countReal counts the truncation remainder marker instead of treating it as one phantom item | #3783 \u2014 dedicated suite for the summary.current_milestone/archived segmentation, matching this module's one-file-per-feature-slice precedent (e.g. audit-uat-acknowledged.test.cjs) rather than growing the unrelated 6900+ line tests/uat.test.cjs (a different module, keyed off uat.cjs)"
+    },
+    "shell-command-projection": {
+      "files": [
+        "shell-command-projection-dispatch.test.cjs",
+        "shell-command-projection-md-normalize.test.cjs",
+        "shell-command-projection-path-sep.test.cjs"
+      ],
+      "issue": "#3854 \u2014 the tight-list suite pins the markdown write-normalizer's blank-line policy through the exported normalizeContent/platformWriteSync seam; a distinct concern from dispatch routing and path separation"
     }
   }
 }

package/scripts/lint-test-file-count.cjs

@@ -74,7 +74,16 @@ function prodPrefix(filename) {
 function testEffectivePrefix(testName) {
   const bare = testName
     .replace(/\.integration\.test\.(ts|cjs)$/, '')
-    .replace(/\.test\.(ts|cjs)$/, '');
+    .replace(/\.test\.(ts|cjs)$/, '')
+    // #3227: strip a trailing suite/kind qualifier (`.unit`, `.property`,
+    // `.security`, `.slow`, `.install`, `.rule`, `.regression`, `.qa`, ...).
+    // A production prefix comes from `prodPrefix`, which strips only the file
+    // extension, so it never contains a dot — any surviving trailing `.<word>`
+    // is a qualifier. Without this, `frontmatter.property` matched no module at
+    // all (65 files counted against nothing repo-wide) and `state-contract.unit`
+    // matched the SHORTER `state` module through the `prefix + '-'` rule
+    // (9 files mis-bucketed).
+    .replace(/\.[a-z0-9]+$/i, '');
   const m = bare.match(/^(?:feat|bug|enh|fix)-\d+(?:-\d+)*-(.+)$/);
   return m ? m[1] : bare;
 }
@@ -109,12 +118,25 @@ function buildTestMap(prodPrefixes, allTestFiles) {
   const map = new Map([...prodPrefixes.keys()].map(p => [p, []]));
   for (const tf of allTestFiles) {
     const ep = testEffectivePrefix(path.basename(tf));
+    // fs.readdirSync order (and therefore prodPrefixes' Map insertion order,
+    // which is built from it in collectProdPrefixes) is NOT stable across
+    // platforms/filesystems — e.g. ext4 hash order on Linux CI differs from
+    // HFS+/APFS on macOS. When one module's name is a hyphen-extension of
+    // another's (e.g. `verify` and `verify-command-grounding`), first-match-
+    // wins bucketing is therefore platform-dependent. Scan every candidate
+    // and keep the longest (most specific) matching prefix, so the bucket a
+    // test file lands in is decided by specificity, never iteration order.
+    let bestPrefix = null;
     for (const prefix of prodPrefixes.keys()) {
       if (ep === prefix || ep.startsWith(prefix + '-')) {
-        map.get(prefix).push(tf);
-        break;
+        if (bestPrefix === null || prefix.length > bestPrefix.length) {
+          bestPrefix = prefix;
+        }
       }
     }
+    if (bestPrefix !== null) {
+      map.get(bestPrefix).push(tf);
+    }
   }
   return map;
 }

package/scripts/lint-unreachable-guard-drift.cjs

@@ -8,37 +8,43 @@
  * Design:      .gsd/phase/feat-3409-unreachable-shell-guard-lint/40-design.md
  * Test matrix: .gsd/phase/feat-3409-unreachable-shell-guard-lint/50-test-matrix.md
  *
- * `gsd-tools.cjs`'s `--pick <field>` extractor coerces a missing/absent
- * field to the empty string and exits **0** (probe-confirmed in
- * 40-design.md). So in `$(gsd_run query V --pick F 2>/dev/null || echo D)`
- * the `|| echo D` arm can fire only on a typo in the verb name — never on
- * the field absence it was written to handle. Three shipped shell guards
- * silently relied on that unreachable arm (#3365's Walking Skeleton gate,
- * `PHASE_REQ_IDS`, and `complete-milestone.md`'s bare `cat <glob>`, all
- * fixed alongside this guard — see `tests/unreachable-shell-guard.test.cjs`,
- * which this file does not touch).
+ * RETIRED — Detector A (`--pick` + `|| echo` on one line), #3884.
+ * `gsd-tools.cjs`'s `--pick <field>` extractor used to coerce a missing/
+ * absent field to the empty string and exit **0**, which made the `|| echo D`
+ * arm in `$(gsd_run query V --pick F 2>/dev/null || echo D)` unreachable on
+ * field absence — the exact defect Detector A existed to flag (this file's
+ * own prior header quoted the premise verbatim: "the `|| echo D` arm can
+ * fire only on a typo in the verb name, never on the field absence it was
+ * written to handle"). ADR-3473 §8.4 ("Failure is a value") makes `--pick`
+ * exit **non-zero** on an absent field (see
+ * `.gsd/phase/feat-3884-failure-is-a-value/40-design.md` rows B6-B14), so
+ * that premise is now FALSE: the `|| echo D` arm is reachable, and the shape
+ * Detector A forbade is the CORRECT idiom going forward. Keeping Detector A
+ * would forbid the fix, so it is removed rather than updated — see this
+ * file's Guard ledger entry in 40-design.md ("net: −1 detector, 0 added").
+ * `docs/how-to/resolve-unreachable-guard-findings.md` Shape A was updated in
+ * the same change (#3884) to say the same thing. The three shell guards this
+ * file's Detector A shipped alongside (#3365's Walking Skeleton gate,
+ * `PHASE_REQ_IDS`, `complete-milestone.md`'s bare `cat <glob>`) were fixed
+ * under #3409 with remedies that never took the now-retired shape (a bare
+ * `--pick` with no fallback, a two-line `X=…`/`X="${X:-D}"` split, and an
+ * array expansion, respectively) — see
+ * `tests/unreachable-shell-guard.test.cjs`, which this file does not touch
+ * and which #3884 confirmed still passes unchanged.
  *
- * TWO detectors, each narrow by design (mirroring the sibling drift guards'
- * precedent of a small, specific shape rather than a wide heuristic):
- *
- *   Detector A — a line carrying BOTH a `--pick` token AND a `|| echo`
- *   fallback. `--pick` is the discriminator: a `|| echo` default WITHOUT
- *   `--pick` (e.g. `config-get k 2>/dev/null || echo "default"`, ~132 of the
- *   141 `$(… || echo …)` lines in the prompt layer) genuinely observes a
- *   nonzero exit code and is left alone — see 40-design.md's Rejected #2
- *   ("detect on `gsd_run` + `|| echo`" was tried and reverted for exactly
- *   this false-positive volume).
+ * ONE detector remains, unaffected by the above — its mechanism (nullglob
+ * success-on-empty) has nothing to do with `--pick`'s exit code:
  *
  *   Detector B — `cat` or `ls` invoked in COMMAND POSITION with an operand
- *   containing an unquoted glob metacharacter (`*` or `?`). Both detectors
- *   are, at bottom, the SAME shape: a fallback/guard arm that a
- *   success-on-empty case silently defeats. Detector A is `--pick … ||
- *   echo`; Detector B-ii below is `ls <glob> … || echo` — the identical
- *   defect, one level down the stack, with `ls`'s own nullglob-driven
- *   success-on-empty standing in for `--pick`'s absence-coerced-to-''.
- *   SCOPED to exactly three fired shapes, per a full measurement across the
- *   four SCAN_DIRS (measured counts recorded in the PR description; 0 sites
- *   for B-iii today, by design — see KNOWN LIMITS):
+ *   containing an unquoted glob metacharacter (`*` or `?`). At bottom the
+ *   same class of bug Detector A used to catch one level up the stack: a
+ *   fallback/guard arm that a success-on-empty case silently defeats.
+ *   Detector B-ii below is `ls <glob> … || echo` — with `ls`'s own
+ *   nullglob-driven success-on-empty standing in for what used to be
+ *   `--pick`'s absence-coerced-to-''. SCOPED to exactly three fired shapes,
+ *   per a full measurement across the four SCAN_DIRS (measured counts
+ *   recorded in the PR description; 0 sites for B-iii today, by design — see
+ *   KNOWN LIMITS):
  *
  *     B-i.   `cat <glob>` fires UNCONDITIONALLY. This is the stdin-hang
  *            shape (measured rc=137 at 3s under an unmatched glob +
@@ -96,9 +102,6 @@
  * `npm run lint:ci` runs CodeQL js/redos over this repo, the same
  * discipline `lint-planning-prompt-drift.cjs` documents in its own header:
  *
- *   - PICK_RE / ECHO_FALLBACK_RE carry only a single bounded `\s*`
- *     quantifier each, over a fixed literal — no nesting, nothing to
- *     backtrack.
  *   - CAT_LS_COMMAND_RE's alternation is a FIXED, non-overlapping set (a
  *     handful of literal command-position anchors, then a fixed
  *     `(cat|ls)`), with one `[ \t]*` quantifier between the anchor and the
@@ -171,11 +174,6 @@
  * SCAN_EXT: `.md` only.
  *
  * KNOWN, ACCEPTED limits (same tradeoffs the sibling guards document):
- *   - A cross-line split defeats Detector A (`--pick` on one line, `|| echo`
- *     on the next) — left to code review, per-line textual scan only.
- *   - `|| printf` and other non-`echo` fallbacks are not detected by
- *     Detector A — narrow by design; widening is a one-line change if a
- *     site ever appears.
  *   - Detector B's command-position anchor set (line start; `;`, `&`, `|`,
  *     `(`; the keywords `if`/`then`/`elif`/`while`/`do`) is what lets
  *     `$(cat …)` / `$(ls …)` — the dominant real invocation idiom in this
@@ -214,16 +212,6 @@ const path = require('node:path');
 const driftScan = require('./lib/drift-scan.cjs');
 const { sanitizeForReport, scanTree } = driftScan;
 
-// ─── Detector A — `--pick` + `|| echo` ────────────────────────────────────
-//
-// `--pick` is the discriminator (see module header); `|| echo` is the
-// unreachable fallback arm it silently defeats. Both must be present on the
-// SAME line for the shape to be the exact unreachable-arm defect #3409
-// fixes — see the module header for why a bare "`gsd_run` + `|| echo`" rule
-// was tried and reverted (Rejected #2).
-const PICK_RE = /--pick\b/;
-const ECHO_FALLBACK_RE = /\|\|\s*echo\b/;
-
 // ─── Detector B — cat <glob> (B-i), ls <glob> … || <real fallback> (B-ii),
 // or ls <glob> at the head of if/elif/while (B-iii) ────────────────────────
 //
@@ -378,22 +366,28 @@ const BASELINE_REL_PATH = path.join('scripts', 'baselines', 'unreachable-guard-d
 
 // The tracking issue this guard's own baseline entries are owned by, absent
 // a more specific site owner named at `--update` time. #3409 is this
-// guard's own issue: any site it finds that this PR does not convert is a
-// "one careless line from the same class" per 40-design.md's Postel's Law
-// section, tracked here until the upstream `--pick` contract fix (#3473)
-// or a per-site conversion lands.
+// guard's own issue: any Detector B site it finds that this PR does not
+// convert is a "one careless line from the same class" per 40-design.md's
+// Postel's Law section, tracked here until a per-site conversion lands.
+// (Detector A's own entries, if any had ever existed, would have been
+// tracked the same way until the upstream `--pick` contract fix landed —
+// #3884 — but the baseline shipped with zero Detector A entries; see the
+// retirement note at the top of this file.)
 const RATCHET_OWNER_ISSUE = '#3409';
 
 /**
- * Pure: scan `text` (one file's content) for Detector A / Detector B
- * violations and malformed escape-marker declarations. `relPath` is the
- * repo-relative path (native separators or POSIX, either accepted) —
- * normalized via `toPosixRel` and attached as `file` on every result.
+ * Pure: scan `text` (one file's content) for Detector B violations and
+ * malformed escape-marker declarations. `relPath` is the repo-relative path
+ * (native separators or POSIX, either accepted) — normalized via
+ * `toPosixRel` and attached as `file` on every result.
  *
  * Returns `{ violations, malformed }`:
- *   - `violations`: `[{ file, line, kind: 'A'|'B', found, text }]` — `text`
- *     is the TRIMMED source line (the baseline key), `found` names the
- *     discriminating token (`--pick` for A, `cat`/`ls` for B).
+ *   - `violations`: `[{ file, line, kind: 'B', found, text }]` — `text` is
+ *     the TRIMMED source line (the baseline key), `found` names the
+ *     discriminating command (`cat`/`ls`). `kind` is retained as a field
+ *     (rather than dropped now that only one detector remains) so the
+ *     baseline JSON shape and the `--json` report shape are unchanged by
+ *     Detector A's retirement.
  *   - `malformed`: `[{ file, line, text, reason }]` — an ATTEMPTED
  *     `# gsd-scan-ignore:` declaration whose reason names no issue and no
  *     URL. Checked on EVERY line independent of whether that line also
@@ -428,9 +422,6 @@ function findUnreachableGuardDrift(text, relPath) {
     }
     if (exempt) continue;
 
-    if (PICK_RE.test(line) && ECHO_FALLBACK_RE.test(line)) {
-      violations.push({ file, line: lineNo, kind: 'A', found: '--pick', text: line.trim() });
-    }
     const globInfo = detectGlobOperand(line);
     if (globInfo) {
       violations.push({ file, line: lineNo, kind: 'B', found: globInfo.command, text: line.trim() });
@@ -774,8 +765,6 @@ function main() {
   if (!json) {
     if (fresh.length > 0) {
       process.stderr.write('unreachable-guard-drift: NEW unreachable shell-guard shape(s) found in the prompt layer.\n');
-      process.stderr.write('Detector A (--pick + || echo): the fallback can never fire on field absence — replace with an\n');
-      process.stderr.write('explicit -z/empty-string test on the resolved value.\n');
       process.stderr.write('Detector B (cat/ls over a glob operand): under a nullglob set elsewhere in the same shell\n');
       process.stderr.write('session, an unmatched glob reads from stdin (cat) or lists the cwd (ls) — use an array\n');
       process.stderr.write('expansion or an existence test instead.\n');
@@ -825,8 +814,6 @@ module.exports = {
   dedupeViolationsForBaseline,
   sortEntries,
   writeBaseline,
-  PICK_RE,
-  ECHO_FALLBACK_RE,
   CAT_LS_COMMAND_RE,
   HEREDOC_AFTER_COMMAND_RE,
   EXIT_TESTING_KEYWORDS,