ultimate-pi 0.17.0 → 0.18.0

package/.pi/harness/corpus/graphify-kb-updater.config.json

@@ -0,0 +1,159 @@
+{
+	"schema_version": "1.1.0",
+	"policy": "hybrid-allowlist-auto-promotion-with-conservative-staging",
+	"auto_promote_allowlist": true,
+	"source_taxonomy": {
+		"article": {
+			"category": "public_article_or_engineering_blog",
+			"risk_class": "low_to_medium",
+			"default_policy": "allowlist_auto_promote_when_approved"
+		},
+		"paper": {
+			"category": "research_paper_or_abstract_feed",
+			"risk_class": "medium",
+			"default_policy": "stage_until_rights_review"
+		},
+		"book": {
+			"category": "book_or_longform_local_file",
+			"risk_class": "high",
+			"default_policy": "manual_approval_required"
+		},
+		"transcript": {
+			"category": "youtube_or_audio_transcript",
+			"risk_class": "high",
+			"default_policy": "manual_approval_required"
+		},
+		"youtube": {
+			"category": "youtube_candidate_or_video_reference",
+			"risk_class": "high",
+			"default_policy": "stage_metadata_only_until_approved"
+		}
+	},
+	"competitor_taxonomy": {
+		"ai_coding_agents": {
+			"description": "Coding-agent products, CLIs, IDE agents, and model-native coding surfaces.",
+			"keywords": [
+				"claude code",
+				"cursor",
+				"codex",
+				"aider",
+				"copilot",
+				"windsurf",
+				"zed",
+				"replit",
+				"devin"
+			]
+		},
+		"agentic_harnesses": {
+			"description": "Harnesses, orchestration frameworks, eval loops, task runners, and review gates.",
+			"keywords": [
+				"harness",
+				"orchestration",
+				"agent bus",
+				"eval",
+				"review gate",
+				"multi-agent",
+				"workflow"
+			]
+		},
+		"context_engineering": {
+			"description": "Context retrieval, compaction, memory, skills, MCP, and codebase indexing.",
+			"keywords": [
+				"context engineering",
+				"mcp",
+				"memory",
+				"retrieval",
+				"compaction",
+				"skills",
+				"knowledge graph"
+			]
+		}
+	},
+	"allowlist": [
+		{
+			"domain": "openai.com",
+			"approved": true,
+			"approved_by": "repo-policy",
+			"approved_at": "2026-05-23",
+			"allowed_source_classes": ["article"]
+		},
+		{
+			"domain": "anthropic.com",
+			"approved": true,
+			"approved_by": "repo-policy",
+			"approved_at": "2026-05-23",
+			"allowed_source_classes": ["article"]
+		},
+		{
+			"domain": "github.blog",
+			"approved": true,
+			"approved_by": "repo-policy",
+			"approved_at": "2026-05-23",
+			"allowed_source_classes": ["article"]
+		},
+		{
+			"domain": "martinfowler.com",
+			"approved": true,
+			"approved_by": "repo-policy",
+			"approved_at": "2026-05-23",
+			"allowed_source_classes": ["article"]
+		},
+		{
+			"domain": "addyosmani.com",
+			"approved": true,
+			"approved_by": "repo-policy",
+			"approved_at": "2026-05-23",
+			"allowed_source_classes": ["article"]
+		},
+		{
+			"domain": "arxiv.org",
+			"approved": false,
+			"approved_by": "manual-review-required",
+			"approved_at": "manual-review-required",
+			"allowed_source_classes": ["paper"]
+		}
+	],
+	"article_queries": [
+		"agentic engineering harness engineering AI coding agents",
+		"AI coding harness evaluation orchestration context engineering"
+	],
+	"paper_feeds": [
+		{
+			"title": "arXiv software engineering agents search feed",
+			"url": "https://arxiv.org/search/cs?query=agentic+software+engineering&searchtype=all",
+			"rights_access": {
+				"license": "source-specific",
+				"access": "public abstract/feed only; paper text requires review",
+				"approved_by": "manual-review-required",
+				"approved_at": "manual-review-required"
+			},
+			"provenance": {
+				"origin": "curated_search_feed",
+				"locator": "https://arxiv.org/search/cs?query=agentic+software+engineering&searchtype=all",
+				"notes": "Feed metadata only; paper body requires approval."
+			}
+		}
+	],
+	"local_books": [
+		{
+			"path": "data/books",
+			"max_files": 75
+		}
+	],
+	"local_transcripts": [
+		{
+			"path": "data/youtube-transcripts",
+			"max_files": 100
+		}
+	],
+	"youtube_candidates": [
+		{
+			"title": "Review queue placeholder for agentic engineering YouTube talks",
+			"url": "https://www.youtube.com/results?search_query=agentic+engineering+harness+engineering",
+			"rights_access": null,
+			"approved": false,
+			"competitor_labels": ["agentic_harnesses"]
+		}
+	],
+	"review_queue": []
+}

