@therocketcode/gsd-core 1.4.0

package/scripts/lint-docs-required.cjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Docs-required lint (#3213).
+ *
+ * Mirrors scripts/changeset/lint.cjs. Pure verdict function
+ * evaluateLint({ changedFiles, fragments, labels, malformed }) returns
+ * { ok, reason, triggering } using the LINT_REASON enum. The CLI wrapper
+ * reads the PR diff (`git diff --name-only origin/${base}...HEAD`), parses
+ * each touched `.changeset/*.md` fragment, then calls evaluateLint.
+ *
+ * Tests assert on the structured verdict, never on free text.
+ */
+
+const { parseFragment, FRAGMENT_ERROR } = require('./changeset/parse.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const LINT_REASON = Object.freeze({
+  OK_NO_TRIGGERING_FRAGMENTS: 'ok_no_triggering_fragments',
+  OK_DOCS_UPDATED: 'ok_docs_updated',
+  OK_OPT_OUT_LABEL: 'ok_opt_out_label',
+  OK_FRAGMENTS_EXEMPT: 'ok_fragments_exempt',
+  FAIL_DOCS_MISSING: 'fail_docs_missing',
+  FAIL_MALFORMED_FRAGMENT: 'fail_malformed_fragment',
+});
+
+const OPT_OUT_LABEL = 'no-docs';
+
+// Fragment types that require a docs update. `Fixed` and `Security` are
+// bug-class — they describe regressions or vulnerabilities, not new
+// behavior to document.
+const TRIGGERING_TYPES = new Set(['Added', 'Changed', 'Deprecated', 'Removed']);
+
+const DOCS_PREFIX = 'docs/';
+
+function isFragmentPath(file) {
+  return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
+}
+
+function isDocsFile(file) {
+  return file.startsWith(DOCS_PREFIX);
+}
+
+// Per-fragment escape hatch: parse.cjs extracts `<!-- docs-exempt: <reason> -->`
+// from the body into `fragment.docsExempt` (a non-empty reason string when the
+// marker was present and well-formed; `null` otherwise). A non-empty audit
+// trail is required — the lint defends in depth here too: even if a caller
+// constructs a fragment with `docsExempt: ''`, that does not count as exempt.
+function isExemptFragment(fragment) {
+  return typeof fragment.docsExempt === 'string' && fragment.docsExempt.trim().length > 0;
+}
+
+/**
+ * Pure verdict — no fs, no git.
+ *
+ * Malformed fragments fail closed: a triggering fragment with bad frontmatter
+ * cannot silently bypass docs enforcement. The changeset-required lint only
+ * checks fragment _presence_, not _validity_, so docs lint takes responsibility
+ * for any fragment it tries to consume.
+ *
+ * @param {object} args
+ * @param {string[]} args.changedFiles  - file paths changed in the PR
+ * @param {Array<{ path: string, type: string, body: string, docsExempt: string|null }>} args.fragments
+ *   - parsed records for well-formed `.changeset/*.md` files in `changedFiles`
+ * @param {Array<{ path: string, reason: string }>} [args.malformed]
+ *   - records for `.changeset/*.md` files that failed `parseFragment`
+ * @param {string[]} args.labels        - PR labels
+ * @returns {{ ok: boolean, reason: string, triggering: string[], malformed?: Array<{path:string,reason:string}> }}
+ */
+function evaluateLint({ changedFiles, fragments, labels, malformed = [] }) {
+  if (malformed.length > 0) {
+    return {
+      ok: false,
+      reason: LINT_REASON.FAIL_MALFORMED_FRAGMENT,
+      triggering: [],
+      malformed,
+    };
+  }
+
+  const triggering = fragments.filter((f) => TRIGGERING_TYPES.has(f.type));
+  const triggeringPaths = triggering.map((f) => f.path);
+
+  if (triggering.length === 0) {
+    return { ok: true, reason: LINT_REASON.OK_NO_TRIGGERING_FRAGMENTS, triggering: [] };
+  }
+
+  // Per-fragment exempt path: every triggering fragment must carry the marker.
+  // Partial exemption fails closed — one un-marked Added fragment still requires docs.
+  if (triggering.every(isExemptFragment)) {
+    return { ok: true, reason: LINT_REASON.OK_FRAGMENTS_EXEMPT, triggering: triggeringPaths };
+  }
+
+  if (labels.includes(OPT_OUT_LABEL)) {
+    return { ok: true, reason: LINT_REASON.OK_OPT_OUT_LABEL, triggering: triggeringPaths };
+  }
+
+  if (changedFiles.some(isDocsFile)) {
+    return { ok: true, reason: LINT_REASON.OK_DOCS_UPDATED, triggering: triggeringPaths };
+  }
+
+  return { ok: false, reason: LINT_REASON.FAIL_DOCS_MISSING, triggering: triggeringPaths };
+}
+
+function readFragmentsFromDisk(changedFiles, rootDir) {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const fragments = [];
+  const malformed = [];
+  for (const rel of changedFiles) {
+    if (!isFragmentPath(rel)) continue;
+    const abs = path.join(rootDir, rel);
+    if (!fs.existsSync(abs)) continue; // fragment deleted in PR — skip
+    let src;
+    try {
+      src = fs.readFileSync(abs, 'utf8');
+    } catch (e) {
+      malformed.push({ path: rel, reason: 'read_error', detail: e.code || e.message });
+      continue;
+    }
+    const parsed = parseFragment(src);
+    if (!parsed.ok) {
+      malformed.push({ path: rel, reason: parsed.reason, detail: parsed.detail || null });
+      continue;
+    }
+    fragments.push({
+      path: rel,
+      type: parsed.fragment.type,
+      body: parsed.fragment.body,
+      docsExempt: parsed.fragment.docsExempt,
+    });
+  }
+  return { fragments, malformed };
+}
+
+function main() {
+  const fs = require('node:fs');
+  const cp = require('node:child_process');
+  const path = require('node:path');
+
+  const rootDir = path.join(__dirname, '..');
+
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  let labels = [];
+  if (eventPath && fs.existsSync(eventPath)) {
+    try {
+      const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+      labels = (event.pull_request?.labels || []).map((l) => l.name);
+    } catch { /* fall through */ }
+  }
+
+  const base = process.env.GITHUB_BASE_REF || 'main';
+  let changedFiles = [];
+  try {
+    // execFileSync with argv — no shell, so a malicious GITHUB_BASE_REF
+    // cannot inject shell syntax. Git's own ref-name validator rejects
+    // any metacharacters it would otherwise interpret.
+    const out = cp.execFileSync(
+      'git',
+      ['diff', '--name-only', `origin/${base}...HEAD`],
+      { encoding: 'utf8', cwd: rootDir },
+    );
+    changedFiles = out.split('\n').filter(Boolean);
+  } catch (e) {
+    throw new ExitError(2, `could not compute diff: ${e.message}`);
+  }
+
+  const { fragments, malformed } = readFragmentsFromDisk(changedFiles, rootDir);
+  const verdict = evaluateLint({ changedFiles, fragments, labels, malformed });
+
+  if (process.argv.includes('--json')) {
+    process.stdout.write(
+      JSON.stringify({ ...verdict, changedFiles, fragments, malformed, labels }, null, 2) + '\n',
+    );
+  } else if (verdict.ok) {
+    process.stdout.write(`ok docs-lint: ${verdict.reason}\n`);
+  } else if (verdict.reason === LINT_REASON.FAIL_MALFORMED_FRAGMENT) {
+    process.stderr.write(`\nERROR docs-lint: ${verdict.reason}\n`);
+    process.stderr.write(
+      `${malformed.length} changeset fragment(s) failed to parse — docs lint cannot consume them:\n`,
+    );
+    for (const m of malformed) {
+      process.stderr.write(`  ${m.path}  (reason: ${m.reason}${m.detail ? `, detail: ${m.detail}` : ''})\n`);
+    }
+    process.stderr.write(
+      `\nFix the fragment frontmatter (\`type:\` + \`pr:\`) before this PR can pass.\n`,
+    );
+  } else {
+    process.stderr.write(`\nERROR docs-lint: ${verdict.reason}\n`);
+    process.stderr.write(
+      `${verdict.triggering.length} changeset fragment(s) require documentation updates:\n`,
+    );
+    for (const f of fragments.filter((f) => TRIGGERING_TYPES.has(f.type))) {
+      process.stderr.write(`  ${f.path}  (type: ${f.type})\n`);
+    }
+    process.stderr.write(`\nNo files under docs/ were modified in this PR.\n\n`);
+    process.stderr.write(
+      `Update the relevant docs/ file(s), or add the \`${OPT_OUT_LABEL}\` label if this change\n`,
+    );
+    process.stderr.write(
+      `is genuinely internal-only (infrastructure, refactor, test-only). Per-fragment\n`,
+    );
+    process.stderr.write(
+      `exemption via \`<!-- docs-exempt: <reason> -->\` inside the fragment body also works.\n`,
+    );
+  }
+  return verdict.ok ? 0 : 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = {
+  evaluateLint,
+  readFragmentsFromDisk,
+  LINT_REASON,
+  OPT_OUT_LABEL,
+  TRIGGERING_TYPES,
+  FRAGMENT_ERROR,
+  isFragmentPath,
+  isDocsFile,
+  isExemptFragment,
+};

package/scripts/lint-legacy-dir-name.cjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * lint-legacy-dir-name.cjs
+ *
+ * Prevents accidental re-introduction of the bare legacy directory token
+ * `get-shit-done` now that the package has been renamed to `gsd-core` (#604).
+ *
+ * The forbidden token is constructed by splitting across the concat operator
+ * so this guard script cannot flag itself:
+ *   const FORBIDDEN = 'get-shit' + '-done';
+ *
+ * Regex: FORBIDDEN + '(?!-\\w)' — allows any hyphenated slug variant
+ *   (get-shit-done-OLD, get-shit-done-classic, get-shit-done-cli, etc.)
+ *   while forbidding the bare word boundary that would indicate a stale
+ *   directory reference. This is the exact pattern that would appear in a
+ *   path like `~/.claude/get-shit-done/` or `'get-shit-done'` in code.
+ *
+ * Allowlist:
+ *   - CHANGELOG.md (historical record; reviewed manually)
+ *   - .changeset/ (ephemeral release-note fragments; consumed into CHANGELOG on
+ *     release — like CHANGELOG, not swept by rename PRs)
+ *   - Translated READMEs: README.ja-JP.md, README.ko-KR.md, README.pt-BR.md, README.zh-CN.md
+ *   - Locale-specific docs dirs: docs/ja-JP/, docs/ko-KR/, docs/pt-BR/, docs/zh-CN/
+ *   - Lines containing the marker `gsd-allow-legacy-name` (intentional uses)
+ *   - Binary files (detected by NUL byte scan)
+ *   - This guard script itself (by path)
+ *
+ * Exit 0 if no violations; exit 1 if any are found (with stderr diagnostics).
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// Constructed with split to avoid self-match when this script is scanned.
+const FORBIDDEN = 'get-shit' + '-done';
+const FORBIDDEN_RE = new RegExp(FORBIDDEN + '(?!-\\w)', 'gi');
+
+const ALLOW_MARKER = 'gsd-allow-legacy-name';
+const SELF_PATH = path.resolve(__filename);
+// GSD_LINT_LEGACY_REPO_ROOT is used by tests to redirect the guard to a
+// temporary fixture git repo without touching the real working tree.
+const REPO_ROOT = process.env.GSD_LINT_LEGACY_REPO_ROOT
+  ? path.resolve(process.env.GSD_LINT_LEGACY_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+const ALLOWLIST_FILES = new Set([
+  'CHANGELOG.md',
+  'README.ja-JP.md',
+  'README.ko-KR.md',
+  'README.pt-BR.md',
+  'README.zh-CN.md',
+]);
+
+const ALLOWLIST_DIR_PREFIXES = [
+  // Pending changeset fragments are ephemeral release-note stubs consumed into
+  // CHANGELOG on release — like CHANGELOG itself, they should not be swept by
+  // rename PRs and may legitimately contain the legacy token in historical prose.
+  '.changeset/',
+  'docs/ja-JP/',
+  'docs/ko-KR/',
+  'docs/pt-BR/',
+  'docs/zh-CN/',
+];
+
+function isAllowlisted(relPath) {
+  if (ALLOWLIST_FILES.has(relPath)) return true;
+  for (const prefix of ALLOWLIST_DIR_PREFIXES) {
+    if (relPath.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+function isBinary(fullPath) {
+  // Read a small chunk and check for NUL bytes.
+  let fd;
+  try {
+    fd = fs.openSync(fullPath, 'r');
+    const buf = Buffer.allocUnsafe(512);
+    const bytesRead = fs.readSync(fd, buf, 0, 512, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } catch {
+    return false;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
+function main() {
+  // Enumerate tracked files via git ls-files so only committed/staged source is checked.
+  let trackedFiles;
+  try {
+    trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-legacy-dir-name: git ls-files failed: ' + err.message);
+  }
+
+  const violations = [];
+
+  for (const relPath of trackedFiles) {
+    if (isAllowlisted(relPath)) continue;
+
+    const fullPath = path.join(REPO_ROOT, relPath);
+
+    // Skip this guard script itself.
+    if (path.resolve(fullPath) === SELF_PATH) continue;
+
+    if (isBinary(fullPath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Unreadable files (permissions, etc.) — skip silently.
+      continue;
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Skip lines that carry the explicit allow marker.
+      if (line.includes(ALLOW_MARKER)) continue;
+
+      FORBIDDEN_RE.lastIndex = 0;
+      let match;
+      while ((match = FORBIDDEN_RE.exec(line)) !== null) {
+        violations.push({
+          file: relPath,
+          line: i + 1,
+          col: match.index + 1,
+          text: match[0],
+        });
+      }
+    }
+  }
+
+  if (violations.length === 0) {
+    process.stdout.write('ok lint-legacy-dir-name: ' + trackedFiles.length + ' tracked file(s) checked, 0 violations\n');
+    return 0;
+  }
+
+  process.stderr.write('\nERROR lint-legacy-dir-name: ' + violations.length + ' violation(s) found\n\n');
+  for (const v of violations) {
+    process.stderr.write('  ' + v.file + ':' + v.line + ':' + v.col + ' — ' + JSON.stringify(v.text) + '\n');
+  }
+  process.stderr.write('\n');
+  process.stderr.write('Fix: rename to gsd-core, or add `gsd-allow-legacy-name` marker on the line if the\n');
+  process.stderr.write('      use is intentional (migration modules, tests, guard, changeset).\n\n');
+  return 1;
+}
+
+runMain(main);

package/scripts/lint-package-identity-drift.cjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Drift-guard lint for the Package Identity seam (issue #498).
+ *
+ * The seam (`get-shit-done/bin/lib/package-identity.cjs`, derived from // gsd-allow-legacy-name
+ * package.json) is the single source of GSD's published coordinates. Many
+ * runtime surfaces still carry a literal copy of those coordinates because
+ * they cannot `require()` the seam at runtime: the bash launcher snippet (and
+ * its byte-equal copies across ~85 workflows, kept in lockstep by the
+ * runtime-launcher parity test) and the installer's user-facing install/help
+ * strings.
+ *
+ * This lint makes those literals *value-checked*: every GSD package/repo
+ * coordinate that appears as a literal must equal the seam's current value.
+ * It passes today (the literals are correct) and FAILS the moment a repoint is
+ * not propagated — rename package.json, regenerate the seam, and every stale
+ * literal is reported until updated. That is what turns a repoint into a
+ * one-line change with mechanical enforcement.
+ *
+ * Scope: the runtime/code surface (bin/, hooks/, scripts/, get-shit-done/). // gsd-allow-legacy-name
+ * Pure-prose docs and localized READMEs are intentionally out of scope.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A GSD package coordinate: a scoped npm name whose package part contains
+// "get-shit-done" (so @opengsd/gsd-sdk and unrelated scopes never match). // gsd-allow-legacy-name
+const PACKAGE_RE = /@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]*get-shit-done[A-Za-z0-9._-]*/g; // gsd-allow-legacy-name
+// A GSD repo slug, only inside a GitHub URL context so it never overlaps the
+// scoped package literal above. The `.git` suffix is trimmed before compare.
+const SLUG_RE = /(?:github\.com[/:]|raw\.githubusercontent\.com\/)([A-Za-z0-9._-]+\/[A-Za-z0-9._-]*get-shit-done[A-Za-z0-9._-]*)/g; // gsd-allow-legacy-name
+
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) {
+    if (text[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Pure: find every GSD coordinate literal in `text` that does not match the
+ * expected seam values. Returns [{ kind, found, expected, line }].
+ */
+function findCoordinateDrift(text, { packageName, repoSlug }) {
+  const out = [];
+  for (const m of text.matchAll(PACKAGE_RE)) {
+    if (m[0] !== packageName) {
+      out.push({ kind: 'package', found: m[0], expected: packageName, line: lineOf(text, m.index) });
+    }
+  }
+  for (const m of text.matchAll(SLUG_RE)) {
+    const slug = m[1].replace(/\.git$/, '');
+    if (slug !== repoSlug) {
+      out.push({ kind: 'slug', found: slug, expected: repoSlug, line: lineOf(text, m.index) });
+    }
+  }
+  return out;
+}
+
+// Directories scanned, relative to repo root.
+const SCAN_DIRS = ['bin', 'hooks', 'scripts', 'gsd-core'];
+const SCAN_EXT = new Set(['.js', '.cjs', '.sh', '.md']);
+// Files exempt because they ARE the source of truth / the tooling that defines
+// the coordinate patterns. The generated seam holds the correct value by
+// construction; the generator and this lint carry regex/templates, not stray
+// literals.
+const EXEMPT = new Set([
+  path.join('gsd-core', 'bin', 'lib', 'package-identity.cjs'),
+  path.join('scripts', 'generate-package-identity.cjs'),
+  path.join('scripts', 'lint-package-identity-drift.cjs'),
+]);
+
+function walk(dir, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return acc;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
+      walk(full, acc);
+    } else if (entry.isFile() && SCAN_EXT.has(path.extname(entry.name))) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+/**
+ * Scan the repo's runtime/code surface and return all coordinate drift, each
+ * annotated with the repo-relative file path.
+ */
+function scanRepo(root) {
+  const seam = require(path.join(root, 'gsd-core', 'bin', 'lib', 'package-identity.cjs'));
+  const expected = { packageName: seam.packageName, repoSlug: seam.repoSlug };
+  const violations = [];
+  for (const dir of SCAN_DIRS) {
+    const files = walk(path.join(root, dir), []);
+    for (const file of files) {
+      const rel = path.relative(root, file);
+      if (EXEMPT.has(rel)) continue;
+      let text;
+      try {
+        text = fs.readFileSync(file, 'utf8');
+      } catch (e) {
+        continue;
+      }
+      for (const d of findCoordinateDrift(text, expected)) {
+        violations.push({ file: rel, ...d });
+      }
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const root = path.join(__dirname, '..');
+  const violations = scanRepo(root);
+  if (violations.length === 0) {
+    process.stdout.write('ok identity-drift: all GSD coordinate literals match the seam\n');
+    return;
+  }
+  process.stderr.write('identity-drift: stale GSD coordinate literal(s) found.\n');
+  process.stderr.write('Repoint by editing package.json, then `node scripts/generate-package-identity.cjs`,\n');
+  process.stderr.write('and update the value-checked materialization sites below:\n');
+  for (const d of violations) {
+    process.stderr.write(`  ${d.file}:${d.line}  ${d.kind} '${d.found}' != '${d.expected}'\n`);
+  }
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = { findCoordinateDrift, scanRepo };

package/scripts/lint-pr-check-project-dir.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+
+const DEFAULT_RELATIVE_FILES = [
+  '.github/workflows/test.yml',
+  '.github/workflows/pr-template-format.yml',
+  '.github/workflows/changeset-required.yml',
+  'scripts/lint-command-contract.cjs',
+  'scripts/lint-skill-deps.cjs',
+  'scripts/lint-descriptions.cjs',
+  'scripts/lint-shell-command-projection-drift.cjs',
+  'scripts/pr-template-policy.cjs',
+  'scripts/changeset/lint.cjs',
+];
+
+function defaultFiles(rootDir = ROOT) {
+  return DEFAULT_RELATIVE_FILES
+    .map((file) => path.join(rootDir, file))
+    .filter((file) => fs.existsSync(file));
+}
+
+function findForbiddenCwd(content, file = '<inline>') {
+  const findings = [];
+  const lines = content.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    const pattern = /\bcwd\b/g;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      findings.push({
+        file,
+        line: index + 1,
+        column: match.index + 1,
+        source: line.trim(),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function checkFiles(files, { rootDir = ROOT } = {}) {
+  const findings = [];
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf8');
+    const rel = path.relative(rootDir, file);
+    findings.push(...findForbiddenCwd(content, rel));
+  }
+  return findings;
+}
+
+function formatFindings(findings) {
+  const lines = [
+    `ERROR lint-pr-check-project-dir: ${findings.length} forbidden cwd reference(s) found`,
+    '',
+    'PR checkers must use projectDir for project roots; cwd is forbidden in this layer.',
+    '',
+  ];
+
+  for (const finding of findings) {
+    lines.push(`  ${finding.file}:${finding.line}:${finding.column}`);
+    lines.push(`    ${finding.source}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const files = argv.length > 0 ? argv.map((file) => path.resolve(file)) : defaultFiles();
+  const findings = checkFiles(files);
+
+  if (findings.length === 0) {
+    console.log(`ok lint-pr-check-project-dir: ${files.length} PR check files checked`);
+    return 0;
+  }
+
+  process.stderr.write(formatFindings(findings));
+  return 1;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  DEFAULT_RELATIVE_FILES,
+  checkFiles,
+  defaultFiles,
+  findForbiddenCwd,
+  formatFindings,
+  main,
+};

package/scripts/lint-shell-command-projection-drift.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Focused drift guard for issue #3442:
+ * prevent installer-owned inline shim/wrapper text builders from bypassing the
+ * Shell Command Projection Module seam.
+ *
+ * Scope intentionally excludes subprocess execution helpers (spawnSync /
+ * execFileSync) because those are safe internal execution primitives, not
+ * serialized shell-command rendering.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+
+const forbidden = [
+  {
+    label: 'inline cmd shim builder',
+    pattern: /@ECHO OFF\\r\\n@SETLOCAL\\r\\n@node /,
+  },
+  {
+    label: 'inline pwsh shim builder',
+    pattern: /#!\/usr\/bin\/env pwsh\\n& node /,
+  },
+  {
+    label: 'inline sh shim builder',
+    pattern: /#!\/usr\/bin\/env sh\\nexec node /,
+  },
+];
+
+function main() {
+  const targetArg = process.argv[2] || path.join(ROOT, 'bin', 'install.js');
+  const target = path.resolve(targetArg);
+  const rel = path.relative(ROOT, target);
+
+  let content;
+  try {
+    content = fs.readFileSync(target, 'utf8');
+  } catch (error) {
+    throw new ExitError(1, `lint-shell-command-projection-drift: failed to read ${target}: ${error.message}`);
+  }
+
+  const matches = forbidden.filter((rule) => rule.pattern.test(content));
+  if (matches.length === 0) {
+    process.stdout.write(`ok shell-projection-drift: ${rel}\n`);
+    return 0;
+  }
+
+  process.stderr.write(`ERROR shell-projection-drift: inline serialized shim builders found in ${rel}\n`);
+  for (const match of matches) {
+    process.stderr.write(`  - ${match.label}\n`);
+  }
+  process.stderr.write('Route shim/wrapper rendering through gsd-core/bin/lib/shell-command-projection.cjs\n');
+  process.stderr.write('Safe subprocess execution via spawnSync/execFileSync is intentionally allowed.\n');
+  return 1;
+}
+
+runMain(main);