ultimate-pi 0.17.0 → 0.18.1

package/.pi/harness/docs/practice-map.md

@@ -0,0 +1,110 @@
+# Harness practice map
+
+Source of truth linking harness phases to proven practices (graphify corpus), agents/scripts, spawn topology, and **agent translation** (ADR 0042). Orchestrators and agents should cite this doc when unsure why a lane exists.
+
+See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchestration.md), [ADR 0041](adrs/0041-intelligent-planning-reconnaissance.md), [ADR 0042](adrs/0042-agent-native-orchestration.md), [ADR 0043](adrs/0043-path-first-harness-tools.md), [ADR 0044](adrs/0044-harness-steer-loop.md), [`raw/modules/structured-planning.md`](../../../raw/modules/structured-planning.md).
+
+## Agent translation (human practice → agent design)
+
+| Human practice | Agent translation |
+|----------------|-------------------|
+| Meeting / chair | Parent as **scheduler + gate checker** only |
+| Fagan inspection rounds | **Schema-bound probes** + merge (`parallel_probes` profile) |
+| Two-pizza cap per batch | **Token/spawn budget** per phase (`harness-spawn-budget.ts`) |
+| RACI roles | **Disjoint prompt contexts**, not serial speakers |
+| WBS decomposition | **Lake-first `execution_plan`** (few outcomes, bundled context) |
+| Sprint / story points | **`executor_strategy` + lake `done_criteria`** |
+| Critical path | **`critical_path_lake_ids`** |
+| Replan on every failure | **Steer loop** (`implementation_gap`) vs **plan revise** (`plan_gap`) |
+| Tool payloads in chat | **Path-first** approve/submit/merge (ADR 0043) |
+
+## Team management rules (all `/harness-*` orchestrators)
+
+1. **Parallelism law** — Parallel `subagent` `tasks` only when outputs are independent inputs to a later merge (implementation ∥ stack research; inspector ∥ adversary in `parallel_probes`). Never parallelize decompose ∥ hypothesis.
+2. **Two-pizza cap per batch** — Max 2 research lanes, max 1 optional `planning-context` subagent, max 1 executor, max 1 debate lane agent per `subagent` call (plan-verify may use 2 probes + integrator in separate batches).
+3. **No redundant thinkers** — If artifact X exists, downstream agents read it; they do not re-derive (e.g. decompose after `planning-context.yaml`).
+4. **Sequential dependency chain** — planning context → problem framing / decompose → hypothesis → research → synthesis/author → DAG → plan-verify → approve → execute → review → (steer)* → policy.
+5. **Plan-verify (agent-native)** — For `fast`/`standard`, parallel probes then integrator; parent is chair, not participant. Threaded debate remains for `full` until parity.
+6. **Tool intelligence** — Parent chooses graphify, sg, ccc; subprocesses optional. **Path-first:** disk is source of truth; tool args are pointers (ADR 0043).
+
+## `/harness-plan` — Planning Process Group
+
+| Phase | Practice | Agent translation | Actor | Spawn |
+|-------|----------|---------------------|-------|-------|
+| 0 | Tooling / fast feedback | Pre-index once | Parent + `ccc` | Automatic |
+| 1 | Reconnaissance before WBS | **ContextPack** on disk | Parent tools or optional `planning-context` | No default subprocess |
+| 2a | Problem framing / lakes | Lake outcomes, not ticket tree | `decompose` or synthesizer section | Sequential after context gate |
+| 2b | Hypothesis-driven approach | Falsifiable claim grounded in framing | `hypothesis` or synthesizer | After `artifacts/decomposition.yaml` |
+| 3.5 | Spike / external research | Paths in research brief | Researchers optional | Artifacts required |
+| 4 | Fork resolution (batched) | One `ask_user` gate | Parent | After 3.5 |
+| 4b | Lake-first execution plan | `executor_strategy`, context bundles | `plan-synthesizer` (low/med) or `execution-plan-author` (high) | Single agent |
+| 4c | Deterministic quality gate | Script, not LLM | `validate-plan-dag.mjs` | Parent; hard stop |
+| 4d | Tailor process to risk | Probe depth, not meeting count | `harness_plan_debate_eligibility` | Pre plan-verify |
+| 4e | Architectural intent | Fitness-function spec | `harness/sentrux-steward` optional | When structural risk |
+| 5 | Plan-verify (Review Gate) | Parallel probes + integrator | Debate cast / probes | `parallel_probes` or threaded |
+| 6 | Baseline + approve | Path-only `approve_plan` | Parent | `approve_plan`, `create_plan` |
+
+### Review Gate — debate RACI (threaded / full profile)
+
+| Agent | Inspection role | Practice | When |
+|-------|-----------------|----------|------|
+| `hypothesis-validator` | Blind verifier | Independent verification (ADR 0034) | Round 1 / fast path |
+| `plan-evaluator` | Inspector | Neutral checklist | Every required focus |
+| `plan-adversary` | Red team | Adversarial review | Every required focus |
+| `sprint-contract-auditor` | DoD auditor | Sprint contract | `quality` focus |
+| `review-integrator` | Recorder | Single round artifact | End of round |
+| Parent | Chair | Gates only | Always |
+
+### Plan-verify profiles
+
+| Profile | When | Team shape |
+|---------|------|------------|
+| `full` | High risk, material fork | Threaded: all four focuses |
+| `standard` | Default med | `parallel_probes`: inspector ∥ adversary → integrator |
+| `light` | Low risk | Threaded: `spec` + `quality` |
+| `fast` | Med/low, clear stack | Consolidated verify + blind hypothesis-validator |
+
+## `/harness-run` — Executing Process Group
+
+| Step | Practice | Agent translation | Actor |
+|------|----------|-------------------|-------|
+| Gate | Change control | `plan_ready` required | Parent |
+| Pre-work | Fitness baseline | `sentrux gate --save` | Parent |
+| Work | Single implementer | `executor_strategy` | `harness/running/executor` |
+| Post-work | Observation | `sentrux check` / signal artifact | Parent |
+| Handoff | Generator–evaluator | `submit_executor_handoff` | Executor |
+| Next | Always verify | **`/harness-review`** (not replan on blocked) | Parent routing |
+
+## `/harness-review` — Monitoring and Controlling
+
+| Phase | Practice | Agent translation | Actor |
+|-------|----------|-------------------|-------|
+| 1 | Automated QC + fitness | Deterministic first | Parent scripts |
+| 2 | Measure vs plan | Benchmark on disk | `evaluator` benchmark |
+| 3 | Policy audit | Verdict (no fail-fast skip) | `evaluator` verdict |
+| 4 | Red team | Tiered: full attempt 1, lite 2+ steer | `adversary` |
+| 5 | Outcome + repair brief | Machine routing | Parent + `review-outcome.yaml`, `repair-brief.yaml` |
+| 6 | Steer gate | One `ask_user` | harness-decisions |
+| 7 | Steer / revise | `implementation_gap` → `/harness-steer`; `plan_gap` → plan revise | ADR 0044 |
+
+`--quick` = deterministic + benchmark + verdict (no adversary). Steer attempts 2+ default to lite review unless `block_merge`.
+
+## `/harness-steer` — Repair sub-cycle (ADR 0044)
+
+| Step | Practice | Actor |
+|------|----------|-------|
+| 0 | Read review + repair briefs | Parent |
+| 1 | Policy phase → `execute` | Parent |
+| 2 | Repair scope | `harness/running/executor` `mode: repair` |
+| 3 | Re-verify | `/harness-review` |
+
+## Anti-patterns
+
+- **Do not** spawn `decompose` and `hypothesis` in the same parallel `tasks` batch.
+- **Do not** run `graphify query` in `decompose` when planning-context coverage is ok (ADR 0041).
+- **Do not** parallelize threaded debate lanes in one batch (except `parallel_probes` inspector ∥ adversary per ADR 0042).
+- **Do not** let executor or parent self-certify.
+- **Do not** stop review on benchmark fail — complete verdict and route via steer (ADR 0044).
+- **Do not** tell user to run `/harness-plan "<new task>"` on test failure — use `/harness-steer` with `repair-brief.yaml`.
+- **Do not** re-`approve_plan` every steer attempt — only when packet changes.
+- **Do not** embed full plan packets in `approve_plan` / `submit_*` tool args (ADR 0043).

