@opengsd/gsd-core 1.5.0-rc.2 → 1.5.0-rc.4

package/scripts/lint-allow-test-rule-refs.cjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-allow-test-rule-refs.cjs — enforce that NEW `allow-test-rule:` exemption
+ * comments carry a tracking-issue reference.
+ *
+ * ## Why
+ *
+ * `allow-test-rule:` is an inline comment that disables the `no-source-grep`
+ * ESLint rule for a whole test file.  Today many such comments exist with no
+ * issue reference, making it impossible to audit or revisit them.  Per ADR-456
+ * (docs/adr/456-test-rigor-architecture.md) every NEW exemption must carry a
+ * `#NNN` issue reference or an https:// URL so the decision is traceable.
+ *
+ * ## What "compliant" means
+ *
+ * A compliant `allow-test-rule:` comment is one whose reason text (everything
+ * after the colon) contains either:
+ *   - a `#\d+` token  (e.g. `// allow-test-rule: see #1234`)
+ *   - an https?:// URL
+ *
+ * Any other comment is an OFFENDER.
+ *
+ * ## Grandfathering
+ *
+ * All pre-existing untracked exemptions are recorded in
+ * scripts/lint-allow-test-rule-refs.allowlist.json (seeded at gate introduction
+ * time).  The identity ratchet (scripts/lib/allowlist-ratchet.cjs) means:
+ *   - A NEW non-compliant comment not in the allowlist → gate fails.
+ *   - A previously-offending comment that is now compliant → allowlist entry is
+ *     STALE and must be pruned (ratchet-down; the baseline only ever shrinks).
+ *
+ * ## Offender identifiers
+ *
+ * Identifiers are stable cross-rename-safe strings of the form:
+ *   `<repo-relative-path> :: <trimmed-reason>`
+ *
+ * e.g. `tests/foo.test.cjs :: source-text-is-the-product`
+ *
+ * If a file has multiple non-compliant comments with the SAME reason text, only
+ * one identifier is recorded (deduped via Set).
+ *
+ * See docs/adr/456-test-rigor-architecture.md for the full policy.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { assertWithinAllowlist } = require('./lib/allowlist-ratchet.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+const TESTS_DIR = process.env.GSD_LINT_ALLOW_TEST_RULE_TESTS_DIR || path.join(ROOT, 'tests');
+const ALLOWLIST_PATH =
+  process.env.GSD_LINT_ALLOW_TEST_RULE_ALLOWLIST ||
+  path.join(__dirname, 'lint-allow-test-rule-refs.allowlist.json');
+
+/**
+ * Extracts the reason text after `allow-test-rule:` from a single line of source
+ * text in any comment form that the no-source-grep ESLint rule honours.
+ *
+ * The ESLint rule tests `c.value` (AST comment node value, delimiters stripped)
+ * with /allow-test-rule:\s*\S/, which fires on BOTH:
+ *   // allow-test-rule: <reason>    (line comment)
+ *   /* allow-test-rule: <reason> * / (block comment, single-line)
+ *
+ * By scanning line-by-line and extracting everything after `allow-test-rule:` on
+ * each line, we cover both forms without a cross-line regex (which was previously
+ * matching arbitrary `/* ... * /` pairs spanning hundreds of lines, causing false
+ * positives).
+ *
+ * The trailing `*\/` and whitespace are stripped so block-comment closers don't
+ * bleed into the extracted reason.
+ */
+const ALLOW_TEST_RULE_LINE_RE = /allow-test-rule:\s*(.+)/;
+/** Matches a compliant issue reference or URL */
+const ISSUE_REF_RE = /#\d+|https?:\/\//;
+
+/**
+ * Recursively collect offender identifiers from all *.test.cjs files under dir.
+ *
+ * @param {string} dir  absolute path to scan
+ * @returns {string[]}  sorted, deduped list of `<relpath> :: <reason>` strings
+ */
+function collectOffenders(dir) {
+  const offenders = new Set();
+
+  function scan(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        scan(full);
+      } else if (entry.isFile() && entry.name.endsWith('.test.cjs')) {
+        const relpath = path.relative(ROOT, full).split(path.sep).join('/');
+        let content;
+        try {
+          content = fs.readFileSync(full, 'utf8');
+        } catch {
+          // skip unreadable files (e.g. binary)
+          continue;
+        }
+        // Scan line-by-line.  By testing each line for `allow-test-rule:` we
+        // cover BOTH comment forms without a cross-line regex:
+        //   // allow-test-rule: <reason>         ← line comment
+        //   /* allow-test-rule: <reason> */      ← single-line block comment
+        //
+        // For each matching line we extract the reason (everything after the
+        // colon), then strip any trailing block-comment closer `*/` and
+        // whitespace so the identifier stays clean.
+        for (const line of content.split('\n')) {
+          const m = ALLOW_TEST_RULE_LINE_RE.exec(line);
+          if (!m) continue;
+          // Strip trailing block-comment closer and whitespace if present
+          const reason = m[1].replace(/\s*\*\/\s*$/, '').trim();
+          if (!reason) continue;
+          if (ISSUE_REF_RE.test(reason)) continue; // compliant — skip
+          offenders.add(`${relpath} :: ${reason}`);
+        }
+      }
+    }
+  }
+
+  scan(dir);
+  return [...offenders].sort();
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const unknown = args.filter((a) => a !== '--help');
+  if (unknown.length > 0) {
+    throw new ExitError(2, `lint-allow-test-rule-refs: unknown argument(s): ${unknown.join(', ')}`);
+  }
+
+  const current = collectOffenders(TESTS_DIR);
+  const known = JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf8'));
+
+  const failures = [];
+  const { novel } = assertWithinAllowlist({
+    label: 'allow-test-rule-refs',
+    current,
+    known,
+    fail: (msg) => failures.push(msg),
+    pruneHint: 'edit scripts/lint-allow-test-rule-refs.allowlist.json',
+  });
+
+  if (failures.length > 0) {
+    for (const msg of failures) process.stderr.write(`${msg}\n`);
+    if (novel.length > 0) {
+      process.stderr.write(
+        '\nNew allow-test-rule exemption without an issue ref — add `see #NNN` per ADR-456' +
+          ' (docs/adr/456-test-rigor-architecture.md).\n'
+      );
+    }
+    throw new ExitError(1);
+  }
+
+  console.log(
+    `ok lint-allow-test-rule-refs: ${current.length} grandfathered exemption(s) tracked, no novel untracked offenders`
+  );
+}
+
+runMain(main);

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

