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

package/scripts/issue-version-gate.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+'use strict';
+
+const { PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs');
+
+/**
+ * Version gate for bug-report issues.
+ *
+ * GitHub Issue Forms enforce `required: true` only in the web form; issues
+ * filed via the REST API, `gh issue create`, or automated/AI reporters can
+ * omit the GSD Version field entirely. This module provides the pure logic
+ * for detecting bug reports missing a usable version so a workflow can
+ * auto-close them. See .github/workflows/version-gate.yml.
+ */
+
+const BUG_LABEL = 'bug';
+const NEEDS_VERSION_LABEL = 'needs-version';
+const VERSION_GATE_MARKER = '<!-- gsd-version-gate -->';
+
+// Labels that opt an issue out of the version gate.
+const EXEMPT_LABELS = ['version-exempt'];
+
+// Heading GitHub renders for the bug template's `label: GSD Version` field.
+// Issue Forms render input labels as `### <label>`; matches the exact heading
+// `### GSD Version` (any heading level) — bare `### Version` is NOT matched.
+const VERSION_HEADING_RE = /^#{1,6}\s*GSD\s+Version\s*$/i;
+
+// GitHub's placeholder for an empty optional form field.
+const NO_RESPONSE_RE = /^_no response_$/i;
+
+// A value "looks like a version" if it contains a semver-ish token
+// (1.18, v1.4.1, 1.18.0-dev) or a git commit SHA (7-40 hex chars).
+const SEMVER_TOKEN_RE = /\bv?\d+\.\d+(?:\.\d+)?(?:[-+.][0-9A-Za-z.-]+)?\b/;
+const SHA_TOKEN_RE = /\b[0-9a-f]{7,40}\b/i;
+
+function normalizeLabels(labels) {
+  if (!Array.isArray(labels)) return [];
+  return labels
+    .map((l) => (typeof l === 'string' ? l : l && l.name))
+    .filter(Boolean)
+    .map((l) => String(l).toLowerCase());
+}
+
+function hasExemptLabel(labels) {
+  const names = normalizeLabels(labels);
+  return names.some((l) => EXEMPT_LABELS.includes(l));
+}
+
+function isBugReport({ labels, body } = {}) {
+  const names = normalizeLabels(labels);
+  if (names.includes(BUG_LABEL)) return true;
+  // Labels are authoritative: if any label was applied and it isn't `bug`,
+  // this is not a bug report (e.g. an `enhancement`-labeled issue that happens
+  // to contain a version heading must not be gated). Only fall back to the
+  // bug-template's `### GSD Version` heading for fully unlabeled submissions
+  // (bare REST API / `gh issue create`).
+  if (names.length > 0) return false;
+  return hasVersionHeading(body);
+}
+
+function hasVersionHeading(body) {
+  if (!body) return false;
+  return String(body)
+    .split(/\r?\n/)
+    .some((line) => VERSION_HEADING_RE.test(line));
+}
+
+/**
+ * Extract the value beneath the "GSD Version" heading. Returns null when the
+ * section is absent, '' when the section is present but empty.
+ */
+function extractVersion(body) {
+  if (!body) return null;
+  const lines = String(body).split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (VERSION_HEADING_RE.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  const collected = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,6}\s/.test(lines[i])) break; // next section heading
+    collected.push(lines[i]);
+  }
+  return collected.join('\n').trim();
+}
+
+function isValidVersion(value) {
+  if (value == null) return false;
+  const v = String(value).trim();
+  if (!v) return false;
+  if (NO_RESPONSE_RE.test(v)) return false;
+  return SEMVER_TOKEN_RE.test(v) || SHA_TOKEN_RE.test(v);
+}
+
+/**
+ * Decide what to do with an issue. Returns { action: 'skip'|'close', reason }.
+ */
+function evaluateVersionGate({ labels, body } = {}) {
+  if (hasExemptLabel(labels)) return { action: 'skip', reason: 'exempt-label' };
+  if (!isBugReport({ labels, body })) return { action: 'skip', reason: 'not-a-bug' };
+  const version = extractVersion(body);
+  if (isValidVersion(version)) return { action: 'skip', reason: 'valid-version' };
+  const reason = version == null ? 'missing-version' : 'invalid-version';
+  return { action: 'close', reason };
+}
+
+function renderCloseComment() {
+  return [
+    VERSION_GATE_MARKER,
+    'Closing automatically — this bug report does not include a valid **GSD Version**.',
+    '',
+    'A version is required to reproduce and triage bugs. Grab it with one of:',
+    '',
+    '```',
+    `npm list -g ${PACKAGE_NAME}`,
+    `npx ${PACKAGE_NAME} --version`,
+    '```',
+    '',
+    'Then **edit this issue to add the version (e.g. `1.18.0`) and reopen it**, or comment with the version and a maintainer will reopen it. If a version genuinely does not apply, a maintainer can add the `version-exempt` label.',
+  ].join('\n');
+}
+
+module.exports = {
+  BUG_LABEL,
+  NEEDS_VERSION_LABEL,
+  VERSION_GATE_MARKER,
+  EXEMPT_LABELS,
+  normalizeLabels,
+  hasExemptLabel,
+  isBugReport,
+  hasVersionHeading,
+  extractVersion,
+  isValidVersion,
+  evaluateVersionGate,
+  renderCloseComment,
+};

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -0,0 +1,326 @@
+[
+  "tests/agent-classification-parity.test.cjs :: runtime-contract-is-the-product — docs/AGENTS.md section layout + docs/INVENTORY.md table ARE the classification surface being validated",
+  "tests/agent-frontmatter.test.cjs :: source-text-is-the-product",
+  "tests/agent-required-reading-consistency.test.cjs :: source-text-is-the-product",
+  "tests/agent-size-budget.test.cjs :: source-text-is-the-product",
+  "tests/agent-skills-awareness.test.cjs :: source-text-is-the-product",
+  "tests/ai-evals.test.cjs :: source-text-is-the-product",
+  "tests/analyze-dependencies.test.cjs :: source-text-is-the-product",
+  "tests/anti-pattern-enforcement.test.cjs :: source-text-is-the-product",
+  "tests/ask-user-questions-fallback.test.cjs :: source-text-is-the-product",
+  "tests/audit-fix-command.test.cjs :: source-text-is-the-product",
+  "tests/autonomous-allowed-tools.test.cjs :: source-text-is-the-product",
+  "tests/autonomous-converge.test.cjs :: source-text-is-the-product",
+  "tests/autonomous-decomposition.test.cjs :: source-text-is-the-product",
+  "tests/autonomous-interactive.test.cjs :: source-text-is-the-product",
+  "tests/autonomous-to-flag.test.cjs :: source-text-is-the-product",
+  "tests/bug-131-release-tarball-smoke-explicit-home.test.cjs :: integration-test-input",
+  "tests/bug-14-progress-auto-flag-dropped.test.cjs :: source-text-is-the-product",
+  "tests/bug-17-askuserquestion-option-cap.test.cjs :: source-text-is-the-product",
+  "tests/bug-170-workflow-fallback-install-hint.test.cjs :: workflow markdown is shipped product text; this test validates fallback hint literals across all workflow files",
+  "tests/bug-1891-file-resolution.test.cjs :: structural-implementation-guard",
+  "tests/bug-1924-preserve-user-artifacts.test.cjs :: source-text-is-the-product",
+  "tests/bug-1967-cache-invalidation.test.cjs :: source-text-is-the-product",
+  "tests/bug-211-launcher-home-fallback.test.cjs :: structural/behavioral regression for the ~/.claude fallback arm in",
+  "tests/bug-2136-sh-hook-version.test.cjs :: structural-regression-guard",
+  "tests/bug-214-phase-researcher-write-truncation-contract.test.cjs :: source-text-is-the-product",
+  "tests/bug-214-writer-agents-write-truncation-contract.test.cjs :: source-text-is-the-product",
+  "tests/bug-222-research-synthesizer-write-contract.test.cjs :: source-text-is-the-product",
+  "tests/bug-224-pick-stdout-capture.test.cjs :: structural-implementation-guard",
+  "tests/bug-2346-agent-read-loop-guards.test.cjs :: source-text-is-the-product",
+  "tests/bug-2388-plan-phase-no-branch-rename.test.cjs :: source-text-is-the-product",
+  "tests/bug-2396-makefile-test-priority.test.cjs :: source-text-is-the-product",
+  "tests/bug-2399-commit-docs-plan-phase.test.cjs :: source-text-is-the-product",
+  "tests/bug-2410-stream-checkpoint-heartbeats.test.cjs :: source-text-is-the-product",
+  "tests/bug-2419-project-researcher-agent.test.cjs :: source-text-is-the-product",
+  "tests/bug-2421-planner-grep-gate-hygiene.test.cjs :: source-text-is-the-product",
+  "tests/bug-2424-reapply-patches-baseline-detection.test.cjs :: source-text-is-the-product",
+  "tests/bug-2470-update-md-claude-path.test.cjs :: source-text-is-the-product",
+  "tests/bug-2492-context-coverage-gate.test.cjs :: source-text-is-the-product",
+  "tests/bug-2502-insert-phase-state-update.test.cjs :: source-text-is-the-product",
+  "tests/bug-2516-inherit-model-execute-phase.test.cjs :: source-text-is-the-product",
+  "tests/bug-2543-gsd-slash-namespace.test.cjs :: structural-regression-guard",
+  "tests/bug-2549-2550-2552-discuss-phase-context.test.cjs :: source-text-is-the-product",
+  "tests/bug-2559-stale-search-year.test.cjs :: source-text-is-the-product",
+  "tests/bug-2661-roadmap-sync-parallel.test.cjs :: source-text-is-the-product",
+  "tests/bug-2686-review-fix-worktree.test.cjs :: source-text-is-the-product",
+  "tests/bug-2698-crlf-install.test.cjs :: source-text-is-the-product",
+  "tests/bug-2770-annotate-deps-int-coerce.test.cjs :: source-text-is-the-product",
+  "tests/bug-2772-gitmodules-path-intersection.test.cjs :: source-text-is-the-product",
+  "tests/bug-2784-update-cache-clear-path.test.cjs :: structural-regression-guard",
+  "tests/bug-279-codex-agent-mapping.test.cjs :: source-text-is-the-product [adapter header contract in bin/install.js]",
+  "tests/bug-2808-skill-hyphen-name.test.cjs :: source-text-is-the-product",
+  "tests/bug-2831-opencode-home-path-prefix.test.cjs :: source-text-is-the-product",
+  "tests/bug-2839-review-fix-transactional-cleanup.test.cjs :: source-text-is-the-product",
+  "tests/bug-2948-spike-wrap-up-dispatch.test.cjs :: source-text-is-the-product",
+  "tests/bug-2949-sketch-wrap-up-dispatch.test.cjs :: source-text-is-the-product",
+  "tests/bug-2954-help-md-slash-command-stubs.test.cjs :: source-text-is-the-product",
+  "tests/bug-2973-profile-user-skills-path.test.cjs :: source-text-is-the-product. profile-user.md IS the",
+  "tests/bug-2990-code-fixer-worktree-branch.test.cjs :: source-text-is-the-product",
+  "tests/bug-3086-git-create-tag-config-gate.test.cjs :: workflow-markdown-is-the-runtime-contract",
+  "tests/bug-3096-ai-integration-phase-parallel-race.test.cjs :: reads product workflow markdown (ai-integration-phase.md) to verify structural ordering contract — not a source-grep test",
+  "tests/bug-3097-3099-executor-worktree-path-safety.test.cjs :: reads markdown product files (gsd-executor.md, worktree-path-safety.md) to verify structural protocol — not source-grep",
+  "tests/bug-3120-secure-phase-empty-register.test.cjs :: reads product workflow markdown (secure-phase.md) to verify structural guard contract — not a source-grep test",
+  "tests/bug-3126-global-skills-base-runtime-path.test.cjs :: last three tests read init.cjs source to verify delegation contract to runtime-homes.cjs — structural guard, no behavioral IR exposed",
+  "tests/bug-3127-state-begin-phase-idempotent.test.cjs :: reads runtime STATE.md written to temp dir — behavioral output test, not source-grep",
+  "tests/bug-3128-roadmap-plan-count-slug-layout.test.cjs :: reads roadmap.cjs source to verify isPlanFile pattern was adopted — structural contract prevents silent regression to old filter",
+  "tests/bug-3129-validate-commit-git-bypass.test.cjs :: reads hook shell script to verify delegation pattern — structural contract test, not source-grep",
+  "tests/bug-3130-update-npx-robust-invocation.test.cjs :: reads product workflow markdown (update.md) to verify structural invocation contract — not a source-grep test",
+  "tests/bug-3135-capture-backlog-workflow.test.cjs :: source-text-is-the-product — workflow and command .md files",
+  "tests/bug-3156-plan-phase-opencode-dispatch.test.cjs :: source-text-is-the-product",
+  "tests/bug-3168-task-to-agent-rename.test.cjs :: source-text-is-the-product",
+  "tests/bug-3236-capture-seed-one-shot.test.cjs :: source-text-is-the-product — workflow and command .md files",
+  "tests/bug-3258-no-stale-gsd-intel-references.test.cjs :: source-text-is-the-product — workflow, reference, and docs .md files",
+  "tests/bug-3290-intel-updater-layout-block.test.cjs :: source-text-is-the-product — agents/gsd-intel-updater.md IS",
+  "tests/bug-33-settings-model-profile-adaptive.test.cjs :: source-text-is-the-product",
+  "tests/bug-3381-verify-work-workstream.test.cjs :: source-text-is-the-product — verify-work.md is a runtime workflow contract.",
+  "tests/bug-3384-secondary-defects.test.cjs :: source-text-is-the-product",
+  "tests/bug-3418-progress-flag-routing.test.cjs :: source-text-is-the-product",
+  "tests/bug-3430-planner-phase-contract.test.cjs :: source-text-is-the-product",
+  "tests/bug-3431-debug-command-yaml.test.cjs :: source-text-is-the-product",
+  "tests/bug-3446-resume-continue-here-discovery.test.cjs :: source-text-is-the-product",
+  "tests/bug-3489-complete-phase-idempotent.test.cjs :: source-text-is-the-product",
+  "tests/bug-3491-nested-git-worktree.test.cjs :: source-text-is-the-product",
+  "tests/bug-3516-reapply-patches-gsd-update-filter.test.cjs :: source-text-is-the-product",
+  "tests/bug-3521-quick-cleanup-cwd-pin.test.cjs :: source-text-is-the-product",
+  "tests/bug-3523-cjs-loadconfig-branching-strategy-warning.test.cjs :: validates runtime CLI stdout/stderr warning behavior, not source grep",
+  "tests/bug-3542-executor-git-stash-prohibition.test.cjs :: source-text-is-the-product",
+  "tests/bug-3582-codex-skills-materialized.test.cjs :: source-text-is-the-product",
+  "tests/bug-3605-stale-research-insert-phase-agent-refs.test.cjs :: source-text-is-the-product",
+  "tests/bug-3628-bundled-hook-classifier-whitelist.test.cjs :: architectural-invariant",
+  "tests/bug-3657-verify-reapply-patches-pristine-drift.test.cjs :: source-text-is-the-product.",
+  "tests/bug-3657-verify-reapply-patches-pristine-drift.test.cjs :: source-text-is-the-product — Finding 2 reads reapply-patches.md to",
+  "tests/bug-3677-agent-colon-namespace-leak.test.cjs :: source-text-is-the-product",
+  "tests/bug-3678-executor-commit-docs-respect.test.cjs :: source-text-is-the-product",
+  "tests/bug-3683-command-colon-namespace-leak.test.cjs :: source-text-is-the-product",
+  "tests/bug-3683-command-cross-reference-invariant.test.cjs :: source-text-is-the-product",
+  "tests/bug-3683-workflow-colon-namespace-leak.test.cjs :: source-text-is-the-product",
+  "tests/bug-3689-resume-glob-nomatch.test.cjs :: source-text-is-the-product",
+  "tests/bug-3691-annotate-deps-plans-block-variants.test.cjs :: source-text-is-the-product",
+  "tests/bug-3706-ui-safety-gate-false-positives.test.cjs :: source-text-is-the-product",
+  "tests/bug-3707-locked-worktree-cleanup.test.cjs :: source-text-is-the-product",
+  "tests/bug-3727-code-review-fix-flag-dispatch.test.cjs :: source-text-is-the-product",
+  "tests/bug-378-update-check-scoped-name.test.cjs :: structural assertion on hook delegation; the behavior being",
+  "tests/bug-3784-gsd-settings-model-profile-ui-omits-adaptive.test.cjs :: source-text-is-the-product",
+  "tests/bug-3805-fast-md-log-to-state-schema.test.cjs :: source-text-is-the-product",
+  "tests/bug-3810-no-gsd-sdk-runtime-refs.test.cjs :: source-text-is-the-product",
+  "tests/bug-397-state-preserve-executor-authored.test.cjs :: reads runtime STATE.md written to temp dir — behavioral output test, not source-grep",
+  "tests/bug-444-resolver-local-claude-install.test.cjs :: structural/behavioral regression for the repo-local .claude/ install",
+  "tests/bug-474-clock-seam-date-determinism.test.cjs :: source-text-is-the-product",
+  "tests/bug-503-update-agent-antigravity-detection.test.cjs :: source-text-is-the-product",
+  "tests/bug-570-codex-leak-scanner.test.cjs :: source-text-is-the-product",
+  "tests/bug-571-doc-writer-fix-mode-edit-only.test.cjs :: source-text-is-the-product",
+  "tests/bug-619-codebase-drift-gate-shim.test.cjs :: source-text-is-the-product",
+  "tests/bug-621-plan-phase-gap-analysis-gsd-run.test.cjs :: source-text-is-the-product",
+  "tests/bug-622-graphify-optional-graph-html.test.cjs :: source-text-is-the-product",
+  "tests/bug-630-wave-cleanup-orchestrator-root.test.cjs :: source-text-is-the-product",
+  "tests/bug-637-workflow-no-hardcoded-home-tool.test.cjs :: source-text-is-the-product",
+  "tests/bug-685-windowshide-spawn.test.cjs :: source-text-is-the-product",
+  "tests/bug-687-agy-timeout.test.cjs :: source-text-is-the-product",
+  "tests/bug-704-codex-launcher-path-corruption.test.cjs :: source-text-is-the-product",
+  "tests/bug-851-codex-quick-adapter-agent-type-fallback.test.cjs :: source-text-is-the-product",
+  "tests/bug-891-non-claude-runtime-home-fallback.test.cjs :: structural/behavioral regression for non-Claude runtime-home",
+  "tests/bug-924-claude-flat-skill-layout.test.cjs :: source-text-is-the-product",
+  "tests/bug-936-no-nested-spawner-wrap.test.cjs :: source-text-is-the-product",
+  "tests/bug-947-hermes-gsd-prefix.test.cjs :: source-text-is-the-product",
+  "tests/bug-950-quick-summary-status-complete.test.cjs :: source-text-is-the-product",
+  "tests/bug-967-verify-key-links-strict-paths.test.cjs :: <runtime-contract-is-the-product> the plan-md.md reference",
+  "tests/bug-967-verify-key-links-strict-paths.test.cjs :: <runtime-contract-is-the-product> the plan-md.md reference example IS the documented authoring surface for key_links; asserting it uses a file path (not an endpoint) directly tests the documented contract.",
+  "tests/bug-983-trae-windsurf-claude-path-leak.test.cjs :: source-text-is-the-product",
+  "tests/bug-patterns-reference.test.cjs :: source-text-is-the-product",
+  "tests/chain-flag-plan-phase.test.cjs :: source-text-is-the-product",
+  "tests/changeset-cli.test.cjs :: reads a product workflow .md file (not CJS source) to verify",
+  "tests/check-update-config-dir.test.cjs :: structural-regression-guard",
+  "tests/ci-test-scope.test.cjs :: CLI usage banner presence is a user-facing contract.",
+  "tests/ci-test-scope.test.cjs :: CLI usage failure text is user-facing contract for this parser guard.",
+  "tests/claude-md.test.cjs :: source-text-is-the-product",
+  "tests/claude-skills-migration.test.cjs :: source-text-is-the-product",
+  "tests/cleanup-branch-pruning.test.cjs :: source-text-is-the-product",
+  "tests/cline-install.test.cjs :: source-text-is-the-product",
+  "tests/cline-support.test.cjs :: source-text-is-the-product",
+  "tests/clock-seam.test.cjs :: line 159 reads the STATE.md temp file written by readModifyWriteStateMd — this is a runtime output file assertion, not a source-grep; the API returns void so a file read-back is the only way to verify the transform was applied",
+  "tests/code-review-agent-skills.test.cjs :: source-text-is-the-product",
+  "tests/code-review-command.test.cjs :: source-text-is-the-product",
+  "tests/code-review-pipeline-regression.test.cjs :: source-text-is-the-product",
+  "tests/code-review.test.cjs :: source-text-is-the-product",
+  "tests/codebuddy-install.test.cjs :: source-text-is-the-product",
+  "tests/codex-config.test.cjs :: source-text-is-the-product",
+  "tests/command-contract.test.cjs :: source-text-is-the-product — commands/gsd/*.md files ARE the",
+  "tests/commands.test.cjs :: source-text-is-the-product",
+  "tests/concurrency-safety.test.cjs :: source-text-is-the-product",
+  "tests/config-field-docs.test.cjs :: docs-parity",
+  "tests/context-enrichment.test.cjs :: source-text-is-the-product",
+  "tests/contributor-standards.test.cjs :: source-text-is-the-product",
+  "tests/copilot-install.test.cjs :: integration-test-input",
+  "tests/core.test.cjs :: architectural-invariant",
+  "tests/core.test.cjs :: structural-regression-guard",
+  "tests/cursor-hooks.test.cjs :: source-text-is-the-product",
+  "tests/cursor-reviewer.test.cjs :: source-text-is-the-product",
+  "tests/debug-session-management.test.cjs :: source-text-is-the-product",
+  "tests/discuss-all-flag.test.cjs :: source-text-is-the-product",
+  "tests/discuss-checkpoint.test.cjs :: source-text-is-the-product",
+  "tests/discuss-mode.test.cjs :: structural-implementation-guard",
+  "tests/discuss-phase-power.test.cjs :: source-text-is-the-product",
+  "tests/docs-parity-live-registry.test.cjs :: source-text-is-the-product",
+  "tests/drift-detection.test.cjs :: source-text-is-the-product",
+  "tests/edge-probe-docs-fixtures.test.cjs :: runtime-contract-is-the-product — the rendered reference/SPEC/ADR vocab surfaces are the runtime contract; this pins their bijection to the code (docs-parity)",
+  "tests/edge-probe-planner-contract.test.cjs :: runtime-contract-is-the-product — plan-phase.md's planner prompt is the deployed runtime contract under assertion",
+  "tests/edge-probe-spec-phase-contract.test.cjs :: runtime-contract-is-the-product — spec-phase.md Step 5.5 is the deployed workflow runtime contract under assertion",
+  "tests/edit-phase.test.cjs :: source-text-is-the-product",
+  "tests/enh-2310-chunked-plan-phase.test.cjs :: source-text-is-the-product",
+  "tests/enh-2380-sync-skills.test.cjs :: source-text-is-the-product",
+  "tests/enh-2415-claude-md-link-mode.test.cjs :: source-text-is-the-product",
+  "tests/enh-2430-learnings-consumption.test.cjs :: source-text-is-the-product",
+  "tests/enh-2433-todo-phase-linking.test.cjs :: source-text-is-the-product",
+  "tests/enh-2446-milestones-drift.test.cjs :: source-text-is-the-product",
+  "tests/enh-2447-roadmap-wave-deps.test.cjs :: source-text-is-the-product",
+  "tests/enh-2448-artifact-registry.test.cjs :: source-text-is-the-product",
+  "tests/enh-2500-codebase-mapper-arch-rich-format.test.cjs :: source-text-is-the-product",
+  "tests/enh-2789-description-budget.test.cjs :: source-text-is-the-product",
+  "tests/enh-2790-skill-consolidation.test.cjs :: source-text-is-the-product",
+  "tests/enh-2792-namespace-skills.test.cjs :: source-text-is-the-product",
+  "tests/enh-3209-plan-phase-ingest-adr.test.cjs :: source-text-is-the-product",
+  "tests/enh-48-cwd-drift-guard-e2e.test.cjs :: integration-test-input",
+  "tests/enh-72-business-context.test.cjs :: source-text-is-the-product",
+  "tests/enh-769-context-fork-effort.install.test.cjs :: integration-test-input",
+  "tests/enh-770-claude-hook-events.test.cjs :: runtime-contract-is-the-product — hooks.json IS the",
+  "tests/enh-770-claude-hook-events.test.cjs :: runtime-contract-is-the-product — the hookEventName is",
+  "tests/enh-770-claude-hook-events.test.cjs :: runtime-contract-is-the-product — the stamp template token",
+  "tests/enh-770-claude-hook-events.test.cjs :: runtime-contract-is-the-product — the stdin-read and",
+  "tests/enh-773-codex-exec-automation-flags.test.cjs :: source-text-is-the-product",
+  "tests/enh-778-cross-runtime-command-enrichment.test.cjs :: source-text-is-the-product",
+  "tests/enh-789-codebuddy-commands.test.cjs :: source-text-is-the-product",
+  "tests/eslint-rules.test.cjs :: <source-grep reason> must still error",
+  "tests/eslint-rules.test.cjs :: pending migration",
+  "tests/eslint-rules.test.cjs :: source-text-is-the-product",
+  "tests/execute-phase-active-flags.test.cjs :: source-text-is-the-product",
+  "tests/execute-phase-step-5-5-deviation-doc.test.cjs :: source-text-is-the-product",
+  "tests/execute-phase-wave.test.cjs :: behavioral — calls gsd-tools and asserts structured output",
+  "tests/execute-phase-wave.test.cjs :: behavioral — exercises config-set validation, not source text",
+  "tests/execute-phase-wave.test.cjs :: behavioral — exercises gsd-tools wave-defaulting logic",
+  "tests/execute-phase-wave.test.cjs :: source-text-is-the-product",
+  "tests/execute-phase-worktree-artifacts.test.cjs :: source-text-is-the-product",
+  "tests/explore-command.test.cjs :: source-text-is-the-product",
+  "tests/extract-learnings.test.cjs :: source-text-is-the-product",
+  "tests/feat-22-surfacing-docs.test.cjs :: docs-parity",
+  "tests/feat-2840-issue-driven-orchestration-guide.test.cjs :: structural-IR parser for a docs guide. The .includes()",
+  "tests/feat-3039-help-tiered.test.cjs :: source-text-is-the-product",
+  "tests/feat-3167-ship-pr-body-sections.test.cjs :: source-text-is-the-product",
+  "tests/feat-3210-fallow-integration.test.cjs :: source-text-is-the-product",
+  "tests/feat-3210-fallow-integration.test.cjs :: source-text-is-the-product — code-review.md IS the workflow the orchestrator",
+  "tests/feat-3309-human-verify-mode.test.cjs :: source-text-is-the-product",
+  "tests/feat-443-effort-install-wiring.install.test.cjs :: integration-test-input",
+  "tests/feat-488-effort-sync.test.cjs :: structural-regression-guard — readFileSync asserts on installed agent .md files (the product under mutation) to verify dry-run safety and apply correctness; stderr.includes guards the CLI argument-rejection contract.",
+  "tests/fix-3722-execute-phase-human-needed-checkpoint.test.cjs :: source-text-is-the-product",
+  "tests/forensics.test.cjs :: source-text-is-the-product",
+  "tests/frontmatter-cli.test.cjs :: source-text-is-the-product",
+  "tests/gates-taxonomy.test.cjs :: source-text-is-the-product",
+  "tests/gsd-check-update-worker-platform-gate.test.cjs :: structural assertion on spawn-options shape; the behavior",
+  "tests/gsd-researcher-app-aware.test.cjs :: source-text-is-the-product",
+  "tests/gsd-researcher-flow-diagram.test.cjs :: source-text-is-the-product",
+  "tests/gsd-settings-advanced.test.cjs :: source-text-is-the-product",
+  "tests/gsd2-import.test.cjs :: source-text-is-the-product",
+  "tests/hermes-skills-migration.test.cjs :: source-text-is-the-product",
+  "tests/import-command.test.cjs :: source-text-is-the-product",
+  "tests/ingest-docs.test.cjs :: source-text-is-the-product",
+  "tests/inline-plan-threshold.test.cjs :: source-text-is-the-product",
+  "tests/install-minimal-hooks.test.cjs :: source-text-is-the-product",
+  "tests/install-nested-layout.test.cjs :: source-text-is-the-product",
+  "tests/install-runtime-artifacts.test.cjs :: source-text-is-the-product",
+  "tests/install.test.cjs :: runtime-contract-is-the-product",
+  "tests/install.test.cjs :: source-text-is-the-product",
+  "tests/intel.test.cjs :: source-text-is-the-product — agents/gsd-intel-updater.md IS the",
+  "tests/intel.test.cjs :: source-text-is-the-product — readFileSync assertions target API-SURFACE.md, which is the generated product of intelApiSurface; asserting on its text content is the only way to verify correct generation.",
+  "tests/inventory-headings-countfree.test.cjs :: runtime-contract-is-the-product — INVENTORY.md heading format is the shipped doc surface being locked",
+  "tests/ios-scaffold-safety.test.cjs :: source-text-is-the-product",
+  "tests/issue-2639-codex-toml-neutralization.test.cjs :: source-text-is-the-product",
+  "tests/issue-429-comment-text-gate.test.cjs :: source-text-is-the-product",
+  "tests/issue-498-package-identity.test.cjs :: architectural-invariant",
+  "tests/issue-498-update-backup-runtime-dir.test.cjs :: structural assertion on the deployed update.md backup bash;",
+  "tests/issue-57-runtime-install-no-drift.test.cjs :: delegation-presence guard. Catches wholesale removal of the registry",
+  "tests/issue-57-runtime-install-no-drift.test.cjs :: structural guard over bin/install.js source. Behavioral assertions",
+  "tests/issue-607-installer-dry-run.install.test.cjs :: integration-test-input",
+  "tests/issue-607-legacy-cleanup.test.cjs :: integration-test-input",
+  "tests/issue-787-cline-hooks-agents.test.cjs :: source-text-is-the-product",
+  "tests/issue-815-update-next-channel.test.cjs :: reads product workflow/command markdown to verify the --next RC channel contract — not a source-grep test",
+  "tests/locking-bugs-1909-1916-1925-1927.test.cjs :: architectural-invariant",
+  "tests/mcp-tool-inheritance.test.cjs :: source-text-is-the-product",
+  "tests/milestone-summary.test.cjs :: source-text-is-the-product",
+  "tests/milestone.test.cjs :: source-text-is-the-product",
+  "tests/milestone.test.cjs :: structural-regression-guard",
+  "tests/model-catalog-runtime-defaults.test.cjs :: source-text-is-the-product",
+  "tests/next-safety-gates.test.cjs :: source-text-is-the-product",
+  "tests/next-up-clear-order.test.cjs :: source-text-is-the-product",
+  "tests/no-hardcoded-home-gsd-tools.test.cjs :: source-text-is-the-product",
+  "tests/opencode-permissions.test.cjs :: architectural-invariant",
+  "tests/orphan-worktree-detection.test.cjs :: architectural-invariant",
+  "tests/orphaned-hooks.test.cjs :: structural-regression-guard",
+  "tests/package-legitimacy-gate.test.cjs :: source-text-is-the-product",
+  "tests/parallel-dependent-plans.test.cjs :: source-text-is-the-product",
+  "tests/path-replacement.test.cjs :: source-text-is-the-product",
+  "tests/phase-dependency-levels.test.cjs :: source-text-is-the-product",
+  "tests/phase.test.cjs :: source-text-is-the-product",
+  "tests/phase.test.cjs :: state-md-is-the-runtime-contract — regression tests for",
+  "tests/phase6-capability-docs.test.cjs :: source-text-is-the-product",
+  "tests/phase6-capstone-conformance.test.cjs :: source-text-is-the-product",
+  "tests/phase6-planning-capabilities.test.cjs :: source-text-is-the-product",
+  "tests/plan-bounce.test.cjs :: source-text-is-the-product",
+  "tests/plan-phase-drift-guard.test.cjs :: source-text-is-the-product",
+  "tests/plan-phase-ui-redirect.test.cjs :: source-text-is-the-product",
+  "tests/plan-review-convergence.test.cjs :: source-text-is-the-product",
+  "tests/planner-decomposition.test.cjs :: source-text-is-the-product",
+  "tests/planner-language-regression.test.cjs :: source-text-is-the-product",
+  "tests/playwright-ui-verify.test.cjs :: source-text-is-the-product",
+  "tests/policy-160-route0-resume.test.cjs :: source-text-is-the-product",
+  "tests/policy-release-no-npm-self-upgrade.test.cjs :: source-text-is-the-product",
+  "tests/product-name-purity.test.cjs :: source-text-is-the-product",
+  "tests/profile-output.test.cjs :: source-text-is-the-product",
+  "tests/progress-forensic.test.cjs :: source-text-is-the-product",
+  "tests/prompt-budget-cli.test.cjs :: prompt-content-is-the-product",
+  "tests/prompt-thinning.test.cjs :: source-text-is-the-product",
+  "tests/quick-session-management.test.cjs :: source-text-is-the-product",
+  "tests/qwen-skills-migration.test.cjs :: source-text-is-the-product",
+  "tests/read-guard.test.cjs :: source-text-is-the-product",
+  "tests/reapply-patches.test.cjs :: source-text-is-the-product",
+  "tests/reapply-verify-hunks.test.cjs :: source-text-is-the-product",
+  "tests/release-coverage-scope.test.cjs :: source-text-is-the-product",
+  "tests/release-tarball-smoke-workflow.test.cjs :: source-text-is-the-product",
+  "tests/release-tarball-smoke.install.test.cjs :: integration-test-input",
+  "tests/research-agent-profiles.test.cjs :: <runtime-contract-is-the-product> research agent .md content is the governed surface",
+  "tests/review-default-reviewers-workflow.test.cjs :: source-text-is-the-product",
+  "tests/roadmap.test.cjs :: source-text-is-the-product",
+  "tests/roadmapper-granularity.test.cjs :: source-text-is-the-product",
+  "tests/run-tests-harness.test.cjs :: run-tests.cjs is a CLI test harness whose only IR is its",
+  "tests/runtime-launcher-parity.test.cjs :: structural parity/drift guard — asserts literal presence/absence of the canonical gsd_run launcher and the retired $GSD_SDK / `/gsd-tools` tokens across workflow markdown; there is no typed IR for \"this source file does not contain substring X\".",
+  "tests/runtime-name-policy.test.cjs :: runtime-contract-is-the-product — FALLBACK_ALIASES source text IS the",
+  "tests/scan-command.test.cjs :: source-text-is-the-product",
+  "tests/secret-scan-lint.security.test.cjs :: source-text-is-the-product",
+  "tests/secure-phase.test.cjs :: source-text-is-the-product",
+  "tests/security-prompt-injection.security.test.cjs :: structural-regression-guard",
+  "tests/security-scan.security.test.cjs :: source-text-is-the-product",
+  "tests/seed-scan-new-milestone.test.cjs :: source-text-is-the-product",
+  "tests/settings-integrations.test.cjs :: source-text-is-the-product",
+  "tests/settings-jsonc.test.cjs :: structural-regression-guard",
+  "tests/skill-frontmatter-contract.test.cjs :: source-text-is-the-product",
+  "tests/spawn-liveness-banner.test.cjs :: source-text-is-the-product",
+  "tests/state-acquirestatelock-non-eexist.test.cjs :: architectural-invariant",
+  "tests/state.test.cjs :: source-text-is-the-product",
+  "tests/subagent-timeout.test.cjs :: source-text-is-the-product",
+  "tests/template.test.cjs :: source-text-is-the-product",
+  "tests/thinking-partner.test.cjs :: source-text-is-the-product",
+  "tests/thread-session-management.test.cjs :: source-text-is-the-product",
+  "tests/ultraplan-phase.test.cjs :: source-text-is-the-product",
+  "tests/verify-health.test.cjs :: source-text-is-the-product",
+  "tests/verify-test-quality.test.cjs :: source-text-is-the-product",
+  "tests/verify-work-auto-transition.test.cjs :: source-text-is-the-product",
+  "tests/windows-robustness.test.cjs :: source-text-is-the-product",
+  "tests/windows-test-parity-guard.test.cjs :: structural-regression-guard",
+  "tests/workflow-compat.test.cjs :: source-text-is-the-product",
+  "tests/workflow-guard-registration.test.cjs :: structural-regression-guard",
+  "tests/workflow-maintainer-skip.test.cjs :: source-text-is-the-product",
+  "tests/workflow-shell-pinning.test.cjs :: file-scope prefilter, not a test assertion — we need to",
+  "tests/workflow-size-budget.test.cjs :: source-text-is-the-product",
+  "tests/workspace.test.cjs :: source-text-is-the-product",
+  "tests/worktree-cleanup.test.cjs :: source-text-is-the-product",
+  "tests/worktree.test.cjs :: source-text-is-the-product"
+]

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,14 @@
         "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"
     }
   }
 }