harness-everything 0.25.1 → 0.27.0

package/scripts/lib/verification-contract.js

@@ -0,0 +1,357 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CONTRACT_RELATIVE = path.join('.harness', 'verify.json');
+const CONTRACT_VERSION = 1;
+const MAX_TIMEOUT_SEC = 3600;
+
+function runGit(cwd, args) {
+  return spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    windowsHide: true,
+    timeout: 5000,
+  });
+}
+
+function findGitRoot(cwd = process.cwd()) {
+  const result = runGit(cwd, ['rev-parse', '--show-toplevel']);
+  return result.status === 0 ? path.resolve(result.stdout.trim()) : path.resolve(cwd);
+}
+
+function within(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
+}
+
+function resolveContained(root, value, label, { mustExist = true } = {}) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} must be a non-empty relative path`);
+  if (path.isAbsolute(value)) throw new Error(`${label} must stay inside the repository`);
+  const resolved = path.resolve(root, value);
+  if (!within(root, resolved)) throw new Error(`${label} escapes the repository`);
+  if (mustExist && !fs.existsSync(resolved)) throw new Error(`${label} does not exist: ${value}`);
+  if (mustExist) {
+    const physicalRoot = fs.realpathSync.native(path.resolve(root));
+    const physicalTarget = fs.realpathSync.native(resolved);
+    if (!within(physicalRoot, physicalTarget)) throw new Error(`${label} escapes the repository through a symbolic link`);
+    return physicalTarget;
+  }
+  return resolved;
+}
+
+function assertKnownFields(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${label} contains unknown field: ${key}`);
+  }
+}
+
+function readContract(repoRoot) {
+  const contractPath = path.join(repoRoot, CONTRACT_RELATIVE);
+  if (!fs.existsSync(contractPath)) return null;
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`verify.json is invalid JSON: ${error.message}`);
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('verify.json must contain a JSON object');
+  assertKnownFields(raw, new Set(['version', 'roots', 'checks']), 'verify.json');
+  if (raw.version !== CONTRACT_VERSION) throw new Error(`verify.json version must be ${CONTRACT_VERSION}`);
+  if (!Array.isArray(raw.checks) || raw.checks.length === 0) throw new Error('verify.json checks must be a non-empty array');
+
+  const rootValues = raw.roots === undefined ? ['.'] : raw.roots;
+  if (!Array.isArray(rootValues) || rootValues.length === 0) throw new Error('verify.json roots must be a non-empty array');
+  const seenRoots = new Set();
+  const roots = rootValues.map((value, index) => {
+    const resolved = resolveContained(repoRoot, value, `verify.json roots[${index}]`);
+    const key = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    if (seenRoots.has(key)) throw new Error(`verify.json has duplicate root: ${value}`);
+    seenRoots.add(key);
+    return { declared: value, path: resolved };
+  });
+
+  const ids = new Set();
+  const checks = raw.checks.map((check, index) => {
+    if (!check || typeof check !== 'object' || Array.isArray(check)) throw new Error(`verify.json checks[${index}] must be an object`);
+    assertKnownFields(check, new Set(['id', 'run', 'cwd', 'timeoutSec']), `verify.json checks[${index}]`);
+    if (typeof check.id !== 'string' || !check.id.trim()) throw new Error(`verify.json checks[${index}].id must be non-empty`);
+    if (ids.has(check.id)) throw new Error(`verify.json check id is duplicated: ${check.id}`);
+    ids.add(check.id);
+    if (typeof check.run !== 'string' || !check.run.trim()) throw new Error(`verify.json checks[${index}].run must be non-empty`);
+    const cwdValue = check.cwd === undefined ? '.' : check.cwd;
+    const cwd = resolveContained(repoRoot, cwdValue, `verify.json checks[${index}].cwd`);
+    const timeoutSec = check.timeoutSec === undefined ? 600 : check.timeoutSec;
+    if (!Number.isInteger(timeoutSec) || timeoutSec < 1 || timeoutSec > MAX_TIMEOUT_SEC) {
+      throw new Error(`verify.json checks[${index}].timeoutSec must be an integer from 1 to ${MAX_TIMEOUT_SEC}`);
+    }
+    return {
+      id: check.id,
+      run: check.run.trim(),
+      cwd,
+      cwdDeclared: cwdValue,
+      timeoutSec,
+      source: 'contract',
+    };
+  });
+
+  for (const check of checks) {
+    const owners = roots.filter(root => within(root.path, check.cwd))
+      .sort((a, b) => b.path.length - a.path.length);
+    if (!owners.length) throw new Error(`verify.json check ${check.id} cwd is outside declared roots`);
+    check.root = owners[0].path;
+  }
+
+  return { path: contractPath, roots, checks };
+}
+
+function detectRunner(dir) {
+  if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(dir, 'bun.lockb')) || fs.existsSync(path.join(dir, 'bun.lock'))) return 'bun';
+  return 'npm';
+}
+
+function packageCommand(runner, name) {
+  return `${runner} run ${name}`;
+}
+
+function addCandidate(list, seen, candidate) {
+  const key = [candidate.source, candidate.run, candidate.cwd].join('\0');
+  if (seen.has(key)) return;
+  seen.add(key);
+  list.push(candidate);
+}
+
+function readTextIfExists(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+}
+
+function detectRoot(root) {
+  const checks = [];
+  const candidates = [];
+  const seen = new Set();
+  const pkgPath = path.join(root, 'package.json');
+
+  if (fs.existsSync(pkgPath)) {
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch (error) {
+      throw new Error(`package.json at ${root} is unreadable/invalid JSON (${error.message})`);
+    }
+    const scripts = pkg && typeof pkg === 'object' && pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    const runner = detectRunner(root);
+    for (const name of ['lint', 'test']) {
+      const script = scripts[name];
+      if (typeof script === 'string' && script.trim() && !/no test specified/i.test(script)) {
+        checks.push({
+          id: `package-${name}`,
+          run: packageCommand(runner, name),
+          cwd: root,
+          timeoutSec: 600,
+          source: 'package-auto',
+          root,
+        });
+      }
+    }
+    for (const name of ['check', 'typecheck', 'verify', 'build']) {
+      const script = scripts[name];
+      if (typeof script === 'string' && script.trim()) {
+        addCandidate(candidates, seen, { source: `package:${name}`, run: packageCommand(runner, name), cwd: root });
+      }
+    }
+  }
+
+  if (fs.existsSync(path.join(root, '.pre-commit-config.yaml')) || fs.existsSync(path.join(root, '.pre-commit-config.yml'))) {
+    addCandidate(candidates, seen, { source: 'pre-commit', run: 'pre-commit run --all-files', cwd: root });
+  }
+
+  const makeText = readTextIfExists(path.join(root, 'Makefile'));
+  if (makeText) {
+    const targets = new Set([...makeText.matchAll(/^([A-Za-z0-9_.-]+)\s*:(?![=])/gm)].map(match => match[1]));
+    for (const target of ['test', 'check', 'lint', 'ci']) {
+      if (targets.has(target)) addCandidate(candidates, seen, { source: 'make', run: `make ${target}`, cwd: root });
+    }
+  }
+
+  const justText = readTextIfExists(path.join(root, 'justfile')) || readTextIfExists(path.join(root, 'Justfile'));
+  if (justText) {
+    const recipes = new Set([...justText.matchAll(/^([A-Za-z0-9_-]+)\s*(?:[^:=\r\n]*)?:\s*$/gm)].map(match => match[1]));
+    for (const recipe of ['test', 'check', 'ci']) {
+      if (recipes.has(recipe)) addCandidate(candidates, seen, { source: 'just', run: `just ${recipe}`, cwd: root });
+    }
+  }
+
+  const pyproject = readTextIfExists(path.join(root, 'pyproject.toml'));
+  if (/\[tool\.pytest(?:\.|\])/m.test(pyproject)) {
+    addCandidate(candidates, seen, { source: 'pyproject:pytest', run: 'pytest', cwd: root });
+    addCandidate(candidates, seen, { source: 'pyproject:pytest', run: 'uv run pytest', cwd: root });
+  }
+  if (/\[tool\.ruff(?:\.|\])/m.test(pyproject)) {
+    addCandidate(candidates, seen, { source: 'pyproject:ruff', run: 'ruff check .', cwd: root });
+    addCandidate(candidates, seen, { source: 'pyproject:ruff', run: 'uv run ruff check .', cwd: root });
+  }
+  if (fs.existsSync(path.join(root, 'tsconfig.json'))) addCandidate(candidates, seen, { source: 'typescript', run: 'npx tsc --noEmit', cwd: root });
+  if (['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', '.eslintrc', '.eslintrc.json', '.eslintrc.js', '.eslintrc.cjs'].some(name => fs.existsSync(path.join(root, name)))) {
+    addCandidate(candidates, seen, { source: 'eslint', run: 'npx eslint .', cwd: root });
+  }
+  if (fs.existsSync(path.join(root, 'tox.ini'))) addCandidate(candidates, seen, { source: 'tox', run: 'tox', cwd: root });
+  if (fs.existsSync(path.join(root, 'noxfile.py'))) addCandidate(candidates, seen, { source: 'nox', run: 'nox', cwd: root });
+  if (fs.existsSync(path.join(root, 'Cargo.toml'))) addCandidate(candidates, seen, { source: 'cargo', run: 'cargo test', cwd: root });
+  if (fs.existsSync(path.join(root, 'go.mod'))) addCandidate(candidates, seen, { source: 'go', run: 'go test ./...', cwd: root });
+
+  if (hasCommitHook(root)) {
+    addCandidate(candidates, seen, { source: 'git-hook', run: 'git commit (pre-commit hook configured)', cwd: root });
+  }
+
+  return { checks, candidates };
+}
+
+function enumerateSubmoduleRoots(repoRoot) {
+  const roots = [path.resolve(repoRoot)];
+  const result = runGit(repoRoot, ['submodule', 'status', '--recursive']);
+  if (result.status !== 0 || !result.stdout.trim()) return roots;
+  for (const line of result.stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const match = line.match(/^[ +-U]?([0-9a-fA-F]{40,64})\s+(.+?)(?:\s+\(.+\))?$/);
+    if (!match) continue;
+    const candidate = path.resolve(repoRoot, match[2]);
+    if (within(repoRoot, candidate) && fs.existsSync(candidate)) roots.push(candidate);
+  }
+  return [...new Set(roots)];
+}
+
+function hookIsRunnable(stat, platform = process.platform) {
+  return !!stat && stat.isFile() && (platform === 'win32' || (stat.mode & 0o111) !== 0);
+}
+
+function hasCommitHook(repoRoot, platform = process.platform) {
+  const result = runGit(repoRoot, ['rev-parse', '--git-path', 'hooks/pre-commit']);
+  if (result.status !== 0) return false;
+  const value = result.stdout.trim();
+  if (!value) return false;
+  const hook = path.isAbsolute(value) ? value : path.resolve(repoRoot, value);
+  let stat;
+  try { stat = fs.statSync(hook); }
+  catch (_) { return false; }
+  return hookIsRunnable(stat, platform);
+}
+
+function normalizeCommand(command) {
+  return String(command || '').trim().replace(/\s+/g, ' ');
+}
+
+function hasControlOperators(command) {
+  return /(?:&&|\|\||[;|\r\n])/.test(command);
+}
+
+function commandMatches(command, expected) {
+  const actual = normalizeCommand(command);
+  const target = normalizeCommand(expected);
+  if (!actual || !target || hasControlOperators(actual)) return false;
+  return actual === target || actual.startsWith(target + ' ');
+}
+
+function isGitCommit(command) {
+  const actual = normalizeCommand(command);
+  return /^git\s+commit(?:\s|$)/i.test(actual);
+}
+
+function bypassesHooks(command) {
+  const actual = normalizeCommand(command);
+  if (/(?:^|\s)--no-verify(?:\s|$)/i.test(actual) || /(?:^|\s)-n(?:\s|$)/.test(actual)) return true;
+
+  // Git accepts boolean short options in clusters, e.g. `git commit -an`.
+  // Treat a cluster containing -n as hook bypass only when every clustered
+  // option is a no-argument commit flag; this avoids mistaking attached
+  // arguments such as `-S<key>` or `-m<message>` for --no-verify.
+  return actual.split(/\s+/).some(token =>
+    /^-[avqseipon]+$/i.test(token) && token.length > 2 && token.slice(1).toLowerCase().includes('n')
+  );
+}
+
+function legacyVerificationCommand(command) {
+  const value = normalizeCommand(command);
+  return /^(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|lint|build|typecheck|check|verify)\b|npx\s+(?:jest|vitest|mocha|tsc|eslint)\b|(?:jest|vitest|mocha|pytest|rspec|phpunit)\b|uv\s+run\s+(?:pytest|ruff)\b|(?:make|just)\s+(?:test|check|lint|ci)\b|cargo\s+(?:test|check)\b|go\s+test\b|dotnet\s+(?:test|build)\b)/i.test(value);
+}
+
+function verificationCommandSet(cwd, options = {}) {
+  const repoRoot = path.resolve(options.root || findGitRoot(cwd));
+  let contract = null;
+  try { contract = readContract(repoRoot); }
+  catch (error) {
+    // The verify gate treats an invalid authoritative contract as FAILED.
+    // Preserve that fail-closed state here instead of falling through to
+    // legacy recognition and manufacturing contradictory verification evidence.
+    return {
+      repoRoot,
+      contract: null,
+      contractInvalid: true,
+      contractError: error && error.message ? error.message : String(error),
+      commands: [],
+      commitHookDeclared: false,
+    };
+  }
+
+  if (contract) {
+    return {
+      repoRoot,
+      contract,
+      contractInvalid: false,
+      commands: contract.checks.map(check => check.run),
+      commitHookDeclared: contract.checks.some(check => /^pre-commit\s+/i.test(normalizeCommand(check.run))),
+    };
+  }
+
+  const root = findGitRoot(cwd);
+  let detected;
+  try { detected = detectRoot(root); }
+  catch (_) { detected = { checks: [], candidates: [] }; }
+  return {
+    repoRoot,
+    contract: null,
+    contractInvalid: false,
+    commands: [
+      ...detected.checks.map(check => check.run),
+      ...detected.candidates.filter(candidate => candidate.source !== 'git-hook').map(candidate => candidate.run),
+    ],
+    commitHookDeclared: false,
+  };
+}
+
+function isVerificationCommand(command, options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const actual = normalizeCommand(command);
+  if (!actual || hasControlOperators(actual)) return false;
+  const set = verificationCommandSet(cwd, options);
+  if (set.contractInvalid) return false;
+
+  if (isGitCommit(actual)) {
+    return !!set.commitHookDeclared && !bypassesHooks(actual) && hasCommitHook(set.repoRoot);
+  }
+  if (set.commands.some(expected => commandMatches(actual, expected))) return true;
+  return !set.contract && legacyVerificationCommand(actual);
+}
+
+module.exports = {
+  CONTRACT_RELATIVE,
+  MAX_TIMEOUT_SEC,
+  addCandidate,
+  commandMatches,
+  detectRoot,
+  enumerateSubmoduleRoots,
+  findGitRoot,
+  hasCommitHook,
+  hookIsRunnable,
+  isVerificationCommand,
+  legacyVerificationCommand,
+  normalizeCommand,
+  readContract,
+  resolveContained,
+  verificationCommandSet,
+  within,
+};