package/.pi/harness/env.harness.template

@@ -21,6 +21,8 @@ HARNESS_WEB_SEARCH_ENGINE=ddg_html
 
 # --- PostHog (optional) ---
 # Project key — required for harness_* telemetry when HARNESS_TELEMETRY_ENABLED=true
+# WSL2: ultimate-pi loads 00-posthog-network-bootstrap.ts (IPv4 fetch for *.posthog.com).
+# If flush still fails, set POSTHOG_ENABLED=false or fix outbound HTTPS to PostHog.
 # POSTHOG_API_KEY=
 # POSTHOG_HOST=https://us.i.posthog.com
 # POSTHOG_ENABLED=true
@@ -39,6 +41,6 @@ HARNESS_WEB_SEARCH_ENGINE=ddg_html
 # --- Wiki / Obsidian vault (optional) ---
 VAULT_WIKI_PATH=vault/wiki
 
-# --- Sentrux gate (optional) ---
-# Require Sentrux stub for harness-verify (see .pi/scripts/harness-verify.mjs)
-# HARNESS_SENTRUX_REQUIRED=true
+# --- Sentrux fitness functions ---
+# Require sentrux check + run signal (or CI stub) in harness-verify
+HARNESS_SENTRUX_REQUIRED=true

package/.pi/harness/evals/smoke/sentrux-stub.json

