@opengsd/gsd-core 1.2.0-rc.1

package/scripts/command-contract-helpers.cjs

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * command-contract-helpers.cjs  (ADR-0002)
+ *
+ * Single source of truth for the commands/gsd/*.md contract constants and
+ * parsers shared by scripts/lint-command-contract.cjs and
+ * tests/command-contract.test.cjs.
+ *
+ * Keeping these in one place ensures the lint script and the test suite
+ * always agree on what constitutes a valid tool, a valid @-ref, and a valid
+ * frontmatter structure. A new canonical tool added here is automatically
+ * enforced by both consumers.
+ */
+
+const CANONICAL_TOOLS = new Set([
+  'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
+  'Task', 'Agent', 'Skill', 'SlashCommand',
+  'AskUserQuestion', 'WebFetch', 'WebSearch', 'TodoWrite',
+  'mcp__context7__resolve-library-id',
+  'mcp__context7__query-docs',
+  'mcp__context7__*',
+]);
+
+function parseFrontmatter(content) {
+  // CRLF-tolerant split: Windows checkouts (autocrlf=true) leave a trailing
+  // \r on every line, making lines.indexOf('---', 1) return -1 (the value
+  // would be '---\r', not '---') → returns {} → every field appears missing.
+  const lines = content.split(/\r?\n/);
+  if (lines[0].trim() !== '---') return {};
+  const end = lines.indexOf('---', 1);
+  if (end === -1) return {};
+  const fm = {};
+  let key = null;
+  for (const line of lines.slice(1, end)) {
+    const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (kv) { key = kv[1]; fm[key] = kv[2].trim(); }
+    else if (key && line.match(/^\s+-\s+/)) {
+      const val = line.replace(/^\s+-\s+/, '').trim();
+      fm[key] = fm[key] ? fm[key] + '\n' + val : val;
+    }
+  }
+  return fm;
+}
+
+function executionContextRefs(content) {
+  const refs = [];
+  const re = /<execution_context(?:_extended)?>([\s\S]*?)<\/execution_context(?:_extended)?>/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    for (const rawLine of m[1].split('\n')) {
+      const line = rawLine.trim();
+      if (!line.startsWith('@')) continue;
+      const token = line.split(/\s+/)[0];
+      const trailingProse = line.length > token.length;
+      const normalized = token
+        .replace(/^@(?:~|\$HOME)\//, '')
+        .replace(/^(?:\.claude\/)?(?:get-shit-done\/)?/, '');
+      refs.push({ token, normalized, trailingProse });
+    }
+  }
+  return refs;
+}
+
+module.exports = { CANONICAL_TOOLS, parseFrontmatter, executionContextRefs };

