harness-everything 0.25.1 → 0.27.0

package/ci/mechanism-35-verification-contract.test.js

@@ -0,0 +1,416 @@
+'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 VERIFY = path.join(ROOT, 'harness-everything', 'scripts', 'verify-gate.js');
+const { isVerificationShell } = require('../hooks/scripts/lib/workflow-isolation');
+const { hasCommitHook, hookIsRunnable } = require('../scripts/lib/verification-contract');
+const { getWorkspaceKey } = require('../scripts/lib/workspace');
+
+function run(command, args, cwd, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, ...(options.env || {}) },
+    timeout: options.timeout || 30000,
+  });
+  if (!options.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 Verify Test']);
+  git(dir, ['config', 'user.email', 'verify@example.invalid']);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'fixture\n');
+  git(dir, ['add', 'README.md']);
+  git(dir, ['commit', '-m', 'seed']);
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function invokeGate(cwd, options = {}) {
+  const args = options.json === false ? [] : ['--json'];
+  const result = run(process.execPath, [VERIFY, ...args], cwd, {
+    allowFailure: true,
+    env: options.env || {},
+    timeout: options.timeout || 30000,
+  });
+  if (options.json === false) return result;
+  let report;
+  try {
+    report = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`verify-gate did not emit JSON (exit=${result.status})\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  }
+  return { ...result, report };
+}
+
+function packageScript(body) {
+  return {
+    name: 'verify-fixture',
+    version: '1.0.0',
+    private: true,
+    scripts: body,
+  };
+}
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-verify-contract-'));
+
+assert.strictEqual(hookIsRunnable({ isFile: () => true, mode: 0o100755 }, 'linux'), true);
+assert.strictEqual(hookIsRunnable({ isFile: () => true, mode: 0o100644 }, 'linux'), false);
+assert.strictEqual(hookIsRunnable({ isFile: () => true, mode: 0o100644 }, 'win32'), true);
+assert.strictEqual(hookIsRunnable({ isFile: () => false, mode: 0o100755 }, 'linux'), false);
+
+try {
+  // Taxonomy: truly no checks is distinct from discovered-but-unrun.
+  const empty = path.join(temp, 'empty');
+  initRepo(empty);
+  let result = invokeGate(empty);
+  assert.strictEqual(result.status, 0);
+  assert.strictEqual(result.report.status, 'UNCHECKED_NO_CHECKS');
+  assert.deepStrictEqual(result.report.candidates, []);
+  const emptyHuman = invokeGate(empty, { json: false });
+  assert.match(emptyHuman.stdout + emptyHuman.stderr, /PROHIBITED: Do NOT cite this run as proof/i);
+
+  // npm compatibility: placeholder is no check; lint/test auto-run; failure blocks.
+  const npmRepo = path.join(temp, 'npm');
+  initRepo(npmRepo);
+  writeJson(path.join(npmRepo, 'package.json'), packageScript({
+    test: 'echo "Error: no test specified" && exit 1',
+  }));
+  result = invokeGate(npmRepo);
+  assert.strictEqual(result.report.status, 'UNCHECKED_NO_CHECKS');
+
+  writeJson(path.join(npmRepo, 'package.json'), packageScript({
+    lint: 'node -e "process.exit(0)"',
+    test: 'node -e "process.exit(0)"',
+  }));
+  result = invokeGate(npmRepo);
+  assert.strictEqual(result.status, 0);
+  assert.strictEqual(result.report.status, 'PASSED');
+  assert.strictEqual(result.report.checks.length, 2);
+  assert.ok(result.report.checks.every(check => check.exitCode === 0));
+
+  writeJson(path.join(npmRepo, 'package.json'), packageScript({
+    test: 'node -e "process.exit(9)"',
+  }));
+  result = invokeGate(npmRepo);
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  assert.strictEqual(result.report.checks[0].exitCode, 9);
+
+  fs.writeFileSync(path.join(npmRepo, 'package.json'), '{ invalid json');
+  result = invokeGate(npmRepo);
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  assert.match(result.report.reason, /package\.json/i);
+
+  fs.writeFileSync(path.join(npmRepo, '.verify-fail.tmp'), 'fail');
+  result = invokeGate(npmRepo);
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  fs.rmSync(path.join(npmRepo, '.verify-fail.tmp'));
+
+  result = invokeGate(npmRepo, { env: { HARNESS_SKIP_PROJECT_CHECKS: '1' } });
+  assert.strictEqual(result.status, 0);
+  assert.strictEqual(result.report.status, 'SKIPPED');
+
+  // Read-only discovery: candidates are listed but never executed.
+  const detected = path.join(temp, 'detected');
+  initRepo(detected);
+  fs.writeFileSync(path.join(detected, 'sentinel.js'), 'require("fs").writeFileSync("RAN", "bad")\n');
+  fs.writeFileSync(path.join(detected, 'Makefile'), 'test:\n\tnode sentinel.js\ncheck:\n\t@echo check\n');
+  fs.writeFileSync(path.join(detected, 'justfile'), 'ci:\n    node sentinel.js\n');
+  fs.writeFileSync(path.join(detected, '.pre-commit-config.yaml'), 'repos: []\n');
+  fs.writeFileSync(path.join(detected, 'pyproject.toml'), '[tool.pytest.ini_options]\naddopts = "-q"\n[tool.ruff]\nline-length = 100\n');
+  fs.writeFileSync(path.join(detected, 'tox.ini'), '[tox]\nenvlist = py\n');
+  fs.writeFileSync(path.join(detected, 'noxfile.py'), '# nox fixture\n');
+  fs.writeFileSync(path.join(detected, 'Cargo.toml'), '[package]\nname="x"\nversion="0.1.0"\n');
+  fs.writeFileSync(path.join(detected, 'go.mod'), 'module example.invalid/x\n\ngo 1.22\n');
+  result = invokeGate(detected);
+  assert.strictEqual(result.status, 0);
+  assert.strictEqual(result.report.status, 'UNCHECKED_DISCOVERED');
+  const candidateRuns = result.report.candidates.map(candidate => candidate.run);
+  for (const command of [
+    'pre-commit run --all-files',
+    'make test',
+    'make check',
+    'just ci',
+    'pytest',
+    'ruff check .',
+    'tox',
+    'nox',
+    'cargo test',
+    'go test ./...',
+  ]) assert.ok(candidateRuns.includes(command), `missing candidate: ${command}\n${JSON.stringify(result.report.candidates)}`);
+  assert.ok(!fs.existsSync(path.join(detected, 'RAN')), 'detected commands must not run');
+
+  // package check/typecheck/verify are detected but not auto-run.
+  writeJson(path.join(detected, 'package.json'), packageScript({
+    test: 'node -e "process.exit(0)"',
+    check: 'node sentinel.js',
+    typecheck: 'node sentinel.js',
+    verify: 'node sentinel.js',
+  }));
+  result = invokeGate(detected);
+  assert.strictEqual(result.report.status, 'UNCHECKED_DISCOVERED');
+  assert.ok(result.report.checks.some(check => / run test$/.test(check.run)));
+  assert.ok(result.report.candidates.some(candidate => / run check$/.test(candidate.run)));
+  assert.ok(!fs.existsSync(path.join(detected, 'RAN')));
+
+  // Explicit contract is authoritative and executable.
+  const contracted = path.join(temp, 'contracted');
+  initRepo(contracted);
+  writeJson(path.join(contracted, 'package.json'), packageScript({
+    test: 'node -e "process.exit(13)"',
+  }));
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    roots: ['.'],
+    checks: [{
+      id: 'contract-pass',
+      run: 'node -e "if(process.env.HARNESS_SKIP_PROJECT_CHECKS!==\'1\') process.exit(7)"',
+      cwd: '.',
+      timeoutSec: 10,
+    }],
+  });
+  result = invokeGate(contracted);
+  assert.strictEqual(result.status, 0);
+  assert.strictEqual(result.report.status, 'PASSED');
+  assert.strictEqual(result.report.checks.length, 1, 'package.json must be ignored when contract exists');
+  assert.strictEqual(result.report.checks[0].id, 'contract-pass');
+
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    checks: [{ id: 'contract-fail', run: 'node -e "process.exit(4)"', cwd: '.' }],
+  });
+  result = invokeGate(contracted);
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  assert.strictEqual(result.report.checks[0].id, 'contract-fail');
+  assert.strictEqual(result.report.checks[0].exitCode, 4);
+
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    checks: [{ id: 'timeout', run: 'node -e "setTimeout(()=>{}, 5000)"', timeoutSec: 1 }],
+  });
+  result = invokeGate(contracted, { timeout: 10000 });
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  assert.match(result.report.reason, /timeout/i);
+
+  fs.writeFileSync(path.join(contracted, '.harness', 'verify.json'), '{ bad');
+  result = invokeGate(contracted);
+  assert.strictEqual(result.status, 1);
+  assert.match(result.report.reason, /verify\.json/i);
+
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    unknown: true,
+    checks: [{ id: 'x', run: 'node -e "process.exit(0)"' }],
+  });
+  result = invokeGate(contracted);
+  assert.strictEqual(result.status, 1);
+  assert.match(result.report.reason, /unknown/i);
+
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    roots: ['..'],
+    checks: [{ id: 'escape', run: 'node -e "process.exit(0)"' }],
+  });
+  result = invokeGate(contracted);
+  assert.strictEqual(result.status, 1);
+  assert.match(result.report.reason, /inside|escape|root/i);
+
+  // Multi-root contract reports every root and applies worst-root status.
+  fs.mkdirSync(path.join(contracted, 'sub', 'a'), { recursive: true });
+  fs.mkdirSync(path.join(contracted, 'sub', 'b'), { recursive: true });
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    roots: ['.', 'sub/a', 'sub/b'],
+    checks: [
+      { id: 'root', run: 'node -e "process.exit(0)"', cwd: '.' },
+      { id: 'a', run: 'node -e "process.exit(0)"', cwd: 'sub/a' },
+      { id: 'b', run: 'node -e "process.exit(0)"', cwd: 'sub/b' },
+    ],
+  });
+  result = invokeGate(contracted);
+  assert.strictEqual(result.report.status, 'PASSED');
+  assert.strictEqual(result.report.roots.length, 3);
+  assert.ok(result.report.roots.every(root => root.status === 'PASSED'));
+
+  writeJson(path.join(contracted, '.harness', 'verify.json'), {
+    version: 1,
+    roots: ['.', 'sub/a', 'sub/b'],
+    checks: [
+      { id: 'root', run: 'node -e "process.exit(0)"', cwd: '.' },
+      { id: 'a', run: 'node -e "process.exit(8)"', cwd: 'sub/a' },
+      { id: 'b', run: 'node -e "process.exit(0)"', cwd: 'sub/b' },
+    ],
+  });
+  result = invokeGate(contracted);
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  assert.strictEqual(result.report.roots.find(root => /sub[\\/]a$/.test(root.path)).status, 'FAILED');
+
+  // No-contract multi-root discovery enumerates initialized submodules.
+  const childA = path.join(temp, 'child-a');
+  const childB = path.join(temp, 'child-b');
+  for (const child of [childA, childB]) {
+    initRepo(child);
+    writeJson(path.join(child, 'package.json'), packageScript({ test: 'node -e "process.exit(0)"' }));
+    git(child, ['add', 'package.json']);
+    git(child, ['commit', '-m', 'add passing test']);
+  }
+  const multi = path.join(temp, 'multi');
+  initRepo(multi);
+  writeJson(path.join(multi, 'package.json'), packageScript({ test: 'node -e "process.exit(0)"' }));
+  git(multi, ['add', 'package.json']);
+  git(multi, ['commit', '-m', 'parent test']);
+  git(multi, ['-c', 'protocol.file.allow=always', 'submodule', 'add', childA, 'sub/a']);
+  git(multi, ['-c', 'protocol.file.allow=always', 'submodule', 'add', childB, 'sub/b']);
+  git(multi, ['commit', '-am', 'add submodules']);
+  result = invokeGate(multi);
+  assert.strictEqual(result.report.status, 'PASSED');
+  assert.strictEqual(result.report.roots.length, 3);
+
+  writeJson(path.join(multi, 'sub', 'b', 'package.json'), packageScript({ test: 'node -e "process.exit(6)"' }));
+  result = invokeGate(multi);
+  assert.strictEqual(result.status, 1);
+  assert.strictEqual(result.report.status, 'FAILED');
+  assert.strictEqual(result.report.roots.find(root => /sub[\\/]b$/.test(root.path)).status, 'FAILED');
+
+  // Hook-side recognition uses the same project signals and contract.
+  const classifyRepo = path.join(temp, 'classify');
+  initRepo(classifyRepo);
+  fs.writeFileSync(path.join(classifyRepo, '.pre-commit-config.yaml'), 'repos: []\n');
+  fs.writeFileSync(path.join(classifyRepo, 'Makefile'), 'test:\n\t@echo ok\n');
+  fs.writeFileSync(path.join(classifyRepo, 'justfile'), 'ci:\n    @echo ok\n');
+  fs.writeFileSync(path.join(classifyRepo, 'tox.ini'), '[tox]\nenvlist=py\n');
+  fs.writeFileSync(path.join(classifyRepo, 'Cargo.toml'), '[package]\nname="x"\nversion="0.1.0"\n');
+  fs.writeFileSync(path.join(classifyRepo, 'go.mod'), 'module example.invalid/x\n\ngo 1.22\n');
+  fs.writeFileSync(path.join(classifyRepo, 'pyproject.toml'), '[tool.pytest.ini_options]\naddopts="-q"\n');
+  writeJson(path.join(classifyRepo, '.harness', 'verify.json'), {
+    version: 1,
+    checks: [
+      { id: 'precommit', run: 'pre-commit run --all-files' },
+      { id: 'e2e', run: 'bash scripts/e2e.sh' },
+    ],
+  });
+  fs.mkdirSync(path.join(classifyRepo, '.git', 'hooks'), { recursive: true });
+  const preCommitHook = path.join(classifyRepo, '.git', 'hooks', 'pre-commit');
+  fs.writeFileSync(preCommitHook, '#!/bin/sh\nexit 0\n');
+  assert.strictEqual(hasCommitHook(classifyRepo, 'linux'), false, 'a non-executable POSIX hook must not count as verification');
+  if (process.platform !== 'win32') fs.chmodSync(preCommitHook, 0o755);
+
+  assert.strictEqual(isVerificationShell('pre-commit run --all-files', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('bash scripts/e2e.sh', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('git commit -m x', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('git commit --no-verify -m x', { cwd: classifyRepo }), false);
+  assert.strictEqual(isVerificationShell('git commit -n -m x', { cwd: classifyRepo }), false);
+  assert.strictEqual(isVerificationShell('git commit -an -m x', { cwd: classifyRepo }), false, 'combined -n must still bypass hooks');
+  if (process.platform !== 'win32') {
+    fs.chmodSync(preCommitHook, 0o644);
+    assert.strictEqual(isVerificationShell('git commit -m x', { cwd: classifyRepo }), false, 'a non-executable POSIX hook cannot verify a commit');
+    fs.chmodSync(preCommitHook, 0o755);
+  }
+
+  // An invalid authoritative contract must fail closed in the hook classifier too.
+  // The verify gate reports FAILED here, so legacy command matching must not
+  // silently manufacture lastVerifyAt evidence from the same workspace.
+  fs.writeFileSync(path.join(classifyRepo, '.harness', 'verify.json'), '{ broken');
+  assert.strictEqual(isVerificationShell('npm test', { cwd: classifyRepo }), false, 'invalid contract must suppress legacy verifier fallback');
+  assert.strictEqual(isVerificationShell('pre-commit run --all-files', { cwd: classifyRepo }), false, 'invalid contract must suppress detector-based evidence');
+
+  fs.rmSync(path.join(classifyRepo, '.harness', 'verify.json'));
+  assert.strictEqual(isVerificationShell('git commit -m x', { cwd: classifyRepo }), false, 'commit is not full verification without a declared hook contract');
+  assert.strictEqual(isVerificationShell('pre-commit run --all-files', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('make test', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('just ci', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('tox', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('cargo test', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('go test ./...', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('uv run pytest', { cwd: classifyRepo }), true);
+  assert.strictEqual(isVerificationShell('npm run build', { cwd: classifyRepo }), true, 'legacy build evidence remains recognized without a contract');
+  assert.strictEqual(isVerificationShell('npx tsc --noEmit', { cwd: classifyRepo }), true, 'legacy typecheck evidence remains recognized without a contract');
+  assert.strictEqual(isVerificationShell('echo test', { cwd: classifyRepo }), false, 'plain words must not become verification evidence');
+
+  // Hook evidence: successful declared pre-commit verification after an edit
+  // updates lastVerifyAt, so Stop does not emit a stale verification reminder.
+  writeJson(path.join(classifyRepo, '.harness', 'verify.json'), {
+    version: 1,
+    checks: [{ id: 'precommit', run: 'pre-commit run --all-files' }],
+  });
+  const stateHome = path.join(temp, 'state-home');
+  const session = 'verify-contract-hook';
+  const stateEnv = { HARNESS_STATE_HOME: stateHome, CLAUDE: '1' };
+  const statePersist = path.join(ROOT, 'hooks', 'scripts', 'state-persist.js');
+  const stopGate = path.join(ROOT, 'hooks', 'scripts', 'stop-gate.js');
+  const invokeHook = (script, payload) => spawnSync(process.execPath, [script], {
+    cwd: classifyRepo,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: { ...process.env, ...stateEnv },
+  });
+
+  fs.appendFileSync(path.join(classifyRepo, 'README.md'), 'dirty\n');
+  let hook = invokeHook(statePersist, {
+    session_id: session,
+    cwd: classifyRepo,
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Edit',
+    tool_input: { file_path: path.join(classifyRepo, 'README.md') },
+    tool_response: { stdout: '', exitCode: 0 },
+  });
+  assert.strictEqual(hook.status, 0);
+
+  hook = invokeHook(statePersist, {
+    session_id: session,
+    cwd: classifyRepo,
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    tool_input: { command: 'pre-commit run --all-files' },
+    tool_response: { stdout: 'ok', exitCode: 0 },
+  });
+  assert.strictEqual(hook.status, 0);
+
+  const stateFile = path.join(
+    stateHome,
+    'workspaces',
+    getWorkspaceKey(classifyRepo),
+    'state',
+    'sessions',
+    session,
+    'handoff-state.json',
+  );
+  const handoff = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  assert.ok(handoff.lastVerifyAt >= handoff.lastEditAt, JSON.stringify(handoff));
+
+  const stop = invokeHook(stopGate, { session_id: session, cwd: classifyRepo });
+  assert.strictEqual(stop.status, 0);
+  assert.doesNotMatch(String(stop.stderr || ''), /Verification Reminder/i);
+
+  console.log('Issue #242 verification contract: taxonomy, discovery, execution safety, multi-root scope, hook recognition, and Stop evidence verified.');
+} finally {
+  fs.rmSync(temp, { recursive: true, force: true });
+}

package/ci/mutation-check.js

@@ -15,6 +15,8 @@ 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'],
 ];
 
 let failures = 0;
@@ -32,6 +34,8 @@ 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),
       NODE_OPTIONS: `--require=${loader}`,

package/ci/mutation-loader.js

@@ -40,6 +40,14 @@ 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'
+  ),
 };
 
 if (target && mutation && mutations[mutation]) {

package/docs/audit.md

@@ -2,6 +2,8 @@
 
 Maintainer-facing audit record. If you just want to know whether Harness works and how to verify it yourself, start at [VERIFICATION.md](../VERIFICATION.md) instead — this file records *how the scores below were obtained* and what changed between audit cycles.
 
+> **Current verification-gate note (2026-09-24):** project verification now supports an authoritative `.harness/verify.json` contract, read-only ecosystem discovery, explicit `UNCHECKED_NO_CHECKS` versus `UNCHECKED_DISCOVERED`, and multi-root reporting. Hook-side verification evidence uses the same project-aware command model. Deterministic mechanism evidence is tracked under issue #242; this note does not claim new live-host evidence.
+
 > **Historical snapshot boundary:** the scorecards below are dated audits and are intentionally preserved as evidence of what was measured on each date. Platform capabilities have changed since the 2026-09-01 snapshot (including the OpenAI/Codex local plugin work and the OpenCode plugin implementation). Do not treat any dated platform row as current-state documentation; use [platform-capabilities.md](platform-capabilities.md) for the current matrix.
 
 **Last self-audited: 2026-09-18**, by running the deterministic test suite and gates on macOS (Node.js 24.14.1) — not by reading the code and assuming it works. The 2026-09-01 Windows 11 snapshot is preserved below. Live-host and behavioral evidence layers were not re-run in this cycle; retained artifacts are referenced, not re-measured.

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/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.24.0
+  version: 0.26.0
 ---
 
 # Harness Everything
@@ -20,7 +20,7 @@ Kernel routing entry.
 
 ## Invariants
 1. **Route (MUST)** — establish scope/tier and selected/deferred topology.
-2. **Verify (MUST)** — completion claims need objective evidence.
+2. **Verify (MUST)** — completion claims need objective evidence; `verify-gate.js --json` distinguishes passed, failed, discovered-but-unrun, and absent project checks.
 3. **Zoom out (MUST)** — after 3 same-signature failures, use `zoom-out`.
 4. **Resolve suggestions (MUST)** — read/evaluate each suggested `SKILL.md`; applicable core contracts MUST run, otherwise retain a flow-grounded reason.
 5. **Surface status (MUST)** — non-trivial work renders `### 🚦 Harness Status` with bold `Current`, `Read / Evidence`, `Next`; optional `Risk / Blocked`.