chore(#2896): convert CONTEXT.md prose defect registry into enforced gates (#3325)

* chore(#2896): convert CONTEXT.md prose defect registry into enforced gates Squashes the prior 4-commit sequence and fixes defects found while resuming this branch: 5 orphaned/corrupted DEFECT fragment lines left by an earlier botched edit, 17 "Source of truth: Memtrace `find_symbol`" placeholders that had destroyed real file-path citations, and 3 DEFECT.GENERATIVE-* entries merged into one RULESET.GENERATIVE-FIX predicate (policy, not an unenforced defect) to satisfy the zero DEFECT.<NAME>.<field>= acceptance criterion. Six mechanizable defects get real gates: DEFECT.UNBOUNDED-SUBPROCESS (eslint-rules/require-subprocess-timeout.cjs), DEFECT.CANARY-VERSION-LEAK (scripts/lint-canary-version-leak.cjs + version-gate.yml), DEFECT.CHANGESET-PR-FIELD-DRIFT (findPrFieldDrift in changeset/lint.cjs), DEFECT.FRONTMATTER-SCALAR-BROAD-GREP, DEFECT.REMOVED-BUT-NEEDED, and DEFECT.DEFAULT-FLIP-DOCUMENTATION (new lint scripts, wired into lint:ci). Already-enforced and unenforceable prose entries are deleted; the gate is the record. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * chore(#2896): route the new lint tests' subprocess calls through the bounded process-seam helper The 4 new test files for this PR's lint checks called cp.spawnSync/ execFileSync directly with no timeout, tripping this repo's own existing local/no-unbounded-spawn ESLint rule. Route every one through runNode/gitOrThrow (tests/helpers/process-seam.cjs, tests/helpers/git-fixture.cjs) instead, matching the pattern already used elsewhere in the suite (e.g. tests/changeset-lint.test.cjs). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix: register claude-orchestration.cjs and regenerate stale generated indexes Pre-existing drift on next, unrelated to this PR's own change, surfaced by running lint:ci as part of verifying #2896: two cli_modules (claude-orchestration.cjs, write-set.cjs) landed without a manifest regen, and CONTEXT.md's own edits in this PR staled its two generated indexes. Adds the missing docs/INVENTORY.md row for claude-orchestration.cjs (write-set.cjs already had one — only its manifest entry was stale) and regenerates docs/INVENTORY-MANIFEST.json, docs/CONTEXT-INDEX.json, and examples/dynamic-context-management/CONTEXT-INDEX.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#2896): default-flip-documentation lint's local fallback base was main, not next Found in review: every other base-ref fallback in this repo (see scripts/changeset/lint.cjs's DEFAULT_BASE, #2988) defaults to `next`, the integration branch every PR actually targets — `main` is the release branch. This script's local fallback (used only when GITHUB_BASE_REF is unset, i.e. never in CI, but potentially on a local or direct invocation) diffed against the wrong ref. No test exercised the unset-env-var path, so it shipped unnoticed; every e2e test sets GITHUB_BASE_REF explicitly and is unaffected by this fix. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#2896): stale eslint comment, overclaiming CONTEXT.md wording, and an incompletely-regenerated manifest Found by the isolated Standards code-review pass: - eslint.config.mjs's require-subprocess-timeout comment said "'warn' for now... flip to 'error' once migrated" while the rule already shipped as 'error' with all 8 sites migrated in the same commit — described a state that never existed. - The CONTEXT.md pointer block claimed the rule's bounded call sites "never throw", but roadmap-upgrade.cts's pre-mutation clean-tree check correctly still throws on failure (it gates a destructive real-run migration; degrading to "assume clean" would risk clobbering uncommitted work) — softened the claim to describe both shapes accurately instead of overclaiming one. - docs/INVENTORY-MANIFEST.json's claude-orchestration.cjs/write-set.cjs entries from the prior "fix: register claude-orchestration.cjs..." commit didn't actually land — re-running the generator now includes them; lint:generated-sync is green. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * chore(#2896): backfill changeset pr field with the real PR number Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#2896): normalize buildCorpus file paths to POSIX in lint-removed-but-needed Windows CI caught it: path.relative(root, abs) returns backslash- separated paths on Windows, but findSurvivingReferences's package-lock special case does file.startsWith('.github/workflows') — a forward- slash literal. On Windows the check silently never matched, so tests/removed-but-needed-lint.test.cjs's real-defect-shape fixture got exit 0 instead of the expected exit 1. Normalize at the production source (RULESET.CONTENT-PATH-NORMALIZATION) rather than the test side. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-10 12:55:52 -04:00
parent 5339dd60e5
commit bcf7b04864
25 changed files with 2391 additions and 2344 deletions
--- a/tests/canary-version-leak-lint.test.cjs
+++ b/tests/canary-version-leak-lint.test.cjs
@@ -0,0 +1,109 @@
+'use strict';
+process.env.GSD_TEST_MODE = '1';
+
+/**
+ * Canary-version-leak lint (DEFECT.CANARY-VERSION-LEAK, CONTEXT.md).
+ *
+ * scripts/lint-canary-version-leak.cjs fails a run whose package.json
+ * .version carries a -canary.<N> suffix — that suffix belongs to a dev
+ * branch only and must never land on main (2026-05-16 audit: origin/main at
+ * "1.50.0-canary.0", commit 2d32ad82, #3206). Wired into
+ * .github/workflows/version-gate.yml, gated to PRs targeting main.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const fc = require('fast-check');
+
+const ROOT = path.join(__dirname, '..');
+const LINT_SCRIPT = path.join(ROOT, 'scripts', 'lint-canary-version-leak.cjs');
+const { isCanaryVersion, readPackageVersion } = require(LINT_SCRIPT);
+const { cleanup } = require('./helpers.cjs');
+const { runNode } = require('./helpers/process-seam.cjs');
+
+describe('canary-version-leak lint: isCanaryVersion (pure)', () => {
+  test('a plain release version is not canary', () => {
+    assert.equal(isCanaryVersion('1.8.0'), false);
+  });
+
+  test('a -canary.<N> version IS flagged', () => {
+    assert.equal(isCanaryVersion('1.8.0-canary.3'), true);
+  });
+
+  test('boundary: -canary.0 (N=0) is flagged', () => {
+    assert.equal(isCanaryVersion('1.50.0-canary.0'), true);
+  });
+
+  test('a non-canary prerelease suffix (e.g. -rc.1) is not flagged', () => {
+    assert.equal(isCanaryVersion('1.8.0-rc.1'), false);
+  });
+
+  test('non-string input is not flagged (fails closed to false, main() handles missing version separately)', () => {
+    assert.equal(isCanaryVersion(undefined), false);
+    assert.equal(isCanaryVersion(null), false);
+  });
+
+  test('property: appending -canary.<N> to any base string always flags it', () => {
+    fc.assert(
+      fc.property(
+        fc.string().filter((s) => !/-canary\.\d+/.test(s)),
+        fc.nat(),
+        (base, n) => {
+          assert.equal(isCanaryVersion(`${base}-canary.${n}`), true);
+        },
+      ),
+    );
+  });
+
+  test('property: a version with no "-canary." substring is never flagged', () => {
+    fc.assert(
+      fc.property(
+        fc.string().filter((s) => !s.includes('-canary.')),
+        (version) => {
+          assert.equal(isCanaryVersion(version), false);
+        },
+      ),
+    );
+  });
+});
+
+describe('canary-version-leak lint: the live repo package.json is clean', () => {
+  test('readPackageVersion + isCanaryVersion pass against the real package.json', () => {
+    const version = readPackageVersion(ROOT);
+    assert.equal(typeof version, 'string');
+    assert.equal(isCanaryVersion(version), false, `package.json version '${version}' must not carry -canary.<N>`);
+  });
+});
+
+describe('canary-version-leak lint: main() end-to-end wiring', () => {
+  function writeFixtureRoot(version) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-canary-lint-e2e-'));
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({ name: 'fixture', version }), 'utf8');
+    return tmpDir;
+  }
+
+  test('exit 0 on a clean version (real package.json, 1.8.0)', () => {
+    const result = runNode([LINT_SCRIPT], { cwd: ROOT });
+    assert.equal(result.exitCode, 0, `expected exit 0, got ${result.exitCode}: ${result.stderr}`);
+  });
+
+  test('exit 1 on a fixture package.json carrying a -canary.<N> suffix (never touches the real package.json)', (t) => {
+    const tmpDir = writeFixtureRoot('1.8.0-canary.3');
+    t.after(() => cleanup(tmpDir));
+
+    // The script resolves its target as `<script-dir>/../package.json`, so
+    // run a throwaway copy of the script from inside the fixture root
+    // rather than mutating the real repo's package.json.
+    const scriptCopyDir = path.join(tmpDir, 'scripts');
+    fs.mkdirSync(scriptCopyDir, { recursive: true });
+    const scriptCopy = path.join(scriptCopyDir, 'lint-canary-version-leak.cjs');
+    fs.copyFileSync(LINT_SCRIPT, scriptCopy);
+
+    const result = runNode([scriptCopy]);
+    assert.equal(result.exitCode, 1, `expected exit 1, got ${result.exitCode}`);
+    assert.match(result.stderr, /canary-version-leak/);
+  });
+});
--- a/tests/changeset-lint.test.cjs
+++ b/tests/changeset-lint.test.cjs
@@ -7,7 +7,7 @@ const path = require('node:path');
 const fs = require('node:fs');
 const os = require('node:os');

-const { evaluateLint, LINT_REASON, DEFAULT_BASE: CHANGESET_DEFAULT_BASE } = require(path.join(__dirname, '..', 'scripts', 'changeset', 'lint.cjs'));
+const { evaluateLint, LINT_REASON, findPrFieldDrift, DEFAULT_BASE: CHANGESET_DEFAULT_BASE } = require(path.join(__dirname, '..', 'scripts', 'changeset', 'lint.cjs'));
 const { DEFAULT_BASE: DOCS_DEFAULT_BASE } = require(path.join(__dirname, '..', 'scripts', 'lint-docs-required.cjs'));

 const ROOT = path.join(__dirname, '..');
@@ -87,6 +87,31 @@ function runLint(repoDir) {
  return { status: result.exitCode, report };
 }

+/**
+ * Like runLint, but with a real GITHUB_EVENT_PATH pointing at a synthetic PR
+ * event payload — needed to exercise DEFECT.CHANGESET-PR-FIELD-DRIFT, which
+ * compares each fragment's `pr:` against `event.pull_request.number`.
+ * @param {string} repoDir
+ * @param {number|undefined} prNumber - omit to simulate a push/non-PR run
+ *   (no `pull_request` key in the payload at all).
+ */
+function runLintWithPrEvent(repoDir, prNumber) {
+  const eventPath = path.join(repoDir, 'event.json');
+  const payload = prNumber === undefined ? {} : { pull_request: { number: prNumber, labels: [] } };
+  fs.writeFileSync(eventPath, JSON.stringify(payload));
+  const result = runNode(
+    [LINT_SCRIPT, '--json'],
+    {
+      cwd: repoDir,
+      env: { ...process.env, GITHUB_BASE_REF: 'main', GITHUB_EVENT_PATH: eventPath },
+      timeoutMs: PROBE_TIMEOUT_MS,
+    },
+  );
+  let report = {};
+  try { report = JSON.parse(result.stdout); } catch { /* leave as empty object */ }
+  return { status: result.exitCode, report };
+}
+
 // evaluateLint is a pure function over file lists + label list — no fs, no git.
 // Tests assert on the structured verdict: { ok: bool, reason: LINT_REASON.X }.

@@ -94,7 +119,10 @@ describe('changeset lint: pure verdict (#2975)', () => {
  test('LINT_REASON enum exposes the documented codes', () => {
    assert.deepEqual(
      Object.keys(LINT_REASON).sort(),
-      ['OK_FRAGMENT_PRESENT', 'OK_NO_USER_FACING_CHANGES', 'OK_OPT_OUT_LABEL', 'FAIL_MISSING_FRAGMENT', 'FAIL_INVALID_FRAGMENT'].sort(),
+      [
+        'OK_FRAGMENT_PRESENT', 'OK_NO_USER_FACING_CHANGES', 'OK_OPT_OUT_LABEL',
+        'FAIL_MISSING_FRAGMENT', 'FAIL_INVALID_FRAGMENT', 'FAIL_PR_FIELD_DRIFT',
+      ].sort(),
    );
  });

@@ -175,6 +203,57 @@ describe('changeset lint: pure verdict (#2975)', () => {
    assert.equal(verdict.ok, false);
    assert.equal(verdict.reason, LINT_REASON.FAIL_INVALID_FRAGMENT);
  });
+
+  test('FAIL_PR_FIELD_DRIFT when prFieldDrift is non-empty, even with a fragment present', () => {
+    const verdict = evaluateLint({
+      changedFiles: ['.changeset/good.md'],
+      labels: [],
+      prFieldDrift: [{ file: '.changeset/good.md', found: 1234, expected: 1240 }],
+    });
+    assert.equal(verdict.ok, false);
+    assert.equal(verdict.reason, LINT_REASON.FAIL_PR_FIELD_DRIFT);
+    assert.deepEqual(verdict.drift, [{ file: '.changeset/good.md', found: 1234, expected: 1240 }]);
+  });
+
+  test('FAIL_INVALID_FRAGMENT beats FAIL_PR_FIELD_DRIFT (checked first)', () => {
+    const verdict = evaluateLint({
+      changedFiles: ['.changeset/bad.md'],
+      labels: [],
+      fragmentFailures: [{ file: '.changeset/bad.md', reason: 'invalid_pr', detail: '0' }],
+      prFieldDrift: [{ file: '.changeset/bad.md', found: 1, expected: 2 }],
+    });
+    assert.equal(verdict.reason, LINT_REASON.FAIL_INVALID_FRAGMENT);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DEFECT.CHANGESET-PR-FIELD-DRIFT (#3316, #3325): a fragment's pr: field is a
+// guess (issue number, stacked-PR leftover) that never got backfilled to the
+// real PR number.
+// ---------------------------------------------------------------------------
+describe('changeset lint: findPrFieldDrift (pure)', () => {
+  test('a fragment whose pr matches the real PR number is not drift', () => {
+    assert.deepEqual(findPrFieldDrift([{ file: '.changeset/good.md', pr: 1234 }], 1234), []);
+  });
+
+  test('a fragment whose pr disagrees with the real PR number IS flagged, naming the file', () => {
+    const drift = findPrFieldDrift([{ file: '.changeset/stale.md', pr: 1234 }], 1240);
+    assert.deepEqual(drift, [{ file: '.changeset/stale.md', found: 1234, expected: 1240 }]);
+  });
+
+  test('realPrNumber === null (no PR event payload) always yields no drift — push/non-PR runs never fail', () => {
+    assert.deepEqual(findPrFieldDrift([{ file: '.changeset/anything.md', pr: 999 }], null), []);
+  });
+
+  test('a pr: 0 placeholder entry is silent even when it disagrees with a real, non-zero PR number', () => {
+    // CONTRIBUTING.md documents pr:0 as the deliberate placeholder used
+    // "during initial commit" before the real PR number is backfilled — it
+    // is unbackfilled, not drifted, so it must never be flagged. (In the
+    // real main() wiring, parseFragment already rejects pr:0 upstream as
+    // invalid_pr before a fragment reaches this function at all — this test
+    // locks in the pure function's own contract independent of that.)
+    assert.deepEqual(findPrFieldDrift([{ file: '.changeset/placeholder.md', pr: 0 }], 1234), []);
+  });
 });

 // ---------------------------------------------------------------------------
@@ -315,3 +394,76 @@ describe('#2988: changeset + docs lints resolve the same local base fallback', (
      `the two lints must not diverge on base resolution: changeset='${CHANGESET_DEFAULT_BASE}' docs='${DOCS_DEFAULT_BASE}'`);
  });
 });
+
+// ---------------------------------------------------------------------------
+// DEFECT.CHANGESET-PR-FIELD-DRIFT end-to-end: real main() wiring reading
+// GITHUB_EVENT_PATH's pull_request.number and comparing it against each
+// changed fragment's pr: field.
+// ---------------------------------------------------------------------------
+describe('changeset lint: PR-field-drift end-to-end wiring', () => {
+  test('correct pr: (matches the real PR number) passes the gate', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-lint-e2e-'));
+    t.after(() => cleanup(tmpDir));
+
+    buildTempRepo(tmpDir, [
+      { file: 'bin/thing.js', content: '// placeholder\n' },
+      { file: '.changeset/good.md', content: '---\ntype: Fixed\npr: 4242\n---\n**Good** fix. (#4242)\n' },
+    ]);
+
+    const { status, report } = runLintWithPrEvent(tmpDir, 4242);
+
+    assert.equal(status, 0, `expected exit 0, got ${status}: ${JSON.stringify(report)}`);
+    assert.equal(report.reason, LINT_REASON.OK_FRAGMENT_PRESENT);
+  });
+
+  test('wrong pr: (stale/guessed number) fails the gate, naming the offending file', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-lint-e2e-'));
+    t.after(() => cleanup(tmpDir));
+
+    buildTempRepo(tmpDir, [
+      { file: 'bin/thing.js', content: '// placeholder\n' },
+      { file: '.changeset/stale.md', content: '---\ntype: Fixed\npr: 3312\n---\n**Stale pr field** fix. (#3316)\n' },
+    ]);
+
+    const { status, report } = runLintWithPrEvent(tmpDir, 3316);
+
+    assert.equal(status, 1, `expected exit 1, got ${status}`);
+    assert.equal(report.reason, LINT_REASON.FAIL_PR_FIELD_DRIFT);
+    assert.ok(Array.isArray(report.drift), 'drift must be an array');
+    const entry = report.drift.find((d) => d.file.endsWith('.changeset/stale.md'));
+    assert.ok(entry, `drift must name the offending file, got: ${JSON.stringify(report.drift)}`);
+    assert.equal(entry.found, 3312);
+    assert.equal(entry.expected, 3316);
+  });
+
+  test('no PR event payload (push / non-PR run) skips the drift check entirely, even with a stale pr:', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-lint-e2e-'));
+    t.after(() => cleanup(tmpDir));
+
+    buildTempRepo(tmpDir, [
+      { file: 'bin/thing.js', content: '// placeholder\n' },
+      { file: '.changeset/anything.md', content: '---\ntype: Fixed\npr: 999\n---\n**Anything** fix. (#999)\n' },
+    ]);
+
+    // runLint() (no override) sets GITHUB_EVENT_PATH: '' — no payload at all.
+    const { status, report } = runLint(tmpDir);
+
+    assert.equal(status, 0, `expected exit 0, got ${status}: ${JSON.stringify(report)}`);
+    assert.equal(report.reason, LINT_REASON.OK_FRAGMENT_PRESENT);
+  });
+
+  test('event payload present but with no pull_request key (also push-shaped) skips the drift check', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-lint-e2e-'));
+    t.after(() => cleanup(tmpDir));
+
+    buildTempRepo(tmpDir, [
+      { file: 'bin/thing.js', content: '// placeholder\n' },
+      { file: '.changeset/anything.md', content: '---\ntype: Fixed\npr: 999\n---\n**Anything** fix. (#999)\n' },
+    ]);
+
+    const { status, report } = runLintWithPrEvent(tmpDir, undefined);
+
+    assert.equal(status, 0, `expected exit 0, got ${status}: ${JSON.stringify(report)}`);
+    assert.equal(report.reason, LINT_REASON.OK_FRAGMENT_PRESENT);
+  });
+});
--- a/tests/default-flip-documentation-lint.test.cjs
+++ b/tests/default-flip-documentation-lint.test.cjs
@@ -0,0 +1,197 @@
+'use strict';
+process.env.GSD_TEST_MODE = '1';
+
+/**
+ * Default-flip-documentation lint (DEFECT.DEFAULT-FLIP-DOCUMENTATION,
+ * CONTEXT.md).
+ *
+ * scripts/lint-default-flip-documentation.cjs fails a PR that changes an
+ * EXISTING default value in gsd-core/bin/shared/config-defaults.manifest.json
+ * (the single source `CONFIG_DEFAULTS` loads at runtime) without a
+ * `## Breaking Changes` PR-body section covering the migration semantics
+ * (#3309: the v2 default flip from mid-flight to end-of-phase).
+ *
+ * Scope note: this check is deliberately narrower than the full DEFECT text
+ * — it does NOT cover `buildNewProjectConfig`'s hardcoded object literal in
+ * src/config.cts, because that literal mixes env-derived branches with
+ * CONFIG_DEFAULTS spreads and cannot be reduced to a resolved value map from
+ * source text alone without executing the compiled module at both refs. A
+ * line/text diff of that literal would inherit the exact false-positive
+ * risk (a harmless refactor reading as a "flip") this check exists to
+ * avoid, so it is left out rather than shipped noisy. See the script's own
+ * header comment for the full rationale.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+const LINT_SCRIPT = path.join(ROOT, 'scripts', 'lint-default-flip-documentation.cjs');
+const { flatten, findDefaultValueChanges, evaluateDefaultFlipDoc, MANIFEST_PATH } = require(LINT_SCRIPT);
+const { cleanup } = require('./helpers.cjs');
+const { runNode } = require('./helpers/process-seam.cjs');
+const { gitOrThrow } = require('./helpers/git-fixture.cjs');
+
+describe('default-flip-documentation lint: flatten (pure)', () => {
+  test('flattens a nested object into dot-path leaves', () => {
+    assert.deepEqual(
+      flatten({ workflow: { human_verify_mode: 'end-of-phase' }, model_profile: 'balanced' }),
+      { 'workflow.human_verify_mode': 'end-of-phase', model_profile: 'balanced' },
+    );
+  });
+
+  test('an array is a leaf, not recursed into (reordering reads as one change, not N)', () => {
+    assert.deepEqual(flatten({ tags: ['a', 'b'] }), { tags: ['a', 'b'] });
+  });
+});
+
+describe('default-flip-documentation lint: findDefaultValueChanges (pure)', () => {
+  test('the real #3309 defect shape IS a change: an existing key value differs', () => {
+    const changes = findDefaultValueChanges(
+      { 'workflow.human_verify_mode': 'mid-flight' },
+      { 'workflow.human_verify_mode': 'end-of-phase' },
+    );
+    assert.deepEqual(changes, [{ key: 'workflow.human_verify_mode', from: 'mid-flight', to: 'end-of-phase' }]);
+  });
+
+  test('LOOKALIKE: a brand-new key (addition, not a flip) is NOT a change', () => {
+    const changes = findDefaultValueChanges({ a: 1 }, { a: 1, b: 2 });
+    assert.deepEqual(changes, []);
+  });
+
+  test('LOOKALIKE: a removed key (not a flip either) is NOT a change', () => {
+    const changes = findDefaultValueChanges({ a: 1, b: 2 }, { a: 1 });
+    assert.deepEqual(changes, []);
+  });
+
+  test('LOOKALIKE: the whole object reordered/restructured with identical resolved values is NOT a change (the false-positive the audit called out)', () => {
+    const base = { workflow: { a: 1, b: 2 }, git: { create_tag: true } };
+    const head = { git: { create_tag: true }, workflow: { b: 2, a: 1 } };
+    assert.deepEqual(findDefaultValueChanges(flatten(base), flatten(head)), []);
+  });
+
+  test('an unchanged value is not reported', () => {
+    assert.deepEqual(findDefaultValueChanges({ a: 1 }, { a: 1 }), []);
+  });
+});
+
+describe('default-flip-documentation lint: evaluateDefaultFlipDoc (pure)', () => {
+  test('no changes: always ok regardless of PR body', () => {
+    assert.equal(evaluateDefaultFlipDoc([], '').ok, true);
+  });
+
+  test('a real flip with no Breaking Changes section in the PR body fails', () => {
+    const verdict = evaluateDefaultFlipDoc([{ key: 'x', from: 1, to: 2 }], 'just a normal PR description');
+    assert.equal(verdict.ok, false);
+  });
+
+  test('a real flip WITH a "## Breaking Changes" heading in the PR body passes', () => {
+    const verdict = evaluateDefaultFlipDoc(
+      [{ key: 'x', from: 1, to: 2 }],
+      'Summary\n\n## Breaking Changes\n\nNew default takes effect on config-set.',
+    );
+    assert.equal(verdict.ok, true);
+  });
+
+  test('the heading match is case-insensitive and tolerates heading level', () => {
+    const verdict = evaluateDefaultFlipDoc([{ key: 'x', from: 1, to: 2 }], '# breaking changes\ndetails');
+    assert.equal(verdict.ok, true);
+  });
+});
+
+describe('default-flip-documentation lint: main() end-to-end wiring', () => {
+  const git = (dir, ...args) => gitOrThrow(args, { cwd: dir });
+
+  function buildRepo(tmpDir, baseManifest, headManifest) {
+    git(tmpDir, 'init', '-q', '-b', 'main');
+    git(tmpDir, 'config', 'user.email', 'test@example.com');
+    git(tmpDir, 'config', 'user.name', 'Test');
+    const manifestAbs = path.join(tmpDir, MANIFEST_PATH);
+    fs.mkdirSync(path.dirname(manifestAbs), { recursive: true });
+    fs.writeFileSync(manifestAbs, JSON.stringify(baseManifest));
+    git(tmpDir, 'add', '-A');
+    git(tmpDir, 'commit', '-q', '-m', 'base');
+    git(tmpDir, 'update-ref', 'refs/remotes/origin/main', 'HEAD');
+
+    git(tmpDir, 'checkout', '-q', '-b', 'pr');
+    fs.writeFileSync(manifestAbs, JSON.stringify(headManifest));
+    git(tmpDir, 'add', '-A');
+    git(tmpDir, 'commit', '-q', '-m', 'pr');
+
+    const scriptsDir = path.join(tmpDir, 'scripts');
+    const libDir = path.join(scriptsDir, 'lib');
+    fs.mkdirSync(libDir, { recursive: true });
+    const scriptCopy = path.join(scriptsDir, 'lint-default-flip-documentation.cjs');
+    fs.copyFileSync(LINT_SCRIPT, scriptCopy);
+    fs.copyFileSync(path.join(ROOT, 'scripts', 'lib', 'cli-exit.cjs'), path.join(libDir, 'cli-exit.cjs'));
+    return scriptCopy;
+  }
+
+  function runWithPrBody(tmpDir, scriptCopy, prBody) {
+    const eventPath = path.join(tmpDir, 'event.json');
+    fs.writeFileSync(eventPath, JSON.stringify({ pull_request: { body: prBody } }));
+    return runNode(
+      [scriptCopy],
+      {
+        cwd: tmpDir,
+        env: { ...process.env, GITHUB_BASE_REF: 'main', GITHUB_EVENT_PATH: eventPath },
+      },
+    );
+  }
+
+  test('exit 1: a flipped default with no Breaking Changes section in the PR body', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-default-flip-e2e-'));
+    t.after(() => cleanup(tmpDir));
+    const scriptCopy = buildRepo(
+      tmpDir,
+      { workflow: { human_verify_mode: 'mid-flight' } },
+      { workflow: { human_verify_mode: 'end-of-phase' } },
+    );
+    const result = runWithPrBody(tmpDir, scriptCopy, 'Flips the default. No migration notes.');
+    assert.equal(result.exitCode, 1, `expected exit 1, got ${result.exitCode}: ${result.stderr}`);
+    assert.match(result.stderr, /DEFAULT-FLIP-DOCUMENTATION/);
+  });
+
+  test('exit 0: a flipped default WITH a Breaking Changes section', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-default-flip-e2e-doc-'));
+    t.after(() => cleanup(tmpDir));
+    const scriptCopy = buildRepo(
+      tmpDir,
+      { workflow: { human_verify_mode: 'mid-flight' } },
+      { workflow: { human_verify_mode: 'end-of-phase' } },
+    );
+    const result = runWithPrBody(
+      tmpDir,
+      scriptCopy,
+      '## Breaking Changes\n\nNew default takes effect when config.json is regenerated; opt back in with `gsd config-set workflow.human_verify_mode mid-flight`.',
+    );
+    assert.equal(result.exitCode, 0, `expected exit 0, got ${result.exitCode}: ${result.stderr}`);
+  });
+
+  test('LOOKALIKE: manifest restructured/reformatted with identical resolved values does NOT fail, even with no Breaking Changes section', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-default-flip-e2e-reformat-'));
+    t.after(() => cleanup(tmpDir));
+    const scriptCopy = buildRepo(
+      tmpDir,
+      { a: 1, workflow: { x: true, y: false } },
+      { workflow: { y: false, x: true }, a: 1 },
+    );
+    const result = runWithPrBody(tmpDir, scriptCopy, 'Pure reformat, no PR body sections at all.');
+    assert.equal(result.exitCode, 0, `expected exit 0 (no real value change), got ${result.exitCode}: ${result.stderr}`);
+  });
+
+  test('exit 0 and skip when there is no PR event payload (push / local run)', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-default-flip-e2e-noevent-'));
+    t.after(() => cleanup(tmpDir));
+    const scriptCopy = buildRepo(tmpDir, { a: 1 }, { a: 2 });
+    const result = runNode(
+      [scriptCopy],
+      { cwd: tmpDir, env: { ...process.env, GITHUB_BASE_REF: 'main', GITHUB_EVENT_PATH: '' } },
+    );
+    assert.equal(result.exitCode, 0, `expected exit 0, got ${result.exitCode}: ${result.stderr}`);
+    assert.match(result.stdout, /skipping/);
+  });
+});
--- a/tests/eslint-rules.test.cjs
+++ b/tests/eslint-rules.test.cjs
@@ -9,6 +9,7 @@
 *   - local/no-elapsed-assertion
 *   - local/no-raw-rmsync-in-tests
 *   - local/no-adhoc-markdown-parsing
+ *   - local/require-subprocess-timeout
 */

 const { test, describe } = require('node:test');