package/scripts/diff-touches-shipped-paths.cjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Used by the release-sdk hotfix cherry-pick loop to decide whether a
+ * candidate commit can possibly change what ships in the npm package.
+ *
+ * Reads a newline-separated list of paths from stdin (typically the
+ * output of `git diff-tree --no-commit-id --name-only -r <SHA>`) and
+ * exits with one of three codes so the workflow can distinguish a
+ * legitimate "skip this commit" signal from a classifier failure.
+ *
+ * "Shipped" = the union of:
+ *   - package.json (always included by `npm pack`, regardless of `files`)
+ *   - every entry in package.json `files`, treated as either an exact
+ *     file match or a directory prefix (matching `npm pack` semantics).
+ *   - CI-gating test paths: `tests/<anything>` plus
+ *     `sdk/src/<anything>/<name>.test.<ts|cjs|mjs|js>` and `.spec.` variants
+ *     — these don't ship in the tarball, but they gate the hotfix-branch
+ *     test job. A test fixture update that aligns with a cherry-picked
+ *     production fix MUST be pickable or CI fails on the hotfix run.
+ *     #3621 — root cause of the v1.42.3 hotfix red CI.
+ *
+ * `package-lock.json` is intentionally NOT considered shipped — `npm pack`
+ * excludes it from the tarball unless it's explicitly in `files`, and at
+ * the time of writing this repo's `files` whitelist does not include it.
+ *
+ * Exit codes (the workflow MUST treat these distinctly — bug #2983):
+ *   0  at least one path is shipped       → cherry-pick is meaningful
+ *   1  no shipped paths                   → CI / test / docs / planning
+ *                                            only; hotfix loop skips
+ *   2  classifier error                   → bad/missing package.json,
+ *                                            I/O failure, or any
+ *                                            uncaught exception. The
+ *                                            workflow MUST fail-fast on
+ *                                            this code rather than
+ *                                            treating it as a skip.
+ *
+ * Why distinct codes: Node's default exit code for uncaught throws is 1,
+ * which would otherwise be indistinguishable from the legitimate "no
+ * shipped paths" result. CodeRabbit on PR #2981 / bug #2983.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const EXIT_SHIPPED = 0;
+const EXIT_NOT_SHIPPED = 1;
+const EXIT_ERROR = 2;
+
+function loadShipPrefixes(pkgPath) {
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const files = Array.isArray(pkg.files) ? pkg.files : [];
+  return ['package.json', ...files];
+}
+
+// #3621: paths that gate hotfix-branch CI even though they don't appear
+// in the npm tarball. When a cherry-picked production fix changes behavior
+// that an existing test on the v1.42.2 base asserts against, the matching
+// test fixture from `main` must also be cherry-picked or CI fails on the
+// hotfix run (exactly what happened on v1.42.3 — production fix(3562) was
+// picked, the bundled test-fixture correction in commit 08848df8 was not).
+// Combined with the `test:` prefix being added to the candidate-loop regex
+// in hotfix.yml, this lets `test(####):` fixture-alignment commits be
+// cherry-picked alongside their production counterparts.
+function isCiGating(diffPath) {
+  if (diffPath.startsWith('tests/')) return true;
+  // SDK vitest specs live next to source. Production source ships via
+  // sdk/dist/ (already in package.json `files`); the test files are what's
+  // missing from that surface.
+  if (diffPath.startsWith('sdk/src/') && /\.(test|spec)\.(ts|cjs|mjs|js)$/.test(diffPath)) return true;
+  return false;
+}
+
+function isShipped(diffPath, shipPrefixes) {
+  // Normalize Windows-style separators just in case (git always emits
+  // forward slashes, but a developer running this locally on a different
+  // tool's output shouldn't get a false negative).
+  const p = diffPath.replace(/\\/g, '/');
+  return shipPrefixes.some((s) => p === s || p.startsWith(s + '/'));
+}
+
+// #2980: commits that touch `.github/workflows/*` cannot be cherry-picked
+// onto a hotfix branch because the default GITHUB_TOKEN lacks the
+// `workflow` permission and the push step fails. Detect them upfront so a
+// `test:`-eligible commit bundling a workflow edit still gets skipped.
+function isPushBlocking(diffPath) {
+  return diffPath.replace(/\\/g, '/').startsWith('.github/workflows/');
+}
+
+function fail(message, err) {
+  process.stderr.write(`diff-touches-shipped-paths: ${message}\n`);
+  if (err && err.stack) process.stderr.write(`${err.stack}\n`);
+  process.exit(EXIT_ERROR);
+}
+
+function main() {
+  // Surface ANY uncaught failure as exit 2 (classifier error) rather
+  // than letting Node's default-1 shadow the legitimate
+  // "no shipped paths" result. Bug #2983.
+  process.on('uncaughtException', (err) => fail('uncaught exception', err));
+  process.on('unhandledRejection', (err) => fail('unhandled rejection', err));
+
+  let shipPrefixes;
+  try {
+    const pkgPath = path.resolve(process.cwd(), 'package.json');
+    shipPrefixes = loadShipPrefixes(pkgPath);
+  } catch (err) {
+    return fail(`failed to read package.json from ${process.cwd()}`, err);
+  }
+
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('error', (err) => fail('stdin read error', err));
+  process.stdin.on('data', (chunk) => {
+    buf += chunk;
+  });
+  process.stdin.on('end', () => {
+    try {
+      const paths = buf.split('\n').map((s) => s.trim()).filter(Boolean);
+      // #2980 still wins over #3621: any commit touching .github/workflows/*
+      // is unpickable regardless of other content because the push step
+      // fails on workflow scope rejection. Check this first.
+      if (paths.some(isPushBlocking)) {
+        process.exit(EXIT_NOT_SHIPPED);
+      }
+      if (paths.some((p) => isShipped(p, shipPrefixes))) {
+        process.exit(EXIT_SHIPPED);
+      }
+      // #3621: a commit whose only relevant paths are CI-gating tests is
+      // still pickable — it can change whether the hotfix CI passes even
+      // though it doesn't change what the npm tarball ships.
+      if (paths.some(isCiGating)) {
+        process.exit(EXIT_SHIPPED);
+      }
+      process.exit(EXIT_NOT_SHIPPED);
+    } catch (err) {
+      fail('classification failed', err);
+    }
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { loadShipPrefixes, isShipped, isCiGating, isPushBlocking, EXIT_SHIPPED, EXIT_NOT_SHIPPED, EXIT_ERROR };

package/scripts/fix-slash-commands.cjs

@@ -0,0 +1,147 @@
+'use strict';
+/**
+ * One-shot script + library: bidirectional GSD slash-command namespace normalizer.
+ *
+ * - Default direction (transformContent): retired /gsd-<cmd> → /gsd:<cmd>
+ *   (keeps monorepo sources, docs, and workflows in the active colon form).
+ * - Reverse direction (transformContentToHyphen): /gsd:<cmd> / gsd:<cmd> → gsd-<cmd>
+ *   (used during skill installation for runtimes that register skills under the
+ *   canonical hyphen form established in #2808).
+ *
+ * Both directions only rewrite known commands from `commands/gsd/*.md` (longest-first
+ * matching + word-boundary safety). Non-commands (gsd-sdk, gsd-tools, etc.) are
+ * intentionally left untouched.
+ *
+ * The transforms are pure and exported for use by the installer and tests.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
+const SEARCH_DIRS = [
+  path.join(__dirname, '..', 'get-shit-done', 'bin', 'lib'),
+  path.join(__dirname, '..', 'get-shit-done', 'workflows'),
+  path.join(__dirname, '..', 'get-shit-done', 'references'),
+  path.join(__dirname, '..', 'get-shit-done', 'templates'),
+  path.join(__dirname, '..', 'get-shit-done', 'contexts'),
+  path.join(__dirname, '..', 'commands', 'gsd'),
+  path.join(__dirname, '..', 'agents'),
+  path.join(__dirname, '..', 'hooks'),
+];
+
+const TOP_LEVEL_FILES = [
+  path.join(__dirname, '..', '.clinerules'),
+];
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.turbo']);
+const EXTENSIONS = new Set(['.md', '.cjs', '.js', '.ts', '.tsx']);
+
+// Test files contain intentional fixture strings (e.g. inputs the sanitizer
+// is expected to strip). Rewriting them changes test semantics.
+function isTestFile(name) {
+  return /\.test\.(c?js|tsx?)$/.test(name);
+}
+
+function buildPattern(cmdNames) {
+  // Empty input would compile `/gsd-()(?=[^a-zA-Z0-9_-]|$)/g`, which the regex
+  // engine still matches at any `/gsd-` token followed by a non-word boundary
+  // (e.g. EOL, whitespace, punctuation) — rewriting it to a stray `/gsd:`.
+  // Short-circuit so the caller can no-op on a missing/empty registry rather
+  // than perform an unintended broad rewrite.
+  if (!Array.isArray(cmdNames) || cmdNames.length === 0) return null;
+  const sorted = [...cmdNames].sort((a, b) => b.length - a.length); // longest first to avoid partial matches
+  return new RegExp(`/gsd-(${sorted.join('|')})(?=[^a-zA-Z0-9_-]|$)`, 'g');
+}
+
+/**
+ * Pure transform: rewrite retired `/gsd-<cmd>` to `/gsd:<cmd>` for the given command names.
+ * Returns the rewritten string. Identifiers not in `cmdNames` (e.g. `/gsd-sdk`,
+ * `/gsd-tools`) are left untouched.
+ */
+function transformContent(src, cmdNames) {
+  const pattern = buildPattern(cmdNames);
+  if (!pattern) return src;
+  return src.replace(pattern, (_, cmd) => `/gsd:${cmd}`);
+}
+
+/**
+ * Build regex for the reverse direction (colon form → hyphen form).
+ * Matches both "gsd:cmd" and "/gsd:cmd" (the leading / is preserved automatically
+ * because it is not part of the match). Uses longest-first ordering plus
+ * bidirectional word-boundary safety (negative lookbehind on the left, lookahead
+ * on the right) so matches only occur at token boundaries.
+ */
+function buildColonPattern(cmdNames) {
+  if (!Array.isArray(cmdNames) || cmdNames.length === 0) return null;
+  const sorted = [...cmdNames].sort((a, b) => b.length - a.length);
+  return new RegExp(`(?<![a-zA-Z0-9_-])gsd:(${sorted.join('|')})(?=[^a-zA-Z0-9_-]|$)`, 'g');
+}
+
+/**
+ * Pure transform (reverse): rewrite `/gsd:<cmd>` / `gsd:<cmd>` to hyphen form
+ * for known GSD commands.
+ *
+ * Non-command identifiers (e.g. gsd-sdk, gsd-tools) are left untouched, matching
+ * the safety contract of the forward transform.
+ */
+function transformContentToHyphen(src, cmdNames) {
+  const pattern = buildColonPattern(cmdNames);
+  if (!pattern) return src;
+  return src.replace(pattern, (_, cmd) => `gsd-${cmd}`);
+}
+
+function readCmdNames() {
+  return fs.readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, ''));
+}
+
+function processFile(file, cmdNames) {
+  const pattern = buildPattern(cmdNames);
+  if (!pattern) return;
+  let src;
+  try { src = fs.readFileSync(file, 'utf-8'); } catch { return; }
+  const replaced = transformContent(src, cmdNames);
+  if (replaced !== src) {
+    fs.writeFileSync(file, replaced, 'utf-8');
+    const count = (src.match(pattern) || []).length;
+    console.log(`  ${count} replacements: ${path.relative(path.join(__dirname, '..'), file)}`);
+  }
+}
+
+function processDir(dir, cmdNames) {
+  const pattern = buildPattern(cmdNames);
+  if (!pattern) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      processDir(full, cmdNames);
+    } else if (EXTENSIONS.has(path.extname(e.name)) && !isTestFile(e.name)) {
+      processFile(full, cmdNames);
+    }
+  }
+}
+
+if (require.main === module) {
+  const cmdNames = readCmdNames();
+  for (const dir of SEARCH_DIRS) {
+    processDir(dir, cmdNames);
+  }
+  for (const file of TOP_LEVEL_FILES) {
+    processFile(file, cmdNames);
+  }
+  console.log('Done.');
+}
+
+module.exports = {
+  transformContent,
+  transformContentToHyphen,
+  buildPattern,
+  buildColonPattern,
+  readCmdNames,
+  SKIP_DIRS
+};

