harness-everything 0.25.1 → 0.27.0

package/plugins/harness-everything/skills/harness-everything/scripts/verify-gate.js

@@ -1,100 +1,248 @@
 #!/usr/bin/env node
+'use strict';
+
 /**
- * Verification Gatekeeper
- * Runs the target project's own mechanical checks (lint/test scripts from the
- * nearest package.json) and refuses completion (Exit 1) when any of them fail.
+ * Harness project verification gate.
  *
- * Escape hatches, both deliberate:
- * - `.verify-fail.tmp` in cwd forces a failure - the hermetic self-regression
- *   suite uses it to prove the blocking mechanism without needing a real
- *   broken project.
- * - HARNESS_SKIP_PROJECT_CHECKS=1 skips the project-script phase (the tmp-file
- *   check above still applies). The gate sets it for its own children so a
- *   project whose test suite itself drives the Harness runtime (like this repo) cannot
- *   recurse back into the gate.
+ * Contract: .harness/verify.json
+ * Discovery: read-only candidates; legacy package lint/test remains auto-run.
+ * UNCHECKED_* is non-blocking control flow and is never passing-test evidence.
  */
-const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 
-console.log("=== 🛡️ Harness Verification Gate ===");
-
-// Phase 1: explicit failure injection (test/demo hook).
-if (fs.existsSync('.verify-fail.tmp')) {
-  console.error("❌ Verification FAILED: .verify-fail.tmp present (injected failure).");
-  console.error("Please fix the code and run this gate again.");
-  process.exit(1);
+function loadVerificationModel() {
+  for (const candidate of [
+    path.resolve(__dirname, '../../scripts/lib/verification-contract.js'),
+    path.resolve(__dirname, '../../../scripts/lib/verification-contract.js'),
+  ]) {
+    if (fs.existsSync(candidate)) return require(candidate);
+  }
+  throw new Error('verification-contract runtime is missing from this Harness distribution');
 }
 
-if (process.env.HARNESS_SKIP_PROJECT_CHECKS === '1') {
-  console.log("ℹ️ HARNESS_SKIP_PROJECT_CHECKS=1 - project scripts skipped (recursion guard / hermetic test mode).");
-  console.log("✅ Verification SUCCESS (injection check only).");
-  process.exit(0);
+const {
+  detectRoot,
+  enumerateSubmoduleRoots,
+  findGitRoot,
+  readContract,
+} = loadVerificationModel();
+
+const jsonMode = process.argv.includes('--json');
+const cwd = path.resolve(process.cwd());
+const repoRoot = findGitRoot(cwd);
+
+function emptyReport(status, reason) {
+  return {
+    status,
+    reason,
+    repoRoot,
+    roots: [],
+    checks: [],
+    candidates: [],
+  };
 }
 
-// Phase 2: locate the nearest package.json, walking up from cwd but never
-// above the enclosing git repository (same scoping rule as tier-router.js).
-function findPackageDir() {
-  let dir = path.resolve(process.cwd());
-  while (true) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    if (fs.existsSync(path.join(dir, '.git'))) return null; // repo root reached, none found
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
+function emit(report) {
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return;
+  }
+
+  console.log('=== 🛡️ Harness Verification Gate ===');
+  console.log(`Status: ${report.status}`);
+  console.log(`Repository: ${report.repoRoot}`);
+  if (report.reason) console.log(`Reason: ${report.reason}`);
+
+  for (const root of report.roots || []) {
+    console.log(`\n[${root.status}] ${root.path}`);
+    if (root.reason) console.log(`  ${root.reason}`);
+    for (const check of root.checks || []) {
+      const exit = check.exitCode === null ? 'timeout/error' : check.exitCode;
+      console.log(`  check ${check.id}: ${check.run} (exit ${exit}, ${check.durationMs}ms)`);
+      if (check.stdout) process.stdout.write(check.stdout.endsWith('\n') ? check.stdout : check.stdout + '\n');
+      if (check.stderr) process.stderr.write(check.stderr.endsWith('\n') ? check.stderr : check.stderr + '\n');
+    }
+    for (const candidate of root.candidates || []) {
+      console.log(`  candidate [${candidate.source}]: ${candidate.run}`);
+    }
   }
+
+  if (report.status === 'UNCHECKED_NO_CHECKS' || report.status === 'UNCHECKED_DISCOVERED') {
+    console.log('\nExit code is 0 (non-blocking), but NO COMPLETE AUTOMATED EVIDENCE was produced.');
+    console.log('PROHIBITED: Do NOT cite this run as proof that tests pass. Perform the listed or project-declared verification first.');
+  } else if (report.status === 'PASSED') {
+    console.log('\n✅ Verification PASSED. Objective project checks completed successfully.');
+  } else if (report.status === 'FAILED') {
+    console.error('\n❌ Verification FAILED. Fix the reported check/contract error and run this gate again.');
+  } else if (report.status === 'SKIPPED') {
+    console.log('ℹ️ Project checks skipped by HARNESS_SKIP_PROJECT_CHECKS=1.');
+  }
+}
+
+function finish(report) {
+  emit(report);
+  process.exit(report.status === 'FAILED' ? 1 : 0);
+}
+
+function statusRank(status) {
+  return {
+    PASSED: 0,
+    UNCHECKED_NO_CHECKS: 1,
+    UNCHECKED_DISCOVERED: 2,
+    FAILED: 3,
+  }[status] ?? 0;
+}
+
+function aggregateStatus(roots) {
+  if (!roots.length) return 'UNCHECKED_NO_CHECKS';
+  return roots.reduce((worst, root) => statusRank(root.status) > statusRank(worst) ? root.status : worst, 'PASSED');
 }
 
-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 executeCheck(check) {
+  const started = Date.now();
+  const result = spawnSync(check.run, {
+    cwd: check.cwd,
+    shell: true,
+    encoding: 'utf8',
+    windowsHide: true,
+    timeout: check.timeoutSec * 1000,
+    env: { ...process.env, HARNESS_SKIP_PROJECT_CHECKS: '1' },
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  const durationMs = Date.now() - started;
+  const timedOut = !!(result.error && result.error.code === 'ETIMEDOUT');
+  const exitCode = typeof result.status === 'number' ? result.status : null;
+  return {
+    id: check.id,
+    run: check.run,
+    cwd: check.cwd,
+    source: check.source,
+    exitCode,
+    durationMs,
+    timedOut,
+    signal: result.signal || null,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    passed: !timedOut && exitCode === 0,
+  };
 }
 
-const pkgDir = findPackageDir();
-let scripts = {};
-if (pkgDir) {
-  try {
-    scripts = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')).scripts || {};
-  } catch (err) {
-    console.error(`❌ Verification FAILED: package.json at ${pkgDir} is unreadable/invalid JSON (${err.message}).`);
-    process.exit(1);
+function publicCheck(check) {
+  return {
+    id: check.id,
+    run: check.run,
+    cwd: check.cwd,
+    source: check.source,
+    exitCode: check.exitCode,
+    durationMs: check.durationMs,
+    ...(check.timedOut ? { timedOut: true } : {}),
+    ...(check.signal ? { signal: check.signal } : {}),
+    ...(!jsonMode && check.stdout ? { stdout: check.stdout } : {}),
+    ...(!jsonMode && check.stderr ? { stderr: check.stderr } : {}),
+  };
+}
+
+function candidateView(candidate) {
+  return {
+    source: candidate.source,
+    run: candidate.run,
+    cwd: candidate.cwd,
+  };
+}
+
+function rootReason(status, checks, candidates) {
+  if (status === 'FAILED') {
+    const failed = checks.find(check => !check.passed);
+    if (!failed) return 'verification failed';
+    return failed.timedOut
+      ? `check ${failed.id} timed out after ${failed.durationMs}ms`
+      : `check ${failed.id} exited ${failed.exitCode}`;
   }
+  if (status === 'UNCHECKED_DISCOVERED') return `${candidates.length} verification candidate(s) detected but not executed`;
+  if (status === 'UNCHECKED_NO_CHECKS') return 'no project verification checks were declared or detected';
+  return `${checks.length} check(s) passed`;
 }
 
-// npm-init's placeholder ("no test specified" + exit 1) is absence of a test
-// suite, not a failing one - running it would block every fresh project.
-const runnable = ['lint', 'test'].filter(name =>
-  typeof scripts[name] === 'string' &&
-  scripts[name].trim() !== '' &&
-  !/no test specified/i.test(scripts[name])
-);
-
-if (!pkgDir || runnable.length === 0) {
-  console.log("⚠️ Verification UNCHECKED: No automated lint/test scripts detected in package.json.");
-  console.log("   Exit code is 0 (non-blocking), but NO AUTOMATED EVIDENCE was produced.");
-  console.log("   PROHIBITED: Do NOT cite this run as proof that tests pass. Perform manual or alternative verification first.");
-  process.exit(0);
+function contractPlan(contract) {
+  const rootResults = contract.roots.map(root => ({
+    path: root.path,
+    status: 'UNCHECKED_NO_CHECKS',
+    reason: '',
+    checks: [],
+    candidates: [],
+  }));
+  const byPath = new Map(rootResults.map(root => [path.resolve(root.path), root]));
+
+  for (const check of contract.checks) {
+    const executed = executeCheck(check);
+    const root = byPath.get(path.resolve(check.root));
+    root.checks.push(executed);
+  }
+
+  for (const root of rootResults) {
+    root.status = root.checks.length === 0
+      ? 'UNCHECKED_NO_CHECKS'
+      : root.checks.some(check => !check.passed) ? 'FAILED' : 'PASSED';
+    root.reason = rootReason(root.status, root.checks, root.candidates);
+  }
+  return rootResults;
 }
 
-const runner = detectRunner(pkgDir);
-for (const name of runnable) {
-  console.log(`\n▶ Running "${runner} run ${name}" in ${pkgDir} ...`);
-  try {
-    execSync(`${runner} run ${name}`, {
-      cwd: pkgDir,
-      stdio: 'inherit',
-      timeout: 10 * 60 * 1000,
-      env: { ...process.env, HARNESS_SKIP_PROJECT_CHECKS: '1' }
+function discoveredPlan() {
+  const roots = [];
+  for (const rootPath of enumerateSubmoduleRoots(repoRoot)) {
+    const detected = detectRoot(rootPath);
+    const executed = detected.checks.map(executeCheck);
+    const candidates = detected.candidates;
+    const status = executed.some(check => !check.passed)
+      ? 'FAILED'
+      : candidates.length > 0 ? 'UNCHECKED_DISCOVERED'
+        : executed.length > 0 ? 'PASSED' : 'UNCHECKED_NO_CHECKS';
+    roots.push({
+      path: rootPath,
+      status,
+      reason: rootReason(status, executed, candidates),
+      checks: executed,
+      candidates,
     });
-    console.log(`✅ ${name} passed.`);
-  } catch (err) {
-    console.error(`\n❌ Verification FAILED: "${runner} run ${name}" exited non-zero${err.signal ? ` (signal ${err.signal})` : ''}.`);
-    console.error("Fix the failures above and run this gate again.");
-    process.exit(1);
   }
+  return roots;
 }
 
-console.log("\n✅ Verification SUCCESS. You may now complete the task.");
-process.exit(0);
+function finalize(roots) {
+  const status = aggregateStatus(roots);
+  const failingRoot = roots.find(root => root.status === status);
+  const report = {
+    status,
+    reason: failingRoot ? failingRoot.reason : '',
+    repoRoot,
+    roots: roots.map(root => ({
+      path: root.path,
+      status: root.status,
+      reason: root.reason,
+      checks: root.checks.map(publicCheck),
+      candidates: root.candidates.map(candidateView),
+    })),
+    checks: roots.flatMap(root => root.checks.map(publicCheck)),
+    candidates: roots.flatMap(root => root.candidates.map(candidateView)),
+  };
+  finish(report);
+}
+
+try {
+  // Injection remains first and cannot be bypassed by the recursion guard.
+  if (fs.existsSync(path.join(cwd, '.verify-fail.tmp'))) {
+    finish(emptyReport('FAILED', '.verify-fail.tmp present (injected failure)'));
+  }
+
+  if (process.env.HARNESS_SKIP_PROJECT_CHECKS === '1') {
+    finish(emptyReport('SKIPPED', 'HARNESS_SKIP_PROJECT_CHECKS=1 recursion guard'));
+  }
+
+  const contract = readContract(repoRoot);
+  finalize(contract ? contractPlan(contract) : discoveredPlan());
+} catch (error) {
+  finish(emptyReport('FAILED', error && error.message ? error.message : String(error)));
+}

package/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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 };