@@ -2,5 +2,5 @@
 	"schema_version": "1.0.0",
 	"signal_type": "stub",
 	"score": 0.5,
-	"note": "Placeholder until Sentrux MCP is wired. Satisfies HARNESS_SENTRUX_REQUIRED gate in harness:verify."
+	"note": "Fallback when HARNESS_RUN_DIR/artifacts/sentrux-signal.yaml is absent. Prefer run signal from /harness-run (ADR 0006)."
 }

package/.pi/harness/evals/smoke/smoke-harness-plan.mjs

@@ -26,13 +26,16 @@ async function scanFocusCoverage(fixtureRoot, requiredFocus) {
 	let last_round_index = 0;
 	const { readdir } = await import("node:fs/promises");
 	const files = (await readdir(art)).filter((f) =>
-		/^review-round(?:-r\d+|-consolidated)\.yaml$/i.test(f),
+		/^review-round(?:-r\d+|-consolidated|-parallel-probes)\.yaml$/i.test(f),
 	);
 	for (const name of files.sort()) {
 		const consolidated = /^review-round-consolidated\.yaml$/i.test(name);
+		const parallelProbes = /^review-round-parallel-probes\.yaml$/i.test(name);
 		const m = consolidated
 			? ["review-round-consolidated.yaml", "1"]
-			: /^review-round-r(\d+)\.yaml$/i.exec(name);
+			: parallelProbes
+				? ["review-round-parallel-probes.yaml", "1"]
+				: /^review-round-r(\d+)\.yaml$/i.exec(name);
 		if (!m) continue;
 		const roundIndex = consolidated ? 1 : Number(m[1]);
 		if (roundIndex > last_round_index) last_round_index = roundIndex;

package/.pi/harness/specs/README.md

@@ -13,7 +13,7 @@ This directory is the canonical contract surface for Phase 1 harness artifacts.
 
 These schemas define the minimum machine-readable contracts for:
 
-- planning (`PlanPacket`, `PlanDecompositionBrief`, `PlanHypothesisBrief`, `PlanHypothesisEval`, `PlanAdversaryBrief`)
+- planning (`PlanPacket`, `PlanPlanningContext`, `PlanDecompositionBrief`, `PlanHypothesisBrief`, `PlanHypothesisEval`, `PlanAdversaryBrief`, legacy `PlanScoutFindings`)
 - execution telemetry (`RunTrace`, `HarnessRunRecord`)
 - PostHog harness events (`HarnessPostHogEvent`)
 - observation bus (`HarnessObservation`)

package/.pi/harness/specs/harness-run-context.schema.json

@@ -75,6 +75,17 @@
 		},
 		"turn_override_run_id": {
 			"type": ["string", "null"]
+		},
+		"steer_approved": {
+			"type": "boolean"
+		},
+		"steer_attempt": {
+			"type": "integer",
+			"minimum": 0
+		},
+		"steer_max_attempts": {
+			"type": "integer",
+			"minimum": 1
 		}
 	}
 }