package/using-git-worktrees/SKILL.md

@@ -4,7 +4,7 @@ description: Use when work needs isolation or before major implementation plans
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.25.1
+  version: 0.27.0
 ---
 
 # Using Git Worktrees

package/using-git-worktrees/references/submodules-in-worktrees.md

@@ -111,9 +111,19 @@ git -C <primary> submodule update
 
 The PowerShell form is identical except paths/refs should be quoted as shown above.
 
+## Preferred automated check
+
+From the superproject worktree, run the cross-platform helper before staging a gitlink and again before removing the worktree:
+
+```bash
+node <this-skill-dir>/scripts/submodule-reachability.js --json
+```
+
+Exit 0 means every linked-worktree submodule commit was proven reachable outside the current worktree (or the superproject is not a linked worktree). An uninitialized gitlink is checked against the primary checkout and fails closed if that object is absent; initialize it to inspect remote refs, or fetch the commit into the primary checkout. Exit 1 means at least one commit is not proven externally reachable. Exit 2 is a usage/Git inspection error, including an unmerged submodule gitlink. The check MUST cover the current submodule HEAD and the gitlink SHAs in both the superproject index and HEAD. Checking out an older published submodule commit MUST NOT hide an unpublished staged or committed gitlink. The JSON report retains the working HEAD fields and adds `referencedCommits`, with each SHA, its `sources` (`index` and/or `HEAD`), and its external reachability evidence. Every referenced commit must pass before removal; a clean submodule status is valid input.
+
 ## Pre-removal check
 
