harness-everything 0.25.0 → 0.26.0

package/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/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/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" }
+        }
+      }
+    }
+  }
+}