@@ -160,6 +160,20 @@
         "edge-probe.test.cjs"
       ],
       "issue": "550"
+    },
+    "federated-config": {
+      "files": [
+        "federated-config.test.cjs",
+        "federated-config-loadconfig.test.cjs",
+        "federated-config-key-removal.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "external-job": {
+      "files": [
+        "external-job-waiting.test.cjs"
+      ],
+      "issue": "#1165"
     }
   }
 }

package/scripts/mutation-matrix.cjs

@@ -34,17 +34,59 @@ const { readFileSync } = require('fs');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
+// ── Per-module mutation score ratchet ─────────────────────────────────────────
+// ADR-456 / issue #1187: every covered module declares a minScore floor.
+//
+// HOW THE RATCHET WORKS:
+//   • minScore locks in the current measured mutation score (minus a 1–2 pt
+//     margin for run-to-run timeout variance).
+//   • CI fails a shard if the module's live score drops below its minScore.
+//   • Raise minScore (never lower) as a module's tests improve.
+//   • The goal is every module reaching TARGET_MUTATION_SCORE (80).
+//
+// GOODHART SAFETY: scores are improved by writing genuine behavioural
+// assertions that kill real mutants — never by adding brittle exact-string
+// matches on incidental output. A justified `// Stryker disable` on a
+// confirmed equivalent mutant is acceptable.
+//
+// HOW TO UPDATE:
+//   1. Run the per-module Stryker shard locally.
+//   2. Note the reported score.
+//   3. Set minScore = floor(score) - 1 (never lower than current value).
+//   4. Open a PR — the CI gate will enforce the new floor on every future run.
+
+/** Long-run target for all modules (ADR-456). */
+const TARGET_MUTATION_SCORE = 80;
+
 // ── Single source of truth: covered modules ───────────────────────────────────