-For every changed gitlink SHA, prove at least one external home exists:
+Prefer the helper above. Raw fallback: for every changed gitlink SHA, prove at least one external home exists:
 
 ```bash
 git -C <submodule> branch -r --contains <sha>

package/using-git-worktrees/scripts/submodule-reachability.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function runGit(args, cwd, { allowFailure = false } = {}) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (!allowFailure && result.status !== 0) {
+    const message = (result.stderr || result.stdout || '').trim();
+    throw new Error(`git ${args.join(' ')} failed${message ? `: ${message}` : ''}`);
+  }
+  return result;
+}
+
+function gitText(args, cwd, options) {
+  const result = runGit(args, cwd, options);
+  return result.status === 0 ? result.stdout.trim() : '';
+}
+
+function absoluteCommonDir(root) {
+  const absolute = runGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], root, { allowFailure: true });
+  if (absolute.status === 0) return path.resolve(absolute.stdout.trim());
+  const raw = gitText(['rev-parse', '--git-common-dir'], root);
+  return path.resolve(root, raw);
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+function samePath(a, b) {
+  const normalize = value => {
+    let resolved = path.resolve(value);
+    try { resolved = fs.realpathSync.native(resolved); } catch { /* keep resolved */ }
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  };
+  return normalize(a) === normalize(b);
+}
+
+function parseSubmoduleStatus(text) {
+  if (!text.trim()) return [];
+  return text.split(/\r?\n/).filter(Boolean).map(line => {
+    // gitText() trims the whole command output, so the first clean-status
+    // marker (a leading space) may already be gone. Accept only the four Git
+    // status states here; an omitted marker is normalized back to clean.
+    const match = line.match(/^([ +U-]?)([0-9a-fA-F]{40,64})\s+(.+?)(?:\s+\(.+\))?$/);
+    if (!match) throw new Error(`cannot parse git submodule status line: ${line}`);
+    return {
+      prefix: match[1] || ' ',
+      recordedSha: match[2],
+      path: match[3],
+    };
+  });
+}
+
+function primaryHasCommit(primaryRoot, commonDir, submodulePath, sha, moduleGitDir = null) {
+  if (!primaryRoot) return false;
+  const primarySub = path.join(primaryRoot, ...submodulePath.split('/'));
+  // A deinitialized submodule leaves an empty directory, and `git -C` then
+  // resolves to the enclosing repository. Only the exact submodule repo counts.
+  const toplevel = runGit(['-C', primarySub, 'rev-parse', '--show-toplevel'], primaryRoot, { allowFailure: true });
+  let result = null;
+  if (toplevel.status === 0 && samePath(toplevel.stdout.trim(), primarySub)) {
+    result = runGit(['-C', primarySub, 'cat-file', '-e', `${sha}^{commit}`], primaryRoot, { allowFailure: true });
+    if (result.status === 0) return true;
+  }
+
+  // A nested submodule repository is stored below its parent's module repo,
+  // e.g. .git/modules/parent/modules/child. Callers pass that exact location
+  // when recursion is known; direct submodules retain the historical fallback.
+  const candidateGitDir = moduleGitDir || path.join(commonDir, 'modules', ...submodulePath.split('/'));
+  result = runGit(['--git-dir', candidateGitDir, 'cat-file', '-e', `${sha}^{commit}`], primaryRoot, { allowFailure: true });
+  return result.status === 0;
+}
+
+// Read the recorded gitlinks from their owning repository, not from the
+// submodule working HEAD (which may have been checked out to an older commit).
+function recordedGitlinks(owner, relativePath) {
+  const commits = new Map();
+  function add(sha, source) {
+    if (!commits.has(sha)) commits.set(sha, { sha, sources: [] });
+    commits.get(sha).sources.push(source);
+  }
+  const index = runGit(['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', relativePath], owner).stdout;
+  for (const record of index.split('\0').filter(Boolean)) {
+    const match = record.match(/^160000 ([0-9a-f]{40,64}) ([0-3])\t(.*)$/s);
+    if (!match || match[3] !== relativePath) continue;
+    if (match[2] !== '0') throw new Error(`unmerged submodule gitlink cannot be verified: ${relativePath}`);
+    add(match[1], 'index');
+  }
+  if (runGit(['rev-parse', '--verify', 'HEAD'], owner, { allowFailure: true }).status === 0) {
+    const tree = runGit(['--literal-pathspecs', 'ls-tree', '-z', 'HEAD', '--', relativePath], owner).stdout;
+    for (const record of tree.split('\0').filter(Boolean)) {
+      const match = record.match(/^160000 commit ([0-9a-f]{40,64})\t(.*)$/s);
+      if (match && match[2] === relativePath) add(match[1], 'HEAD');
+    }
+  }
+  return [...commits.values()];
+}
+
+function inspect(root = process.cwd()) {
+  root = path.resolve(gitText(['rev-parse', '--show-toplevel'], path.resolve(root)));
+  const superGitDir = path.resolve(gitText(['rev-parse', '--absolute-git-dir'], root));
+  const commonDir = absoluteCommonDir(root);
+  const linkedWorktree = superGitDir !== commonDir;
+  const primaryRoot = linkedWorktree && path.basename(commonDir).toLowerCase() === '.git'
+    ? path.dirname(commonDir)
+    : null;
+  const status = gitText(['submodule', 'status', '--recursive'], root);
+  const submodules = [];
+  const initializedPaths = [];
+  const primaryModuleDirs = new Map();
+
+  for (const entry of parseSubmoduleStatus(status)) {
+    if (entry.prefix === 'U') {
+      throw new Error(`unmerged submodule gitlink cannot be verified: ${entry.path}`);
+    }
+
+    const parentPath = initializedPaths.filter(parent => entry.path.startsWith(parent + '/'))
+      .sort((a, b) => b.length - a.length)[0];
+    const owner = parentPath ? path.join(root, ...parentPath.split('/')) : root;
+    const relativePath = parentPath ? entry.path.slice(parentPath.length + 1) : entry.path;
+    const subPath = path.join(root, ...entry.path.split('/'));
+    const parentModuleGitDir = parentPath ? primaryModuleDirs.get(parentPath) : null;
+    const primaryModuleGitDir = parentPath
+      ? path.join(parentModuleGitDir, 'modules', ...relativePath.split('/'))
+      : path.join(commonDir, 'modules', ...entry.path.split('/'));
+    primaryModuleDirs.set(entry.path, primaryModuleGitDir);
+    const referencedCommits = recordedGitlinks(owner, relativePath).map(reference => {
+      // A recorded object may be absent locally but already recovered in primary.
+      const hasObject = entry.prefix !== '-' && runGit(
+        ['cat-file', '-e', `${reference.sha}^{commit}`], subPath, { allowFailure: true }
+      ).status === 0;
+      const remoteRefs = hasObject ? gitText(
+        ['for-each-ref', '--contains', reference.sha, '--format=%(refname:short)', 'refs/remotes/'], subPath
+      ).split(/\r?\n/).filter(Boolean) : [];
+      const presentInPrimary = linkedWorktree
+        ? primaryHasCommit(primaryRoot, commonDir, entry.path, reference.sha, primaryModuleGitDir) : true;
+      return {
+        ...reference,
+        remoteRefs,
+        reachableFromRemote: remoteRefs.length > 0,
+        presentInPrimary,
+        externallyReachable: !linkedWorktree || remoteRefs.length > 0 || presentInPrimary,
+      };
+    });
+
+    if (entry.prefix === '-') {
+      const presentInPrimary = linkedWorktree
+        ? primaryHasCommit(primaryRoot, commonDir, entry.path, entry.recordedSha, primaryModuleGitDir)
+        : true;
+      const externallyReachable = !linkedWorktree || presentInPrimary;
+      submodules.push({
+        path: entry.path,
+        sha: entry.recordedSha,
+        initialized: false,
+        detached: null,
+        perWorktreeModuleDir: null,
+        reachableFromRemote: false,
+        remoteRefs: [],
+        presentInPrimary,
+        referencedCommits,
+        externallyReachable: externallyReachable && referencedCommits.every(reference => reference.externallyReachable),
+      });
+      continue;
+    }
+
+    initializedPaths.push(entry.path);
+    const head = runGit(['-C', subPath, 'rev-parse', 'HEAD'], root, { allowFailure: true });
+    if (head.status !== 0) {
+      throw new Error(`cannot inspect initialized submodule ${entry.path}: ${(head.stderr || head.stdout || '').trim()}`);
+    }
+
+    const sha = head.stdout.trim();
+    const branch = gitText(['-C', subPath, 'branch', '--show-current'], root);
+    const subGitDir = path.resolve(gitText(['-C', subPath, 'rev-parse', '--absolute-git-dir'], root));
+    const remoteRefs = gitText(
+      ['-C', subPath, 'for-each-ref', '--contains', sha, '--format=%(refname:short)', 'refs/remotes/'],
+      root
+    ).split(/\r?\n/).filter(Boolean);
+    const reachableFromRemote = remoteRefs.length > 0;
+    const presentInPrimary = linkedWorktree
+      ? primaryHasCommit(primaryRoot, commonDir, entry.path, sha, primaryModuleGitDir)
+      : true;
+    const externallyReachable = !linkedWorktree || reachableFromRemote || presentInPrimary;
+
+    submodules.push({
+      path: entry.path,
+      sha,
+      initialized: true,
+      detached: branch === '',
+      branch: branch || null,
+      gitDir: subGitDir,
+      perWorktreeModuleDir: linkedWorktree && isInside(subGitDir, path.join(commonDir, 'worktrees')),
+      reachableFromRemote,
+      remoteRefs,
+      presentInPrimary,
+      referencedCommits,
+      externallyReachable: externallyReachable && referencedCommits.every(reference => reference.externallyReachable),
+    });
+  }
+
+  return {
+    root,
+    linkedWorktree,
+    gitDir: superGitDir,
+    commonDir,
+    primaryRoot,
+    ok: submodules.every(entry => entry.externallyReachable),
+    submodules,
+  };
+}
+
+function printHuman(report) {
+  console.log(`Superproject: ${report.root}`);
+  console.log(`Linked worktree: ${report.linkedWorktree ? 'yes' : 'no'}`);
+  if (!report.submodules.length) {
+    console.log('Submodules: none');
+    return;
+  }
+  for (const entry of report.submodules) {
+    const state = entry.externallyReachable ? 'OK' : 'UNREACHABLE';
+    console.log(`[${state}] ${entry.path} @ ${entry.sha}`);
+    for (const reference of entry.referencedCommits) {
+      console.log(`  ${reference.sources.join('/')} gitlink: ${reference.sha} (${reference.externallyReachable ? 'OK' : 'UNREACHABLE'})`);
+    }
+    if (!entry.initialized) {
+      console.log('  initialized: no');
+      console.log(`  present in primary checkout: ${entry.presentInPrimary ? 'yes' : 'no'}`);
+      if (report.linkedWorktree && !entry.presentInPrimary) {
+        console.log('  remote reachability: unverified; initialize the submodule or fetch the commit into the primary checkout');
+      }
+      continue;
+    }
+    console.log(`  branch: ${entry.branch || '(detached)'}`);
+    console.log(`  per-worktree git dir: ${entry.perWorktreeModuleDir ? 'yes' : 'no'}`);
+    console.log(`  remote reachability: ${entry.remoteRefs.length ? entry.remoteRefs.join(', ') : 'none'}`);
+    console.log(`  present in primary checkout: ${entry.presentInPrimary ? 'yes' : 'no'}`);
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const json = argv.includes('--json');
+  const rootIndex = argv.indexOf('--root');
+  const root = rootIndex >= 0 ? argv[rootIndex + 1] : process.cwd();
+  if (rootIndex >= 0 && !root) throw new Error('--root requires a path');
+  const report = inspect(root);
+  if (json) process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  else printHuman(report);
+  process.exitCode = report.ok ? 0 : 1;
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`submodule-reachability: ${error.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = { inspect, parseSubmoduleStatus, primaryHasCommit };