package/.pi/harness/corpus/systemd/graphify-kb-updater.env.template

@@ -0,0 +1,4 @@
+# Copy to ~/.config/ultimate-pi/graphify-kb-updater.env and edit paths.
+UP_ROOT=/home/USER/ai-projects/ultimate-pi
+NODE_ENV=production
+GRAPHIFY_KB_ARGS=--apply --refresh-graph --pilot-report --max-promotions 25

package/.pi/harness/corpus/systemd/graphify-kb-updater.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Ultimate Pi Graphify knowledge-base updater
+Documentation=file:%h/ai-projects/ultimate-pi/.pi/harness/docs/graphify-kb-updater-runbook.md
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+EnvironmentFile=%h/.config/ultimate-pi/graphify-kb-updater.env
+WorkingDirectory=${UP_ROOT}
+ExecStart=/usr/bin/flock -n %t/graphify-kb-updater.lock /usr/bin/timeout 45m /usr/bin/env node .pi/scripts/graphify-kb-updater.mjs ${GRAPHIFY_KB_ARGS}
+StandardOutput=append:%h/.local/state/ultimate-pi/graphify-kb-updater.log
+StandardError=append:%h/.local/state/ultimate-pi/graphify-kb-updater.err
+TimeoutStartSec=50m
+Nice=10
+IOSchedulingClass=best-effort
+IOSchedulingPriority=7

package/.pi/harness/corpus/systemd/graphify-kb-updater.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=Run Ultimate Pi Graphify knowledge-base updater daily on a bounded schedule
+
+[Timer]
+OnCalendar=*-*-* 08:30:00
+RandomizedDelaySec=30m
+Persistent=true
+Unit=graphify-kb-updater.service
+
+[Install]
+WantedBy=timers.target

package/.pi/harness/docs/adrs/0001-harness-constitution.md

@@ -13,7 +13,8 @@ ultimate-pi needs a stable governance model for agentic runs: plan-before-mutate
 2. Phases are `plan → execute → evaluate → adversary → merge` with policy-gate as the source of truth.
 3. Local JSONL under `.pi/harness/runs/` is the **source of truth** for run history; PostHog is for team dashboards.
 4. Context for harness paths uses **context-mode only** — never lean-ctx in harness skills or extensions.
-5. `@posthog/pi` remains the LLM analytics layer; harness domain events use `harness-telemetry.ts`.
+5. Context-mode execute tools (`ctx_execute`, `ctx_batch_execute`, `ctx_execute_file`) are subject to the same phase matrix as `bash`/`write` via policy-gate.
+6. `@posthog/pi` remains the LLM analytics layer; harness domain events use `harness-telemetry.ts`.
 
 ## Consequences
 

package/.pi/harness/docs/adrs/0006-sentrux-dual-layer.md

@@ -5,15 +5,16 @@
 
 ## Context
 
-Evaluator trust requires both programmatic gates (policy, budget, integrity) and external observation signals (Sentrux MCP).
+Evaluator trust requires both programmatic gates (policy, budget, integrity) and **measured structural actuals** from the Sentrux CLI (Pi sessions use CLI only — no Sentrux MCP in harness).
 
 ## Decision
 
 1. **Rules file:** `.sentrux/rules.toml` synced from manifest — see [ADR 0009](0009-sentrux-rules-lifecycle.md).