package/scripts/gen-inventory-manifest.cjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates docs/INVENTORY-MANIFEST.json — a structural skeleton of every
+ * shipped surface derived entirely from the filesystem. Commit this file;
+ * CI re-runs the script and diffs. A non-empty diff means a surface shipped
+ * without an INVENTORY.md row.
+ *
+ * Usage:
+ *   node scripts/gen-inventory-manifest.cjs              # print to stdout
+ *   node scripts/gen-inventory-manifest.cjs --write      # write docs/INVENTORY-MANIFEST.json
+ *   node scripts/gen-inventory-manifest.cjs --check      # exit 1 if committed manifest is stale
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..');
+const MANIFEST_PATH = path.join(ROOT, 'docs', 'INVENTORY-MANIFEST.json');
+
+const FAMILIES = [
+  {
+    name: 'agents',
+    dir: path.join(ROOT, 'agents'),
+    filter: (f) => /^gsd-.*\.md$/.test(f),
+    toName: (f) => f.replace(/\.md$/, ''),
+  },
+  {
+    name: 'commands',
+    dir: path.join(ROOT, 'commands', 'gsd'),
+    filter: (f) => f.endsWith('.md'),
+    toName: (f) => '/gsd-' + f.replace(/\.md$/, ''),
+  },
+  {
+    name: 'workflows',
+    dir: path.join(ROOT, 'get-shit-done', 'workflows'),
+    filter: (f) => f.endsWith('.md'),
+    toName: (f) => f,
+  },
+  {
+    name: 'references',
+    dir: path.join(ROOT, 'get-shit-done', 'references'),
+    filter: (f) => f.endsWith('.md'),
+    toName: (f) => f,
+  },
+  {
+    name: 'cli_modules',
+    dir: path.join(ROOT, 'get-shit-done', 'bin', 'lib'),
+    filter: (f) => f.endsWith('.cjs'),
+    toName: (f) => f,
+  },
+  {
+    name: 'hooks',
+    dir: path.join(ROOT, 'hooks'),
+    filter: (f) => /\.(js|sh)$/.test(f),
+    toName: (f) => f,
+  },
+];
+
+function buildManifest() {
+  const manifest = { generated: new Date().toISOString().slice(0, 10), families: {} };
+  for (const { name, dir, filter, toName } of FAMILIES) {
+    manifest.families[name] = fs
+      .readdirSync(dir)
+      .filter((f) => fs.statSync(path.join(dir, f)).isFile() && filter(f))
+      .map(toName)
+      .sort();
+  }
+  return manifest;
+}
+
+const [, , flag] = process.argv;
+
+if (flag === '--check') {
+  const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+  const live = buildManifest();
+  // Strip the generated date for comparison
+  delete committed.generated;
+  delete live.generated;
+  const committedStr = JSON.stringify(committed, null, 2);
+  const liveStr = JSON.stringify(live, null, 2);
+  if (committedStr !== liveStr) {
+    process.stderr.write(
+      'docs/INVENTORY-MANIFEST.json is stale. Run:\n' +
+      '  node scripts/gen-inventory-manifest.cjs --write\n' +
+      'then add a matching row in docs/INVENTORY.md for each new entry.\n\n',
+    );
+    // Show diff-friendly output
+    for (const family of Object.keys(live.families)) {
+      const liveSet = new Set(live.families[family]);
+      const committedSet = new Set((committed.families || {})[family] || []);
+      for (const name of liveSet) {
+        if (!committedSet.has(name)) process.stderr.write('  + ' + family + '/' + name + '\n');
+      }
+      for (const name of committedSet) {
+        if (!liveSet.has(name)) process.stderr.write('  - ' + family + '/' + name + '\n');
+      }
+    }
+    process.exit(1);
+  }
+  process.stdout.write('docs/INVENTORY-MANIFEST.json is up to date.\n');
+} else if (flag === '--write') {
+  const manifest = buildManifest();
+  fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+  process.stdout.write('Wrote ' + MANIFEST_PATH + '\n');
+} else {
+  process.stdout.write(JSON.stringify(buildManifest(), null, 2) + '\n');
+}

