harness-everything 0.25.1 → 0.26.0

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

package/verification-loop/references/project-verification-contract.md

@@ -0,0 +1,112 @@
+# Project Verification Contract
+
+Harness project verification has two layers:
+
+1. **Declared contract** — `.harness/verify.json` is authoritative and executable.
+2. **Read-only discovery** — ecosystem signals are reported as candidates when no contract exists. Detected candidates are never auto-run except the legacy `package.json` `lint` / `test` scripts.
+
+This keeps verification explicit without turning discovery into an accidental command runner.
+
+## Contract
+
+Create `.harness/verify.json` at the enclosing Git repository root. Its documented JSON Schema is `<this-skill-dir>/references/verify-contract.schema.json`:
+
+```json
+{
+  "version": 1,
+  "roots": [".", "sub/a", "sub/b"],
+  "checks": [
+    {
+      "id": "precommit",
+      "run": "pre-commit run --all-files",
+      "cwd": ".",
+      "timeoutSec": 600
+    },
+    {
+      "id": "sub-a-e2e",
+      "run": "bash scripts/e2e.sh",
+      "cwd": "sub/a",
+      "timeoutSec": 600
+    }
+  ]
+}
+```
+
+Rules:
+
+- `version` MUST be `1`.
+- `roots` is optional; default is `["."]`. Every root MUST stay inside the enclosing Git repository and exist.
+- `checks` MUST be a non-empty array.
+- Each check MUST have a unique non-empty `id`, non-empty `run`, repository-contained `cwd` (default `.`), and optional integer `timeoutSec` from 1 through 3600.
+- Unknown fields, invalid JSON, duplicate IDs, escaping paths, or invalid values make verification `FAILED`.
+- Contract checks run with `HARNESS_SKIP_PROJECT_CHECKS=1` so a project's checks cannot recursively invoke the same project gate.
+- When a contract exists, ecosystem detection and legacy npm auto-run are not used.
+
+A `git commit` is accepted as successful verification evidence only when:
+- the declared contract contains a `pre-commit ...` check,
+- a runnable pre-commit hook is configured for that repository (on POSIX, the hook file must have an executable bit), and
+- the commit command does not use `--no-verify` or `-n`.
+
+This prevents a generic commit from being mistaken for proof that the declared verification contract ran.
+
+## Status taxonomy
+
+| Status | Meaning | Exit |
+|---|---|---:|
+| `PASSED` | Every executed authoritative check exited 0. | 0 |
+| `FAILED` | A check failed/timed out, the injected failure marker exists, or declared/project metadata is invalid. | 1 |
+| `UNCHECKED_NO_CHECKS` | No contract, no runnable legacy npm checks, and no verification candidates were detected. | 0 |
+| `UNCHECKED_DISCOVERED` | Verification candidates exist but at least one was not executed. | 0 |
+| `SKIPPED` | `HARNESS_SKIP_PROJECT_CHECKS=1` recursion guard. | 0 |
+
+Every `UNCHECKED_*` human report MUST include:
+
+> PROHIBITED: Do NOT cite this run as proof that tests pass.
+
+An exit code of 0 from `UNCHECKED_*` is non-blocking control flow, not passing-test evidence.
+
+## Discovery when no contract exists
+
+Discovery is read-only. Harness may report:
+
+- `package.json`: `lint` / `test` remain legacy auto-run; `check`, `typecheck`, `verify` are candidates.
+- `.pre-commit-config.yaml`: `pre-commit run --all-files`.
+- `Makefile`: `test`, `check`, `lint`, `ci` targets.
+- `justfile`: `test`, `check`, `ci` recipes.
+- Python: pytest/ruff configuration in `pyproject.toml`, `tox.ini`, `noxfile.py`.
+- `Cargo.toml`: `cargo test`.
+- `go.mod`: `go test ./...`.
+- `core.hooksPath`, `.husky/`, or `.git/hooks/pre-commit`: commit-time gate presence.
+
+Detected commands are suggestions only. Their existence does not become pass evidence until they are explicitly run or declared in the contract.
+
+## Multi-root behavior
+
+With a contract, `roots` defines the verification scope. Each check is attributed to the most-specific declared root containing its `cwd`.
+
+Without a contract, Harness reports the main Git root plus initialized submodule roots from `git submodule status --recursive`.
+
+Overall status uses the most conservative root result:
+
+```text
+FAILED > UNCHECKED_DISCOVERED > UNCHECKED_NO_CHECKS > PASSED
+```
+
+A submodule with no checks remains visible as its own `UNCHECKED_NO_CHECKS` root; it is never silently merged into the parent result.
+
+## Structured output
+
+Run:
+
+```bash
+node harness-everything/scripts/verify-gate.js --json
+```
+
+The output contains:
+
+- `status`, `reason`, and `repoRoot`
+- `roots[]` with per-root status/reason
+- `checks[]` with `id`, `run`, `cwd`, `source`, `exitCode`, and `durationMs`
+- `candidates[]` with `source`, `run`, and `cwd`
+
+The machine-readable result conforms to `<this-skill-dir>/references/verify-result.schema.json`. It is evidence metadata; only `PASSED` means the gate produced passing verification evidence.