package/.pi/harness/specs/harness-spawn-context.schema.json

@@ -14,7 +14,7 @@
 		"agent": {
 			"type": "string",
 			"minLength": 1,
-			"description": "Target subagent id, e.g. harness/planning/scout-graphify"
+			"description": "Target subagent id, e.g. harness/running/executor"
 		},
 		"mode": {
 			"type": "string",
@@ -23,6 +23,7 @@
 				"revise",
 				"plan_review",
 				"execute",
+				"repair",
 				"benchmark",
 				"verdict",
 				"adversary",
@@ -61,6 +62,19 @@
 		"handoff_summary": {
 			"type": "string",
 			"description": "Prior phase bullet summary for chained spawns (harness-auto)"
+		},
+		"critical_path_work_item_ids": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 },
+			"description": "Limiting-step work item ids from execution_plan.schedule_metadata (execute phase)"
+		},
+		"repair_brief_path": {
+			"type": "string",
+			"description": "Path to repair-brief.yaml (steer / repair mode)"
+		},
+		"executor_strategy": {
+			"type": "string",
+			"enum": ["single_pass", "per_lake", "per_work_item"]
 		}
 	}
 }

package/.pi/harness/specs/plan-execution-plan.schema.json

@@ -36,9 +36,41 @@
 			"items": { "$ref": "#/$defs/risk" }
 		},
 		"schedule_metadata": { "$ref": "#/$defs/schedule_metadata" },
-		"dag_validation": { "$ref": "#/$defs/dag_validation" }
+		"dag_validation": { "$ref": "#/$defs/dag_validation" },
+		"lakes": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/lake" }
+		},
+		"executor_strategy": {
+			"type": "string",
+			"enum": ["single_pass", "per_lake", "per_work_item"]
+		},
+		"critical_path_lake_ids": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		}
 	},
 	"$defs": {
+		"lake": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["lake_id", "title", "outcome", "done_criteria"],
+			"properties": {
+				"lake_id": { "type": "string", "minLength": 1 },
+				"title": { "type": "string", "minLength": 1 },
+				"outcome": { "type": "string", "minLength": 1 },
+				"done_criteria": { "type": "string", "minLength": 1 },
+				"context_bundle_path": { "type": "string", "minLength": 1 },
+				"files": {
+					"type": "array",
+					"items": { "type": "string", "minLength": 1 }
+				},
+				"out_of_scope": {
+					"type": "array",
+					"items": { "type": "string", "minLength": 1 }
+				}
+			}
+		},
 		"phase": {
 			"type": "object",
 			"additionalProperties": false,
@@ -107,6 +139,12 @@
 					"type": "array",
 					"minItems": 1,
 					"items": { "type": "string", "minLength": 1 }
+				},
+				"lake_id": { "type": "string", "minLength": 1 },
+				"context_bundle_path": { "type": "string", "minLength": 1 },
+				"context_refs": {
+					"type": "array",
+					"items": { "type": "string", "minLength": 1 }
 				}
 			}
 		},