-2. **CLI gate:** `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` fails if `HARNESS_SENTRUX_REQUIRED=true` and no `harness-sentrux-signal` stub/file exists for the run (placeholder until MCP wired). Resolve `$UP_PKG` via [.pi/scripts/README.md](../../../scripts/README.md).
-3. **MCP layer (Q2+):** Evaluator sessions must record at least one Sentrux observation before `harness_eval_verdict` promotion when Sentrux is enabled.
-4. Observations flow through `observation-bus.ts` as `HarnessObservation` envelopes.
-5. PostHog event: `harness_sentrux_signal` with `signal_type` and `score` only — no secrets.
+2. **Run observation:** `/harness-run` writes `artifacts/sentrux-signal.yaml` and appends session custom entry `harness-sentrux-signal` after `sentrux check` + `sentrux gate` (baseline from `sentrux gate --save` before execute).
+3. **Verify gate:** `harness-verify.mjs` with `HARNESS_SENTRUX_REQUIRED=true` prefers `$HARNESS_RUN_DIR/artifacts/sentrux-signal.yaml`; falls back to `.pi/harness/evals/smoke/sentrux-stub.json` only when no run signal exists (CI smoke / pre-run verify).
+4. **Evaluator:** `harness/evaluator` in `benchmark` mode reads `sentrux-signal.yaml` and `benchmark-log.yaml` — metrics are inputs, not executor optimization targets.
+5. Observations flow through `observation-bus.ts` as `HarnessObservation` envelopes when wired.
+6. PostHog event: `harness_sentrux_signal` with `signal_type` and `score` only — no secrets.
 
 ## Consequences
 
@@ -23,7 +24,7 @@ Evaluator trust requires both programmatic gates (policy, budget, integrity) and
 
 ### Negative
 
-- Full MCP integration remains follow-up when Sentrux server is available.
+- Teams must run `/harness-run` (or write `sentrux-signal.yaml`) before promotion verify when stub fallback is insufficient.
 
 ## References
 

package/.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md