package/verification-loop/references/verification-phases.md

@@ -25,11 +25,12 @@ flowchart TD
     RunScript --> ReportResult{All Verification Gates Passed?}
     DirectReport --> ReportResult
     
-    ReportResult -- Exit 0 / All Green --> Deliver[Task Ready for Delivery / PR]
-    ReportResult -- Failures Detected --> Fix[Fix Issues in Code & Re-verify] --> Build
+    ReportResult -- PASSED --> Deliver[Task Ready for Delivery / PR]
+    ReportResult -- FAILED --> Fix[Fix Issues in Code & Re-verify] --> Build
+    ReportResult -- UNCHECKED_* --> Manual[Run declared/listed verification; exit 0 alone is not evidence] --> Build
 ```
 
-Adapt commands according to the project's ecosystem and active environment (`environment-detection`). Run commands directly without non-portable POSIX pipe assumptions (avoid raw `head`, `tail`, `grep`, `2>/dev/null` piping on Windows).
+Adapt commands according to the project's ecosystem and active environment (`environment-detection`). Run commands directly without non-portable POSIX pipe assumptions (avoid raw `head`, `tail`, `grep`, `2>/dev/null` piping on Windows). For repository-specific mechanical gates and structured `PASSED` / `FAILED` / `UNCHECKED_*` semantics, follow `<this-skill-dir>/references/project-verification-contract.md`.
 
 ## Phase 1: Build Verification
 

package/verification-loop/references/verify-contract.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dyphn1/Harness-everything/verification-loop/references/verify-contract.schema.json",
+  "title": "Harness project verification contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "checks"],
+  "properties": {
+    "version": { "const": 1 },
+    "roots": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "run"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "run": { "type": "string", "minLength": 1 },
+          "cwd": { "type": "string", "minLength": 1, "default": "." },
+          "timeoutSec": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 600 }
+        }
+      }
+    }
+  }
+}

package/verification-loop/references/verify-result.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dyphn1/Harness-everything/verification-loop/references/verify-result.schema.json",
+  "title": "Harness verification result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "reason", "repoRoot", "roots", "checks", "candidates"],
+  "properties": {
+    "status": {
+      "enum": ["PASSED", "FAILED", "UNCHECKED_NO_CHECKS", "UNCHECKED_DISCOVERED", "SKIPPED"]
+    },
+    "reason": { "type": "string" },
+    "repoRoot": { "type": "string" },
+    "roots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "status", "reason", "checks", "candidates"],
+        "properties": {
+          "path": { "type": "string" },
+          "status": {
+            "enum": ["PASSED", "FAILED", "UNCHECKED_NO_CHECKS", "UNCHECKED_DISCOVERED"]
+          },
+          "reason": { "type": "string" },
+          "checks": { "$ref": "#/$defs/checkArray" },
+          "candidates": { "$ref": "#/$defs/candidateArray" }
+        }
+      }
+    },
+    "checks": { "$ref": "#/$defs/checkArray" },
+    "candidates": { "$ref": "#/$defs/candidateArray" }
+  },
+  "$defs": {
+    "checkArray": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "run", "cwd", "source", "exitCode", "durationMs"],
+        "properties": {
+          "id": { "type": "string" },
+          "run": { "type": "string" },
+          "cwd": { "type": "string" },
+          "source": { "type": "string" },
+          "exitCode": { "type": ["integer", "null"] },
+          "durationMs": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "candidateArray": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source", "run", "cwd"],
+        "properties": {
+          "source": { "type": "string" },
+          "run": { "type": "string" },
+          "cwd": { "type": "string" }
+        }
+      }
+    }
+  }
+}