package/.pi/harness/specs/plan-packet.schema.json

@@ -94,6 +94,10 @@
 		},
 		"execution_plan": {
 			"$ref": "plan-execution-plan.schema.json"
+		},
+		"executor_strategy": {
+			"type": "string",
+			"enum": ["single_pass", "per_lake", "per_work_item"]
 		}
 	}
 }

package/.pi/harness/specs/plan-phase-status.schema.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-phase-status.schema.json",
+	"title": "PlanPhaseStatus",
+	"description": "Orchestrator-recorded plan phase outcome before baseline approval.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "plan_status"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"plan_status": {
+			"type": "string",
+			"enum": ["ready", "partial", "needs_clarification"]
+		},
+		"notes": { "type": "string" }
+	}
+}

package/.pi/harness/specs/plan-phase-waiver.schema.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-phase-waiver.schema.json",
+	"title": "PlanPhaseWaiver",
+	"description": "Explicit human waiver for partial scouts or plan-phase blockers before approve_plan.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "waived"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"waived": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["reason", "rationale"],
+				"properties": {
+					"reason": { "type": "string", "minLength": 1 },
+					"rationale": { "type": "string", "minLength": 1 }
+				}
+			}
+		}
+	}
+}

package/.pi/harness/specs/plan-planning-context.schema.json

@@ -0,0 +1,50 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-planning-context.schema.json",
+	"title": "PlanPlanningContext",
+	"type": "object",
+	"additionalProperties": true,
+	"required": ["schema_version", "status", "summary", "coverage"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"status": {
+			"type": "string",
+			"enum": ["ok", "partial", "failed", "error"]
+		},
+		"task_ref": { "type": "string" },
+		"summary": { "type": "string", "minLength": 1 },
+		"coverage": {
+			"type": "object",
+			"required": ["architecture", "structure"],
+			"properties": {
+				"architecture": { "$ref": "#/$defs/coverageLane" },
+				"structure": { "$ref": "#/$defs/coverageLane" },
+				"semantic": { "$ref": "#/$defs/coverageLane" }
+			},
+			"additionalProperties": true
+		},
+		"findings": { "type": "array" },
+		"key_paths": { "type": "array", "items": { "type": "string" } },
+		"evidence_refs": { "type": "array" },
+		"open_questions": { "type": "array" }
+	},
+	"$defs": {
+		"coverageLane": {
+			"type": "object",
+			"required": ["status"],
+			"properties": {
+				"status": {
+					"type": "string",
+					"enum": ["ok", "partial", "skipped", "failed", "error"]
+				},
+				"tools_used": {
+					"type": "array",
+					"items": { "type": "string" }
+				},
+				"summary": { "type": "string" },
+				"key_paths": { "type": "array", "items": { "type": "string" } }
+			},
+			"additionalProperties": true
+		}
+	}
+}

package/.pi/harness/specs/repair-brief.schema.json

@@ -0,0 +1,45 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/repair-brief.schema.json",
+	"title": "RepairBrief",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"run_id",
+		"steer_attempt",
+		"remediation_class",
+		"source_artifacts",
+		"fix_directives"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"run_id": { "type": "string", "minLength": 1 },
+		"steer_attempt": { "type": "integer", "minimum": 1 },
+		"remediation_class": {
+			"type": "string",
+			"enum": ["implementation_gap", "plan_gap", "rollback", "inconclusive"]
+		},
+		"source_artifacts": {
+			"type": "object",
+			"additionalProperties": { "type": "string" }
+		},
+		"failed_acceptance_check_ids": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"priority_lake_ids": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"fix_directives": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"constraints": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		}
+	}
+}

package/.pi/harness/specs/review-outcome.schema.json