-// Each entry: { cjs: '<built artifact>', tests: ['tests/...', ...] }
-// A module is "covered" iff its tests are wired into the Stryker command runner
-// (stryker.config.mjs commandRunner.command). Mutating an uncovered module can
-// only ever produce survived mutants — so we scope strictly to these 6.
+// Each entry: { cjs: '<built artifact>', tests: ['tests/...', ...], minScore: N }
+//
+// minScore is the CI break threshold for this module's shard.
+// Floors are measured scores minus 1–2 pts for run-to-run variance.
+// Measured CI scores 2026-06-14 (issue #1187, timeout-free — source of truth):
+//   context-utilization     92.31% → floor 80  (target already met)
+//   prompt-budget           68.33% → floor 66  (local was 99.6% — TIMEOUT INFLATION; CI is the truth)
+//   frontmatter             63.35% → floor 62
+//   adr-parser              69.30% → floor 68
+//   config-schema           54.55% → floor 52  (local was 69.7% — TIMEOUT INFLATION; CI is the truth)
+//   active-workstream-store 81.91% → floor 80
+//   core-utils              77.52% → floor 75
+//
+// LESSON: floors MUST be calibrated from CI mutation runs (CI runs with
+// timeout≈0, deterministic). Local runs count timeouts as kills and
+// inflate scores significantly (prompt-budget: 99.6% local vs 68.3% CI;
+// config-schema: 69.7% local vs 54.55% CI). Never set a floor from a
+// local run without CI cross-check.
 const COVERED = {
   'context-utilization': {
     cjs: 'gsd-core/bin/lib/context-utilization.cjs',
     tests: [
       'tests/context-utilization.property.test.cjs',
     ],
+    // After mutation-killer assertions added in #1187: measured 92.31% (2026-06-14).
+    // 3 survivors are __esModule boilerplate (genuinely equivalent CJS interop mutants).
+    // minScore raised to TARGET (80) — module now meets ADR-456 goal.
+    minScore: 80,
   },
   'prompt-budget': {
     cjs: 'gsd-core/bin/lib/prompt-budget.cjs',
@@ -52,6 +94,9 @@ const COVERED = {
       'tests/prompt-budget.property.test.cjs',
       'tests/prompt-budget.unit.test.cjs',
     ],
+    // CI 68.33% timeout-free (164 killed / 1 timeout / 240 total) 2026-06-14;
+    // local was 99.6% — timeout inflation. Floor = 68 - 2 margin.
+    minScore: 66,
   },
   frontmatter: {
     cjs: 'gsd-core/bin/lib/frontmatter.cjs',
@@ -59,6 +104,7 @@ const COVERED = {
       'tests/frontmatter.property.test.cjs',
       'tests/frontmatter.unit.test.cjs',
     ],
+    minScore: 62,
   },
   'adr-parser': {
     cjs: 'gsd-core/bin/lib/adr-parser.cjs',
@@ -67,12 +113,16 @@ const COVERED = {
       'tests/adr-parser.test.cjs',
       'tests/adr-parser.unit.test.cjs',
     ],
+    minScore: 68,
   },
   'config-schema': {
     cjs: 'gsd-core/bin/lib/config-schema.cjs',
     tests: [
       'tests/config-schema.property.test.cjs',
     ],
+    // CI 54.55% timeout-free (18 killed / 0 timeout / 33 total) 2026-06-14;
+    // local was 69.7% — timeout inflation. Floor = 54 - 2 margin.
+    minScore: 52,
   },
   'active-workstream-store': {
     cjs: 'gsd-core/bin/lib/active-workstream-store.cjs',
@@ -80,6 +130,14 @@ const COVERED = {
       'tests/active-workstream-store.test.cjs',
       'tests/active-workstream-store.unit.test.cjs',
     ],
+    minScore: 80,
+  },
+  'core-utils': {
+    cjs: 'gsd-core/bin/lib/core-utils.cjs',
+    tests: [
+      'tests/core-utils.test.cjs',
+    ],
+    minScore: 75,  // measured 77.52% (2026-06-14, issue #1187); floor = 77 - 2
   },
 };
 