package/scripts/generate-package-identity.cjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Single source for GSD's published-package coordinates (issue #498).
+ *
+ * `deriveIdentity(pkg)` is the pure core: it turns a parsed package.json into
+ * the coordinate record every consumer needs. The generated runtime module
+ * `get-shit-done/bin/lib/package-identity.cjs` bakes those values at build
+ * time, because the installed tree carries only a synthetic
+ * `{"type":"commonjs"}` package.json (no `.name`) — so a runtime
+ * `require('package.json').name` resolves to `undefined` (the #378 bug this
+ * seam retires). Baking from package.json reconciles #378 (renames survive)
+ * with #2992 (the value is never an LLM runtime choice).
+ */
+
+/**
+ * Parse `owner/name` out of a package.json `repository.url`, stripping the
+ * `git+` prefix and `.git` suffix npm conventionally adds.
+ */
+function parseRepoSlug(repository) {
+  const url = typeof repository === 'string' ? repository : (repository && repository.url) || '';
+  const m = url.replace(/^git\+/, '').replace(/\.git$/, '').match(/github\.com[/:]([^/]+\/[^/]+)$/);
+  return m ? m[1] : '';
+}
+
+/**
+ * Pure: package.json object -> the package identity coordinates.
+ */
+function deriveIdentity(pkg = {}) {
+  const packageName = pkg.name || '';
+  const binName = pkg.bin ? Object.keys(pkg.bin)[0] || '' : '';
+  const repoSlug = parseRepoSlug(pkg.repository);
+  const repoUrl = repoSlug ? `https://github.com/${repoSlug}` : '';
+  const changelogRawUrl = repoSlug
+    ? `https://raw.githubusercontent.com/${repoSlug}/main/CHANGELOG.md`
+    : '';
+  return { packageName, binName, repoSlug, repoUrl, changelogRawUrl };
+}
+
+/**
+ * Pure: format the `npx` fallback install command. Shape matches the literal
+ * the update workflow embeds: `npx -y --package=<pkg>@latest -- <bin>
+ * [--<runtime>] --<scope>`. The runtime flag is omitted when not supplied.
+ *
+ * This function is the canonical source — `render()` serializes it verbatim
+ * into the generated module, so the runtime copy can never drift from it.
+ */
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+const GENERATED_HEADER =
+  '// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.\n' +
+  '// Single source for GSD package coordinates (issue #498). Regenerate with:\n' +
+  '//   node scripts/generate-package-identity.cjs\n';
+
+/**
+ * Render the generated runtime module text for a derived identity. Values are
+ * baked as literals; `formatManualInstall` is embedded by `.toString()` so the
+ * runtime command builder is byte-identical to the tested source above.
+ */
+function render(identity) {
+  const { packageName, binName, repoSlug, repoUrl, changelogRawUrl } = identity;
+  const j = (v) => JSON.stringify(v);
+  return (
+    GENERATED_HEADER +
+    "'use strict';\n\n" +
+    `const packageName = ${j(packageName)};\n` +
+    `const binName = ${j(binName)};\n` +
+    `const repoSlug = ${j(repoSlug)};\n` +
+    `const repoUrl = ${j(repoUrl)};\n` +
+    `const changelogRawUrl = ${j(changelogRawUrl)};\n\n` +
+    `${formatManualInstall.toString()}\n\n` +
+    'function manualInstallCommand(opts = {}) {\n' +
+    '  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });\n' +
+    '}\n\n' +
+    'module.exports = Object.freeze({\n' +
+    '  packageName,\n' +
+    '  // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it\n' +
+    '  // survives the installed tree’s synthetic package.json (fixes the #378 undefined).\n' +
+    '  PACKAGE_NAME: packageName,\n' +
+    '  binName,\n' +
+    '  repoSlug,\n' +
+    '  repoUrl,\n' +
+    '  changelogRawUrl,\n' +
+    '  manualInstallCommand,\n' +
+    '});\n'
+  );
+}
+
+function main() {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  const out = path.join(__dirname, '..', 'get-shit-done', 'bin', 'lib', 'package-identity.cjs');
+  fs.writeFileSync(out, render(deriveIdentity(pkg)));
+  process.stdout.write(`wrote ${path.relative(path.join(__dirname, '..'), out)}\n`);
+}
+
+if (require.main === module) main();
+
+module.exports = { deriveIdentity, parseRepoSlug, formatManualInstall, render, main };