@@ -0,0 +1,46 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/review-outcome.schema.json",
+	"title": "ReviewOutcome",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"run_id",
+		"status",
+		"remediation_class",
+		"recommended_next"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"run_id": { "type": "string", "minLength": 1 },
+		"status": {
+			"type": "string",
+			"enum": ["pass", "fail", "inconclusive"]
+		},
+		"remediation_class": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"implementation_gap",
+				"plan_gap",
+				"rollback",
+				"inconclusive"
+			]
+		},
+		"recommended_next": { "type": "string", "minLength": 1 },
+		"failed_acceptance_check_ids": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"steer_attempt": { "type": "integer", "minimum": 0 },
+		"review_tier": {
+			"type": "string",
+			"enum": ["full", "lite"]
+		},
+		"source_artifacts": {
+			"type": "object",
+			"additionalProperties": { "type": "string" }
+		}
+	}
+}

package/.pi/harness/specs/sentrux-manifest-proposal.schema.json

@@ -0,0 +1,80 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/sentrux-manifest-proposal.schema.json",
+	"title": "SentruxManifestProposal",
+	"description": "Graphify-grounded proposal to evolve architecture.manifest.json (intent layer). Chair applies after approval.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"change_class",
+		"summary",
+		"evidence",
+		"manifest_patch",
+		"adr_required",
+		"human_required"
+	],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"change_class": {
+			"type": "string",
+			"enum": [
+				"none",
+				"tune_constraint",
+				"add_boundary",
+				"add_layer",
+				"split_layer"
+			]
+		},
+		"summary": {
+			"type": "string",
+			"minLength": 1
+		},
+		"evidence": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["source", "ref", "summary"],
+				"properties": {
+					"source": {
+						"type": "string",
+						"enum": ["graphify", "sg", "sentrux", "plan", "manifest"]
+					},
+					"ref": {
+						"type": "string",
+						"minLength": 1
+					},
+					"summary": {
+						"type": "string",
+						"minLength": 1
+					}
+				}
+			}
+		},
+		"manifest_patch": {
+			"type": "object",
+			"description": "JSON Merge Patch (RFC 7396) ops against architecture.manifest.json",
+			"additionalProperties": true
+		},
+		"adr_required": {
+			"type": "boolean"
+		},
+		"adr_draft": {
+			"type": "string"
+		},
+		"human_required": {
+			"type": "boolean"
+		},
+		"open_questions": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	}
+}

package/.pi/harness/specs/sentrux-signal.schema.json

@@ -0,0 +1,43 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/sentrux-signal.schema.json",
+	"title": "SentruxSignal",
+	"description": "Per-run Sentrux CLI observation for evaluator and harness-verify promotion.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"run_id",
+		"check_pass",
+		"gate_status",
+		"recorded_at"
+	],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"run_id": {
+			"type": "string",
+			"minLength": 1
+		},
+		"check_pass": {
+			"type": "boolean"
+		},
+		"gate_status": {
+			"type": "string",
+			"enum": ["pass", "degraded", "skipped", "not_installed"]
+		},
+		"quality_signal_summary": {
+			"type": "string"
+		},
+		"recorded_at": {
+			"type": "string",
+			"format": "date-time"
+		},
+		"phase": {
+			"type": "string",
+			"enum": ["execute", "evaluate", "review"]
+		}
+	}
+}

package/.pi/harness/specs/steer-state.schema.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/steer-state.schema.json",
+	"title": "SteerState",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "run_id", "attempt", "max_attempts", "active"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"run_id": { "type": "string", "minLength": 1 },
+		"attempt": { "type": "integer", "minimum": 0 },
+		"max_attempts": { "type": "integer", "minimum": 1 },
+		"active": { "type": "boolean" },
+		"steer_approved": { "type": "boolean" },
+		"last_review_tier": {
+			"type": "string",
+			"enum": ["full", "lite"]
+		}
+	}
+}