@@ -178,6 +236,7 @@ function buildResult(moduleNames) {
     name,
     mutate: COVERED[name].cjs,
     tests: COVERED[name].tests.join(' '),
+    minScore: COVERED[name].minScore,
   }));
 
   return {
@@ -194,8 +253,9 @@ function printHuman(result, changedFiles) {
   console.log(`Shards (${result.matrix.include.length}):`);
   for (const shard of result.matrix.include) {
     console.log(`  [${shard.name}]`);
-    console.log(`    mutate: ${shard.mutate}`);
-    console.log(`    tests:  ${shard.tests}`);
+    console.log(`    mutate:   ${shard.mutate}`);
+    console.log(`    tests:    ${shard.tests}`);
+    console.log(`    minScore: ${shard.minScore}`);
   }
 }
 
@@ -219,4 +279,45 @@ function main() {
   }
 }
 
-runMain(main);
+// ── MUTATION_BREAK resolver ───────────────────────────────────────────────────
+/**
+ * Resolves the per-shard mutation break threshold from the MUTATION_BREAK env var.
+ *
+ * Fail-closed contract:
+ *   - undefined  → 60  (local run: no env set, documented backstop)
+ *   - set but empty (e.g. CI matrix.minScore missing) → throws (wiring error)
+ *   - non-numeric or out-of-range [1, 100] → throws (invalid config)
+ *   - valid integer string → returns that number
+ *
+ * This function is the single call site for reading MUTATION_BREAK.
+ * stryker.config.mjs imports and calls it so CI shards with a bad
+ * MUTATION_BREAK fail immediately rather than silently falling back to 60
+ * and bypassing a per-module floor above 60 (e.g. prompt-budget: 90).
+ *
+ * @param {string|undefined} raw - value of process.env.MUTATION_BREAK
+ * @returns {number}
+ */
+function resolveMutationBreak(raw) {
+  if (raw === undefined) {
+    // Local run with no MUTATION_BREAK set — use documented backstop.
+    return 60;
+  }
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new Error(
+      'MUTATION_BREAK is set but empty — CI shard wiring is broken (matrix.minScore missing?)'
+    );
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1 || n > 100) {
+    throw new Error(
+      `MUTATION_BREAK invalid: "${raw}" (expected a per-module minScore 1-100)`
+    );
+  }
+  return n;
+}
+
+// Export internals for programmatic use (tests/mutation-matrix-ratchet.test.cjs).
+// The require.main guard prevents main() from running when this file is require()d.
+module.exports = { COVERED, TARGET_MUTATION_SCORE, resolveMutationBreak };
+
+if (require.main === module) runMain(main);

