harness-everything 0.4.0 → 0.4.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "author": {
     "name": "Miya Daniel"
   },

package/.github/workflows/behavioral-evals.yml

@@ -9,10 +9,10 @@ jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
-          node-version: 20
+          node-version: 24
       - name: Validate eval case structure (free)
         run: node behavioral-evals/run.js validate
       - name: Install Harness for eval

package/.github/workflows/ci.yml

@@ -16,12 +16,12 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
-          node-version: 20
+          node-version: 24
       - name: Install dependencies for regression suite
         run: npm ci
       - name: Run hermetic self-regression suite
@@ -29,10 +29,26 @@ jobs:
       - name: Run focused mutation checks
         run: npm run test:mutations
 
+  runtime-floor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - name: Install dependencies on minimum supported Node
+        run: npm ci
+      - name: Run representative regression suite on Node 22
+        run: npm test
+      - name: Verify installer contract on Node 22
+        run: node ci/installer-roundtrip.test.js
+
   skill-quality:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Install waza CLI
@@ -80,12 +96,12 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
-          node-version: 20
+          node-version: 24
       - name: Install Node dependencies
         run: npm ci
       - name: Docs, manifest, and eval-coverage consistency
@@ -110,12 +126,12 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
-          node-version: 20
+          node-version: 24
       - name: CLI --help works
         run: node bin/cli.js --help
       - name: Install, verify, uninstall, and restore seeded user files

package/.github/workflows/release.yml

@@ -28,14 +28,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout full release history
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
-      # semantic-release 25 requires a newer Node runtime than the product's
-      # normal Node 20 CI matrix. This only changes the release runner.
+      # Release tooling uses the repository's primary Node runtime.
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: 24
           cache: npm

package/.nvmrc

@@ -0,0 +1 @@
+24

package/AGENTS.md