package/scripts/lint-command-contract.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * lint-command-contract.cjs  (ADR-0002)
+ *
+ * Enforces the commands/gsd/*.md contract across all 65 command files:
+ *
+ *   1. name:        present, non-empty, matches gsd: or gsd- prefix
+ *   2. description: present, non-empty
+ *   3. allowed-tools: block present, non-empty, all entries from CANONICAL_TOOLS
+ *   4. execution_context @-refs: every @-reference resolves to an existing file on disk
+ *   5. execution_context @-refs: each appears on its own line (no trailing prose)
+ *
+ * Exit 0 = clean. Exit 1 = violations (with diagnostics).
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT          = path.join(__dirname, '..');
+const COMMANDS_DIR  = path.join(ROOT, 'commands', 'gsd');
+const GSD_ROOT      = path.join(ROOT, 'get-shit-done');
+
+const {
+  CANONICAL_TOOLS,
+  parseFrontmatter,
+  executionContextRefs: extractExecutionContextRefs,
+} = require('./command-contract-helpers.cjs');
+
+// ─── check one file ───────────────────────────────────────────────────────────
+
+function check(filePath) {
+  const content  = fs.readFileSync(filePath, 'utf-8');
+  const rel      = path.relative(ROOT, filePath);
+  const fm       = parseFrontmatter(content);
+  const violations = [];
+
+  // 1. name: present + gsd: / gsd- prefix
+  if (!fm.name || !fm.name.trim()) {
+    violations.push('name: field missing or empty');
+  } else if (!/^gsd[:-]/.test(fm.name.trim())) {
+    violations.push(`name: must start with "gsd:" or "gsd-", got "${fm.name.trim()}"`);
+  }
+
+  // 2. description: present + non-empty
+  if (!fm.description || !fm.description.trim()) {
+    violations.push('description: field missing or empty');
+  }
+
+  // 3. allowed-tools: present + non-empty + all entries canonical
+  if (!fm['allowed-tools'] || !fm['allowed-tools'].trim()) {
+    violations.push('allowed-tools: block missing or empty');
+  } else {
+    const tools = fm['allowed-tools'].split('\n').map(t => t.trim()).filter(Boolean);
+    for (const tool of tools) {
+      const valid =
+        CANONICAL_TOOLS.has(tool) ||
+        (tool.startsWith('mcp__context7__') && CANONICAL_TOOLS.has('mcp__context7__*'));
+      if (!valid) violations.push(`allowed-tools: unknown tool "${tool}"`);
+    }
+  }
+
+  // 4+5. execution_context @-refs resolve + no trailing prose
+  const refs = extractExecutionContextRefs(content);
+  for (const { token, normalized, trailingProse } of refs) {
+    const absPath = path.join(GSD_ROOT, normalized);
+    if (!fs.existsSync(absPath)) {
+      violations.push(`execution_context: @-ref "${normalized}" does not exist on disk`);
+    }
+    if (trailingProse) {
+      violations.push(`execution_context: @-ref "${token}" has trailing prose on the same line`);
+    }
+  }
+
+  if (violations.length === 0) return null;
+  return { file: rel, violations };
+}
+
+// ─── run ─────────────────────────────────────────────────────────────────────
+
+const commandFiles = fs
+  .readdirSync(COMMANDS_DIR)
+  .filter(f => f.endsWith('.md'))
+  .map(f => path.join(COMMANDS_DIR, f));
+
+const results = commandFiles.map(check).filter(Boolean);
+
+if (results.length === 0) {
+  console.log(
+    `ok lint-command-contract: ${commandFiles.length} command files checked, 0 violations`,
+  );
+  process.exit(0);
+}
+
+const total = results.reduce((n, r) => n + r.violations.length, 0);
+process.stderr.write(
+  `\nERROR lint-command-contract: ${total} violation(s) across ${results.length} file(s)\n\n`,
+);
+for (const r of results) {
+  process.stderr.write(`  ${r.file}\n`);
+  for (const v of r.violations) {
+    process.stderr.write(`    - ${v}\n`);
+  }
+  process.stderr.write('\n');
+}
+process.stderr.write('See docs/adr/0002-command-contract-validation-module.md for the contract spec.\n\n');
+process.exit(1);