package/scripts/pr-target-policy.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * PR target-branch policy — ADR-230.
+ *
+ * Extracted from .github/workflows/pr-target-validator.yml so the classification
+ * logic can be unit-tested independently and required by the workflow at checkout
+ * from the TRUSTED base-branch copy (fork-tamper-safe).
+ *
+ * Pure module: no I/O, no GitHub API calls, no side effects.
+ *
+ * See: docs/branching.md, docs/adr/230-introduce-next-integration-branch.md
+ */
+
+/**
+ * The five patterns that allow a PR to target `main`.
+ * Verbatim from the github-script in pr-target-validator.yml.
+ *
+ * @type {RegExp[]}
+ */
+const MAIN_ALLOWED_PATTERNS = [
+  /^release\/\d+\.\d+\.0$/,           // release branches
+  /^hotfix\/\d+\.\d+\.\d+$/,          // hotfix branches
+  /^fix\/critical-/,                  // production-down emergencies
+  /^chore\/backmerge-/,               // auto-backmerge from this workflow
+  /^revert\/critical-/,               // emergency reverts
+];
+
+/**
+ * Classify a pull request by its base and head branch names.
+ *
+ * @param {string} base  - The PR's target branch (e.g. 'next', 'main', 'release/1.2.0').
+ * @param {string} head  - The PR's source branch (e.g. 'feat/my-feature').
+ * @returns {{ decision: 'allowed' | 'blocked' | 'unusual' }}
+ */
+function classifyPrTarget(base, head) {
+  // PRs targeting `next` are always fine.
+  if (base === 'next') {
+    return { decision: 'allowed' };
+  }
+
+  // PRs targeting `main`: only specific branch types allowed.
+  if (base === 'main') {
+    const allowed = MAIN_ALLOWED_PATTERNS.some(re => re.test(head));
+    if (allowed) {
+      return { decision: 'allowed' };
+    }
+    return { decision: 'blocked' };
+  }
+
+  // PRs targeting release/X.Y.0 or hotfix/X.Y.Z are fine (stabilization PRs).
+  if (/^release\/\d+\.\d+\.0$/.test(base) || /^hotfix\/\d+\.\d+\.\d+$/.test(base)) {
+    return { decision: 'allowed' };
+  }
+
+  // Any other target is unusual but not forbidden.
+  return { decision: 'unusual' };
+}
+
+module.exports = {
+  MAIN_ALLOWED_PATTERNS,
+  classifyPrTarget,
+};

package/scripts/release-tarball-smoke.cjs

@@ -57,6 +57,11 @@ const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 // https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
 // ). Raise to 600 s (the same ceiling the before() helper uses for pack+install).
 const CHILD_TIMEOUT_MS = process.platform === 'win32' ? 600_000 : 120_000;
+const QUIET_NPM_ENV = Object.freeze({
+  npm_config_loglevel: 'error',
+  npm_config_update_notifier: 'false',
+  NO_UPDATE_NOTIFIER: '1',
+});
 
 // ---------------------------------------------------------------------------
 // Frozen result-code enum
@@ -304,7 +309,7 @@ function runSmoke({
   // Use the caller-supplied npmEnv if provided (allows HOME isolation on Docker
   // hosts where HOME may be unwritable — same pattern as runNpm() in helpers.cjs).
   // Falls back to process.env to preserve existing CLI / programmatic behaviour. (#131)
-  const effectiveNpmEnv = npmEnv !== undefined ? npmEnv : process.env;
+  const effectiveNpmEnv = { ...(npmEnv !== undefined ? npmEnv : process.env), ...QUIET_NPM_ENV };
   const installResult = spawnSync(
     npmCmd,
     ['install', '-g', '--prefix', installPrefix, tarballPath],
@@ -570,6 +575,7 @@ function cliMain() {
         encoding: 'utf-8',
         shell: process.platform === 'win32',
         timeout: CHILD_TIMEOUT_MS,
+        env: { ...process.env, ...QUIET_NPM_ENV },
       },
     ).trim();
     // npm pack outputs the filename on stdout (last line when verbose)

package/scripts/research-profiles.cjs

@@ -24,7 +24,7 @@ const PROFILES = [
       'Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.',
     color: 'cyan',
     tools:
-      'Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
+      'Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
       '@~/.claude/gsd-core/references/research-philosophy.md',
@@ -46,7 +46,7 @@ const PROFILES = [
       'Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.',
     color: 'cyan',
     tools:
-      'Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
+      'Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
       '@~/.claude/gsd-core/references/research-philosophy.md',
@@ -68,7 +68,7 @@ const PROFILES = [
     description:
       'Researches a single gray area decision and returns a structured comparison table with rationale. Spawned by discuss-phase advisor mode.',
     color: 'cyan',
-    tools: 'Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*',
+    tools: 'Read, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],
@@ -117,7 +117,7 @@ const PROFILES = [
       'Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.',
     color: 'purple',
     tools:
-      'Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
+      'Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],
@@ -134,7 +134,7 @@ const PROFILES = [
     description:
       'Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /gsd:new-project after 4 researcher agents complete.',
     color: 'purple',
-    tools: 'Read, Write, Bash',
+    tools: 'Read, Write, Bash, Skill',
     requiredIncludes: [],
     requiredSeamCalls: [
       'gsd_run query commit',