harness-everything 0.25.0 → 0.26.0

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

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

package/plugins/harness-everything/skills/using-git-worktrees/SKILL.md

@@ -4,44 +4,45 @@ description: Use when work needs isolation or before major implementation plans
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.19.1
+  version: 0.25.1
 ---
 
 # Using Git Worktrees
 
-Use native worktree support first; raw Git is the fallback.
+Use native worktree support first; raw Git is fallback.
 
 ## Contract
 
-- **Tier 3 / Fable (MUST resolve)** — before broad source/artifact mutation, reuse/create a verified linked worktree. If isolation is unavailable or the user explicitly chooses to stay in place, MUST report an explicit degraded fallback/risk before continuing.
-- **Ordinary mode (SHOULD)** — use isolation when it materially reduces collision/risk; explicit user preference may keep work in place.
-- **MUST NOT** nest a worktree inside an already isolated worktree.
+- **Tier 3 / Fable (MUST resolve)** — isolate before broad mutation. If unavailable or explicitly declined, MUST report an explicit degraded fallback/risk.
+- **Ordinary mode SHOULD** isolate when it materially reduces collision/risk.
+- **MUST NOT** nest a worktree inside an isolated worktree.
 
 ## Workflow
 
-**Step 0 — Detect isolation** (adapt per `environment-detection`):
+**Step 0 — Detect**:
 ```bash
 git rev-parse --git-dir
 git rev-parse --git-common-dir
 git branch --show-current
 git rev-parse --show-superproject-working-tree
+git submodule status --recursive
 ```
-Different git/common dirs and no superproject => already isolated; continue to Step 2. A submodule is a normal repo for this check.
+Different git/common dirs and no superproject => already isolated. If submodules exist, **MUST** read `<this-skill-dir>/references/submodules-in-worktrees.md` before committing inside them.
 
-**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree` first; otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. Use an already-ignored or external/sibling path when possible. If creation/entry fails, MUST surface the degraded isolation disposition before continuing.
+**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree`; otherwise `git worktree add "$path" -b "$BRANCH_NAME"`. On failure, MUST surface the degraded disposition.
 
-**Step 2 — Setup**: install project dependencies as needed.
+**Step 2 — Setup**: install dependencies as needed.
 
-**Step 3 — Baseline**: run relevant tests/build before implementation when useful; surface existing failures before relying on the baseline.
+**Step 3 — Baseline**: run relevant tests/build when useful; surface existing failures.
 
 Deep dive: <this-skill-dir>/references/workflow-details.md
 
 ## USE FOR:
-- Tier 3 / Fable-class mutable engineering
+- Tier 3 / Fable mutable engineering
 - feature work needing isolation
 - pre-implementation-plan setup
 
 ## DO NOT USE FOR:
 - nesting inside an existing worktree
-- read-only analysis with no mutation
-- branch/merge workflows unrelated to workspace isolation
+- read-only analysis
+- unrelated branch/merge workflows

package/plugins/harness-everything/skills/using-git-worktrees/references/submodules-in-worktrees.md