@@ -20,7 +20,10 @@ Sentrux enforces architecture via [`.sentrux/rules.toml`](https://sentrux.dev/do
    - On `agent_end` when harness phase is `plan` or `merge`
    - `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` fails if manifest hash ≠ last sync (`--check`)
 7. **Custom rules:** TOML outside the managed block is preserved on sync.
-8. **Skill:** `harness-sentrux-setup` documents bootstrap vs `--force`.
+8. **Skill:** `harness-sentrux-setup` documents bootstrap vs steward vs sync vs observation.
+9. **Intent evolution:** `harness/sentrux-steward` proposes JSON Merge Patches via `submit_sentrux_manifest_proposal` → `artifacts/sentrux-manifest-proposal.yaml`, with graphify-first evidence (`graphify-out/GRAPH_REPORT.md`, `graphify query` / `path` / `explain`). Chair applies manifest edits; never silent auto-merge.
+10. **Material changes:** `add_layer`, `add_boundary`, `split_layer` require `adr_required` + `ask_user` when `human_required`. `tune_constraint` may proceed with sentrux/graphify evidence only when chair agrees.
+11. **Observation vs intent:** `/harness-run` + `/harness-review` run CLI fitness functions; observation failures → replan/fix. Manifest changes → steward + ADR, not directory-tree guessing.
 
 ## Consequences
 
@@ -36,6 +39,8 @@ Sentrux enforces architecture via [`.sentrux/rules.toml`](https://sentrux.dev/do
 ## References
 
 - ADR 0006 (Sentrux dual layer)
+- `.pi/agents/harness/sentrux-steward.md`, `.pi/prompts/harness-sentrux-steward.md`
+- `.pi/harness/specs/sentrux-manifest-proposal.schema.json`, `sentrux-signal.schema.json`
 - `.pi/scripts/harness-sentrux-bootstrap.mjs`
 - `.pi/scripts/sentrux-rules-sync.mjs`
 - `.agents/skills/harness-sentrux-setup/SKILL.md`

package/.pi/harness/docs/adrs/0031-harness-run-context.md

@@ -17,7 +17,7 @@ Manual harness steps required copying `run_id` and `plan-packet.json` paths betw
 4. **Hook order:** `harness-run-context` `before_agent_start` allocates/reuses `run_id` before `trace-recorder` `agent_start`. Trace writes phase files `trace-<phase>.json` plus rollup `trace.json`.
 5. PostHog `harness_run_started` at most once per logical `run_id`.
 6. Short commands: `/harness-run`, `/harness-eval`, etc. without args; recovery via `/harness-run-status`, `/harness-use-run`.
-7. After execute, handoff recommends **`/harness-eval`** in the same session; review commands spawn isolated subagents (see ADR 0032). `active-run.json` still supports cross-session recovery when Pi was closed mid-run.
+7. After execute, handoff recommends **`/harness-eval`** in the same session; review commands spawn isolated subagents (see ADR 0032). `active-run.json` still supports cross-session recovery when Pi was closed mid-run. On a **new Pi session**, if disk has a non-stale active run but this session has no `harness-run-context` entry yet, show a one-time resume message and live-widget hint pointing at **`/harness-use-run <run-id>`** (no silent auto-bind).
 8. `hasApprovedPlanSignal` uses user-visible prompt only; execute requires `plan_ready` from disk validation **and** recorded `ask_user` approval (or `harness-plan-approval` entry).
 9. **Plan-phase writes:** policy-gate allows `write`/`edit` only on canonical `.pi/harness/runs/<run_id>/plan-packet.json` after approval; all other paths stay blocked until execute phase.
 10. **Approval-before-persist:** agents present the full plan, call `ask_user` (Approve / Request changes / Cancel), then write the packet. `--quick` narrows planning only — it does not skip approval.

package/.pi/harness/docs/adrs/0032-harness-command-orchestration.md

@@ -28,9 +28,16 @@ Harness slash prompts duplicated logic already defined in `harness/*` agents. Th
 - Orchestrator must parse subagent JSON reliably and pass complete spawn context.
 - Scope enforcement remains prompt-driven for executor until optional path allowlist.
 
+## Amendment (2026-05-23)
+
+- **`/harness-review`** is the master **post-run** orchestrator (benchmark + verdict + adversary). See ADR 0039.
+- **`/harness-eval`** and **`/harness-critic`** are thin deprecated aliases; do not implement separate pipelines.
+- Post-run artifacts use **`submit_*`** + **`harness_artifact_ready`** per ADR 0037; parent does not parse subprocess JSON into `artifacts/eval-verdict.yaml`.
+
 ## References
 
 - `.pi/prompts/harness-*.md`
+- ADR 0039 — post-run review gate
 - `.pi/agents/harness/*.md`
 - `vendor/pi-subagents/src/subagents.ts`, `.pi/extensions/lib/harness-subagents-bridge.ts`
 - `.pi/extensions/lib/harness-subagent-policy.ts`

package/.pi/harness/docs/adrs/0034-darwin-plan-research-pipeline.md

@@ -9,13 +9,13 @@
 
 ## Decision
 
-1. **Always-on research chain** after parallel scouts:
+1. **Always-on research chain** after planning context (ADR 0041; **sequential** — WBS before approach):
    - `harness/planning/decompose` — DeepMind-style problem decomposition (`PlanDecompositionBrief`)
-   - `harness/planning/hypothesis` — DARWIN hypothesis generation (`PlanHypothesisBrief`)
+   - `harness/planning/hypothesis` — DARWIN hypothesis generation (`PlanHypothesisBrief`); spawned only after `artifacts/decomposition.yaml` exists
 2. **Parent maps hypothesis → PlanPacket** — `plan-packet.schema.json` unchanged; execution gating stable.
 3. **Review Gate (ADR 0035):** outcome-based debate with `hypothesis-validator` on R1 (blind — task + hypothesis only). Retired `hypothesis-eval` as a separate pre-approval agent.
 4. **`approve_plan` optional `research_brief`** — rendered in `plan-review.md`; not written to `plan-packet.json`.
-5. **`--quick`** still skips semantic scout only; never skips decompose/hypothesis.
+5. **`--quick`** still skips semantic coverage in planning context only; never skips decompose/hypothesis.
 
 ## Consequences
 

package/.pi/harness/docs/adrs/0036-implementation-research-and-selective-debate.md

@@ -13,14 +13,14 @@ ADR 0034–0035 established Darwin research and outcome-based Review Gate debate
 
 ## Decision
 
-1. **Phase 3.5** — After decompose/hypothesis, parent spawns in parallel:
-   - `harness/planning/implementation-researcher` → `PlanImplementationResearchBrief` → `artifacts/implementation-research.yaml`
-   - `harness/planning/stack-researcher` → `PlanStackBrief` → `artifacts/stack.yaml`
+1. **Phase 3.5** — After decompose/hypothesis, parent produces (subprocess optional):
+   - `artifacts/implementation-research.yaml` (`PlanImplementationResearchBrief`) — inline and/or `implementation-researcher`
+   - `artifacts/stack.yaml` (`PlanStackBrief`) — inline and/or `stack-researcher`
 2. Research stays **outside** debate; debate agents cite artifacts, no web tools.
-3. **Phase 4d** — `harness_plan_debate_eligibility` (pre-debate only) selects `full | standard | light` and `required_focuses`; persisted on messenger + bus at `harness_debate_open`.
+3. **Phase 4d** — `harness_plan_debate_eligibility` (pre-debate only) selects `full | standard | light | fast` and `required_focuses`; persisted on messenger + bus at `harness_debate_open`.
 4. **Light profile** — `spec` + `quality` only, `min_focus_rounds=2`, reduced global cap; gate uses stored `required_focuses` (not hardcoded four).
 5. **Sprint auditor** — shared `lanesForRound(roundIndex, focus)` spawns sprint lane when `focus === quality` OR `roundIndex >= 4`.
-6. **`--quick`** still skips semantic scout only; never skips Phase 3.5 or debate.
+6. **`--quick`** still skips semantic coverage in planning context only; never skips Phase 3.5 artifacts (med/high risk) or debate.
 
 ## Profiles
 
@@ -29,6 +29,9 @@ ADR 0034–0035 established Darwin research and outcome-based Review Gate debate
 | full | high risk, material fork, open implementation questions, DAG manual patch, many tensions | all four | 4 |
 | standard | default (ambiguous → standard) | all four | 4 |
 | light | low risk, no fork, high-confidence implementation + clear stack primary | spec, quality | 2 |
+| fast | med/low, clear stack, no open questions | spec, quality | 1 (consolidated `review_gate_mode`) |
+
+See [practice-map.md](../practice-map.md) and [ADR 0040](0040-practice-grounded-orchestration.md).
 
 ## Consequences
 

package/.pi/harness/docs/adrs/0039-harness-post-run-review-gate.md

@@ -0,0 +1,47 @@
+# ADR 0039: Post-run review gate (`/harness-review`)
+
+- **Status:** Accepted
+- **Date:** 2026-05-23
+
+## Context
+
+Post-run flow split across `/harness-eval`, a thin `/harness-review` (verdict-only), and `/harness-critic`. Cross-session resume left `owner_pi_session_id` on the plan session, blocking parent orchestration. Status routing used session handoff strings instead of canonical `artifacts/eval-verdict.yaml`. Prompts still instructed parent JSON parsing and `write` to eval artifacts (ADR 0037 violation).
+
+## Decision
+
+1. **`/harness-review`** is the **master post-run orchestrator** (plan-grade): deterministic gates → benchmark evaluator → policy verdict → adversary (parallel with verdict when precheck allows) → optional tie-breaker → **`artifacts/review-outcome.yaml`**. Always complete review before replan; blocked execute routes here, not `/harness-plan`. `--quick` skips adversary and tie-breaker. Steer attempts 2+ may use **lite** review (benchmark + verdict; skip adversary unless prior `block_merge`).
+2. **`/harness-eval`** and **`/harness-critic`** are **deprecated aliases** that forward to `/harness-review` in the same turn.
+3. **Ownership:** `/harness-use-run --claim` and auto-claim on post-run commands (unless `--readonly`) set `owner_pi_session_id` and `pi_session_id` to the current Pi session.
+4. **Disk truth:** `resolveCompletionStatuses` reads `artifacts/eval-verdict.yaml` and `artifacts/adversary-report.yaml` for `nextStepAfterOutcome` and widget next steps. Persisted `next_recommended_command` on `run-context.yaml` wins when set.
+5. **Artifacts:** Evaluator uses `submit_eval_verdict`; adversary uses `submit_adversary_report`. Parent gates with `harness_artifact_ready` only. Parent may write `artifacts/benchmark-log.yaml` via `write_harness_yaml`; parent must not write eval/adversary verdict YAML.
+6. **Rollback:** `submit_executor_handoff` mirrors `rollback_refs` to `artifacts/executor-rollback.yaml` (no `artifacts/*.json`).
+
+## Phases (orchestrator)
+
+| Phase | Actor | Output |
+|-------|--------|--------|
+| 0 | Parent | Parse args; claim run; require execute complete |
+| 1 | Parent | `harness-verify.mjs`; optional `benchmark-log.yaml` |
+| 2 | `harness/evaluator` benchmark | `eval-verdict.yaml` |
+| 2b | Parent | Record benchmark fail in review-outcome; continue to verdict unless harness-verify hard-stops |
+| 3 | `harness/evaluator` verdict | `eval-verdict.yaml` (policy) |
+| 4 | `harness/adversary` | `adversary-report.yaml` |
+| 5 | `harness/tie-breaker` | conditional |
+
+## Consequences
+
+### Positive
+
+- One command after `/harness-run`; same-session and cross-session resume with `--claim`.
+- Widget and run context align with on-disk verdicts.
+
+### Negative
+
+- Full post-run pipeline latency is sequential in one command (acceptable vs broken multi-session flow).
+
+## References
+
+- ADR 0032 (amended), ADR 0037
+- `.pi/prompts/harness-review.md`
+- `.pi/lib/harness-run-context.ts` (`claimRunOwnership`, `resolveCompletionStatuses`)
+- `.agents/skills/harness-review/SKILL.md`

package/.pi/harness/docs/adrs/0040-practice-grounded-orchestration.md

@@ -0,0 +1,40 @@
+# ADR 0040: Practice-grounded orchestration and team topology
+
+- **Status:** Accepted
+- **Date:** 2026-05-23
+
+## Context
+
+Harness commands (`/harness-plan`, `/harness-run`, `/harness-review`) already followed structured planning, generator–evaluator separation, and outcome-based debate (ADRs 0032–0039). The graphify corpus (PMBOK process groups, Team Topologies, Code Complete inspection, harness engineering, Lean spikes) was not surfaced in prompts—orchestrators could spawn redundant parallel thinkers (e.g. decompose ∥ hypothesis) and debate lanes without clear RACI.
+
+## Decision
+
+1. **Practice map** — [practice-map.md](../practice-map.md) is the source of truth: phase → practice → agent/script → spawn topology, debate RACI, anti-patterns.
+2. **Planning sequence** — After planning context (ADR 0041), **decompose then hypothesis** (sequential invariant). Hypothesis requires `artifacts/decomposition.yaml` (amends ADR 0034). For `low`/`med` risk, a single **plan-synthesizer** spawn may produce decomposition, hypothesis, and `execution_plan` in one pass, but those artifacts must still land on disk before blind validation (ADR 0042)—sequential **invariant**, not necessarily three parent spawn batches.
+3. **Reconnaissance dedup** — `decompose` must not run `graphify query` when `artifacts/planning-context.yaml` has `coverage.architecture.status: ok` (legacy: `scout-graphify.yaml` with `status: ok`).
+4. **Team topology rules** — Documented in practice-map and orchestration skills:
+   - Parallel only for independent merges (implementation ∥ stack; optional legacy scouts ≤3).
+   - Max 2 research lanes, 1 optional `planning-context` subagent, 1 executor, 1 debate agent per `subagent` batch.
+   - Debate: parent is chair; one agent per batch; Fagan-style roles (inspector, red team, DoD auditor, blind verifier, recorder).
+5. **Command prompts** — Name the proven practice per phase; link practice-map.
+6. **Profiles** — `fast` consolidated Review Gate documented alongside `light` threaded gate (ADR 0036 amended).
+
+## Consequences
+
+### Positive
+
+- Every harness phase traceable to corpus-backed practice.
+- Fewer detached hypotheses and duplicate graphify work (strengthened by ADR 0041 planning-context artifact).
+- Clearer debate roster; smaller teams on low-risk plans via `fast`/`light`.
+
+### Negative
+
+- Slightly longer plan phase wall-clock (sequential decompose → hypothesis).
+- More documentation for agents to reference.
+
+## References
+
+- [practice-map.md](../practice-map.md)
+- ADR 0034, ADR 0036, ADR 0039
+- `.pi/prompts/harness-plan.md`, `.pi/prompts/harness-run.md`, `.pi/prompts/harness-review.md`
+- `graphify-out/GRAPH_REPORT.md` — Planning / Executing / Monitoring communities, Team Topologies, Harness Engineering

package/.pi/harness/docs/adrs/0041-intelligent-planning-reconnaissance.md

@@ -0,0 +1,39 @@
+# ADR 0041: Intelligent planning reconnaissance (tools over tool-scouts)
+
+- **Status:** Accepted
+- **Date:** 2026-05-23
+
+## Context
+
+ADR 0033 and 0040 mandated three parallel planning scouts (`scout-graphify`, `scout-structure`, `scout-semantic`), each bound to one tool family. That enforced coverage but constrained orchestrator intelligence: the parent always paid for three subprocesses even when one tool pass or a short graphify query sufficed.
+
+The graphify corpus (Superpowers: *Rigid Where It Matters, Flexible Where It Doesn't*; context engineering: *Context > Model Intelligence*) supports hard gates on **artifacts and phase order**, not on **how many subprocesses** gather context.
+
+## Decision
+
+1. **Phase 1 default** — Parent compiles `artifacts/planning-context.yaml` using repo tools (`graphify`, `sg`, `ccc`, reads) per task need. No mandatory scout subprocess batch.
+2. **Artifact contract** — `plan-planning-context.schema.json` requires `coverage.architecture` and `coverage.structure` at `ok` or `partial`; `coverage.semantic` may be `skipped` when `--quick`.
+3. **Optional subprocess** — At most one `harness/planning/planning-context` subagent when isolation warrants; `submit_planning_context` writes the canonical artifact.
+4. **Legacy compat (one release)** — `scout-*.yaml` trio still satisfies approval readiness with deprecation warning; `decompose` dedup reads `planning-context` first.
+5. **Phase 3.5** — Requires `implementation-research.yaml` and `stack.yaml` for med/high risk; subprocess researchers optional (parent may spike inline).
+6. **Spawn topology** — Remove default parallel scout batch rules; keep decompose∥hypothesis and debate sequential laws.
+
+## Consequences
+
+### Positive
+
+- Orchestrator chooses tools and depth by task; fewer ceremonial subprocesses.
+- Single shared artifact reduces merge friction and redundant graphify in decompose.
+- Hard gates (DAG, debate, approval) unchanged.
+
+### Negative
+
+- Parent context window bears more reconnaissance load unless `planning-context` subagent is used.
+- Legacy scout agents remain on disk until removal after deprecation window.
+
+## References
+
+- [practice-map.md](../practice-map.md)
+- ADR 0033, ADR 0040
+- `.pi/prompts/harness-plan.md`
+- `plan-planning-context.schema.json`

package/.pi/harness/docs/adrs/0042-agent-native-orchestration.md

@@ -0,0 +1,35 @@
+# ADR 0042: Agent-native orchestration
+
+- **Status:** Accepted
+- **Date:** 2026-05-23
+
+## Context
+
+Harness commands inherited human PM rituals: serial debate “meetings,” ticket-granularity WBS, and tool calls that re-embed full plan packets in model context. Agents optimize for context window, spawn cost, and verifiable artifacts—not calendar boundaries or social coordination (see [practice-map.md](../practice-map.md)).
+
+## Decision
+
+1. **Agent translation column** — practice-map documents human practice → agent equivalent (scheduler + gates, lake-first plans, path-first tools, steer loop).
+2. **Boiling lakes** — Fewer `work_items` with richer specs and `context_bundle_path`; `executor_strategy` on PlanPacket (`single_pass` | `per_lake` | `per_work_item`).
+3. **Plan-verify probes** — For `fast`/`standard` profiles, parallel inspector + adversary probes replace serial “one role per batch” debate where gate supports `parallel_probes` (ADR 0036 extended).
+4. **Plan synthesizer** — For `low`/`med` risk, one `harness/planning/plan-synthesizer` pass may replace separate author spawn; **decomposition + hypothesis artifacts still required** on disk for blind validation (ADR 0040 invariant).
+5. **Path-first tools** — See ADR 0043; disk is source of truth for approval and submit pipelines.
+6. **Steer loop** — See ADR 0044; always complete post-run review; repair vs plan revise routing.
+
+## Consequences
+
+### Positive
+
+- Lower plan/review wall-clock and token use.
+- Plans sized for agent throughput, not sprint ticket count.
+
+### Negative
+
+- More ADRs and schema fields for agents to learn.
+- Migration period: optional fat tool args remain one release.
+
+## References
+
+- [practice-map.md](../practice-map.md)
+- ADR 0040, 0041, 0043, 0044
+- `.cursor/plans/agent-native_harness_workflows_1d353489.plan.md` (design source)

package/.pi/harness/docs/adrs/0043-path-first-harness-tools.md

@@ -0,0 +1,38 @@
+# ADR 0043: Path-first harness tool contracts
+
+- **Status:** Accepted
+- **Date:** 2026-05-23
+
+## Context
+
+`approve_plan`, `create_plan`, and `submit_*` often pass full YAML/JSON documents in tool arguments when the same bytes already exist under `.pi/harness/runs/<run_id>/`. That duplicates tokens and trains models to carry large structs in chat history.
+
+## Decision
+
+1. **`approve_plan`** — Primary API: `approve_plan({ human_summary?: string })`. Extension loads `plan_packet` from `runCtx.plan_packet_path` and `research-brief.yaml` from the run dir. Optional `plan_packet` / `research_brief` deprecated for one release.
+2. **`create_plan`** — Primary API: `create_plan()` or `create_plan({ plan_packet_path?: string })`. Verifies approval marker and optional content hash from approve time.
+3. **`submit_*`** — Accept `source_path` under the active run; read, validate, promote to canonical path. `document` remains optional (deprecated).
+4. **`merge_harness_yaml`** — Parent merges patches from artifact paths without pasting bodies into tool args.
+5. **Tool results** — Return `{ path, sha256, status }` (and ids where relevant), not full documents.
+
+## Safety
+
+- Draft/canonical packet must exist on disk before approve.
+- Re-`approve_plan` required when `execution_plan` or `acceptance_checks` change after a `plan_gap` revise (hash gate).
+
+## Consequences
+
+### Positive
+
+- Approval turns stay small in session history.
+- Subagents write once to disk; submit is O(path) tokens.
+
+### Negative
+
+- Agents must write drafts before approve/submit (explicit discipline).
+
+## References
+
+- `.pi/extensions/harness-plan-approval.ts`
+- `.pi/extensions/lib/harness-subagent-submit-pipeline.ts`
+- ADR 0042, 0044

package/.pi/harness/docs/adrs/0044-harness-steer-loop.md

@@ -0,0 +1,36 @@
+# ADR 0044: Harness steer loop (post-run repair)
+
+- **Status:** Accepted
+- **Date:** 2026-05-23
+
+## Context
+
+After `/harness-run`, failed benchmarks or blocked execution previously routed users to `/harness-plan "<new task>"` even when the approved plan was still valid—high friction and duplicate planning context.
+
+## Decision
+
+1. **Always review** — `/harness-run` ends with `next_command: /harness-review` (including `blocked` / partial work). Remove benchmark fail-fast skip of verdict/adversary (ADR 0039 amended).
+2. **Review artifacts** — Parent writes `artifacts/review-outcome.yaml` and `artifacts/repair-brief.yaml` (path pointers, not pasted bodies).
+3. **Remediation routing** — `review-outcome.remediation_class`: `implementation_gap` → `/harness-steer`; `plan_gap` → `/harness-plan` revise with `repair_brief_path`; `pass` → policy status. **Review outcome wins** over executor `scope_drift` when they disagree; tie → `plan_gap`.
+4. **`/harness-steer`** — Thin orchestrator: read briefs, set policy **phase `execute`**, spawn `harness/executor` with `mode: repair`, then `/harness-review` again.
+5. **Caps** — `HARNESS_STEER_MAX_ATTEMPTS` (default 3). **Tiered review:** full review on initial run + steer 1; steers 2+ use lite (benchmark + verdict) unless prior `block_merge` or user forces full.
+6. **Sentrux** — Refresh baseline or compare new violations only after steer mutations (avoid false degraded on every attempt).
+7. **Evaluate-phase writes** — Orchestrator may write review/steer YAML under run `artifacts/` in `evaluate`/`adversary` phase (allowlisted files).
+
+## Consequences
+
+### Positive
+
+- One `approve_plan`; many repair cycles without re-typing tasks.
+- `harness-auto` can loop until pass or cap.
+
+### Negative
+
+- Higher review cost on failed runs (mitigated by tiered adversary).
+
+## References
+
+- `.pi/prompts/harness-steer.md`
+- `.pi/harness/specs/review-outcome.schema.json`, `repair-brief.schema.json`
+- `nextStepAfterOutcome` in `.pi/lib/harness-run-context.ts`
+- ADR 0039 (amended), 0043

package/.pi/harness/docs/adrs/README.md

@@ -24,6 +24,16 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0036](0036-implementation-research-and-selective-debate.md) | Implementation research and selective debate | Accepted |
 | [0037](0037-subagent-submit-tools.md) | Subagent submit tools (subprocess extension) | Accepted |
 | [0038](0038-budget-telemetry-only.md) | Budget caps telemetry-only by default | Accepted |
+| [0039](0039-harness-post-run-review-gate.md) | `/harness-review` master post-run gate | Accepted |
+| [0040](0040-practice-grounded-orchestration.md) | Practice-grounded orchestration & team topology | Accepted |
+| [0041](0041-intelligent-planning-reconnaissance.md) | Intelligent planning reconnaissance (tools over tool-scouts) | Accepted |
+| [0042](0042-agent-native-orchestration.md) | Agent-native orchestration (lakes, plan-verify probes, synthesizer) | Accepted |
+| [0043](0043-path-first-harness-tools.md) | Path-first harness tool contracts | Accepted |
+| [0044](0044-harness-steer-loop.md) | Post-run steer loop (repair vs plan revise) | Accepted |
+
+## Practice map
+
+Phase-to-practice mapping for slash commands: [practice-map.md](../practice-map.md).
 
 ## Template