harness-everything 0.26.0 → 0.27.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.26.0",
+      "version": "0.27.0",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "author": {
     "name": "Miya Daniel"
   },

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.27.0](https://github.com/dyphn1/Harness-everything/compare/v0.26.0...v0.27.0) (2026-09-27)
+
+### Features
+
+* **skills:** restore deterministic submodule reachability check ([0dd06e0](https://github.com/dyphn1/Harness-everything/commit/0dd06e0bd6aa38e04b3e8c11892d8d006c440821))
+
+### Bug Fixes
+
+* **plugin:** sync nested submodule reachability ([94dbe4c](https://github.com/dyphn1/Harness-everything/commit/94dbe4c94ed2278fcb5cb6faf0f252ef5b282323))
+* **skills:** land submodule reachability gate on main ([1b6de2b](https://github.com/dyphn1/Harness-everything/commit/1b6de2b5fd0cc6ae1b99530ef00c24f12efefb55))
+* **skills:** require exact primary submodule repo for reachability ([c3f0f76](https://github.com/dyphn1/Harness-everything/commit/c3f0f76e1a127837b1faa2f5bebe06c01da1e8e4))
+* **skills:** resolve nested submodule object stores ([aa6440b](https://github.com/dyphn1/Harness-everything/commit/aa6440b625b223948d6e69cbf9775fe45b861c50))
+* **skills:** verify staged and committed submodule references ([6678496](https://github.com/dyphn1/Harness-everything/commit/6678496acadea25465ff3283b97bc31e4d17d455))
+
 ## [0.26.0](https://github.com/dyphn1/Harness-everything/compare/v0.25.1...v0.26.0) (2026-09-24)
 
 ### Features

package/ci/mechanism-34-worktree-submodule-reachability.test.js

@@ -0,0 +1,307 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const HELPER = path.join(ROOT, 'using-git-worktrees', 'scripts', 'submodule-reachability.js');
+
+function run(command, args, cwd, { allowFailure = false, env = {}, input } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    input,
+    env: { ...process.env, ...env },
+  });
+  if (!allowFailure && result.status !== 0) {
+    throw new Error([
+      `${command} ${args.join(' ')} failed with ${result.status}`,
+      result.stdout,
+      result.stderr,
+    ].filter(Boolean).join('\n'));
+  }
+  return result;
+}
+
+function git(cwd, args, options) {
+  return run('git', args, cwd, options);
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, ['init', '-b', 'main']);
+  git(dir, ['config', 'user.name', 'Harness Test']);
+  git(dir, ['config', 'user.email', 'harness@example.invalid']);
+}
+
+function readJsonRun(cwd) {
+  const result = run(process.execPath, [HELPER, '--json'], cwd, { allowFailure: true });
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`helper did not emit JSON (status=${result.status}): ${result.stdout}\n${result.stderr}`);
+  }
+  return { ...result, parsed };
+}
+
+const base = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-submodule-reachability-'));
+
+try {
+  const child = path.join(base, 'child');
+  const superRepo = path.join(base, 'super');
+  const worktree = path.join(base, 'super-wt');
+
+  initRepo(child);
+  fs.writeFileSync(path.join(child, 'seed.txt'), 'seed\n');
+  git(child, ['add', 'seed.txt']);
+  git(child, ['commit', '-m', 'seed']);
+  const seedSha = git(child, ['rev-parse', 'HEAD']).stdout.trim();
+
+  initRepo(superRepo);
+  fs.writeFileSync(path.join(superRepo, 'README.md'), 'super\n');
+  git(superRepo, ['add', 'README.md']);
+  git(superRepo, ['commit', '-m', 'super seed']);
+  git(superRepo, ['-c', 'protocol.file.allow=always', 'submodule', 'add', child, 'libs/sub']);
+  git(superRepo, ['commit', '-am', 'add submodule']);
+
+  git(superRepo, ['worktree', 'add', worktree, '-b', 'feat']);
+  git(worktree, ['-c', 'protocol.file.allow=always', 'submodule', 'update', '--init']);
+  const linkedSub = path.join(worktree, 'libs', 'sub');
+  git(linkedSub, ['config', 'user.name', 'Harness Test']);
+  git(linkedSub, ['config', 'user.email', 'harness@example.invalid']);
+
+  // Clean initialized submodules use a leading-space status marker. The helper
+  // must preserve/normalize that state instead of consuming the first SHA byte
+  // as a prefix when command output is trimmed.
+  const cleanRawStatus = git(worktree, ['submodule', 'status', '--recursive']).stdout;
+  assert.match(cleanRawStatus, /^ [0-9a-f]{40,64}\s+libs\/sub\b/, 'fixture must begin with a clean initialized submodule');
+  const clean = readJsonRun(worktree);
+  assert.strictEqual(clean.status, 0, 'a clean initialized linked-worktree submodule must be inspectable');
+  assert.strictEqual(clean.parsed.ok, true);
+  assert.strictEqual(clean.parsed.linkedWorktree, true);
+  const cleanSub = clean.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.ok(cleanSub, 'clean initialized submodule must be reported');
+  assert.strictEqual(cleanSub.sha, seedSha);
+  assert.strictEqual(cleanSub.initialized, true);
+  assert.strictEqual(cleanSub.detached, true);
+  assert.strictEqual(cleanSub.externallyReachable, true);
+
+  // RED case: a new commit exists only in the linked worktree's submodule git dir.
+  git(linkedSub, ['commit', '--allow-empty', '-m', 'isolated child commit']);
+  const isolatedSha = git(linkedSub, ['rev-parse', 'HEAD']).stdout.trim();
+  const isolated = readJsonRun(worktree);
+  assert.strictEqual(isolated.status, 1, 'an unpublished linked-worktree submodule commit must fail');
+  assert.strictEqual(isolated.parsed.ok, false);
+  assert.strictEqual(isolated.parsed.linkedWorktree, true);
+  const isolatedSub = isolated.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.ok(isolatedSub, 'submodule must be reported');
+  assert.strictEqual(isolatedSub.sha, isolatedSha);
+  assert.strictEqual(isolatedSub.detached, true, 'submodule update should leave HEAD detached');
+  assert.strictEqual(isolatedSub.perWorktreeModuleDir, true);
+  assert.strictEqual(isolatedSub.reachableFromRemote, false);
+  assert.strictEqual(isolatedSub.presentInPrimary, false);
+  assert.strictEqual(isolatedSub.externallyReachable, false);
+
+  // A local branch name alone does not make the commit externally reachable.
+  git(linkedSub, ['switch', '-c', 'task']);
+  const namedLocal = readJsonRun(worktree);
+  assert.strictEqual(namedLocal.status, 1, 'a named but unpublished branch must still fail');
+  const namedLocalSub = namedLocal.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.strictEqual(namedLocalSub.detached, false);
+  assert.strictEqual(namedLocalSub.reachableFromRemote, false);
+  assert.strictEqual(namedLocalSub.presentInPrimary, false);
+  assert.strictEqual(namedLocalSub.externallyReachable, false);
+
+  // Recovery path: name the commit, fetch it into the primary checkout's submodule object store.
+  const primarySub = path.join(superRepo, 'libs', 'sub');
+  git(primarySub, ['fetch', linkedSub, 'task:task']);
+  const recovered = readJsonRun(worktree);
+  assert.strictEqual(recovered.status, 0, 'a commit present in the primary checkout must pass');
+  const recoveredSub = recovered.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.strictEqual(recoveredSub.presentInPrimary, true);
+  assert.strictEqual(recoveredSub.externallyReachable, true);
+
+  // Remote path: make a new commit that is absent from primary, then publish it.
+  git(linkedSub, ['switch', 'task']);
+  git(linkedSub, ['commit', '--allow-empty', '-m', 'remote child commit']);
+  const remoteSha = git(linkedSub, ['rev-parse', 'HEAD']).stdout.trim();
+  git(linkedSub, ['push', '-u', 'origin', 'task']);
+  const remote = readJsonRun(worktree);
+  assert.strictEqual(remote.status, 0, 'a commit reachable from a remote-tracking ref must pass');
+  const remoteSub = remote.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.strictEqual(remoteSub.sha, remoteSha);
+  assert.strictEqual(remoteSub.reachableFromRemote, true);
+  assert.strictEqual(remoteSub.externallyReachable, true);
+
+  // A published working HEAD must not hide an unpublished staged/committed gitlink.
+  git(linkedSub, ['commit', '--allow-empty', '-m', 'recorded but unpublished']);
+  const recordedSha = git(linkedSub, ['rev-parse', 'HEAD']).stdout.trim();
+  git(worktree, ['add', 'libs/sub']);
+  git(linkedSub, ['checkout', '--detach', seedSha]);
+  const stagedOnly = readJsonRun(worktree);
+  assert.deepStrictEqual(readJsonRun(worktree).parsed, stagedOnly.parsed, 'identical topology must produce identical evidence');
+  assert.strictEqual(stagedOnly.status, 1, 'the unpublished index SHA must fail even with a published working HEAD');
+  let reference = stagedOnly.parsed.submodules[0].referencedCommits.find(item => item.sha === recordedSha);
+  assert.deepStrictEqual(reference.sources, ['index']);
+  assert.strictEqual(reference.externallyReachable, false);
+
+  git(worktree, ['commit', '-m', 'record unpublished gitlink']);
+  // Stage the safe SHA over it: the unsafe committed SHA must still be checked.
+  git(worktree, ['add', 'libs/sub']);
+  const committedOnly = readJsonRun(worktree);
+  assert.strictEqual(committedOnly.status, 1, 'the unpublished superproject HEAD SHA must fail independently of index and working HEAD');
+  reference = committedOnly.parsed.submodules[0].referencedCommits.find(item => item.sha === recordedSha);
+  assert.deepStrictEqual(reference.sources, ['HEAD']);
+  assert.strictEqual(reference.externallyReachable, false);
+
+  git(primarySub, ['fetch', linkedSub, 'task:recorded-recovery']);
+  const recordedRecovered = readJsonRun(worktree);
+  assert.deepStrictEqual(readJsonRun(worktree).parsed, recordedRecovered.parsed, 'recovered evidence must be deterministic');
+  assert.strictEqual(recordedRecovered.status, 0, 'recovering the recorded SHA in primary must allow the unchanged topology');
+  reference = recordedRecovered.parsed.submodules[0].referencedCommits.find(item => item.sha === recordedSha);
+  assert.strictEqual(reference.presentInPrimary, true);
+  assert.strictEqual(reference.externallyReachable, true);
+
+  // Nested recovery: Git stores a nested submodule under the parent's module
+  // repository (.../modules/<parent>/modules/<child>), not by flattening the
+  // full worktree path below the top-level common dir.
+  const nestedLeafOrigin = path.join(base, 'nested-leaf-origin');
+  const nestedParentOrigin = path.join(base, 'nested-parent-origin');
+  const nestedSuper = path.join(base, 'nested-super');
+  const nestedWorktree = path.join(base, 'nested-super-wt');
+
+  initRepo(nestedLeafOrigin);
+  fs.writeFileSync(path.join(nestedLeafOrigin, 'leaf.txt'), 'leaf\n');
+  git(nestedLeafOrigin, ['add', 'leaf.txt']);
+  git(nestedLeafOrigin, ['commit', '-m', 'leaf seed']);
+
+  initRepo(nestedParentOrigin);
+  fs.writeFileSync(path.join(nestedParentOrigin, 'parent.txt'), 'parent\n');
+  git(nestedParentOrigin, ['add', 'parent.txt']);
+  git(nestedParentOrigin, ['commit', '-m', 'parent seed']);
+  git(nestedParentOrigin, ['-c', 'protocol.file.allow=always', 'submodule', 'add', nestedLeafOrigin, 'nested/leaf']);
+  git(nestedParentOrigin, ['commit', '-am', 'add nested leaf']);
+
+  initRepo(nestedSuper);
+  fs.writeFileSync(path.join(nestedSuper, 'README.md'), 'nested super\n');
+  git(nestedSuper, ['add', 'README.md']);
+  git(nestedSuper, ['commit', '-m', 'nested super seed']);
+  git(nestedSuper, ['-c', 'protocol.file.allow=always', 'submodule', 'add', nestedParentOrigin, 'libs/sub']);
+  git(nestedSuper, ['commit', '-am', 'add nested parent']);
+  git(nestedSuper, ['worktree', 'add', nestedWorktree, '-b', 'nested-feat']);
+  git(nestedWorktree, ['-c', 'protocol.file.allow=always', 'submodule', 'update', '--init', '--recursive']);
+
+  const linkedNestedLeaf = path.join(nestedWorktree, 'libs', 'sub', 'nested', 'leaf');
+  git(linkedNestedLeaf, ['config', 'user.name', 'Harness Test']);
+  git(linkedNestedLeaf, ['config', 'user.email', 'harness@example.invalid']);
+  git(linkedNestedLeaf, ['switch', '-c', 'nested-task']);
+  git(linkedNestedLeaf, ['commit', '--allow-empty', '-m', 'nested worktree-only commit']);
+  const nestedSha = git(linkedNestedLeaf, ['rev-parse', 'HEAD']).stdout.trim();
+
+  const primaryNestedParent = path.join(nestedSuper, 'libs', 'sub');
+  git(primaryNestedParent, ['-c', 'protocol.file.allow=always', 'submodule', 'update', '--init', '--recursive']);
+  const primaryNestedLeaf = path.join(primaryNestedParent, 'nested', 'leaf');
+  git(primaryNestedLeaf, ['fetch', linkedNestedLeaf, 'nested-task:nested-recovery']);
+  git(primaryNestedParent, ['submodule', 'deinit', '--force', '--', 'nested/leaf']);
+
+  const nestedRecovered = readJsonRun(nestedWorktree);
+  assert.strictEqual(nestedRecovered.status, 0, 'a nested commit recovered only in the primary module object store must pass');
+  const nestedEntry = nestedRecovered.parsed.submodules.find(entry => entry.path === 'libs/sub/nested/leaf');
+  assert.ok(nestedEntry, 'nested submodule must be reported');
+  assert.strictEqual(nestedEntry.sha, nestedSha);
+  assert.strictEqual(nestedEntry.reachableFromRemote, false);
+  assert.strictEqual(nestedEntry.presentInPrimary, true);
+  assert.strictEqual(nestedEntry.externallyReachable, true);
+
+  // No-submodule control.
+  const plain = path.join(base, 'plain');
+  initRepo(plain);
+  git(plain, ['commit', '--allow-empty', '-m', 'plain']);
+  const noSubmodule = readJsonRun(plain);
+  assert.strictEqual(noSubmodule.status, 0);
+  assert.strictEqual(noSubmodule.parsed.ok, true);
+  assert.deepStrictEqual(noSubmodule.parsed.submodules, []);
+
+  // A deinitialized submodule can make `git -C <submodule>` resolve to the
+  // superproject. Never use that unrelated HEAD or its remote refs as proof
+  // that the staged gitlink is reachable.
+  const uninitWorktree = path.join(base, 'super-wt-uninitialized');
+  git(superRepo, ['worktree', 'add', uninitWorktree, '-b', 'feat-uninitialized']);
+  git(uninitWorktree, ['-c', 'protocol.file.allow=always', 'submodule', 'update', '--init']);
+  const uninitializedSub = path.join(uninitWorktree, 'libs', 'sub');
+  git(uninitializedSub, ['config', 'user.name', 'Harness Test']);
+  git(uninitializedSub, ['config', 'user.email', 'harness@example.invalid']);
+  git(uninitializedSub, ['commit', '--allow-empty', '-m', 'uninitialized submodule commit']);
+  const uninitializedSha = git(uninitializedSub, ['rev-parse', 'HEAD']).stdout.trim();
+  git(uninitWorktree, ['add', 'libs/sub']);
+  const superSha = git(uninitWorktree, ['rev-parse', 'HEAD']).stdout.trim();
+  git(uninitWorktree, ['update-ref', 'refs/remotes/origin/main', superSha]);
+  git(uninitWorktree, ['submodule', 'deinit', '--force', '--', 'libs/sub']);
+
+  const uninitialized = readJsonRun(uninitWorktree);
+  assert.strictEqual(uninitialized.status, 1, 'an uninitialized staged gitlink without external reachability must fail');
+  const uninitializedEntry = uninitialized.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.ok(uninitializedEntry, 'uninitialized submodule must be reported');
+  assert.strictEqual(uninitializedEntry.initialized, false);
+  assert.strictEqual(uninitializedEntry.sha, uninitializedSha);
+  assert.strictEqual(uninitializedEntry.reachableFromRemote, false);
+  assert.strictEqual(uninitializedEntry.presentInPrimary, false);
+  assert.strictEqual(uninitializedEntry.externallyReachable, false);
+
+  // An unmerged gitlink has no single target SHA and must fail as an
+  // inspection error instead of checking the submodule's current HEAD.
+  const conflictWorktree = path.join(base, 'super-wt-conflict');
+  git(superRepo, ['worktree', 'add', conflictWorktree, '-b', 'feat-conflict']);
+  git(conflictWorktree, ['-c', 'protocol.file.allow=always', 'submodule', 'update', '--init']);
+  const zeroSha = '0'.repeat(seedSha.length);
+  const conflictIndex = [
+    `0 ${zeroSha} 0\tlibs/sub`,
+    `160000 ${seedSha} 1\tlibs/sub`,
+    `160000 ${isolatedSha} 2\tlibs/sub`,
+    `160000 ${remoteSha} 3\tlibs/sub`,
+    '',
+  ].join('\n');
+  git(conflictWorktree, ['update-index', '--index-info'], { input: conflictIndex });
+  const conflictStatus = git(conflictWorktree, ['submodule', 'status', '--recursive']).stdout.trim();
+  assert.match(conflictStatus, /^U/, `fixture must produce an unmerged gitlink: ${conflictStatus}`);
+  const conflict = run(process.execPath, [HELPER, '--json'], conflictWorktree, { allowFailure: true });
+  assert.strictEqual(conflict.status, 2, `unmerged gitlink must fail inspection: ${conflict.stdout}\n${conflict.stderr}`);
+  assert.match(conflict.stderr, /unmerged submodule gitlink/i);
+
+  // A deinitialized primary submodule leaves an empty directory, so
+  // `git -C <primary>/<submodule>` resolves to the primary superproject. An
+  // object in that unrelated store is not proof of submodule reachability.
+  const fallbackWorktree = path.join(base, 'super-wt-primary-fallback');
+  git(superRepo, ['worktree', 'add', fallbackWorktree, '-b', 'feat-primary-fallback']);
+  git(fallbackWorktree, ['-c', 'protocol.file.allow=always', 'submodule', 'update', '--init']);
+  const fallbackSub = path.join(fallbackWorktree, 'libs', 'sub');
+  git(fallbackSub, ['config', 'user.name', 'Harness Test']);
+  git(fallbackSub, ['config', 'user.email', 'harness@example.invalid']);
+  git(fallbackSub, ['switch', '-c', 'fallback-task']);
+  git(fallbackSub, ['commit', '--allow-empty', '-m', 'superproject-store only commit']);
+  const fallbackSha = git(fallbackSub, ['rev-parse', 'HEAD']).stdout.trim();
+  git(fallbackWorktree, ['add', 'libs/sub']);
+  // Empty the primary checkout directory without touching shared submodule
+  // config, which would also uninitialize the linked worktree.
+  fs.rmSync(primarySub, { recursive: true, force: true });
+  fs.mkdirSync(primarySub);
+  fs.rmSync(path.join(superRepo, '.git', 'modules', 'libs', 'sub'), { recursive: true, force: true });
+  git(superRepo, ['fetch', fallbackSub, 'fallback-task:refs/foreign/fallback-task']);
+  assert.strictEqual(git(superRepo, ['cat-file', '-e', `${fallbackSha}^{commit}`], { allowFailure: true }).status, 0,
+    'fixture must place the commit only in the primary superproject object store');
+  const fallback = readJsonRun(fallbackWorktree);
+  assert.strictEqual(fallback.status, 1, 'a commit found only through git -C fallback to the superproject must fail');
+  const fallbackEntry = fallback.parsed.submodules.find(entry => entry.path === 'libs/sub');
+  assert.strictEqual(fallbackEntry.initialized, true);
+  assert.strictEqual(fallbackEntry.sha, fallbackSha);
+  assert.strictEqual(fallbackEntry.presentInPrimary, false);
+  assert.strictEqual(fallbackEntry.externallyReachable, false);
+
+  console.log('Worktree submodule reachability: detached, named-unpublished, uninitialized, and unmerged gitlinks fail safely; primary/remote reachability and no-submodule controls pass.');
+} finally {
+  fs.rmSync(base, { recursive: true, force: true });
+}

package/ci/mutation-check.js

@@ -15,6 +15,7 @@ const checks = [
   ['transcript command qualifiers', 'behavioral-evals/transcript-parser.js', 'ci/mechanism-2t-transcript-parser.test.js'],
   ['fixture path boundaries', 'behavioral-evals/run.js', 'ci/mechanism-2j-behavioral-runner.test.js'],
   ['unbound workspace identity', 'scripts/lib/workspace.js', 'ci/mechanism-2u-issue-42-regressions.test.js'],
+  ['worktree submodule reachability', 'using-git-worktrees/scripts/submodule-reachability.js', 'ci/mechanism-34-worktree-submodule-reachability.test.js'],
   ['verification contract precedence', 'harness-everything/scripts/verify-gate.js', 'ci/mechanism-35-verification-contract.test.js'],
 ];
 
@@ -33,6 +34,7 @@ for (const [label, target, testFile] of checks) {
         'behavioral-evals/transcript-parser.js': 'transcript-command',
         'behavioral-evals/run.js': 'runner-fixture',
         'scripts/lib/workspace.js': 'workspace-identity',
+        'using-git-worktrees/scripts/submodule-reachability.js': 'submodule-reachability',
         'harness-everything/scripts/verify-gate.js': 'verify-contract-precedence',
       }[target],
       HARNESS_MUTATION_TARGET: path.join(ROOT, target),

package/ci/mutation-loader.js

@@ -40,6 +40,10 @@ const mutations = {
     '  if (!workspaceRoot) return UNBOUND_WORKSPACE_KEY;',
     '  if (!workspaceRoot) return path.basename(process.cwd()); // mutation: derive unbound identity from cwd'
   ),
+  'submodule-reachability': (source) => source.replace(
+    '    const externallyReachable = !linkedWorktree || reachableFromRemote || presentInPrimary;',
+    '    const externallyReachable = true; // mutation: accept isolated worktree-only commits'
+  ),
   'verify-contract-precedence': (source) => source.replace(
     '  finalize(contract ? contractPlan(contract) : discoveredPlan());',
     '  finalize(discoveredPlan()); // mutation: ignore the authoritative project contract'

package/git-commit/SKILL.md

@@ -4,7 +4,7 @@ description: "Generate Angular-style commit messages after verifying the environ
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.19.1
+  version: 0.27.0
 ---
 
 # Git Commit (Angular Style)
@@ -20,7 +20,7 @@ metadata:
 
 ## Quick Workflow
 
-1. **MUST** run `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
+1. **MUST** run `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`, including its worktree reachability gate.
 2. **MUST** inspect `git diff --cached` before committing. Nothing staged → prompt user / stage only user-authorized targeted files. Unrelated concerns **SHOULD** be split unless coupling or explicit user intent justifies one commit.
 3. Format `<type>(<scope>): <subject>` per `<this-skill-dir>/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
 4. `git commit -m "..."`, then **MUST** verify the result with `git log -1`.

package/git-commit/guides/SUBMODULES.md

@@ -14,6 +14,59 @@
 3. Generation: For Sub Repos WITH staged changes, MUST execute `COMMIT_GENERATION.md`.
 4. Validation: MUST verify generation success. IF ANY Sub Repo has remaining staged changes, MUST diagnose failure and halt.
 
+## [Reachability Phase]
+Before staging any changed submodule gitlink in the Main Repo, MUST run the preferred deterministic check:
+
+```bash
+node <skills-repo-root>/using-git-worktrees/scripts/submodule-reachability.js --json
+```
+
+- Exit 0: continue to Indexing.
+- Exit 1: MUST stop before staging and inspect the reported unreachable submodule(s); use the options below.
+- Exit 2: MUST diagnose the inspection failure before staging.
+
+If the helper is unavailable, use this raw fallback. First determine whether the Main Repo is a linked worktree:
+
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+```
+
+If the git dir and common dir differ, then for EACH changed Sub Repo:
+
+1. Identify the repository that **owns** the gitlink and the submodule path relative to that owner. For a direct submodule the owner is the Main Repo; for a nested submodule it is the immediate parent submodule. If this cannot be identified reliably, MUST stop and use the helper rather than guess.
+2. Collect every commit that can affect the recorded gitlink, not only the current working HEAD:
+   ```bash
+   git -C <submodule> rev-parse HEAD
+   git -C <owner> ls-files --stage -- <relative-submodule-path>
+   git -C <owner> ls-tree HEAD -- <relative-submodule-path>
+   ```
+   From the last two commands, only mode `160000` stage `0` entries are valid gitlinks. Any stage `1`–`3` entry is unmerged and MUST stop. Check every unique SHA from working HEAD, index, and owner HEAD.
+3. Check whether the Sub Repo is detached:
+   ```bash
+   git -C <submodule> branch --show-current
+   ```
+4. For EACH collected SHA, first check remote-tracking reachability:
+   ```bash
+   git -C <submodule> branch -r --contains <sha>
+   ```
+   If no remote-tracking ref contains it, prove that the **exact** primary-checkout submodule repository owns the object:
+   ```bash
+   git -C <primary>/<submodule> rev-parse --show-toplevel
+   git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+   ```
+   The reported top-level path MUST equal the expected primary submodule path. A missing/deinitialized nested path can make `git -C` fall back to a parent repository; that is not proof. If the exact primary submodule cannot be proven, initialize/fetch it or use the helper, otherwise MUST fail closed.
+
+A branch name alone does not publish a commit. If ANY working/index/HEAD gitlink SHA has neither a containing remote-tracking ref nor a proven exact primary-submodule object, it is an **unpublished gitlink risk**, whether the submodule is detached or on a named branch. MUST stop before `git add <submodule>` and present:
+
+- **[1] Create/publish a branch** — hand off to `<skills-repo-root>/using-git-worktrees/references/submodules-in-worktrees.md`.
+- **[2] Stage anyway** — only on explicit user choice; MUST record the unpublished gitlink risk in the handoff.
+- **[3] Abort** — do not stage the gitlink.
+
+`git-commit` MUST NOT create branches or push as part of this gate. It only detects the risk and hands off to the worktree reference when publication is needed.
+
+If the Main Repo is not a linked worktree, or the commit is already externally reachable, continue normally.
+
 ## [Indexing Phase]
 5. Preference Check: MUST read the resolved Harness memory file `git-commit-prefs.md` for the `auto_stage_submodules` setting. Prefer an existing `MEMORY.md`/`RULES.md`; otherwise use `.github/harness-everything/memories/git-commit-prefs.md`.
 6. Execution:
@@ -24,4 +77,4 @@
    - IF user selects [2]: MUST NOT run `git add`.
 
 ## [State Handoff]
-7. Handoff: MUST summarize completed Sub Repo updates (including paths and logs) and explicitly carry them over when returning control to `SKILL.md`.
+7. Handoff: MUST summarize completed Sub Repo updates (including paths, commit SHA, publication/reachability evidence, and logs) and explicitly carry them over when returning control to `SKILL.md`.

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/skills/git-commit/SKILL.md

@@ -4,7 +4,7 @@ description: "Generate Angular-style commit messages after verifying the environ
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.19.1
+  version: 0.27.0
 ---
 
 # Git Commit (Angular Style)
@@ -20,7 +20,7 @@ metadata:
 
 ## Quick Workflow
 
-1. **MUST** run `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
+1. **MUST** run `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`, including its worktree reachability gate.
 2. **MUST** inspect `git diff --cached` before committing. Nothing staged → prompt user / stage only user-authorized targeted files. Unrelated concerns **SHOULD** be split unless coupling or explicit user intent justifies one commit.
 3. Format `<type>(<scope>): <subject>` per `<this-skill-dir>/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
 4. `git commit -m "..."`, then **MUST** verify the result with `git log -1`.

package/plugins/harness-everything/skills/git-commit/guides/SUBMODULES.md

@@ -14,6 +14,59 @@
 3. Generation: For Sub Repos WITH staged changes, MUST execute `COMMIT_GENERATION.md`.
 4. Validation: MUST verify generation success. IF ANY Sub Repo has remaining staged changes, MUST diagnose failure and halt.
 
+## [Reachability Phase]
+Before staging any changed submodule gitlink in the Main Repo, MUST run the preferred deterministic check:
+
+```bash
+node <skills-repo-root>/using-git-worktrees/scripts/submodule-reachability.js --json
+```
+
+- Exit 0: continue to Indexing.
+- Exit 1: MUST stop before staging and inspect the reported unreachable submodule(s); use the options below.
+- Exit 2: MUST diagnose the inspection failure before staging.
+
+If the helper is unavailable, use this raw fallback. First determine whether the Main Repo is a linked worktree:
+
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+```
+
+If the git dir and common dir differ, then for EACH changed Sub Repo:
+
+1. Identify the repository that **owns** the gitlink and the submodule path relative to that owner. For a direct submodule the owner is the Main Repo; for a nested submodule it is the immediate parent submodule. If this cannot be identified reliably, MUST stop and use the helper rather than guess.
+2. Collect every commit that can affect the recorded gitlink, not only the current working HEAD:
+   ```bash
+   git -C <submodule> rev-parse HEAD
+   git -C <owner> ls-files --stage -- <relative-submodule-path>
+   git -C <owner> ls-tree HEAD -- <relative-submodule-path>
+   ```
+   From the last two commands, only mode `160000` stage `0` entries are valid gitlinks. Any stage `1`–`3` entry is unmerged and MUST stop. Check every unique SHA from working HEAD, index, and owner HEAD.
+3. Check whether the Sub Repo is detached:
+   ```bash
+   git -C <submodule> branch --show-current
+   ```
+4. For EACH collected SHA, first check remote-tracking reachability:
+   ```bash
+   git -C <submodule> branch -r --contains <sha>
+   ```
+   If no remote-tracking ref contains it, prove that the **exact** primary-checkout submodule repository owns the object:
+   ```bash
+   git -C <primary>/<submodule> rev-parse --show-toplevel
+   git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+   ```
+   The reported top-level path MUST equal the expected primary submodule path. A missing/deinitialized nested path can make `git -C` fall back to a parent repository; that is not proof. If the exact primary submodule cannot be proven, initialize/fetch it or use the helper, otherwise MUST fail closed.
+
+A branch name alone does not publish a commit. If ANY working/index/HEAD gitlink SHA has neither a containing remote-tracking ref nor a proven exact primary-submodule object, it is an **unpublished gitlink risk**, whether the submodule is detached or on a named branch. MUST stop before `git add <submodule>` and present:
+
+- **[1] Create/publish a branch** — hand off to `<skills-repo-root>/using-git-worktrees/references/submodules-in-worktrees.md`.
+- **[2] Stage anyway** — only on explicit user choice; MUST record the unpublished gitlink risk in the handoff.
+- **[3] Abort** — do not stage the gitlink.
+
+`git-commit` MUST NOT create branches or push as part of this gate. It only detects the risk and hands off to the worktree reference when publication is needed.
+
+If the Main Repo is not a linked worktree, or the commit is already externally reachable, continue normally.
+
 ## [Indexing Phase]
 5. Preference Check: MUST read the resolved Harness memory file `git-commit-prefs.md` for the `auto_stage_submodules` setting. Prefer an existing `MEMORY.md`/`RULES.md`; otherwise use `.github/harness-everything/memories/git-commit-prefs.md`.
 6. Execution:
@@ -24,4 +77,4 @@
    - IF user selects [2]: MUST NOT run `git add`.
 
 ## [State Handoff]
-7. Handoff: MUST summarize completed Sub Repo updates (including paths and logs) and explicitly carry them over when returning control to `SKILL.md`.
+7. Handoff: MUST summarize completed Sub Repo updates (including paths, commit SHA, publication/reachability evidence, and logs) and explicitly carry them over when returning control to `SKILL.md`.

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 };

package/sbom.cdx.json

@@ -2,23 +2,23 @@
   "$schema": "https://cyclonedx.org/schema/bom-1.7.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.7",
-  "serialNumber": "urn:uuid:d5232bfe-e479-5e87-a012-d5dafb7acdc2",
+  "serialNumber": "urn:uuid:0c1f9661-62c2-51a0-93aa-e317473be0d8",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-24T14:53:53.083Z",
+    "timestamp": "2026-09-27T17:23:19.452Z",
     "tools": [
       {
         "vendor": "Harness Everything",
         "name": "generate-sbom.js",
-        "version": "0.26.0"
+        "version": "0.27.0"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/harness-everything@0.26.0",
+      "bom-ref": "pkg:npm/harness-everything@0.27.0",
       "name": "harness-everything",
-      "version": "0.26.0",
-      "purl": "pkg:npm/harness-everything@0.26.0"
+      "version": "0.27.0",
+      "purl": "pkg:npm/harness-everything@0.27.0"
     }
   },
   "components": [
@@ -1999,7 +1999,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/harness-everything@0.26.0",
+      "ref": "pkg:npm/harness-everything@0.27.0",
       "dependsOn": [
         "pkg:npm/%40commitlint/cli@19.8.1",
         "pkg:npm/%40commitlint/config-conventional@19.8.1",

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 };