harness-everything 0.25.1 → 0.27.0

package/plugins/harness-everything/scripts/lib/verification-contract.js

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

package/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/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`.