@jaimevalasek/aioson 1.23.1 → 1.28.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.28.0] - 2026-06-11
+
+### Added
+- **`forge:compile` — spec → workflow-script compiler (Lane B, opt-in).** `aioson forge:compile [path] --feature=<slug> [--json]` compiles a MEDIUM feature's completed artifacts into `.aioson/plans/{slug}/forge-run.workflow.js` — an auditable, versionable dynamic-workflow script meant to be committed alongside the spec. Compiled structure: one `parallel()` stage per Wave (file-disjoint dev agents, blocked-wave early stop), a deterministic convergence loop on `aioson harness:check` bounded by the governor's `error_streak_limit` (fixes run **sequentially** — criteria don't prove file-disjointness, only waves do) plus a token-budget guard, 3-lens adversarial review (correctness/completeness/regression-risk, majority survives, refute-by-default) for binary criteria without `verification`, and a fresh-context validator stage that closes through the normal `harness:validate` → `last-validator-output.json` → `apply-validation` circuit-breaker cycle. Hard preflights — invalid/missing contract, zero executable criteria, plan without Wave column, `spec:analyze` errors, and `wave_file_overlap` (warning in analyze, **error** here) all refuse compilation with owner-agent guidance. Generated code honors the workflow runtime contract: pure-literal `meta`, plain JS, no `Date.now()`/`Math.random()`/`new Date()`, and all artifact-derived text embedded via `JSON.stringify` (no interpolable template literals — injection-safe). The script never runs `feature:close`/publish.
+- **`@forge-run` agent — the Lane B entry point.** New opt-in agent (`/forge-run`): compile (refusals route to the owner agent), review the compile report with the user (cost warning included), execute the generated script via the workflow runtime (never hand-emulated), and report — PASS recommends the human run `feature:close`, FAIL routes to `@dev` through the normal lane. Registered across CLAUDE.md/AGENTS.md/OPENCODE.md, `.claude/commands` wrapper, `src/constants.js` (MANAGED_FILES + AGENTS), and all template mirrors.
+- **`src/harness/plan-waves.js`** — shared Execution Sequence parser (waves + scope + done columns, `groupByWave`), extracted from `spec:analyze` and reused by the compiler. `spec:analyze` behavior unchanged.
+
+### Tests
+- Added `forge-compile` suite (9 cases: preflight refusals, governor-derived fix-loop cap, wave→parallel structure, runtime-constraint bans, byte-identical recompilation determinism, template-injection invariant, JSON mode). Full suite green (3210 pass).
+
+## [1.27.0] - 2026-06-11
+
+### Added
+- **Wave column — parallelism markers in the MEDIUM implementation plan.** `@pm`'s Execution Sequence gains a `Wave` column: phases sharing a Wave are file-disjoint and dependency-free with respect to each other (parallelizable via isolated subagents/worktrees); waves execute in ascending order. Marking rules are conservative by design — same Wave only when Primary files do not overlap AND neither phase consumes the other's output; when in doubt, sequential (a wrong sequential marking costs wall-clock; a wrong parallel marking costs a merge conflict). This is the cheap prerequisite for any future fan-out execution lane, and forces explicit file-boundary thinking even without one. Template mirror synced.
+- **`wave_file_overlap` check in `spec:analyze`.** The deterministic pass now parses the Execution Sequence table and flags same-wave phases whose Primary files overlap (warning). Noise-guarded for backward compatibility: plans without a Wave column skip the check entirely; placeholder cells (`...`, `-`) and non-integer waves are ignored; paths normalized (backticks stripped, separators unified, case-insensitive).
+
+### Tests
+- Added wave overlap/disjoint/legacy-plan cases to the `spec-analyze` suite (14 total). Full suite green (3201 pass).
+
+## [1.26.0] - 2026-06-11
+
+### Added
+- **`spec:analyze` — deterministic cross-artifact content consistency.** `aioson spec:analyze [path] --feature=<slug> [--json]` is the content sibling of `artifact:validate` (chain presence — untouched): it confronts the feature's artifacts before the execution gate and reports findings by severity. Checks: REQ/AC **ID traceability** (ids declared in `requirements-{slug}.md` never referenced downstream = coverage gap; ids referenced downstream but never declared = orphan/drift signal — both noise-guarded: prose-style plans that cite no ids produce no gap findings), **staleness ordering** (upstream artifact modified after a downstream one was produced, 60s tolerance, project-global `architecture.md` excluded), **readiness states** (`blocked` = error, `ready_with_warnings` = info), **harness-contract sanity** (schema errors = error; executable-coverage warnings = info, via `validateContract`), and **AC→contract linkage** (no declared AC mentioned in the contract = info). Persists `spec-analyze-{slug}.json` to `.aioson/context/` (collected by `feature:export`/`archive`); `error` findings flip `ok: false` (exit 1 in `--json` mode) for gate scripting. Reuses `scanArtifacts`/`detectClassification` from the preflight engine.
+
+### Changed
+- **`@scope-check` preflight runs `spec:analyze`.** The deterministic pass executes before deep loads: `error` findings are blockers routed to the owner agent; `warning` findings enter the drift comparison as pre-computed evidence to confirm or dismiss explicitly. Template mirror synced.
+
+### Tests
+- Added `spec-analyze` suite (11 cases: traceability gaps/orphans, prose-plan noise guard, staleness via mtime, readiness blocked, contract schema/coverage/AC-linkage, persistence, JSON mode). Full suite green (3198 pass).
+
+## [1.25.0] - 2026-06-11
+
+### Added
+- **Fresh-context review payload in `harness:validate`.** The generated `validator-prompt.txt` is now self-contained for isolated execution: it appends a review payload with the deterministic `harness:check` results (exit-code verdicts to copy verbatim), the changed-file list (including untracked, framework state filtered out), and the unified diff vs a resolved base ref — explicit `--base=<ref>`, the loop's `baseline.json` HEAD, merge-base with main/master, or `HEAD` as fallback. Diff is size-capped (`--max-diff-bytes`, default 200KB) with a line-boundary truncation marker; `--no-diff` skips the payload. Degrades gracefully outside a git repository (existing router flows untouched). New module `src/harness/review-payload.js`.
+- **Fresh-context validation protocol.** `@validator` documents the generated prompt as its preferred activation surface — run in a fresh, isolated context (subagent/Task tool or separate session), never inline in the session that implemented the feature. `.aioson/docs/autopilot-handoff.md` post-dev cycle routes `@validator` through the isolated-subagent flow (check → validate → isolated run → re-validate to consume the verdict through the circuit breaker); `@qa`'s recommendation mentions the route. Template mirrors synced.
+
+### Changed
+- **`harness:validate` next-steps guidance** now instructs running the prompt in a fresh isolated context, and the command result exposes a `reviewPayload` summary (base, changed-file count, truncation, checks included). The `waiting_validation`/`apply-validation` state machine is unchanged.
+- **Parser:** `--no-diff` registered as a pure boolean flag (mirrors `--no-index` precedent).
+
+### Tests
+- Added `review-payload` suite (10 cases: git fixtures for base resolution, untracked + framework-state filtering, truncation, check-summary embedding, `harness:validate` integration, `--no-diff`). Full suite green (3187 pass).
+
+## [1.24.0] - 2026-06-11
+
+### Added
+- **`harness:check` — standalone deterministic runner for `criteria[].verification`.** `aioson harness:check [path] --slug=<slug> [--criteria=C1,C2] [--timeout=<ms>] [--json]` executes the contract's executable checks outside `self:loop`, reusing the existing `runCriteria`/`executeInSandbox` stack (timeouts, process-tree kill, credential redaction, failure signatures). Read-only over `progress.json` — circuit/breaker state mutation remains exclusive to the `harness:validate`/`apply-validation` cycle. Persists the report to `.aioson/plans/{slug}/last-check-output.json` (mirroring `last-validator-output.json`), emits `criteria_check_failed` telemetry best-effort, auto-discovers the active contract when `--slug` is omitted, and supports criterion-subset runs via `--criteria`.
+- **`verification` is now a first-class authored field.** The canonical contract doc (`.aioson/docs/sheldon/harness-contract.md` + template mirror) documents `criteria[].verification` with authoring rules (exit 0 = pass, deterministic, cross-platform, prefer the project test runner); `@sheldon` RF-05 instructs producing it for every mechanically checkable `binary: true` criterion. Legacy contracts without the field remain fully valid.
+- **Executable-coverage warning in contract schema validation.** `validateContract` now emits an advisory warning (never an error) for each `binary: true` criterion lacking a `verification` command, surfacing verification debt at `harness:init`/preflight without breaking any existing contract.
+
+### Changed
+- **`@validator` consumes deterministic checks first.** Step 2 of the validator protocol now runs `aioson harness:check . --slug={slug} --json` and copies each executable check's exit-code verdict verbatim into `results[].passed`; LLM judgment is reserved for criteria without `verification`. Output JSON schema unchanged — `harness:apply-validation` and the circuit-breaker cycle are untouched. `@qa`'s validator recommendation and `@dev`'s implementation strategy mention the new command (template mirrors synced).
+
+### Tests
+- Added `harness-check` suite (10 cases: pass/fail/signature, progress.json immutability, subset filter, unknown ids, active-contract auto-discovery, JSON mode, schema rejection) and coverage-warning cases in `harness-contract-schema`. Full suite green (3178 pass).
+
 ## [1.23.0] - 2026-06-10
 
 ### Added

package/docs/en/4-agents/README.md

@@ -1,12 +1,12 @@
 # Agent cards — AIOSON (EN)
 
-This layer will hold one card per AIOSON agent (29 total), translated from [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md).
+This layer will hold one card per AIOSON agent (29 total), translated from [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md).
 
 Cards are being translated progressively. Until a card is available here, the PT version is the canonical reference — it follows the same format and covers the same agents.
 
 ---
 
-## The 29 agents (plus @pair alias)
+## The 29 agents (plus @pair alias)
 
 ### Workflow core (pipeline order)
 
@@ -14,17 +14,18 @@ Cards are being translated progressively. Until a card is available here, the PT
 |---|---|
 | `@setup` | Project onboarding — detect stack, classify MICRO/SMALL/MEDIUM, write `project.context.md` |
 | `@briefing` | Pre-PRD framing — turn `plans/` sketches into structured briefings with gap analysis |
-| `@product` | PRD — vision, problem, users, scope, acceptance criteria |
-| `@sheldon` | PRD quality guardian — gap detection, web research, sizing, in-place enrichment or phased plan |
-| `@analyst` | Domain discovery — entities, flows, brownfield mapping |
-| `@scope-check` | Alignment gate before implementation — validates intent vs plan and catches scope drift |
-| `@architect` | Technical decisions — structure, libraries, integration boundaries |
+| `@product` | PRD — vision, problem, users, scope, acceptance criteria |
+| `@sheldon` | PRD quality guardian — gap detection, web research, sizing, in-place enrichment or phased plan |
+| `@analyst` | Domain discovery — entities, flows, brownfield mapping |
+| `@scope-check` | Alignment gate before implementation — validates intent vs plan and catches scope drift |
+| `@architect` | Technical decisions — structure, libraries, integration boundaries |
 | `@ux-ui` | Design system and UI component specs (MEDIUM) |
 | `@pm` | Backlog and user stories (MEDIUM) |
 | `@orchestrator` | Parallel lane coordination (MEDIUM) |
 | `@dev` | Feature implementation — any stack |
 | `@qa` | Risk-first review, test generation, autonomous fix/test loop |
 | `@validator` | Binary contract verification against `harness-contract.json` |
+| [`@forge-run`](./forge-run.md) | Lane B (opt-in) — compile a MEDIUM feature's specs into an executable workflow and run it (`forge:compile`) |
 | `@tester` | Systematic test engineering — legacy and coverage gaps |
 | `@pentester` | Adversarial security review — OWASP Top 10, LLM Top 10, supply chain |
 
@@ -50,8 +51,10 @@ Cards are being translated progressively. Until a card is available here, the PT
 | `@design-hybrid-forge` | Combine two design skills into a hybrid |
 | `@orache` | Domain investigation and strategic research |
 | `@copywriter` | Conversion copy — landing pages, VSL scripts |
-| [`@discovery-design-doc`](./discovery-design-doc.md) | Discovery, readiness, and design doc package |
+| [`@discovery-design-doc`](./discovery-design-doc.md) | Discovery, readiness, and design doc package |
 
 ---
 
+For the executable-verification theme that `@forge-run`, `@validator`, `@scope-check`, `@sheldon`, and `@pm` participate in, see [Executable verification](../5-reference/executable-verification.md).
+
 Full PT cards with dialogue examples, disk outputs, and handoff maps: [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md)

package/docs/en/4-agents/forge-run.md

@@ -0,0 +1,165 @@
+# @forge-run - Compile and run the Lane B verification workflow
+
+> **For whom:** people with a MEDIUM feature that has a binary contract and a wave-based plan, who want to run the entire executable-verification cycle as a single compiled workflow.
+> **Reading time:** 4 min.
+> **What you will learn:**
+> - What Lane B is and why it is **opt-in** and **additive**
+> - The protocol: `forge:compile` → review with you → execute → report
+> - Why `@forge-run` never weakens a verification nor closes the feature
+
+---
+
+## What it is for
+
+The default executable-verification lane (`@scope-check` → `@dev` → `@qa` → `@validator`) is **unchanged** and remains the recommended path. `@forge-run` is a **second lane (Lane B), optional and additive**: it compiles a MEDIUM feature's artifacts into a single **versionable workflow** and runs the whole deterministic-verification cycle end to end.
+
+Instead of advancing stage by stage manually, `@forge-run` generates `.aioson/plans/{slug}/forge-run.workflow.js` — a Claude Code dynamic-workflow script — and executes it through the workflow runtime (never hand-emulated). The compiled structure mirrors the executable-verification roadmap:
+
+- **`parallel()` per Wave** — same-wave phases are file-disjoint and run in parallel (see the `Wave` column produced by `@pm`).
+- **Deterministic loop over `harness:check`** — bounded by the governor's `error_streak_limit`; fixes are sequential (only waves prove disjointness).
+- **3-lens adversarial review** — for binary criteria that lack `verification` and therefore cannot be checked mechanically.
+- **Fresh-context validator** — closes through the `harness:validate` → `apply-validation` cycle (see `@validator`).
+
+**Hard rule:** one feature per run. `@forge-run` never runs `feature:close` and never publishes.
+
+---
+
+## When to invoke
+
+- A **MEDIUM** feature whose `harness-contract.json` carries `verification` per criterion (authored by `@sheldon`).
+- An implementation plan with the `Wave` column filled in (produced by `@pm`).
+- A clean `aioson spec:analyze` (no `errors`) — the execution-gate precondition.
+- When you want to run the whole executable-verification cycle as a single reproducible, versionable workflow.
+
+---
+
+## When not to invoke
+
+- MICRO or SMALL features → use the default lane (`@dev` → `@qa` → `@validator`).
+- A contract without executable criteria, or a plan without a `Wave` column → the hard preflights refuse to compile.
+- `spec:analyze` reporting `errors` or `wave_file_overlap` → resolve those first; Lane B does not compile over drift.
+- You only want to validate, not execute → use `@validator` directly.
+
+---
+
+## Required inputs
+
+Lane B only compiles when every prerequisite is present — otherwise the hard preflights refuse:
+
+- `.aioson/plans/{slug}/harness-contract.json` — a **valid** contract with at least one executable criterion (`verification` present).
+- `implementation-plan-{slug}.md` — a plan with the `Wave` column filled in.
+- `spec-analyze-{slug}.json` with no `errors` and no `wave_file_overlap`.
+
+---
+
+## Where it fits in the workflow
+
+Lane B is an opt-in branch off the standard MEDIUM flow, taken after the spec and plan are ready:
+
+```text
+@product -> @analyst -> @architect -> @sheldon (authors verification) ->
+@pm (Wave column) -> @scope-check (spec:analyze clean) -> @forge-run (Lane B)
+```
+
+It never replaces the default lane — it compiles the same artifacts into a single executable workflow. (`@pm`, `@sheldon`, and `@validator` cards are tracked in the [agents index](./README.md); PT is canonical until each is translated.)
+
+---
+
+## Typical dialogue
+
+```text
+You > @forge-run
+
+@forge-run > Feature: checkout-stripe (MEDIUM)
+
+             Lane B preflight:
+             - harness-contract.json valid ✓
+             - 5 criteria, 4 with verification (executable) ✓
+             - implementation-plan with Wave column ✓
+             - spec:analyze → ok, no errors, no wave_file_overlap ✓
+
+             $ aioson forge:compile . --feature=checkout-stripe
+             Compiled: .aioson/plans/checkout-stripe/forge-run.workflow.js
+
+             Workflow structure:
+             - Wave 1 (parallel): backend + migrations
+             - Wave 2: frontend
+             - harness:check loop (error_streak limit: 3, sequential fixes)
+             - 3-lens adversarial review for C5 (no verification)
+             - Fresh-context validator → apply-validation
+
+             ⚠ Cost: this workflow runs multiple LLM executions.
+             Review the script before executing. Approve execution? (y/n)
+
+You > y
+
+@forge-run > Executing via the workflow runtime...
+             Wave 1 ✓  Wave 2 ✓
+             harness:check → 4/4 executable criteria PASS
+             Adversarial review C5 → PASS
+             Fresh-context validator → overall_score: 1
+
+             RESULT: PASS
+             Recommendation: run `aioson feature:close` manually.
+```
+
+---
+
+## Disk outputs
+
+| File | Content |
+|---|---|
+| `.aioson/plans/{slug}/forge-run.workflow.js` | Compiled, versionable workflow (Claude Code dynamic workflow) |
+| `.aioson/plans/{slug}/last-check-output.json` | Last `harness:check` result consumed by the loop |
+| `.aioson/plans/{slug}/last-validator-output.json` | Fresh-context validator verdict |
+| `.aioson/plans/{slug}/progress.json` | Post-execution state (`circuit_state`, `ready_for_done_gate`) |
+
+The generated code is deterministic by construction: pure-literal metadata, no `Date.now`/`Math.random`/`new Date`, artifact text always via `JSON.stringify`, and it **never** invokes `feature:close`.
+
+---
+
+## How it reads your project
+
+- `.aioson/plans/{slug}/harness-contract.json` — the contract and criteria with `verification`
+- `.aioson/context/implementation-plan-{slug}.md` — the plan with the `Wave` column
+- `.aioson/plans/{slug}/spec-analyze-{slug}.json` — cross-artifact consistency (execution gate)
+- `.aioson/plans/{slug}/progress.json` — state and the governor's `error_streak_limit`
+
+---
+
+## Related CLI commands
+
+```bash
+# Compile the feature's artifacts into the Lane B workflow
+aioson forge:compile . --feature={slug}
+
+# Parseable output
+aioson forge:compile . --feature={slug} --json
+```
+
+See [forge:compile in the CLI reference](../5-reference/cli-reference.md) and [Executable verification](../5-reference/executable-verification.md) for the full theme.
+
+---
+
+## Hard rules
+
+- **Never** bypass a failed preflight (invalid contract, zero executable criteria, plan without a `Wave` column, `spec:analyze` `errors` or `wave_file_overlap`).
+- **Never** weaken or remove a `verification` check to make a criterion pass.
+- **Never** run `feature:close` or publish — that is always a human decision.
+- One feature per run.
+
+---
+
+## Typical handoff
+
+- **Comes from:** opt-in entry by the user (Lane B); assumes `@sheldon`, `@pm`, and `@scope-check`/`spec:analyze` are already complete.
+- **PASS:** recommends the **human** run `aioson feature:close` manually.
+- **FAIL:** routes back to `@dev` via the **normal lane** to fix and re-verify.
+
+---
+
+## Next step
+
+- `@pm` — produces the `Wave` column that becomes `parallel()` in the workflow (card in the [agents index](./README.md))
+- `@validator` — the fresh-context validator that closes the cycle (card in the [agents index](./README.md))
+- [Executable verification](../5-reference/executable-verification.md) — the full theme (Phases 1–5)

package/docs/en/5-reference/README.md

@@ -14,6 +14,7 @@ This layer currently holds the original EN feature guides. Additional reference
 |---|---|
 | [cli-reference.md](./cli-reference.md) | Full reference for every CLI command |
 | [json-schemas.md](./json-schemas.md) | `--json` output contracts for all commands |
+| [executable-verification.md](./executable-verification.md) | The executable-verification theme: `verification` + `harness:check`, fresh-context validator, `spec:analyze`, Wave markers, Lane B (`forge:compile` + `@forge-run`) |
 
 ---
 

package/docs/en/5-reference/cli-reference.md

@@ -663,88 +663,202 @@ aioson scout:commit --input=<path> --json
 **Exit codes:** 0 = committed (or no-op); 1 = file not found, lock failure.
 
 See [Sub-task Scout — CLI reference](../deyvin-subtask-scout/cli-commands.md) for full details.
-
----
-
-## harness:approve
-
-Approve a pending human gate in the self:loop (loop guardrails). Persists the decision (who, when) to `.aioson/plans/{slug}/gates/{id}.json` and resumes the loop.
-
-```bash
-aioson harness:approve . --slug=<feature> --gate=<gate-id>
-aioson harness:approve . --slug=checkout --gate=database_destructive_change-1
-```
-
-**Options:**
-- `--slug=<feature>` — **required**. Feature slug matching the harness contract.
-- `--gate=<id>` — **required**. Gate id shown in `harness:status` output.
-- `--by=<name>` — override the "decided by" field (defaults to `git config user.name`).
-
-**Idempotent:** re-approving an already-decided gate is a no-op with a warning.
-
----
-
-## harness:reject
-
-Reject a pending human gate. Ends the current loop attempt with a summary. Requires `--reason`.
-
-```bash
-aioson harness:reject . --slug=<feature> --gate=<gate-id> --reason="needs revert"
-```
-
-**Options:**
-- `--slug`, `--gate` — same as `harness:approve`.
-- `--reason=<text>` — **required** on reject. Recorded in the gate decision file.
-
----
-
-## harness:status
-
-Human-readable view of the current loop state for a feature.
-
-```bash
-aioson harness:status . --slug=<feature>
-aioson harness:status . --slug=checkout --json
-```
-
-**Shows:** circuit state (open/closed), current iteration / max, estimated token budget (used/ceiling), last-attempt checks (passed/failed), last failure signature, pending human gates, and recommended next action.
-
-**Options:**
-- `--slug=<feature>` — **required**.
-- `--json` — structured output.
-
----
-
-## harness:retro
-
-Deterministically mine the failure trail of a feature and materialize a retrospective dossier at `.aioson/context/retro/{slug}.md`. LLM-free, network-free. Source files are never modified.
-
-```bash
-aioson harness:retro . --feature=<slug>
-aioson harness:retro . --last=<N>          # last N features by PASS date
-aioson harness:retro . --feature=checkout --json
-```
-
-**Options:**
-- `--feature=<slug>` — mine a specific feature (mutually exclusive with `--last`).
-- `--last=<N>` — mine the N most recently completed features.
-- `--json` — structured output; exit codes are propagated.
-- `--locale=<l>` — output locale (default: project `interaction_language`).
-
-**Exit codes:** 0 = success (including empty dossier); 1 = unexpected I/O error; 12 = input error (invalid slug, conflicting flags, feature not found).
-
-**Sources mined:** QA reports, correction plans, dossier FAIL→PASS cycles, execution events, attempt artifacts, failure signatures, devlogs.
-
----
-
-## harness:preview
-
-Display a truncated, UTF-8-safe preview of an artifact file. Used in self:loop criteria-fail feedback to avoid dumping full file contents into the agent context.
-
-```bash
-aioson harness:preview <file>
-aioson harness:preview .aioson/context/retro/checkout.md
-```
-
-Read-only. Best-effort write for the preview artifact.
-
+
+---
+
+## harness:check
+
+Run the `criteria[].verification` shell commands from `harness-contract.json` deterministically — **outside** the self:loop and **read-only** over `progress.json`. Each criterion's command runs in the sandbox; exit code `0` = pass. Reuses the loop's `runCriteria`/`executeInSandbox` machinery (timeouts, process-tree kill, credential redaction, failure signatures). Persists `last-check-output.json` and emits `criteria_check_failed` telemetry on failure.
+
+```bash
+# Run every verifiable criterion of the active contract (auto-discovered)
+aioson harness:check . --slug=checkout
+
+# Run only a subset of criteria
+aioson harness:check . --slug=checkout --criteria=C1,C3
+
+# Custom timeout and JSON output (exit 0 = pass)
+aioson harness:check . --slug=checkout --timeout=120000 --json
+```
+
+**Options:**
+- `--slug=<feature>` — feature slug matching the harness contract. If omitted, the active contract is auto-discovered.
+- `--criteria=C1,C2` — run only the listed criteria instead of all verifiable ones.
+- `--timeout=<ms>` — per-criterion timeout override.
+- `--json` — structured output; exit code propagated.
+
+**What it does:** the `verification` field is authored per criterion by `@sheldon` for every mechanically-checkable `binary: true` criterion (prefer the project test runner; deterministic; cross-platform; exit 0 = pass). `harness:check` is the standalone deterministic verification of those criteria — it never touches the circuit-breaker state (that stays exclusive to `harness:validate`/`apply-validation`). Legacy contracts without `verification` remain valid; `validateContract` only emits an advisory **warning** for `binary: true` criteria lacking it. `@validator` runs `harness:check` first and copies the exit-code verdicts verbatim into `results[].passed`, LLM-judging only the criteria without `verification`.
+
+See [Executable verification](./executable-verification.md) for the full theme.
+
+---
+
+## harness:validate
+
+Generate the `validator-prompt.txt` for the binary success contract and append a self-contained **review payload** so the validator can judge in a fresh, isolated context. Consumes the verdict back through the circuit breaker.
+
+```bash
+# Generate the validator prompt with review payload
+aioson harness:validate . --slug=checkout
+
+# Resolve the diff against an explicit base
+aioson harness:validate . --slug=checkout --base=main
+
+# Skip the diff (review payload still includes check results + changed files)
+aioson harness:validate . --slug=checkout --no-diff
+
+# Cap the embedded diff size
+aioson harness:validate . --slug=checkout --max-diff-bytes=200000
+```
+
+**Options:**
+- `--slug=<feature>` — **required**. Feature slug matching the harness contract.
+- `--base=<ref>` — git ref to diff against. Resolution order: `--base` > `baseline.json` head > merge-base with `main`/`master` > `HEAD`.
+- `--no-diff` — pure boolean flag; omit the unified diff from the review payload.
+- `--max-diff-bytes=<n>` — cap the embedded diff (default `200000`); truncation happens on a line boundary.
+
+**What it does:** the review payload (built by `src/harness/review-payload.js`) contains (a) the `harness:check` results, (b) the changed-file list (untracked files included, `.aioson/**` framework state filtered out), and (c) a unified diff against the resolved base. It degrades gracefully outside a git repo. The protocol is that `@validator` runs in a **fresh, isolated context** (a subagent / Task tool, or a separate session) — never inline in the implementing session, because implementation history biases the verdict. Typical flow: `harness:check` → `harness:validate` → isolated subagent run → re-run `harness:validate` to consume the verdict through the circuit breaker.
+
+See [Executable verification](./executable-verification.md) for the full theme.
+
+---
+
+## harness:approve
+
+Approve a pending human gate in the self:loop (loop guardrails). Persists the decision (who, when) to `.aioson/plans/{slug}/gates/{id}.json` and resumes the loop.
+
+```bash
+aioson harness:approve . --slug=<feature> --gate=<gate-id>
+aioson harness:approve . --slug=checkout --gate=database_destructive_change-1
+```
+
+**Options:**
+- `--slug=<feature>` — **required**. Feature slug matching the harness contract.
+- `--gate=<id>` — **required**. Gate id shown in `harness:status` output.
+- `--by=<name>` — override the "decided by" field (defaults to `git config user.name`).
+
+**Idempotent:** re-approving an already-decided gate is a no-op with a warning.
+
+---
+
+## harness:reject
+
+Reject a pending human gate. Ends the current loop attempt with a summary. Requires `--reason`.
+
+```bash
+aioson harness:reject . --slug=<feature> --gate=<gate-id> --reason="needs revert"
+```
+
+**Options:**
+- `--slug`, `--gate` — same as `harness:approve`.
+- `--reason=<text>` — **required** on reject. Recorded in the gate decision file.
+
+---
+
+## harness:status
+
+Human-readable view of the current loop state for a feature.
+
+```bash
+aioson harness:status . --slug=<feature>
+aioson harness:status . --slug=checkout --json
+```
+
+**Shows:** circuit state (open/closed), current iteration / max, estimated token budget (used/ceiling), last-attempt checks (passed/failed), last failure signature, pending human gates, and recommended next action.
+
+**Options:**
+- `--slug=<feature>` — **required**.
+- `--json` — structured output.
+
+---
+
+## harness:retro
+
+Deterministically mine the failure trail of a feature and materialize a retrospective dossier at `.aioson/context/retro/{slug}.md`. LLM-free, network-free. Source files are never modified.
+
+```bash
+aioson harness:retro . --feature=<slug>
+aioson harness:retro . --last=<N>          # last N features by PASS date
+aioson harness:retro . --feature=checkout --json
+```
+
+**Options:**
+- `--feature=<slug>` — mine a specific feature (mutually exclusive with `--last`).
+- `--last=<N>` — mine the N most recently completed features.
+- `--json` — structured output; exit codes are propagated.
+- `--locale=<l>` — output locale (default: project `interaction_language`).
+
+**Exit codes:** 0 = success (including empty dossier); 1 = unexpected I/O error; 12 = input error (invalid slug, conflicting flags, feature not found).
+
+**Sources mined:** QA reports, correction plans, dossier FAIL→PASS cycles, execution events, attempt artifacts, failure signatures, devlogs.
+
+---
+
+## harness:preview
+
+Display a truncated, UTF-8-safe preview of an artifact file. Used in self:loop criteria-fail feedback to avoid dumping full file contents into the agent context.
+
+```bash
+aioson harness:preview <file>
+aioson harness:preview .aioson/context/retro/checkout.md
+```
+
+Read-only. Best-effort write for the preview artifact.
+
+---
+
+## spec:analyze
+
+The **content** sibling of `artifact:validate` (which checks chain **presence** — unchanged). Runs deterministic cross-artifact consistency checks before the execution gate. Persists `spec-analyze-{slug}.json`.
+
+```bash
+# Analyze cross-artifact consistency for a feature
+aioson spec:analyze . --feature=checkout
+
+# JSON output for gate scripting (errors → exit 1)
+aioson spec:analyze . --feature=checkout --json
+```
+
+**Options:**
+- `--feature=<slug>` — **required**. Feature slug.
+- `--json` — structured output; `error` findings flip `ok: false` (exit 1).
+
+**What it does:** runs five deterministic checks across the feature's artifacts:
+1. **REQ/AC ID traceability** — declared-but-unreferenced IDs = coverage-gap warning; referenced-but-undeclared IDs = orphan/drift warning (noise-guarded for prose plans).
+2. **Staleness** — an upstream artifact modified after a downstream one = warning (60s tolerance; the project-global `architecture.md` is excluded).
+3. **Readiness** — `blocked` = error; `ready_with_warnings` = info.
+4. **Harness-contract sanity** — schema errors = error; executable-coverage = info.
+5. **AC→contract linkage** = info.
+
+An `error` flips `ok: false` (exit 1 in `--json`). `@scope-check` runs `spec:analyze` in preflight: errors are blockers, warnings are pre-computed drift evidence. When the plan carries a `Wave` column, it also runs the `wave_file_overlap` check (same-wave phases sharing Primary files = warning; plans without a `Wave` column skip it).
+
+See [Executable verification](./executable-verification.md) for the full theme.
+
+---
+
+## forge:compile
+
+**Lane B.** Compile a MEDIUM feature's artifacts into `.aioson/plans/{slug}/forge-run.workflow.js` — an auditable, versionable Claude Code dynamic-workflow script that is committed alongside the spec. Opt-in entry point is the `@forge-run` agent.
+
+```bash
+# Compile the feature into a forge-run.workflow.js
+aioson forge:compile . --feature=checkout
+
+# JSON output (hard preflights may refuse compilation)
+aioson forge:compile . --feature=checkout --json
+```
+
+**Options:**
+- `--feature=<slug>` — **required**. Feature slug.
+- `--json` — structured output; refusals are reported with the owning agent named.
+
+**What it does:** the generated workflow mirrors the executable-verification roadmap:
+- one `parallel()` per **Wave** (file-disjoint dev agents; blocked-wave early stop),
+- a deterministic `harness:check` convergence loop bounded by the governor's `error_streak_limit` (sequential fixes — only waves prove disjointness) plus a token-budget guard,
+- a 3-lens adversarial review (correctness / completeness / regression-risk; majority survives; refute-by-default) for binary criteria **without** `verification`,
+- a fresh-context validator stage closing through `harness:validate` → `last-validator-output.json` → `apply-validation`.
+
+**Hard preflights** refuse compilation and name the owning agent: invalid/missing contract, zero executable criteria, plan without a `Wave` column, `spec:analyze` errors, and `wave_file_overlap` (a *warning* in `spec:analyze`, an **error** here). Generated code is deterministic by construction: pure-literal metadata, plain JS, no `Date.now`/`Math.random`/`new Date`, artifact text via `JSON.stringify` (injection-safe). It **never** runs `feature:close`. New module: `src/harness/plan-waves.js`.
+
+See [@forge-run](../4-agents/forge-run.md) and [Executable verification](./executable-verification.md).
+