@@ -17,10 +17,12 @@ You are modifying **Harness**: an orchestrated agent operating system (skills +
 | `.agents/plugins/` + `plugins/harness-everything/` | Local OpenAI/Codex marketplace + `.codex-plugin` package with canonical skill copies and packaged session/prompt hooks. |
 | `submission/openai/` | Public OpenAI Skills-only listing/test inputs. The public artifact does not include local `.codex-plugin` lifecycle hooks. |
 | `evals/<skill>/` | Trigger/routing eval per skill (waza format). Required for every canonical routed skill. |
-| `behavioral-evals/` | LLM-behavior cases run via headless CLI sessions. On-demand only; costs tokens; never CI. |
+| `behavioral-evals/` | LLM-behavior cases run via headless CLI sessions. They can be run on demand and are also structurally validated by the weekly `behavioral-evals.yml` workflow; live cases run there only when the Claude CLI is available. |
 | `benchmarks/` | BENCHMARK_SOP fixtures and recorded results. Evidence lives here or nowhere. |
 | `.claude-plugin/` | Claude Code plugin distribution manifests. Must list exactly the on-disk canonical skills. |
 | `docs/platform-capabilities.md` | Canonical current platform/install/enforcement/evidence matrix. |
+| `docs/repository-contract.md` | Generated current-state Node/workflow/action/gate contract. Regenerate with `npm run docs:sync`; do not hand-edit. |
+| `.nvmrc` | Primary development/CI Node runtime. `package.json#engines.node` remains the minimum supported runtime. |
 | `docs/`, `references/` | Philosophy, architecture, workflow documentation, shared checklists. |
 
 ## Non-Negotiable Change Rules
@@ -31,24 +33,28 @@ You are modifying **Harness**: an orchestrated agent operating system (skills +
 4. **Release version policy:** normal PRs do not manually bump package/plugin versions. `semantic-release` determines the next stable SemVer from Conventional Commits on `main`, and `scripts/sync-release-version.js` owns distribution-version synchronization. Skill frontmatter versions remain release metadata and must never exceed the package version's numeric base. Nested sub-skills (`<skill>/<sub>/SKILL.md`) inherit the parent skill's version and must always match it.
 5. **Distribution manifests are generated facts, not opinions:** if you add/remove/rename a canonical skill, update/sync every distribution that copies or lists it. Run `npm run plugin:sync`, `npm run test:consistency`, and `npm run test:plugin:openai` rather than updating only `.claude-plugin/plugin.json`.
 6. **Platform capability claims are tested contracts.** If host integration behavior changes, update `docs/platform-capabilities.md` and every affected current-state surface in the same change. Never turn package/mechanism evidence into a live-host claim, and never describe public Skills-only behavior as if it includes local lifecycle hooks.
-7. **CHANGELOG.md keeps pending human-authored notes under `[Unreleased]`.** Do not create new alpha/beta/rc release headings; semantic-release owns stable release headings, tags, and release notes.
-8. **Conventional Commit type is release input.** The final commit/squash title that lands on `main` must follow the convention. Breaking changes release major; `feat` releases minor; `fix`, `perf`, `refactor`, `build`, and `revert` release patch; `docs`, `test`, `ci`, `style`, and `chore` do not release by themselves.
+7. **Runtime/workflow claims are generated facts.** `package.json`, `.nvmrc`, `Dockerfile`, and active `.github/workflows/*.yml` are parsed by `scripts/repository-contract.js`. After changing them, run `npm run docs:sync`; `test:repo-contract` rejects stale generated docs, unsupported action majors, Node runtimes below the support floor, or loss of the Node 22 compatibility lane.
+8. **CHANGELOG.md keeps pending human-authored notes under `[Unreleased]`.** Do not create new alpha/beta/rc release headings; semantic-release owns stable release headings, tags, and release notes.
+9. **Conventional Commit type is release input.** The final commit/squash title that lands on `main` must follow the convention. Breaking changes release major; `feat` releases minor; `fix`, `perf`, `refactor`, `build`, and `revert` release patch; `docs`, `test`, `ci`, `style`, and `chore` do not release by themselves.
 
 ## Verification Before You Claim Done
 
-Run the local gates that mirror CI:
+Run the local gates that cover the same contract categories as CI:
 
 ```bash
-npm test                       # self-regression: syntax, routing, mechanisms
-npm run test:mechanism         # mechanism suites alone
-npm run test:consistency       # manifests, versions, docs links, eval coverage + capability docs
-npm run test:docs:capabilities # platform documentation drift gate
-npm run test:references        # executable/deep-dive references
-npm run test:release           # release catalog + semantic-release/version-sync contract
-npm run test:collision         # description collision detection
-npm run test:routing:skills    # every positive skill route reaches its target
-npm run test:plugin:openai     # local OpenAI/Codex plugin package
-npm run test:plugin:submission # public Skills-only submission inputs/bundle parity
+npm test                         # self-regression: syntax, routing, mechanisms
+npm run test:mutations           # focused mutation checks
+npm run test:mechanism           # mechanism suites alone
+npm run test:consistency         # manifests, versions, docs links, eval coverage + repository contract
+npm run test:repo-contract       # runtime/workflow/action/schedule drift gate
+npm run test:docs:capabilities   # platform documentation drift gate
+npm run test:references          # executable/deep-dive references
+npm run test:release             # release catalog + semantic-release/version-sync contract
+npm run test:collision           # description collision detection
+npm run test:routing:skills      # every positive skill route reaches its target
+npm run test:plugin:openai       # local OpenAI/Codex plugin package
+npm run test:plugin:submission   # public Skills-only submission inputs/bundle parity
+npm run test:platform:compatibility
 ```
 
 If waza is installed (`~/bin/waza`), also run what CI runs:
@@ -59,6 +65,8 @@ waza spec verify <skill> evals/<skill>/eval.yaml --fail --threshold 1
 waza tokens check
 ```
 
+Node.js 24 is the primary CI runtime across Ubuntu, Windows, and macOS. A separate Ubuntu Node.js 22 lane protects the advertised minimum runtime. See [docs/repository-contract.md](docs/repository-contract.md) for the generated current state.
+
 Do not report "it works" from reading code. Record which evidence layer you actually proved: package, deterministic mechanism, live host, or behavior.
 
 ## Behavioral & Benchmark Evidence
@@ -66,6 +74,7 @@ Do not report "it works" from reading code. Record which evidence layer you actu
 Deterministic mechanism tests prove the tested hook/plugin contract; they do **not** prove a real host loaded it or that agents behave differently. For behavior:
 
 - `node behavioral-evals/run.js run --engine opencode` (or `--engine claude`) — on-demand, token-costing.
+- The weekly `behavioral-evals.yml` workflow always validates case structure and runs live cases only when its runner has the Claude CLI.
 - `node benchmarks/run.js scaffold <scenario>` → run both variants → `record` with evidence logs.
 
 For a live-host enforcement claim, preserve a host/session artifact showing the mechanism was actually loaded and fired. Results are committed where the relevant evidence workflow requires it. A benchmark run without a recorded result is indistinguishable from one that never happened.

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.4.1](https://github.com/dyphn1/Harness-everything/compare/v0.4.0...v0.4.1) (2026-09-16)
+
 ## [0.4.0](https://github.com/dyphn1/Harness-everything/compare/v0.3.6...v0.4.0) (2026-09-16)
 
 ### Features

package/CONTRIBUTING.md

@@ -4,24 +4,38 @@ Thanks for your interest in contributing.
 
 ## Development Setup
 
+Harness supports **Node.js 22 or newer**. Node.js **24** is the primary development, CI, Docker, and release runtime; `.nvmrc` is the checked-in default. The generated current-state contract is [docs/repository-contract.md](docs/repository-contract.md).
+
 ```bash
 git clone https://github.com/dyphn1/Harness-everything.git
 cd Harness-everything
+nvm use                  # uses Node 24 from .nvmrc when nvm is available
+npm ci
 npm test
 ```
 
 ## Quality Gates
 
-All contributions must pass:
+The reusable CI workflow runs the repository's deterministic gates across the supported operating-system matrix, with a separate Node 22 minimum-runtime lane. Before opening a PR, run the relevant local gates:
 
 ```bash
-npm test                    # self-regression
-npm run test:mechanism      # hook mechanism checks
-npm run test:consistency    # manifest, version, link checks
-npm run test:release        # release catalog + version automation contract
-npm run test:collision      # description collision detection
+npm test                         # self-regression
+npm run test:mutations           # focused mutation checks
+npm run test:mechanism           # hook/plugin mechanism checks
+npm run test:consistency         # manifests, docs, eval coverage + repository contract
+npm run test:repo-contract       # Node/workflow/action/schedule drift gate
+npm run test:references          # executable/deep-dive references
+npm run test:release             # release catalog + version automation contract
+npm run test:collision           # description collision detection
+npm run test:plugin:openai       # local OpenAI/Codex plugin package
+npm run test:plugin:submission   # public Skills-only package reproducibility
+npm run test:platform:compatibility
 ```
 
+If `waza` is installed, CI also validates canonical skill readiness, routing evals, and token growth. See [AGENTS.md](AGENTS.md) for the repository operating rules.
+
+When runtime or workflow configuration changes, run `npm run docs:sync` and commit the regenerated [docs/repository-contract.md](docs/repository-contract.md). CI rejects stale generated contract data.
+
 ## Skill Contributions
 
 Each skill lives in its own top-level directory with a `SKILL.md`. See [AGENTS.md](AGENTS.md) for full rules, but the non-negotiables:
@@ -46,10 +60,11 @@ If the repository uses squash merging, make the PR title a valid Conventional Co
 ## Pull Requests
 
 1. Fork and create a feature branch.
-2. Make changes and ensure all gates pass.
-3. Update `CHANGELOG.md` under `[Unreleased]` for user-visible changes.
-4. Do not manually bump release versions; release automation owns them.
-5. Open a PR with a Conventional Commit title that accurately represents its release impact.
+2. Make changes and ensure all relevant gates pass.
+3. Run `npm run docs:sync` after runtime/workflow changes and commit generated current-state documentation.
+4. Update `CHANGELOG.md` under `[Unreleased]` for user-visible changes.
+5. Do not manually bump release versions; release automation owns them.
+6. Open a PR with a Conventional Commit title that accurately represents its release impact.
 
 ## Reporting Issues
 

package/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-alpine
+FROM node:24-alpine
 
 # Install bash and git since the scripts depend on them
 RUN apk add --no-cache bash git

package/README.md

@@ -48,6 +48,8 @@ The exact "Harness" behavior depends on the installation surface. Claude Code ha
 
 Harness integrates directly into your workspace. There is no heavy daemon, no paid external APIs, and zero configuration required.
 
+**Runtime:** Harness supports **Node.js 22+**. Node.js **24** is the primary/recommended development and CI runtime (`.nvmrc`). The generated current-state runtime/workflow summary is [docs/repository-contract.md](docs/repository-contract.md).
+
 ```bash
 # Option A: Claude Code plugin (marketplace manifest included)
 #   /plugin marketplace add dyphn1/Harness-everything
@@ -200,18 +202,18 @@ This repo uses a flat layout (waza/agentskills.io convention). The table below m
 |---|---|---|
 | `harness-everything` | **Core Runtime** | Bootstrap, kernel-router, tier-router, verify-gate, self-heal |
 | `hooks` | **Core Runtime** | Claude Code lifecycle hooks (prompt routing, circuit breaker, scope guard, stop gate, etc.) |
-| `scripts` | **Core Runtime** | Installer, manifest, prompts, workspace utilities |
+| `scripts` | **Core Runtime** | Installer, manifest, prompts, workspace utilities, repository contract extraction/sync |
 | `bin` | **Core Runtime** | `harness` CLI entry point |
-| `ci` | **Quality Gates** | Consistency checks, description collision, mechanism tests, invariant-routing regression, documentation capability drift guard |
+| `ci` | **Quality Gates** | Consistency checks, description collision, mechanism tests, invariant-routing regression, documentation/runtime contract drift guards |
 | `.github` | **CI/CD** | GitHub Actions workflows (ci.yml, release.yml, behavioral-evals.yml) |
 | `.claude-plugin` | **Distribution** | Plugin manifests for Claude Code marketplace |
 | `.agents/plugins` | **Distribution** | OpenAI/Codex repository marketplace metadata |
 | `plugins/harness-everything` | **Distribution** | Local OpenAI/Codex plugin package plus canonical skill copies |
 | `submission/openai` | **Distribution / Review** | Public OpenAI Skills-only listing/test inputs |
 | `evals` | **Routing Evals** | 26 trigger/routing eval suites (waza format) |
-| `behavioral-evals` | **Behavioral Evals** | LLM-level discipline cases (headless agent sessions) |
+| `behavioral-evals` | **Behavioral Evals** | LLM-level discipline cases plus weekly structural validation workflow |
 | `benchmarks` | **Benchmarks** | BENCHMARK_SOP fixtures and recorded A/B results |
-| `docs` | **Documentation** | Philosophy, architecture, routing, reflection, platform capabilities, audit |
+| `docs` | **Documentation** | Philosophy, architecture, routing, reflection, platform capabilities, generated repository contract, audit |
 | `references` | **Documentation** | Shared checklists (security, performance, definition-of-done) |
 | `multi-agent-workspace` | **Skill (Tier 3)** | Scaffold six zones, select agency specialists, and generate bounded launchers |
 | `environment-detection` | **Foundation** | Preflight: detect OS, shell, package manager |
@@ -249,6 +251,7 @@ For a deep dive into individual modules and the underlying philosophy, explore o
 * [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
 * [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
 * [Platform Capability Matrix](docs/platform-capabilities.md): Canonical current enforcement/install/evidence boundary per surface.
+* [Repository Runtime & Workflow Contract](docs/repository-contract.md): Generated Node/action/workflow/gate state used by consistency CI.
 * [OpenAI / ChatGPT Plugin Packaging](docs/openai-plugin.md): Local Codex/OpenAI plugin packaging plus public Skills-only submission boundary.
 * [Harness Routing & Triage](docs/routing.md): Detailed trigger criteria for Tiers 1, 2, and 3.
 * [Harness Reflection & Memory](docs/reflection.md): WAL session handoffs and workspace rules immunization.
@@ -264,7 +267,7 @@ Maintainers should follow [RELEASING.md](RELEASING.md) for tag-driven npm releas
 
 **If you are an agent asked to verify a Harness install, start at [VERIFICATION.md](VERIFICATION.md), not here.** It separates package/integrity checks, mechanism evidence, live-host evidence, and behavioral evidence so one kind of pass is not mistaken for another.
 
-`npm test` (`self-evolve/scripts/self-regression.js`) runs deterministic syntax, CLI, routing-matrix, positive skill-route coverage, **invariant-first routing regression**, reference, behavioral-case, Fable model-mode, and mechanism checks (`ci/mechanism-test.js`, `npm run test:mechanism` to run it alone). The suite checks real exit codes and stderr, not just "the code looks right." It runs in CI on Ubuntu, Windows, and macOS for every push and pull request (`.github/workflows/ci.yml`); live model evaluations remain explicitly on-demand.
+`npm test` (`self-evolve/scripts/self-regression.js`) runs deterministic syntax, CLI, routing-matrix, positive skill-route coverage, **invariant-first routing regression**, reference, behavioral-case, Fable model-mode, and mechanism checks (`ci/mechanism-test.js`, `npm run test:mechanism` to run it alone). The suite checks real exit codes and stderr, not just "the code looks right." Primary CI runs on Node.js 24 across Ubuntu, Windows, and macOS for every push and pull request (`.github/workflows/ci.yml`), with a separate Node.js 22 compatibility lane for the advertised minimum runtime.
 
 For a fuller vanilla-vs-Harness behavioral comparison, see [Harness Skills Benchmark SOP](BENCHMARK_SOP.md) — standardized, reproducible scenarios:
 * **Test A:** Over-engineering defense (Tier 1 typo correction)
@@ -276,13 +279,13 @@ For a fuller vanilla-vs-Harness behavioral comparison, see [Harness Skills Bench
 
 Benchmark **results** are tracked in [benchmarks/](benchmarks/README.md) (`run.js scaffold` builds the fixture, `record` commits a schema-validated result bound to a session log). Until those cells are filled, effectiveness claims are unbacked by recorded evidence.
 
-### Behavioral evals (LLM-level, on demand)
+### Behavioral evals (LLM-level, on demand + weekly structural validation)
 
-Mechanism tests prove individual packaged mechanisms; only real host/session evidence proves the host actually loaded and fired them. [behavioral-evals/](behavioral-evals/README.md) runs discipline cases (including pressure variants like "we ship in 5 minutes, skip checks") against headless agent sessions (`claude -p`, OpenCode) in throwaway workspaces: `npm run eval:behavioral`. Token-costing by design — never wired into CI.
+Mechanism tests prove individual packaged mechanisms; only real host/session evidence proves the host actually loaded and fired them. [behavioral-evals/](behavioral-evals/README.md) runs discipline cases (including pressure variants like "we ship in 5 minutes, skip checks") against headless agent sessions (`claude -p`, OpenCode) in throwaway workspaces: `npm run eval:behavioral`. Live runs remain token-costing and can be invoked on demand. The weekly `behavioral-evals.yml` workflow always validates case structure and runs live cases only when the runner actually has the Claude CLI.
 
 ### Catalog hygiene
 
-`npm run test:consistency` keeps the distribution manifests, docs links, skill frontmatter, routing-eval coverage, and the cross-platform capability claims in lockstep with what is actually on disk; `npm run test:docs:capabilities` runs the platform-doc drift check directly. `npm run test:references` checks every executable/deep-dive path named by `SKILL.md`; `npm run test:release` compares release/catalog evidence; `npm run test:routing:skills` recursively classifies nested skills and executes the real router for every directly-routable skill's positive cases; `npm run test:routing:invariants` guards the invariant-first architecture; and `harness verify-install` detects stale installed versions or file trees. The installer E2E gate performs install → verify-install → uninstall against seeded user-owned files on Ubuntu, Windows, and macOS so path and ownership symmetry regressions fail CI. `npm run test:collision` fails CI when two skills' descriptions overlap enough to confuse the router.
+`npm run test:consistency` keeps distribution manifests, docs links, skill frontmatter, routing-eval coverage, platform capability claims, and the generated repository runtime/workflow contract in lockstep with what is actually on disk. `npm run test:repo-contract` runs the runtime/workflow drift gate directly, while `npm run docs:sync` regenerates [docs/repository-contract.md](docs/repository-contract.md) after an intentional change. `npm run test:docs:capabilities` runs the platform-doc drift check directly. `npm run test:references` checks every executable/deep-dive path named by `SKILL.md`; `npm run test:release` compares release/catalog evidence; `npm run test:routing:skills` recursively classifies nested skills and executes the real router for every directly-routable skill's positive cases; `npm run test:routing:invariants` guards the invariant-first architecture; and `harness verify-install` detects stale installed versions or file trees. The installer E2E gate performs install → verify-install → uninstall against seeded user-owned files on Ubuntu, Windows, and macOS so path and ownership symmetry regressions fail CI. `npm run test:collision` fails CI when two skills' descriptions overlap enough to confuse the router.
 
 ---
 
@@ -303,8 +306,9 @@ To contribute to Harness or modify any Skill behavior, ensure you run the local
 ```bash
 npm run self-regression
 npm run test:consistency
+npm run test:repo-contract
 npm run test:plugin:openai
 npm run test:plugin:submission
 ```
 
-All script modifications must pass 100% cleanly before pushing to keep the runtime immunized against behavioral regression.
+After intentional runtime/workflow changes, run `npm run docs:sync` and commit the regenerated repository contract. All script modifications must pass 100% cleanly before pushing to keep the runtime immunized against behavioral regression.

package/RELEASING.md

@@ -15,14 +15,25 @@ Harness releases are stable SemVer releases generated automatically from Convent
 
 There are no alpha, beta, or rc release channels. Historical prerelease tags remain history, but new releases come only from `main` and use `vX.Y.Z` tags.
 
-The migration baseline is the latest stable release tag, currently `v0.3.6`. Existing unreleased manifest strings do not determine the next version; Git history after that tag does.
+Do not hard-code a "current release baseline" in this guide. `semantic-release` discovers the latest stable tag from Git history on each run, and release evidence belongs in [docs/release-evidence.md](docs/release-evidence.md).
+
+## Runtime contract
+
+The release job uses the repository's primary Node runtime from the checked-in current-state policy: Node.js 24 today, with Node.js 22 retained as the minimum supported product runtime. The generated source-of-truth summary is [docs/repository-contract.md](docs/repository-contract.md).
+
+When changing Node versions, GitHub Action majors, or workflow triggers, run:
+
+```bash
+npm run docs:sync
+npm run test:repo-contract
+```
 
 ## Release flow
 
 A push to `main` runs the full reusable CI gate and then semantic-release. A manual `workflow_dispatch` run is available for a safe retry.
 
 1. Check out full Git history and tags.
-2. Run the same CI jobs used for pull requests.
+2. Run the same CI jobs used for pull requests, including the Node 22 minimum-runtime compatibility lane.
 3. Analyze Conventional Commits since the latest stable release.
 4. Exit without publishing when there is no releasable commit.
 5. Calculate the next stable SemVer.

package/VERIFICATION.md

@@ -11,7 +11,7 @@ Harness verification separates four kinds of evidence that must not be conflated
 
 A mechanism test can pass while a live host never loads the plugin. A behavior test can pass on an advisory-only surface without proving any hard enforcement. Keep those claims separate.
 
-The authoritative current platform boundary is [docs/platform-capabilities.md](docs/platform-capabilities.md).
+The authoritative current platform boundary is [docs/platform-capabilities.md](docs/platform-capabilities.md). The generated current runtime/workflow boundary is [docs/repository-contract.md](docs/repository-contract.md).
 
 ---
 
@@ -146,6 +146,21 @@ The capability test checks the current-state documentation surfaces for stale pl
 
 When changing platform integration behavior, update [docs/platform-capabilities.md](docs/platform-capabilities.md) and all affected current-state docs in the same PR.
 
+### 3a. Repository runtime/workflow contract
+
+Runtime and workflow claims are extracted from `package.json`, `.nvmrc`, `Dockerfile`, and active `.github/workflows/*.yml` rather than being independently maintained in prose.
+
+```bash
+npm run repo:contract          # human-readable current state
+npm run repo:contract -- --json
+npm run docs:sync              # regenerate docs/repository-contract.md
+npm run test:repo-contract     # fail on drift
+```
+
+The contract gate requires Node.js 22 or newer as the supported floor, requires the primary `.nvmrc` runtime to match Docker and active primary workflows, keeps an explicit Node 22 CI compatibility lane, rejects GitHub Action majors below the supported floor, preserves the weekly behavioral-eval schedule, and checks that the generated contract document is current.
+
+After intentionally changing runtime/workflow configuration, regenerate the document and commit it in the same PR. Historical audit/evidence snapshots are not rewritten merely because the current contract changed.
+
 ---
 
 ## 4. Behavioral test prompts
@@ -271,13 +286,17 @@ For a comprehensive audit:
 
 ```bash
 npm test
+npm run test:mutations
 npm run test:consistency
+npm run test:repo-contract
 npm run test:references
+npm run test:release
 npm run test:routing:skills
 npm run test:routing:invariants
 npm run test:plugin:openai
 npm run test:plugin:submission
+npm run test:platform:compatibility
 node ci/installer-roundtrip.test.js
 ```
 
-Do not accept "I read the code and it looks right" as evidence for a runtime or live-host claim.
+Primary CI uses Node.js 24 across Ubuntu, Windows, and macOS; the dedicated Node.js 22 lane proves the advertised minimum remains viable. Do not accept "I read the code and it looks right" as evidence for a runtime or live-host claim.

package/ci/repository-contract.test.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const { collectContract, renderContractMarkdown, validateContract } = require('../scripts/repository-contract');
+
+const contract = collectContract();
+const failures = validateContract(contract);
+assert.deepStrictEqual(failures, [], `Repository contract drift:\n- ${failures.join('\n- ')}`);
+
+const rendered = renderContractMarkdown(contract);
+assert.match(rendered, /Minimum supported Node\.js/);
+assert.match(rendered, /GitHub Actions runtime majors/);
+assert.ok(contract.ci.qualityGates.includes('test:consistency'), 'CI contract must expose test:consistency');
+assert.ok(contract.behavioralEvals.scheduled, 'Behavioral eval schedule must remain visible to the contract');
+
+console.log('Repository contract verified: runtime, workflows, action majors, schedule, gates, and generated docs are synchronized.');

package/docs/release-evidence.md

@@ -14,7 +14,9 @@ The source capture for this row is the local review artifact `.git/issue-review-
 
 ## Current review boundary
 
-No evidence in the source capture proves that `0.3.7-beta` was tagged, published to npm, or released on GitHub. The release preparation commit and changelog heading must therefore remain separate from a release claim until a maintainer records the post-tag observations above.
+This file is an evidence ledger, not a source of truth for the current package version. Historical rows stay unchanged until all four observations for a newer release are deliberately collected. Current release/runtime configuration must be read from Git history, package metadata, the release workflow, and [repository-contract.md](repository-contract.md), rather than from prose such as the retired `0.3.7-beta` review note.
+
+A GitHub tag or source version alone is not enough to add a completed row here; keep using `not observed` when registry, workflow, or publication evidence has not been checked.
 
 ## Evidence entry template
 

package/docs/repository-contract.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/repository-contract.js. Run `npm run docs:sync` after workflow/runtime changes. -->
+# Repository runtime and workflow contract
+
+This page is generated from checked-in runtime and workflow sources. Do not edit it by hand. Historical audit/evidence documents are intentionally outside this current-state contract.
+
+## Runtime
+
+- Minimum supported Node.js: **22** (from `package.json#engines.node`: `>=22`)
+- Primary development/CI Node.js: **24** (from `.nvmrc`)
+- Docker verification Node.js: **24** (from `Dockerfile`)
+
+## GitHub Actions runtime majors
+
+- `actions/checkout`: v7
+- `actions/setup-node`: v7
+
+## Active workflows
+
+| Workflow | Node.js versions | Explicit triggers | npm quality gates |
+| --- | --- | --- | --- |
+| `behavioral-evals.yml` | 24 | schedule, workflow_dispatch | n/a |
+| `ci.yml` | 22, 24 | workflow_call | `test`, `test:mutations`, `test:consistency`, `test:references`, `test:release`, `test:collision`, `test:plugin:openai`, `test:plugin:submission`, `test:platform:compatibility` |
+| `release.yml` | 24 | workflow_dispatch | n/a |
+
+## Drift prevention
+
+`npm run test:repo-contract` fails when runtime sources disagree, an active workflow reintroduces an unsupported Node version/action major, the Node 22 compatibility floor is no longer exercised, or this generated document is stale.

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Harness OS Troubleshooting Guide
 
-This guide helps you resolve common issues with Harness OS installation and usage. Platform enforcement claims follow [platform-capabilities.md](platform-capabilities.md).
+This guide helps you resolve common issues with Harness OS installation and usage. Platform enforcement claims follow [platform-capabilities.md](platform-capabilities.md). Current Node/workflow values are generated in [repository-contract.md](repository-contract.md).
 
 ## Installation Issues
 
@@ -31,14 +31,20 @@ export PATH=~/.npm-global/bin:$PATH
 # Check your Node.js version
 node --version
 
-# Harness requires Node.js 18 or higher
-# Update using nvm (recommended):
-nvm install 18
-nvm use 18
+# Harness supports Node.js 22 or newer.
+# Node.js 24 is the primary/recommended development runtime.
+nvm install 24
+nvm use 24
 
-# Or download from https://nodejs.org/
+# To reproduce the minimum-runtime CI lane explicitly:
+nvm install 22
+nvm use 22
+
+# Or download a supported release from https://nodejs.org/
 ```
 
+The checked-in `.nvmrc` selects the primary runtime. If runtime/workflow files change, run `npm run docs:sync` followed by `npm run test:repo-contract` so generated current-state documentation cannot drift.
+
 ### Network Issues
 
 **Symptom:** `npm ERR! network` or timeout errors
@@ -264,6 +270,7 @@ For deterministic cross-platform mechanism checks, prefer:
 ```bash
 npm run test:mechanism
 npm run test:docs:capabilities
+npm run test:repo-contract
 ```
 
 When isolating a specific Claude hook, use the Windows-safe `spawnSync` recipes in [../VERIFICATION.md](../VERIFICATION.md) rather than assuming a shell `echo | node` pipeline behaves the same on every OS.

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {
@@ -13,7 +13,10 @@
     "test:mutations": "node ci/mutation-check.js",
     "test:tdd-quality": "node ci/mechanism-2s-tdd-quality.test.js",
     "tdd:quality": "node tdd/scripts/quality-gate.js",
-    "test:consistency": "node ci/consistency-check.js && node ci/doc-capability-consistency.test.js",
+    "repo:contract": "node scripts/repository-contract.js",
+    "docs:sync": "node scripts/sync-current-docs.js",
+    "test:repo-contract": "node ci/repository-contract.test.js",
+    "test:consistency": "node ci/consistency-check.js && node ci/doc-capability-consistency.test.js && node ci/repository-contract.test.js",
     "test:docs:capabilities": "node ci/doc-capability-consistency.test.js",
     "test:references": "node ci/reference-check.js",
     "test:release": "node ci/release-consistency-check.js && node ci/mechanism-2x-release-automation.test.js && node ci/mechanism-2x-release-commit-message.test.js",
@@ -39,7 +42,7 @@
     "commitlint": "commitlint --edit"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "author": "Miya Daniel",
   "license": "Apache-2.0",

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/scripts/repository-contract.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const ACTION_MINIMUMS = Object.freeze({ checkout: 7, setupNode: 7 });
+const MINIMUM_SUPPORTED_NODE_FLOOR = 22;
+
+function read(root, rel) {
+  return fs.readFileSync(path.join(root, rel), 'utf8');
+}
+
+function readJson(root, rel) {
+  return JSON.parse(read(root, rel));
+}
+
+function parseMinimumNode(engine) {
+  const match = String(engine || '').match(/>=\s*v?(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function parseMajor(text) {
+  const match = String(text || '').trim().match(/^v?(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function uniqSorted(values) {
+  return [...new Set(values.filter(Number.isInteger))].sort((a, b) => a - b);
+}
+
+function extractMajors(text, action) {
+  const escaped = action.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`uses:\\s*${escaped}@v(\\d+)`, 'g');
+  const out = [];
+  let match;
+  while ((match = re.exec(text))) out.push(Number(match[1]));
+  return uniqSorted(out);
+}
+
+function extractNodeVersions(text) {
+  const out = [];
+  const re = /node-version:\s*["']?(\d+)(?:\.\d+)?["']?/g;
+  let match;
+  while ((match = re.exec(text))) out.push(Number(match[1]));
+  return uniqSorted(out);
+}
+
+function extractQualityGates(text) {
+  const gates = [];
+  if (/\bnpm\s+test\b/.test(text)) gates.push('test');
+  const re = /\bnpm\s+run\s+([A-Za-z0-9:_-]+)/g;
+  let match;
+  while ((match = re.exec(text))) gates.push(match[1]);
+  return [...new Set(gates)];
+}
+
+function listWorkflowFiles(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(name => /\.ya?ml$/i.test(name))
+    .sort();
+}
+
+function parseWorkflow(root, file) {
+  const rel = path.posix.join('.github/workflows', file);
+  const text = read(root, rel);
+  return {
+    file,
+    nodeVersions: extractNodeVersions(text),
+    checkoutMajors: extractMajors(text, 'actions/checkout'),
+    setupNodeMajors: extractMajors(text, 'actions/setup-node'),
+    scheduled: /^\s*schedule:\s*$/m.test(text),
+    workflowDispatch: /^\s*workflow_dispatch:\s*$/m.test(text),
+    workflowCall: /^\s*workflow_call:\s*$/m.test(text),
+    qualityGates: extractQualityGates(text),
+  };
+}
+
+function collectContract(root = ROOT) {
+  const pkg = readJson(root, 'package.json');
+  const nvmPath = path.join(root, '.nvmrc');
+  const primaryNode = fs.existsSync(nvmPath) ? parseMajor(read(root, '.nvmrc')) : null;
+  const dockerText = read(root, 'Dockerfile');
+  const dockerMatch = dockerText.match(/^FROM\s+node:(\d+)(?:[^\s]*)/m);
+  const workflows = listWorkflowFiles(root).map(file => parseWorkflow(root, file));
+  const ci = workflows.find(workflow => workflow.file === 'ci.yml' || workflow.file === 'ci.yaml');
+  const behavioral = workflows.find(workflow => /^behavioral-evals\.ya?ml$/.test(workflow.file));
+  const release = workflows.find(workflow => /^release\.ya?ml$/.test(workflow.file));
+
+  return {
+    runtime: {
+      packageEngine: pkg.engines?.node || null,
+      minimumNode: parseMinimumNode(pkg.engines?.node),
+      primaryNode,
+      dockerNode: dockerMatch ? Number(dockerMatch[1]) : null,
+    },
+    githubActions: {
+      checkoutMajors: uniqSorted(workflows.flatMap(workflow => workflow.checkoutMajors)),
+      setupNodeMajors: uniqSorted(workflows.flatMap(workflow => workflow.setupNodeMajors)),
+    },
+    workflows: Object.fromEntries(workflows.map(workflow => [workflow.file, workflow])),
+    ci: ci || null,
+    behavioralEvals: behavioral || null,
+    release: release || null,
+  };
+}
+
+function renderContractMarkdown(contract) {
+  const runtime = contract.runtime;
+  const actionList = values => values.length ? values.map(v => `v${v}`).join(', ') : 'not used';
+  const rows = Object.values(contract.workflows).map(workflow => {
+    const nodes = workflow.nodeVersions.length ? workflow.nodeVersions.map(String).join(', ') : 'n/a';
+    const trigger = [workflow.scheduled && 'schedule', workflow.workflowDispatch && 'workflow_dispatch', workflow.workflowCall && 'workflow_call'].filter(Boolean).join(', ') || 'push/pull request or other';
+    const gates = workflow.qualityGates.length ? workflow.qualityGates.map(g => `\`${g}\``).join(', ') : 'n/a';
+    return `| \`${workflow.file}\` | ${nodes} | ${trigger} | ${gates} |`;
+  }).join('\n');
+
+  return `<!-- GENERATED by scripts/repository-contract.js. Run \`npm run docs:sync\` after workflow/runtime changes. -->\n# Repository runtime and workflow contract\n\nThis page is generated from checked-in runtime and workflow sources. Do not edit it by hand. Historical audit/evidence documents are intentionally outside this current-state contract.\n\n## Runtime\n\n- Minimum supported Node.js: **${runtime.minimumNode}** (from \`package.json#engines.node\`: \`${runtime.packageEngine}\`)\n- Primary development/CI Node.js: **${runtime.primaryNode}** (from \`.nvmrc\`)\n- Docker verification Node.js: **${runtime.dockerNode}** (from \`Dockerfile\`)\n\n## GitHub Actions runtime majors\n\n- \`actions/checkout\`: ${actionList(contract.githubActions.checkoutMajors)}\n- \`actions/setup-node\`: ${actionList(contract.githubActions.setupNodeMajors)}\n\n## Active workflows\n\n| Workflow | Node.js versions | Explicit triggers | npm quality gates |\n| --- | --- | --- | --- |\n${rows}\n\n## Drift prevention\n\n\`npm run test:repo-contract\` fails when runtime sources disagree, an active workflow reintroduces an unsupported Node version/action major, the Node ${runtime.minimumNode} compatibility floor is no longer exercised, or this generated document is stale.\n`;
+}
+
+function validateContract(contract, root = ROOT) {
+  const failures = [];
+  const fail = message => failures.push(message);
+  const { runtime } = contract;
+
+  if (!Number.isInteger(runtime.minimumNode) || runtime.minimumNode < MINIMUM_SUPPORTED_NODE_FLOOR) {
+    fail(`package.json must declare Node >=${MINIMUM_SUPPORTED_NODE_FLOOR}; got ${runtime.packageEngine || 'missing'}`);
+  }
+  if (!Number.isInteger(runtime.primaryNode) || runtime.primaryNode < runtime.minimumNode) {
+    fail(`.nvmrc primary Node must be >= minimum Node ${runtime.minimumNode}; got ${runtime.primaryNode ?? 'missing'}`);
+  }
+  if (runtime.dockerNode !== runtime.primaryNode) {
+    fail(`Dockerfile Node ${runtime.dockerNode ?? 'missing'} must match .nvmrc Node ${runtime.primaryNode ?? 'missing'}`);
+  }
+
+  for (const major of contract.githubActions.checkoutMajors) {
+    if (major < ACTION_MINIMUMS.checkout) fail(`actions/checkout@v${major} is below supported floor v${ACTION_MINIMUMS.checkout}`);
+  }
+  for (const major of contract.githubActions.setupNodeMajors) {
+    if (major < ACTION_MINIMUMS.setupNode) fail(`actions/setup-node@v${major} is below supported floor v${ACTION_MINIMUMS.setupNode}`);
+  }
+  if (contract.githubActions.checkoutMajors.length !== 1) fail(`active workflows must use one checkout major; found ${contract.githubActions.checkoutMajors.join(', ') || 'none'}`);
+  if (contract.githubActions.setupNodeMajors.length !== 1) fail(`active workflows must use one setup-node major; found ${contract.githubActions.setupNodeMajors.join(', ') || 'none'}`);
+
+  for (const workflow of Object.values(contract.workflows)) {
+    for (const node of workflow.nodeVersions) {
+      if (node < runtime.minimumNode) fail(`${workflow.file} uses Node ${node}, below minimum ${runtime.minimumNode}`);
+    }
+  }
+
+  if (!contract.ci) fail('ci.yml is missing');
+  else {
+    if (!contract.ci.nodeVersions.includes(runtime.primaryNode)) fail(`ci.yml must exercise primary Node ${runtime.primaryNode}`);
+    if (!contract.ci.nodeVersions.includes(runtime.minimumNode)) fail(`ci.yml must exercise minimum supported Node ${runtime.minimumNode}`);
+  }
+  if (!contract.behavioralEvals) fail('behavioral-evals.yml is missing');
+  else {
+    if (!contract.behavioralEvals.scheduled) fail('behavioral-evals.yml must retain its scheduled trigger');
+    if (!contract.behavioralEvals.nodeVersions.includes(runtime.primaryNode)) fail(`behavioral-evals.yml must use primary Node ${runtime.primaryNode}`);
+  }
+  if (!contract.release) fail('release.yml is missing');
+  else if (!contract.release.nodeVersions.includes(runtime.primaryNode)) {
+    fail(`release.yml must use primary Node ${runtime.primaryNode}`);
+  }
+
+  const generatedPath = path.join(root, 'docs', 'repository-contract.md');
+  if (!fs.existsSync(generatedPath)) {
+    fail('docs/repository-contract.md is missing; run npm run docs:sync');
+  } else {
+    const actual = fs.readFileSync(generatedPath, 'utf8').replace(/\r\n/g, '\n');
+    const expected = renderContractMarkdown(contract).replace(/\r\n/g, '\n');
+    if (actual !== expected) fail('docs/repository-contract.md is stale; run npm run docs:sync');
+  }
+
+  return failures;
+}
+
+function printSummary(contract) {
+  console.log(`Node: >=${contract.runtime.minimumNode} supported; ${contract.runtime.primaryNode} primary; ${contract.runtime.dockerNode} Docker`);
+  console.log(`Actions: checkout ${contract.githubActions.checkoutMajors.map(v => `v${v}`).join(', ')}; setup-node ${contract.githubActions.setupNodeMajors.map(v => `v${v}`).join(', ')}`);
+  for (const workflow of Object.values(contract.workflows)) {
+    console.log(`${workflow.file}: Node ${workflow.nodeVersions.join(', ') || 'n/a'}; gates ${workflow.qualityGates.join(', ') || 'n/a'}`);
+  }
+}
+
+if (require.main === module) {
+  const args = new Set(process.argv.slice(2));
+  const contract = collectContract();
+  if (args.has('--json')) {
+    process.stdout.write(`${JSON.stringify(contract, null, 2)}\n`);
+  } else if (args.has('--check')) {
+    const failures = validateContract(contract);
+    if (failures.length) {
+      for (const failure of failures) console.error(`❌ ${failure}`);
+      process.exitCode = 1;
+    } else {
+      console.log('✅ Repository runtime/workflow contract is consistent.');
+    }
+  } else {
+    printSummary(contract);
+  }
+}
+
+module.exports = {
+  ACTION_MINIMUMS,
+  MINIMUM_SUPPORTED_NODE_FLOOR,
+  collectContract,
+  renderContractMarkdown,
+  validateContract,
+};

package/scripts/sync-current-docs.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { collectContract, renderContractMarkdown } = require('./repository-contract');
+
+const ROOT = path.resolve(__dirname, '..');
+const output = path.join(ROOT, 'docs', 'repository-contract.md');
+fs.mkdirSync(path.dirname(output), { recursive: true });
+fs.writeFileSync(output, renderContractMarkdown(collectContract(ROOT)), 'utf8');
+console.log(`Updated ${path.relative(ROOT, output).replace(/\\/g, '/')}`);