@@ -24,6 +25,7 @@ const noRawRmsyncInTests = require('../eslint-rules/no-raw-rmsync-in-tests.cjs')
 const noTautologicalAssert = require('../eslint-rules/no-tautological-assert.cjs');
 const noAdhocMarkdownParsing = require('../eslint-rules/no-adhoc-markdown-parsing.cjs');
 const noDuplicateFoldMarker = require('../eslint-rules/no-duplicate-fold-marker.cjs');
+const requireSubprocessTimeout = require('../eslint-rules/require-subprocess-timeout.cjs');

 const ruleTester = new RuleTester({
  languageOptions: {
@@ -1592,7 +1594,7 @@ describe('no-adhoc-markdown-parsing rule', () => {
  });
 });

-// ─── no-duplicate-fold-marker ────────────────────────────────────────────────
+// ─── no-duplicate-fold-marker ────────────────────────────────────────

 describe('no-duplicate-fold-marker rule', () => {
  const REPO_ROOT = path.join(__dirname, '..');
@@ -1962,3 +1964,145 @@ describe('no-duplicate-fold-marker rule', () => {
    );
  });
 });
+
+// ─── require-subprocess-timeout ────────────────────────────────────
+
+describe('require-subprocess-timeout rule', () => {
+  test('rule module exports a create function', () => {
+    assert.strictEqual(typeof requireSubprocessTimeout.create, 'function');
+  });
+
+  // ── INVALID cases (must error) ────────────────────────────────────────────
+
+  test('invalid: execFileSync("git", args, { cwd }) — object-literal options with no timeout key', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [],
+      invalid: [
+        {
+          code: `
+            const { execFileSync } = require('node:child_process');
+            const args = ['status'];
+            const cwd = '/repo';
+            execFileSync('git', args, { cwd });
+          `,
+          filename: 'src/some-module.cts',
+          errors: [{ messageId: 'requireSubprocessTimeout' }],
+        },
+      ],
+    });
+  });
+
+  test('invalid: execSync("npm ci", { encoding: "utf8" }) — object-literal options with no timeout key', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [],
+      invalid: [
+        {
+          code: `
+            const { execSync } = require('node:child_process');
+            execSync('npm ci', { encoding: 'utf8' });
+          `,
+          filename: 'src/some-module.cts',
+          errors: [{ messageId: 'requireSubprocessTimeout' }],
+        },
+      ],
+    });
+  });
+
+  test('invalid: spawnSync with a dotted childProcess.spawnSync callee and no timeout', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [],
+      invalid: [
+        {
+          code: `
+            const childProcess = require('node:child_process');
+            childProcess.spawnSync('git', ['log'], { cwd: '/repo', encoding: 'utf-8' });
+          `,
+          filename: 'src/some-module.cts',
+          errors: [{ messageId: 'requireSubprocessTimeout' }],
+        },
+      ],
+    });
+  });
+
+  test('invalid: execFileSync with NO options argument at all — categorically no timeout', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [],
+      invalid: [
+        {
+          code: `
+            const { execFileSync } = require('node:child_process');
+            execFileSync('git', ['status']);
+          `,
+          filename: 'src/some-module.cts',
+          errors: [{ messageId: 'requireSubprocessTimeout' }],
+        },
+      ],
+    });
+  });
+
+  // ── VALID cases (must NOT error) ──────────────────────────────────────────
+
+  test('valid: execFileSync("git", args, { cwd, timeout: 30000 }) — timeout key present', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [
+        {
+          code: `
+            const { execFileSync } = require('node:child_process');
+            const args = ['status'];
+            const cwd = '/repo';
+            execFileSync('git', args, { cwd, timeout: 30000 });
+          `,
+          filename: 'src/some-module.cts',
+        },
+      ],
+      invalid: [],
+    });
+  });
+
+  test('valid: options as a pre-built identifier — execFileSync("git", args, opts) is not traced', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [
+        {
+          code: `
+            const { execFileSync } = require('node:child_process');
+            const args = ['status'];
+            const opts = { cwd: '/repo', timeout: 30000 };
+            execFileSync('git', args, opts);
+          `,
+          filename: 'src/some-module.cts',
+        },
+      ],
+      invalid: [],
+    });
+  });
+
+  test('valid: same unbounded call under a tests/** filename — rule is inert outside src/*.cts', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [
+        {
+          code: `
+            const { execFileSync } = require('node:child_process');
+            execFileSync('git', ['status'], { cwd: '/repo' });
+          `,
+          filename: 'tests/foo.test.cjs',
+        },
+      ],
+      invalid: [],
+    });
+  });
+
+  test('valid: allow-unbounded-subprocess suppression comment on the call line', () => {
+    ruleTester.run('require-subprocess-timeout', requireSubprocessTimeout, {
+      valid: [
+        {
+          code: `
+            const { execFileSync } = require('node:child_process');
+            execFileSync('git', ['status'], { cwd: '/repo' }); // allow-unbounded-subprocess: bounded by caller's own watchdog
+          `,
+          filename: 'src/some-module.cts',
+        },
+      ],
+      invalid: [],
+    });
+  });
+});
--- a/tests/lint-frontmatter-scalar-broad-grep.test.cjs
+++ b/tests/lint-frontmatter-scalar-broad-grep.test.cjs
@@ -0,0 +1,181 @@
+'use strict';
+process.env.GSD_TEST_MODE = '1';
+
+/**
+ * Frontmatter-scalar-broad-grep lint (DEFECT.FRONTMATTER-SCALAR-BROAD-GREP,
+ * CONTEXT.md).
+ *
+ * scripts/lint-frontmatter-scalar-broad-grep.cjs flags a `grep "^key:"` over
+ * a whole markdown report (not scoped to the frontmatter block, no -m1/
+ * `head -1` single-match guard) whose result feeds an exact-token comparison
+ * — the #586/#651 bug class where a body line beginning `key:` concatenates
+ * onto the intended frontmatter value and misroutes a valid state.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+const LINT_SCRIPT = path.join(ROOT, 'scripts', 'lint-frontmatter-scalar-broad-grep.cjs');
+const { findBroadGrepsInBlock, extractBashBlocks, scan } = require(LINT_SCRIPT);
+const { cleanup } = require('./helpers.cjs');
+const { runNode } = require('./helpers/process-seam.cjs');
+
+describe('frontmatter-scalar-broad-grep lint: findBroadGrepsInBlock (pure)', () => {
+  test('the real #586/#651 defect shape IS flagged: whole-file grep, no scope, no -m1, piped to cut|tr', () => {
+    const lines = [
+      'grep "^status:" "${QUICK_DIR}/${quick_id}-VERIFICATION.md" | cut -d: -f2 | tr -d \' \'',
+    ];
+    const findings = findBroadGrepsInBlock(lines);
+    assert.equal(findings.length, 1);
+    assert.equal(findings[0].key, 'status');
+  });
+
+  test('a variable captured from a broad grep and later compared with == is also flagged', () => {
+    const lines = [
+      'STATUS=$(grep "^status:" "$FILE")',
+      'if [ "$STATUS" == "passed" ]; then echo ok; fi',
+    ];
+    const findings = findBroadGrepsInBlock(lines);
+    assert.equal(findings.length, 1);
+  });
+
+  test('LOOKALIKE: sed-scoped to the frontmatter block is NOT flagged', () => {
+    const lines = [
+      'sed -n \'/^---$/,/^---$/p\' "$f" | grep -m1 "^status:" | cut -d: -f2 | tr -d \' \'',
+    ];
+    assert.deepEqual(findBroadGrepsInBlock(lines), []);
+  });
+
+  test('LOOKALIKE: -m1 on the grep itself is NOT flagged even without a preceding scope', () => {
+    const lines = [
+      'grep -m1 "^status:" "$FILE" | cut -d: -f2 | tr -d \' \'',
+    ];
+    assert.deepEqual(findBroadGrepsInBlock(lines), []);
+  });
+
+  test('LOOKALIKE: piped to `head -1` immediately after grep is NOT flagged (frontmatter is always first)', () => {
+    const lines = [
+      'AUDIT_STATUS=$(grep "^status:" "${AUDIT_FILE}" 2>/dev/null | head -1 | cut -d: -f2 | tr -d \' \')',
+    ];
+    assert.deepEqual(findBroadGrepsInBlock(lines), []);
+  });
+
+  test('LOOKALIKE: a frontmatter block already extracted into a variable (JS regex idiom), then multiple keys parsed from it', () => {
+    const lines = [
+      'FRONTMATTER=$(node -e "',
+      '  const m = content.match(/^---\\n([\\s\\S]*?)\\n---/);',
+      '  if (m) process.stdout.write(m[1]);',
+      '")',
+      'STATUS=$(echo "$FRONTMATTER" | grep "^status:" | cut -d: -f2 | xargs)',
+      'FILES_REVIEWED=$(echo "$FRONTMATTER" | grep "^files_reviewed:" | cut -d: -f2 | xargs)',
+    ];
+    assert.deepEqual(findBroadGrepsInBlock(lines), []);
+  });
+
+  test('LOOKALIKE: an explicit `# lint-allow:` suppression comment silences the finding', () => {
+    const lines = [
+      '# lint-allow: frontmatter-scalar-broad-grep — intentional multi-file scan, not a single report',
+      'grep "^status:" reports/*.md | cut -d: -f2 | tr -d \' \'',
+    ];
+    assert.deepEqual(findBroadGrepsInBlock(lines), []);
+  });
+
+  test('a grep not piped to cut/tr and never compared is NOT flagged (not a token-comparison use)', () => {
+    const lines = ['grep -c "^status:" "$FILE"'];
+    assert.deepEqual(findBroadGrepsInBlock(lines), []);
+  });
+});
+
+describe('frontmatter-scalar-broad-grep lint: extractBashBlocks (pure)', () => {
+  test('extracts a fenced ```bash block and reports its 1-indexed start line', () => {
+    const text = [
+      'intro',
+      '```bash',
+      'echo hi',
+      '```',
+      'outro',
+    ].join('\n');
+    const blocks = extractBashBlocks(text);
+    assert.equal(blocks.length, 1);
+    assert.equal(blocks[0].startLine, 3);
+    assert.deepEqual(blocks[0].lines, ['echo hi']);
+  });
+
+  test('a non-bash fenced block (e.g. ```json) is ignored', () => {
+    const text = ['```json', '{"a":1}', '```'].join('\n');
+    assert.deepEqual(extractBashBlocks(text), []);
+  });
+});
+
+describe('frontmatter-scalar-broad-grep lint: the live repo is clean', () => {
+  test('scan() finds zero offenders in the real workflow/agent/command markdown', () => {
+    const offenders = scan();
+    assert.deepEqual(
+      offenders,
+      [],
+      'un-scoped frontmatter-scalar grep(s) found:\n' + offenders.map((o) => `  ${o.file}:${o.line}  ${o.snippet}`).join('\n'),
+    );
+  });
+});
+
+describe('frontmatter-scalar-broad-grep lint: main() end-to-end wiring', () => {
+  test('exit 0 on the real repo tree', () => {
+    const result = runNode([LINT_SCRIPT], { cwd: ROOT });
+    assert.equal(result.exitCode, 0, `expected exit 0, got ${result.exitCode}: ${result.stderr}`);
+  });
+
+  test('exit 1 on a fixture reproducing the real defect shape', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-frontmatter-grep-lint-e2e-'));
+    t.after(() => cleanup(tmpDir));
+    const workflowsDir = path.join(tmpDir, 'gsd-core', 'workflows');
+    fs.mkdirSync(workflowsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(workflowsDir, 'quick.md'),
+      [
+        '# Quick',
+        '```bash',
+        'grep "^status:" "${QUICK_DIR}/${quick_id}-VERIFICATION.md" | cut -d: -f2 | tr -d \' \'',
+        '```',
+      ].join('\n'),
+    );
+    const scriptCopyDir = path.join(tmpDir, 'scripts');
+    fs.mkdirSync(scriptCopyDir, { recursive: true });
+    const scriptCopy = path.join(scriptCopyDir, 'lint-frontmatter-scalar-broad-grep.cjs');
+    fs.copyFileSync(LINT_SCRIPT, scriptCopy);
+    fs.mkdirSync(path.join(scriptCopyDir, 'lib'), { recursive: true });
+    fs.copyFileSync(path.join(ROOT, 'scripts', 'lib', 'cli-exit.cjs'), path.join(scriptCopyDir, 'lib', 'cli-exit.cjs'));
+
+    const result = runNode([scriptCopy]);
+    assert.equal(result.exitCode, 1, `expected exit 1, got ${result.exitCode}`);
+    assert.match(result.stderr, /FRONTMATTER-SCALAR-BROAD-GREP/);
+  });
+
+  test('exit 0 on a fixture that is properly scoped (no false positive)', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-frontmatter-grep-lint-e2e-clean-'));
+    t.after(() => cleanup(tmpDir));
+    const workflowsDir = path.join(tmpDir, 'gsd-core', 'workflows');
+    fs.mkdirSync(workflowsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(workflowsDir, 'quick.md'),
+      [
+        '# Quick',
+        '```bash',
+        'sed -n \'/^---$/,/^---$/p\' "$f" | grep -m1 "^status:" | cut -d: -f2 | tr -d \' \'',
+        '```',
+      ].join('\n'),
+    );
+    const scriptCopyDir = path.join(tmpDir, 'scripts');
+    fs.mkdirSync(scriptCopyDir, { recursive: true });
+    const scriptCopy = path.join(scriptCopyDir, 'lint-frontmatter-scalar-broad-grep.cjs');
+    fs.copyFileSync(LINT_SCRIPT, scriptCopy);
+    fs.mkdirSync(path.join(scriptCopyDir, 'lib'), { recursive: true });
+    fs.copyFileSync(path.join(ROOT, 'scripts', 'lib', 'cli-exit.cjs'), path.join(scriptCopyDir, 'lib', 'cli-exit.cjs'));
+
+    const result = runNode([scriptCopy]);
+    assert.equal(result.exitCode, 0, `expected exit 0, got ${result.exitCode}: ${result.stderr}`);
+  });
+});
--- a/tests/removed-but-needed-lint.test.cjs
+++ b/tests/removed-but-needed-lint.test.cjs
@@ -0,0 +1,229 @@
+'use strict';
+process.env.GSD_TEST_MODE = '1';
+
+/**
+ * Removed-but-needed lint (DEFECT.REMOVED-BUT-NEEDED, CONTEXT.md).
+ *
+ * scripts/lint-removed-but-needed.cjs fails a PR that deletes a file while a
+ * live consumer (a workflow, docs, or package.json) still references it —
+ * #3316 (root package-lock.json deleted while workflows still used
+ * `cache: 'npm'` + `npm ci`), e3b52c70 (docs referenced a removed
+ * `/gsd-new-workspace` workflow).
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+const LINT_SCRIPT = path.join(ROOT, 'scripts', 'lint-removed-but-needed.cjs');
+const { referencesBasename, referencesNpmLockfileDependency, findSurvivingReferences, scan } = require(LINT_SCRIPT);
+const { cleanup } = require('./helpers.cjs');
+const { runNode } = require('./helpers/process-seam.cjs');
+const { gitOrThrow } = require('./helpers/git-fixture.cjs');
+
+describe('removed-but-needed lint: referencesBasename (pure)', () => {
+  test('a plain filename reference in prose is found', () => {
+    assert.equal(referencesBasename('see docs/gsd-new-workspace.md for details', 'gsd-new-workspace.md'), true);
+  });
+
+  test('no reference at all is not found', () => {
+    assert.equal(referencesBasename('nothing to see here', 'gsd-new-workspace.md'), false);
+  });
+
+  test('a coincidental substring inside a different filename is NOT a false match (word-boundary guard)', () => {
+    assert.equal(referencesBasename('old-config.json.bak lives here', 'config.json'), false);
+  });
+
+  test('a path-embedded reference (with separators) IS found', () => {
+    assert.equal(referencesBasename('run: node scripts/gsd-new-workspace.cjs', 'gsd-new-workspace.cjs'), true);
+  });
+});
+
+describe('removed-but-needed lint: referencesNpmLockfileDependency (pure)', () => {
+  test('`npm ci` is flagged', () => {
+    assert.equal(referencesNpmLockfileDependency('      run: npm ci'), true);
+  });
+
+  test('`cache: \'npm\'` is flagged', () => {
+    assert.equal(referencesNpmLockfileDependency("        cache: 'npm'"), true);
+  });
+
+  test('an unrelated workflow step is not flagged', () => {
+    assert.equal(referencesNpmLockfileDependency('      run: npm run build'), false);
+  });
+});
+
+describe('removed-but-needed lint: findSurvivingReferences (pure)', () => {
+  test('the real #3316 defect shape IS flagged: package-lock.json deleted, workflow still runs npm ci', () => {
+    const violations = findSurvivingReferences(
+      ['package-lock.json'],
+      [{ file: '.github/workflows/ci.yml', content: 'jobs:\n  test:\n    steps:\n      - run: npm ci\n' }],
+    );
+    assert.ok(violations.some((v) => v.deletedFile === 'package-lock.json'));
+  });
+
+  test('a deleted workflow still referenced in docs IS flagged (e3b52c70 shape)', () => {
+    const violations = findSurvivingReferences(
+      ['gsd-core/workflows/new-workspace.md'],
+      [{ file: 'docs/getting-started.md', content: 'run /gsd:new-workspace.md to start' }],
+    );
+    assert.equal(violations.length, 1);
+    assert.equal(violations[0].referencedIn, 'docs/getting-started.md');
+  });
+
+  test('LOOKALIKE: a deleted file with zero surviving references is clean', () => {
+    const violations = findSurvivingReferences(
+      ['gsd-core/workflows/retired.md'],
+      [{ file: 'docs/getting-started.md', content: 'nothing relevant here' }],
+    );
+    assert.deepEqual(violations, []);
+  });
+
+  test('LOOKALIKE: a coincidental basename collision with an unrelated live file is not silently skipped, but the word-boundary guard avoids substring noise', () => {
+    const violations = findSurvivingReferences(
+      ['old/config.json'],
+      [{ file: 'docs/setup.md', content: 'we removed archived-config.json.old, unrelated' }],
+    );
+    assert.deepEqual(violations, []);
+  });
+});
+
+describe('removed-but-needed lint: the live repo (against origin/next) is clean', () => {
+  test('scan() finds zero surviving references for anything deleted since origin/next', () => {
+    let violations;
+    try {
+      violations = scan(ROOT, 'origin/next');
+    } catch {
+      // origin/next unreachable in this environment — nothing to assert.
+      return;
+    }
+    assert.deepEqual(
+      violations,
+      [],
+      'deleted file(s) still referenced by a live consumer:\n'
+        + violations.map((v) => `  ${v.deletedFile} -> ${v.referencedIn}: ${v.reason}`).join('\n'),
+    );
+  });
+});
+
+/**
+ * Build a minimal temp git repo shaped like a PR branch, mirroring
+ * tests/changeset-lint.test.cjs's fixture builder: origin/main = base
+ * commit, pr = PR branch with caller-supplied file mutations on top.
+ * @param {string} tmpDir
+ * @param {Array<{file: string, content: string|null}>} baseFiles
+ * @param {Array<{file: string, content: string|null}>} prFiles - null content deletes
+ */
+function buildTempRepo(tmpDir, baseFiles, prFiles) {
+  const git = (...args) => gitOrThrow(args, { cwd: tmpDir });
+  git('init', '-q', '-b', 'main');
+  git('config', 'user.email', 'test@example.com');
+  git('config', 'user.name', 'Test');
+
+  for (const { file, content } of baseFiles) {
+    const abs = path.join(tmpDir, file);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  git('add', '-A');
+  git('commit', '-q', '-m', 'base');
+  git('update-ref', 'refs/remotes/origin/main', 'HEAD');
+
+  git('checkout', '-q', '-b', 'pr');
+  for (const { file, content } of prFiles) {
+    const abs = path.join(tmpDir, file);
+    if (content === null) {
+      try { fs.unlinkSync(abs); } catch { /* already absent */ }
+    } else {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    }
+  }
+  git('add', '-A');
+  git('commit', '-q', '-m', 'pr changes');
+  return tmpDir;
+}
+
+/**
+ * The lint script resolves its scan root from `path.join(__dirname, '..')`
+ * (matching every other standalone lint script in this repo, e.g.
+ * lint-canary-version-leak.cjs) — it does NOT use `process.cwd()`. So an
+ * end-to-end fixture must run a COPY of the script placed inside the fixture
+ * repo, not the real repo's script, or it would scan the real repo instead
+ * of the fixture tree.
+ * @param {string} tmpDir
+ * @returns {string} path to the copied script inside tmpDir/scripts/
+ */
+function copyScriptInto(tmpDir) {
+  const scriptsDir = path.join(tmpDir, 'scripts');
+  const libDir = path.join(scriptsDir, 'lib');
+  fs.mkdirSync(libDir, { recursive: true });
+  const scriptCopy = path.join(scriptsDir, 'lint-removed-but-needed.cjs');
+  fs.copyFileSync(LINT_SCRIPT, scriptCopy);
+  fs.copyFileSync(path.join(ROOT, 'scripts', 'lib', 'cli-exit.cjs'), path.join(libDir, 'cli-exit.cjs'));
+  return scriptCopy;
+}
+
+describe('removed-but-needed lint: main() end-to-end wiring', () => {
+  test('exit 1 in a fixture repo reproducing the real defect shape (package-lock.json deleted, workflow still npm ci)', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-removed-but-needed-e2e-'));
+    t.after(() => cleanup(tmpDir));
+    buildTempRepo(
+      tmpDir,
+      [
+        { file: 'package-lock.json', content: '{}' },
+        { file: '.github/workflows/ci.yml', content: 'jobs:\n  test:\n    steps:\n      - run: npm ci\n' },
+      ],
+      [{ file: 'package-lock.json', content: null }],
+    );
+    const scriptCopy = copyScriptInto(tmpDir);
+    const result = runNode(
+      [scriptCopy],
+      { cwd: tmpDir, env: { ...process.env, GSD_REMOVED_BUT_NEEDED_BASE: 'main' } },
+    );
+    assert.equal(result.exitCode, 1, `expected exit 1, got ${result.exitCode}: ${result.stderr}`);
+    assert.match(result.stderr, /REMOVED-BUT-NEEDED/);
+  });
+
+  test('exit 0 in a fixture repo where the deletion is clean (no surviving reference, workflow updated too)', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-removed-but-needed-e2e-clean-'));
+    t.after(() => cleanup(tmpDir));
+    buildTempRepo(
+      tmpDir,
+      [
+        { file: 'package-lock.json', content: '{}' },
+        { file: '.github/workflows/ci.yml', content: 'jobs:\n  test:\n    steps:\n      - run: npm install\n' },
+      ],
+      [{ file: 'package-lock.json', content: null }],
+    );
+    const scriptCopy = copyScriptInto(tmpDir);
+    const result = runNode(
+      [scriptCopy],
+      { cwd: tmpDir, env: { ...process.env, GSD_REMOVED_BUT_NEEDED_BASE: 'main' } },
+    );
+    assert.equal(result.exitCode, 0, `expected exit 0, got ${result.exitCode}: ${result.stderr}`);
+  });
+
+  test('gracefully skips (exit 0) when the base ref cannot be resolved', (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-removed-but-needed-e2e-noref-'));
+    t.after(() => cleanup(tmpDir));
+    const git = (...args) => gitOrThrow(args, { cwd: tmpDir });
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 'test@example.com');
+    git('config', 'user.name', 'Test');
+    fs.writeFileSync(path.join(tmpDir, 'README.md'), '# x\n');
+    git('add', '-A');
+    git('commit', '-q', '-m', 'only commit');
+    const scriptCopy = copyScriptInto(tmpDir);
+
+    const result = runNode(
+      [scriptCopy],
+      { cwd: tmpDir, env: { ...process.env, GSD_REMOVED_BUT_NEEDED_BASE: 'nonexistent-branch' } },
+    );
+    assert.equal(result.exitCode, 0, `expected graceful skip (exit 0), got ${result.exitCode}: ${result.stderr}`);
+    assert.match(result.stdout, /skipping/);
+  });
+});