@opengsd/gsd-core 1.2.0-rc.1

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
+ * 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/).
+ * 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).
+const PACKAGE_RE = /@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]*get-shit-done[A-Za-z0-9._-]*/g;
+// 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;
+
+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', 'get-shit-done'];
+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('get-shit-done', '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, 'get-shit-done', '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,98 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+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-no-source-grep.cjs',
+  '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) {
+  process.exit(main());
+}
+
+module.exports = {
+  DEFAULT_RELATIVE_FILES,
+  checkFiles,
+  defaultFiles,
+  findForbiddenCwd,
+  formatFindings,
+  main,
+};

package/scripts/lint-shared-module-handsync.cjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Shared Module hand-sync drift lint — Phase 6 of #3524 (#3575).
+ *
+ * Scans get-shit-done/bin/lib/ for .cjs files and checks whether a matching
+ * TypeScript file exists in sdk/src/<name>.ts, sdk/src/query/<name>.ts, or
+ * sdk/src/<name>/index.ts (excluding *.generated.ts and *.test.ts).
+ *
+ * Allowlist entries are keyed by the (cjs, ts) PAIR. An entry with cjs
+ * `bin/lib/foo.cjs` and ts `sdk/src/foo.ts` only allow-throughs that exact
+ * pair — a sibling at `sdk/src/query/foo.ts` is still flagged.
+ *
+ * Cross-name pairs are also supported when declared in the allowlist
+ * (for example `verify.cjs` <-> `validate.ts`), so cooperating siblings are
+ * observable even when basenames differ.
+ *
+ * If a pair is found:
+ *   - cooperatingSiblings (matching cjs + ts): accepted silently (exit 0).
+ *   - migrateMeBacklog (matching cjs + ts): emits a WARNING only when
+ *     --warn-all is set; otherwise the pair passes silently. Backlog
+ *     pairs never fail CI.
+ *   - Unlisted pairs (cjs or ts not on either list): ERROR — exit 1.
+ *
+ * Usage:
+ *   node scripts/lint-shared-module-handsync.cjs
+ *   node scripts/lint-shared-module-handsync.cjs --root /path/to/repo
+ *   node scripts/lint-shared-module-handsync.cjs --warn-all
+ *   node scripts/lint-shared-module-handsync.cjs --cjs-dir custom/bin/lib --sdk-src custom/sdk/src
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+let ROOT = path.resolve(__dirname, '..');
+let CJS_DIR = null;          // resolved below
+let SDK_SRC = null;          // resolved below
+let SDK_SRC_EXPLICIT = false;
+let ALLOWLIST_OVERRIDE = null; // resolved below
+let WARN_ALL = false;
+let JSON_OUTPUT = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--root' && args[i + 1]) {
+    ROOT = path.resolve(args[++i]);
+  } else if (args[i] === '--cjs-dir' && args[i + 1]) {
+    CJS_DIR = path.resolve(args[++i]);
+  } else if (args[i] === '--sdk-src' && args[i + 1]) {
+    SDK_SRC = path.resolve(args[++i]);
+    SDK_SRC_EXPLICIT = true;
+  } else if (args[i] === '--allowlist' && args[i + 1]) {
+    ALLOWLIST_OVERRIDE = path.resolve(args[++i]);
+  } else if (args[i] === '--warn-all') {
+    WARN_ALL = true;
+  } else if (args[i] === '--json') {
+    JSON_OUTPUT = true;
+  }
+}
+
+if (!CJS_DIR) CJS_DIR = path.join(ROOT, 'get-shit-done', 'bin', 'lib');
+if (!SDK_SRC) SDK_SRC = path.join(ROOT, 'sdk', 'src');
+
+// ---------------------------------------------------------------------------
+// Load allowlist
+// When --root is given (e.g. in tests), prefer <ROOT>/scripts/allowlist.json
+// so fixture trees can supply their own allowlist. Fall back to the copy
+// co-located with this script (default production path).
+// ---------------------------------------------------------------------------
+const ALLOWLIST_PATH = ALLOWLIST_OVERRIDE
+  ? ALLOWLIST_OVERRIDE
+  : fs.existsSync(path.join(ROOT, 'scripts', 'shared-module-handsync-allowlist.json'))
+    ? path.join(ROOT, 'scripts', 'shared-module-handsync-allowlist.json')
+    : path.join(__dirname, 'shared-module-handsync-allowlist.json');
+let allowlist;
+try {
+  allowlist = JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf8'));
+} catch (err) {
+  process.stderr.write(
+    `lint-shared-module-handsync: failed to read allowlist at ${ALLOWLIST_PATH}: ${err.message}\n`
+  );
+  process.exit(1);
+}
+
+/**
+ * Pair identity = `${cjs}::${ts}`. Keying on the pair (not just cjs)
+ * prevents an allowlisted entry from silently passing an unintended
+ * sibling at a different ts path with the same basename.
+ *
+ * @type {Set<string>} pair identities in cooperatingSiblings
+ */
+const cooperatingPairs = new Set(
+  (allowlist.cooperatingSiblings || []).map((e) => `${e.cjs}::${e.ts}`)
+);
+
+/** @type {Map<string, object>} pair identity -> entry for migrateMeBacklog */
+const migrateMap = new Map(
+  (allowlist.migrateMeBacklog || []).map((e) => [`${e.cjs}::${e.ts}`, e])
+);
+
+/** @type {Map<string, Set<string>>} cjs rel path -> explicit declared ts rel paths */
+const explicitTsByCjs = new Map();
+for (const entry of [
+  ...(allowlist.cooperatingSiblings || []),
+  ...(allowlist.migrateMeBacklog || []),
+]) {
+  if (!entry || typeof entry.cjs !== 'string' || typeof entry.ts !== 'string') continue;
+  if (!explicitTsByCjs.has(entry.cjs)) explicitTsByCjs.set(entry.cjs, new Set());
+  explicitTsByCjs.get(entry.cjs).add(entry.ts);
+}
+
+// ---------------------------------------------------------------------------
+// Build SDK name index: name -> array of absolute TS paths
+// (excludes *.generated.ts and *.test.ts)
+// ---------------------------------------------------------------------------
+function buildSdkIndex(sdkSrc) {
+  const index = new Map(); // name -> [absPath, ...]
+
+  function addEntry(name, absPath) {
+    if (!index.has(name)) index.set(name, []);
+    index.get(name).push(absPath);
+  }
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+    for (const ent of entries) {
+      const abs = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        walk(abs);
+      } else if (ent.isFile() && ent.name.endsWith('.ts') &&
+                 !ent.name.endsWith('.generated.ts') &&
+                 !ent.name.endsWith('.test.ts')) {
+        const rel = path.relative(sdkSrc, abs);
+        const parts = rel.split(path.sep);
+
+        // sdk/src/<name>.ts  (direct child, not in a subdir)
+        if (parts.length === 1) {
+          const name = parts[0].slice(0, -3); // strip .ts
+          addEntry(name, abs);
+        }
+        // sdk/src/<name>/index.ts  (one subdir deep, file is index.ts)
+        else if (parts.length === 2 && parts[1] === 'index.ts') {
+          const name = parts[0];
+          addEntry(name, abs);
+        }
+        // sdk/src/query/<name>.ts  (exactly: query/<something>.ts)
+        else if (parts.length === 2 && parts[0] === 'query' && parts[1] !== 'index.ts') {
+          const name = parts[1].slice(0, -3); // strip .ts
+          addEntry(name, abs);
+        }
+      }
+    }
+  }
+
+  walk(sdkSrc);
+  return index;
+}
+
+// ---------------------------------------------------------------------------
+// Scan CJS files (direct children only; exclude *.generated.cjs)
+// ---------------------------------------------------------------------------
+function scanCjsFiles(cjsDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(cjsDir, { withFileTypes: true });
+  } catch (err) {
+    process.stderr.write(
+      `lint-shared-module-handsync: cannot read CJS dir ${cjsDir}: ${err.message}\n`
+    );
+    process.exit(1);
+  }
+  return entries
+    .filter(
+      (e) =>
+        e.isFile() &&
+        e.name.endsWith('.cjs') &&
+        !e.name.endsWith('.generated.cjs')
+    )
+    .map((e) => ({
+      name: e.name.slice(0, -4), // strip .cjs
+      absPath: path.join(cjsDir, e.name),
+    }));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function emitJson(payload) {
+  process.stdout.write(JSON.stringify(payload) + '\n');
+}
+
+function main() {
+  // Check that the directories exist
+  if (!fs.existsSync(CJS_DIR)) {
+    if (JSON_OUTPUT) {
+      emitJson({ ok: false, reason: 'cjs_dir_missing', path: CJS_DIR });
+    } else {
+      process.stderr.write(
+        `lint-shared-module-handsync: CJS dir not found: ${CJS_DIR}\n` +
+          `  Pass --root <repo-root> or --cjs-dir <path> to override.\n`
+      );
+    }
+    process.exit(1);
+  }
+  if (!fs.existsSync(SDK_SRC)) {
+    // SDK tree was retired in ADR-0174 Phase 5.2. In default repo mode this
+    // lint becomes a no-op success; explicit --sdk-src remains fail-loud.
+    if (SDK_SRC_EXPLICIT) {
+      if (JSON_OUTPUT) {
+        emitJson({ ok: false, reason: 'sdk_src_missing', path: SDK_SRC });
+      } else {
+        process.stderr.write(
+          `lint-shared-module-handsync: SDK src dir not found: ${SDK_SRC}\n` +
+            `  Pass --root <repo-root> or --sdk-src <path> to override.\n`
+        );
+      }
+      process.exit(1);
+    }
+
+    if (JSON_OUTPUT) {
+      emitJson({
+        ok: true,
+        reason: 'sdk_retired',
+        cooperatingCount: 0,
+        backlogCount: 0,
+        warnings: [],
+      });
+    } else {
+      process.stdout.write(
+        'ok lint-shared-module-handsync: SDK source tree retired; no hand-sync pairs to lint.\n'
+      );
+    }
+    process.exit(0);
+  }
+
+  const sdkIndex = buildSdkIndex(SDK_SRC);
+  const cjsFiles = scanCjsFiles(CJS_DIR);
+
+  const errors = [];
+  const warnings = [];
+
+  function candidateTsPathsFor(relCjs, name) {
+    const byName = sdkIndex.has(name)
+      ? sdkIndex
+          .get(name)
+          .map((p) => path.relative(ROOT, p).replace(/\\/g, '/'))
+      : [];
+
+    const declared = explicitTsByCjs.has(relCjs)
+      ? Array.from(explicitTsByCjs.get(relCjs))
+      : [];
+
+    const declaredExisting = declared.filter((relTs) => {
+      const abs = path.join(ROOT, relTs);
+      return (
+        relTs.endsWith('.ts') &&
+        !relTs.endsWith('.generated.ts') &&
+        !relTs.endsWith('.test.ts') &&
+        fs.existsSync(abs) &&
+        fs.statSync(abs).isFile()
+      );
+    });
+
+    return Array.from(new Set([...byName, ...declaredExisting]));
+  }
+
+  for (const { name, absPath } of cjsFiles) {
+    // Compute relative CJS path and all declared/discovered TS candidates.
+    const relCjs = path.relative(ROOT, absPath).replace(/\\/g, '/');
+    const tsPaths = candidateTsPathsFor(relCjs, name);
+    if (tsPaths.length === 0) continue;
+
+    // Pair-aware matching, per ts sibling. Each ts candidate is classified
+    // independently against the allowlist so a partially-allowlisted set of
+    // siblings still surfaces the unauthorized ones. See #3632.
+    const unauthorizedTs = [];
+    const backlogTsForCjs = [];
+    for (const relTs of tsPaths) {
+      const pairKey = `${relCjs}::${relTs}`;
+      if (cooperatingPairs.has(pairKey)) continue;
+      if (migrateMap.has(pairKey)) {
+        backlogTsForCjs.push(relTs);
+        continue;
+      }
+      unauthorizedTs.push(relTs);
+    }
+
+    if (unauthorizedTs.length > 0) {
+      errors.push({ relCjs, tsPaths: unauthorizedTs });
+    }
+    if (backlogTsForCjs.length > 0) {
+      const entry = migrateMap.get(`${relCjs}::${backlogTsForCjs[0]}`);
+      warnings.push({ relCjs, tsPaths: backlogTsForCjs, entry });
+    }
+  }
+
+  // Count cjs files whose pair identity (cjs+ts) is on cooperatingSiblings.
+  // A file with multiple ts candidates is counted once if any pair matches.
+  const cooperatingCount = cjsFiles.filter((f) => {
+    const relCjs = path.relative(ROOT, f.absPath).replace(/\\/g, '/');
+    return candidateTsPathsFor(relCjs, f.name).some((relTs) =>
+      cooperatingPairs.has(`${relCjs}::${relTs}`)
+    );
+  }).length;
+
+  // -------------------------------------------------------------------------
+  // Report errors (exit 1)
+  // -------------------------------------------------------------------------
+  if (errors.length > 0) {
+    if (JSON_OUTPUT) {
+      emitJson({
+        ok: false,
+        reason: 'unauthorized_pairs',
+        errors,
+        warnings,
+        cooperatingCount,
+      });
+    } else {
+      process.stderr.write(
+        `\nERROR lint-shared-module-handsync: ${errors.length} unauthorized hand-sync pair(s) found.\n\n`
+      );
+      for (const { relCjs, tsPaths } of errors) {
+        process.stderr.write(`  CJS: ${relCjs}\n`);
+        for (const ts of tsPaths) {
+          process.stderr.write(`   TS: ${ts}\n`);
+        }
+        process.stderr.write('\n');
+      }
+      process.stderr.write(
+        'To resolve, choose one of:\n' +
+          '  1. Migrate to a Shared Module (preferred): create sdk/src/<name>/index.ts as the\n' +
+          '     source-of-truth, write a generator script (sdk/scripts/gen-<name>.mjs), add a\n' +
+          '     freshness check, and update CI. See docs/agents/cjs-sdk-seam.md for the pattern.\n' +
+          '  2. Add an explicit allowlist entry to scripts/shared-module-handsync-allowlist.json\n' +
+          '     with a justification explaining why this pair is a legitimate cooperating sibling\n' +
+          '     rather than a drift anti-pattern. Requires maintainer review via CODEOWNERS.\n\n'
+      );
+    }
+    process.exit(1);
+  }
+
+  // -------------------------------------------------------------------------
+  // Report warnings (no exit code change)
+  // -------------------------------------------------------------------------
+  if (warnings.length > 0 && WARN_ALL && !JSON_OUTPUT) {
+    process.stderr.write(
+      `\nWARNING lint-shared-module-handsync: ${warnings.length} known drift anti-pattern pair(s) in migrateMeBacklog.\n` +
+        `These are tracked for future Shared Module migration but do not block CI.\n\n`
+    );
+    for (const { relCjs, tsPaths, entry } of warnings) {
+      process.stderr.write(`  CJS: ${relCjs}\n`);
+      for (const ts of tsPaths) {
+        process.stderr.write(`   TS: ${ts}\n`);
+      }
+      process.stderr.write(`  Tracked: ${entry.trackedIn}\n`);
+      process.stderr.write(`  Hint: ${entry.justification}\n\n`);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Success
+  // -------------------------------------------------------------------------
+  if (JSON_OUTPUT) {
+    emitJson({
+      ok: true,
+      cooperatingCount,
+      backlogCount: warnings.length,
+      warnings,
+    });
+  } else {
+    process.stdout.write(
+      `ok lint-shared-module-handsync: no unauthorized hand-sync pairs found` +
+        ` (${cooperatingCount} cooperating sibling(s), ${warnings.length} backlog pair(s))\n`
+    );
+  }
+  process.exit(0);
+}
+
+main();

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

@@ -0,0 +1,57 @@
+#!/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 ROOT = path.resolve(__dirname, '..');
+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) {
+  process.stderr.write(`lint-shell-command-projection-drift: failed to read ${target}: ${error.message}\n`);
+  process.exit(1);
+}
+
+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 /,
+  },
+];
+
+const matches = forbidden.filter((rule) => rule.pattern.test(content));
+if (matches.length === 0) {
+  process.stdout.write(`ok shell-projection-drift: ${rel}\n`);
+  process.exit(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 get-shit-done/bin/lib/shell-command-projection.cjs\n');
+process.stderr.write('Safe subprocess execution via spawnSync/execFileSync is intentionally allowed.\n');
+process.exit(1);