@@ -0,0 +1,135 @@
+# Submodules inside linked worktrees
+
+A linked worktree of a superproject does **not** share the primary checkout's submodule object store. After `git submodule update --init`, each submodule normally uses a worktree-specific git dir such as:
+
+```text
+<super>/.git/worktrees/<worktree-id>/modules/<submodule>
+```
+
+The primary checkout uses:
+
+```text
+<super>/.git/modules/<submodule>
+```
+
+A superproject gitlink records only a commit SHA. It does not publish or copy that commit into the primary checkout. Therefore a submodule commit made only on detached HEAD in a linked worktree can become unreachable when that worktree is removed.
+
+## Required rules
+
+1. **MUST use a named branch before committing in the submodule.** `git submodule update` normally leaves the submodule detached.
+2. **MUST make the new submodule commit reachable outside the linked worktree before treating the superproject gitlink bump as deliverable.** Publish it to the submodule remote, or fetch it into the primary checkout's submodule repository.
+3. **MUST verify external reachability before removing the linked worktree.** A branch that exists only inside the linked worktree is not sufficient publication evidence.
+
+## Detect the situation
+
+From the superproject worktree:
+
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git submodule status --recursive
+git -C <submodule> rev-parse --absolute-git-dir
+git -C <submodule> branch --show-current
+```
+
+A linked superproject has different git/common dirs. A blank submodule branch means detached HEAD.
+
+PowerShell uses the same Git commands; quote paths containing spaces:
+
+```powershell
+git -C "<submodule>" rev-parse --absolute-git-dir
+git -C "<submodule>" branch --show-current
+```
+
+## Prevent the problem
+
+Before editing or committing in the submodule:
+
+```bash
+git -C <submodule> switch -c <task-branch>
+# edit + verify
+git -C <submodule> add <paths>
+git -C <submodule> commit -m "<message>"
+SUB_SHA=$(git -C <submodule> rev-parse HEAD)
+```
+
+PowerShell:
+
+```powershell
+git -C "<submodule>" switch -c "<task-branch>"
+# edit + verify
+git -C "<submodule>" add <paths>
+git -C "<submodule>" commit -m "<message>"
+$SubSha = git -C "<submodule>" rev-parse HEAD
+```
+
+## Publish before the gitlink is considered deliverable
+
+Preferred path when the submodule has a remote:
+
+```bash
+git -C <submodule> push -u origin <task-branch>
+git -C <submodule> branch -r --contains "$SUB_SHA"
+```
+
+```powershell
+git -C "<submodule>" push -u origin "<task-branch>"
+git -C "<submodule>" branch -r --contains $SubSha
+```
+
+If pushing is not appropriate, copy the commit into the primary checkout's submodule repository. From the linked worktree first give a detached commit a name if necessary:
+
+```bash
+git -C <worktree>/<submodule> branch -f <task-branch> <sha>
+git -C <primary>/<submodule> fetch <worktree>/<submodule> <task-branch>:<task-branch>
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+```
+
+```powershell
+git -C "<worktree>/<submodule>" branch -f "<task-branch>" "<sha>"
+git -C "<primary>/<submodule>" fetch "<worktree>/<submodule>" "<task-branch>:<task-branch>"
+git -C "<primary>/<submodule>" cat-file -e "<sha>^{commit}"
+```
+
+After the commit is externally reachable, stage the gitlink in the superproject:
+
+```bash
+git add <submodule>
+git diff --cached --submodule=log
+```
+
+## Recovery after an unpublished gitlink was already committed
+
+Do **not** remove the linked worktree. Recover the referenced SHA while its submodule object store still exists:
+
+```bash
+git -C <worktree>/<submodule> branch -f <task-branch> <sha>
+git -C <primary>/<submodule> fetch <worktree>/<submodule> <task-branch>:<task-branch>
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+git -C <primary> submodule update
+```
+
+The PowerShell form is identical except paths/refs should be quoted as shown above.
+
+## Pre-removal check
+
+For every changed gitlink SHA, prove at least one external home exists:
+
+```bash
+git -C <submodule> branch -r --contains <sha>
+# OR, from the primary checkout:
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+```
+
+If neither succeeds, **MUST NOT** remove the linked worktree yet.
+
+## Handoff checklist
+
+For each changed submodule record:
+
+- submodule path
+- commit SHA
+- branch name
+- publication location: remote-tracking ref or primary checkout object store
+- superproject gitlink staged/committed state
+- reachability check result before worktree removal

package/plugins/harness-everything/skills/verification-loop/SKILL.md

@@ -4,44 +4,36 @@ description: "Run objective verification gates (build, types, lint, tests, secur
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.15.0
+  version: 0.26.0
 ---
 
 # Verification Loop
 
-Run objective quality gates before claiming a change is ready.
+Run objective gates before claiming delivery readiness.
 
 ## Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | Completed implementation or change awaiting delivery. |
-| **Expected Output** | Evidence-backed verification report and delivery decision. |
-| **State Mutations** | Fills a report from `<this-skill-dir>/templates/verification-report.template.md`. |
-| **Enforcement Gate** | Build, type, lint, test, security, and diff gates all pass. |
+| **Trigger / Input** | Completed change awaiting delivery. |
+| **Expected Output** | Evidence-backed verification report. |
+| **State Mutations** | Fills `<this-skill-dir>/templates/verification-report.template.md`. |
+| **Enforcement Gate** | Every applicable gate passes. |
 
 ## USE FOR:
-
-- Verify a feature or change before delivery
-- Run quality gates before a PR
+- Verify a completed change
+- Run quality gates before delivery/PR
 
 ## DO NOT USE FOR:
-
-- Fixing failures without re-running the loop
-- Writing new features or tests (use `tdd`)
+- Fixing failures without re-running verification
+- New feature/test implementation (use `tdd`)
 
 ## Workflow
 
-Never claim completion until every applicable gate passes. On failure, fix the cause
-and rerun from the first affected gate.
-
-1. Build: `npm run build`.
-2. Types: `npx tsc --noEmit` or `pyright .`.
-3. Lint: `npm run lint` or `ruff check .`.
-4. Tests and coverage: `npm run test -- --coverage`.
-5. Security scan: secrets and stray logs.
-6. Diff review: `git diff --stat` and unintended-change checks.
-7. Contract reconciliation when the work cites `REQ-*` / ADR/spec/ticket lineage or a contract-integrity trace exists: run the strict `<this-skill-dir>/scripts/contract-integrity-audit.js` gate with current #58 evidence and `--workspace <workspace>` so traced source/test/implementation artifacts are fingerprinted. `AUDIT`, `NOT_EVALUATED`, stale source binding, or drift is **not ready** for delivery.
-8. Fill `<this-skill-dir>/templates/verification-report.template.md` with evidence.
+1. Run applicable build, type, lint, test/coverage, security, and diff gates.
+2. Reconcile cited REQ/ADR/spec lineage with `<this-skill-dir>/scripts/contract-integrity-audit.js`; stale/failed/audit-only evidence is not ready.
+3. For project-declared/discovered mechanical gates, follow `<this-skill-dir>/references/project-verification-contract.md`.
+4. On failure, fix and rerun from the first affected gate.
+5. Fill `<this-skill-dir>/templates/verification-report.template.md` with actual evidence.
 
 Deep dive: `<this-skill-dir>/references/verification-phases.md`