ultimate-pi 0.14.0 → 0.16.0

package/.agents/skills/harness-debate-plan/SKILL.md

@@ -5,7 +5,7 @@ description: Plan-phase Review Gate debate — pi-messenger threads, lane YAML,
 
 # harness-debate-plan
 
-Use when running **Phase 5** of `/harness-plan` — four Review Gate rounds with **pi-messenger-style** turn-taking (claims → rebuttals → integrate), then bus submission.
+Use when running **Phase 5** of `/harness-plan` — outcome-based Review Gate with **within-round dialogue** (claims → rebuttals → clarifications → counters → integrate), then bus submission.
 
 ## Open
 
@@ -14,71 +14,51 @@ harness_debate_open({})
 ```
 
 - Debate id is always `plan-<run_id>` (tool normalizes wrong ids).
-- Creates `.pi/harness/runs/<run_id>/debate-messenger/` (`inbox/<Agent>/`, `threads/round-N/transcript.jsonl`).
-
-Budget profile **plan**: `max_rounds=4`, `round_token_cap=2000`, `debate_global_cap=12000`.
-
-## Per-round spawn order (P1 sequential lanes)
-
-1. Round-specific lane spawns (write lane YAML with `write_harness_yaml`)
-2. `plan-evaluator` → lane artifact + `harness_messenger_post` (claims)
-3. `harness_messenger_read_round` → spawn `plan-adversary` with transcript
-4. `plan-adversary` → lane artifact + `harness_messenger_post` (rebuttals with `in_reply_to`)
-5. R1: `hypothesis-validator` first (blind — no decomposition/PlanPacket in prompt)
-6. R4: `sprint-contract-auditor` required before integrator
-7. `review-integrator` → integrator draft + `harness_messenger_post` (`integrate`)
-8. `harness_debate_submit_round({ round_index, integrator_draft })` — **only** path for `review-round-r{N}.yaml`
-
-| Round | Extra lane artifacts |
-|-------|----------------------|
-| 1 | `hypothesis-validation-r1.yaml` |
-| 4 | `sprint-audit-r4.yaml` (required) |
-
-## Lane artifacts (auto-applied on subagent complete)
-
-When a debate lane subagent finishes, the harness **automatically** writes lane YAML and posts messenger messages (evaluator claims, adversary rebuttals). Look for `harness-debate-next-step` in the transcript.
-
-| Agent | Output path | Messenger |
-|-------|-------------|-----------|
-| hypothesis-validator | `artifacts/hypothesis-validation-r{N}.yaml` | — |
-| plan-evaluator | `artifacts/validation-turn-r{N}.yaml` | `claim` |
-| plan-adversary | `artifacts/adversary-brief-r{N}.yaml` | `rebuttal` |
-| sprint-contract-auditor | `artifacts/sprint-audit-r{N}.yaml` (R4) | optional |
-| review-integrator | *(integrator draft → `harness_debate_submit_round` only)* | `integrate` (on submit) |
-
-Fallback: `harness_debate_apply_lane({ lane, content, round_index? })` if auto-apply missed fenced YAML.
-
-Resume after stop: `harness_debate_round_status({ round_index: N })` then run the listed `next_tool`.
-
-## Messenger tools
-
-```typescript
-harness_messenger_post({
-  round_index: 1,
-  from: "PlanEvaluatorAgent",
-  kind: "claim",
-  body: "...",
-  claim_ids: ["c1", "c2"],
-  to: ["broadcast"],
-})
-harness_messenger_post({
-  round_index: 1,
-  from: "PlanAdversaryAgent",
-  kind: "rebuttal",
-  in_reply_to: ["c1"],
-  body: "...",
-})
-harness_messenger_read_round({ round_index: 1 }) // for next spawn prompt
-```
+- Creates `.pi/harness/runs/<run_id>/debate-messenger/`.
+
+Budget profile **plan**:
+
+| Field | Value |
+|-------|-------|
+| min_focus_rounds | 4 |
+| max_rounds | 12 |
+| max_exchanges_per_round | 3 |
+| round_token_cap | 8000 |
+| debate_global_cap | 80000 |
+
+## Focus coverage (not “exactly 4 rounds”)
+
+Call `harness_debate_focus_coverage` until all of `spec | wbs | schedule | quality` appear in submitted `review-round-r*.yaml` and last `review_gate_ready: true`.
 
-## Integrator + bus
+## Per-round spawn order (sequential only — no parallel debate subagents)
 
-`harness_debate_submit_round` validates messenger thread + integrator rules (`review_gate_ready` false when checks fail without `disputes[]`), writes `review-round-r{N}.yaml`, emits bus `kind: round`.
+1. R1: `hypothesis-validator` (blind) before evaluator.
+2. `plan-evaluator` → lane + messenger `claim`.
+3. `harness_messenger_read_round` → `plan-adversary` → `rebuttal`.
+4. Ping-pong while `unresolved_claim_ids` and `exchange_count < 3`:
+   - `harness_debate_advance_thread({ round_index })` for next spawn hint.
+   - Evaluator `clarification` / adversary `counter`.
+5. `sprint-contract-auditor` when focus is `quality` or round ≥ 4.
+6. `review-integrator` → `harness_debate_submit_round`.
 
-`StackResearchAgent` uses `artifacts/stack.yaml` claims — no spawn.
+Lane YAML + messenger messages **auto-apply** on subagent complete (`harness-debate-next-step`). Fallback: `harness_debate_apply_lane`.
+
+Resume: `harness_debate_round_status({ round_index: N })` → run listed `next_tool`.
+
+## Messenger kinds
+
+| kind | from | when |
+|------|------|------|
+| claim | PlanEvaluatorAgent | after evaluator lane |
+| rebuttal | PlanAdversaryAgent | in_reply_to claim ids |
+| clarification | PlanEvaluatorAgent | addresses open claims |
+| counter | PlanAdversaryAgent | final pass; concede or dispute |
+| integrate | ReviewIntegratorAgent | on submit_round |
 
 ## Close
 
-After round 4: `harness_debate_consensus`. `approve_plan` is **hard-gated** on lane files, messenger, 4 bus rounds, and consensus not `block`.
+`harness_debate_consensus` when focus coverage complete. `approve_plan` is **hard-gated** on lanes, messenger dialogue completeness, bus rounds, consensus not `block`.
 
 Do not `approve_plan` on `policy_decision: block`. On `human_required` → `ask_user` first.
+
+Rubrics: `.pi/prompts/planning-rubrics.md`.

package/.agents/skills/harness-governor/SKILL.md

@@ -28,6 +28,17 @@ When refining plans from noisy requirements:
 3. When gates return `human_required` or promotion is blocked, the orchestrator calls `ask_user` — do not guess scope.
 4. Reference graphify wiki or `graphify query` for architecture constraints before execute.
 
+## Budgets (ADR 0038)
+
+- Default: **`HARNESS_BUDGET_ENFORCE` off** — token/debate caps are telemetry-only (`harness-budget-telemetry`, `harness-budget-soft-limit`). They do **not** block phases or debate lanes.
+- Do **not** skip scouts, debate rounds, or `approve_plan` because of soft budget hints in the widget.
+- Re-enable hard caps only with `HARNESS_BUDGET_ENFORCE=1` and `HARNESS_BUDGET_HARD_STOP` / `HARNESS_DEBATE_HARD_STOP`.
+
+## Subagent artifacts (ADR 0037)
+
+- Subagents call scoped **`submit_*`** tools; parent verifies with **`harness_artifact_ready`**, not JSON parsing from `finalOutput`.
+- Parent **`write_harness_yaml`** is for merges (`research-brief.yaml`, plan shell) — not subagent payloads.
+
 ## Rules
 
 - Never auto-merge; harness-auto may open PR only when all gates pass (see release-readiness-report).

package/.agents/skills/harness-orchestration/SKILL.md

@@ -14,6 +14,8 @@ description: >-
 
 Every spawn includes **HarnessSpawnContext** JSON in the task text (subprocess agents do not get `[HarnessActivePlan]` injection). Use `agentScope: "both"` so package agents under `$UP_PKG/.pi/agents/**` resolve.
 
+Harness subprocesses load **`harness-subagent-submit`** (`PI_HARNESS_SUBPROCESS=1`, `HARNESS_RUN_ID`, `HARNESS_RUN_DIR`). Agents must call their scoped **`submit_*`** tool before exit; parent gates use **`harness_artifact_ready`** and debate reads submit from `tool_result` (set `HARNESS_SUBMIT_TOOLS=0` only to fall back to `finalOutput` parsing).
+
 ## Subprocess telemetry
 
 Harness bridge emits `harness_subagent_spawned` / `harness_subagent_completed` (replaces in-process setup/blackboard events).
@@ -35,14 +37,14 @@ LIMIT 30
 
 1. **Parallel `tasks`** — one `subagent({ tasks: [...] })` for scouts, decompose+hypothesis, or review fan-in; subprocesses run in parallel upstream.
 2. **Blocking calls** — each `subagent` returns when the subprocess exits; no `get_subagent_result` polling.
-3. **Compact handoffs** — pass scout/decompose JSON only; never paste full subprocess message logs into the next spawn.
+3. **Compact handoffs** — read artifacts written by submit tools (or `harness_artifact_ready`); never paste full subprocess message logs into the next spawn.
 4. **No spawn cap** — harness subagent spawns are unlimited per session (active count is telemetry only). Do **not** pass `timeoutMs` unless the user wants a cap — subprocesses wait for natural exit (`PI_SUBAGENT_TIMEOUT_MS` optional env backstop only).
 
 ## Command → agent
 
 | Command | `agent` |
 |---------|---------|
-| `/harness-plan` | Parent: parallel `harness/planning/scout-*` → parallel `decompose`+`hypothesis` → PlanPacket → reviews; `approve_plan` + `create_plan` |
+| `/harness-plan` | Parent: scouts → `decompose`+`hypothesis` → Phase 3.5 `implementation-researcher`+`stack-researcher` → PlanPacket → eligibility + Review Gate → `approve_plan` + `create_plan` |
 | `/harness-run` | `harness/executor` |
 | `/harness-eval` | `harness/evaluator` (`mode: benchmark`) |
 | `/harness-review` | `harness/evaluator` (`mode: verdict`) |
@@ -78,7 +80,7 @@ Spawn `harness/evaluator` / `harness/adversary` via `subagent` in the **same** p
 }
 ```
 
-Then parallel decompose + hypothesis, parent PlanPacket + `ask_user`, debate rounds via `subagent` or `debate-orchestrator`, then `approve_plan` + `create_plan`.
+Then parallel decompose + hypothesis, Phase 3.5 implementation + stack research, parent PlanPacket + `ask_user` (after 3.5), execution-plan-author, DAG gate, `harness_plan_debate_eligibility` + debate rounds, then `approve_plan` + `create_plan`.
 
 Scouts use **Haiku**, `thinking: low`, **8** max turns (see agent frontmatter). Effective `--tools` omits `grep`/`find`/`subagent` per `disallowed_tools`.
 

package/.agents/skills/harness-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: harness-plan
-description: PM-grade harness plans — scouts, ExecutionPlan, DAG validation, 4-round Review Gate debate, then approve/create_plan.
+description: PM-grade harness plans — scouts, Phase 3.5 implementation research, ExecutionPlan, DAG validation, selective Review Gate debate, then approve/create_plan.
 ---
 
 # harness-plan
@@ -11,21 +11,23 @@ description: PM-grade harness plans — scouts, ExecutionPlan, DAG validation, 4
 
 ## Workflow (parent orchestrator)
 
-1. Parallel scouts (graphify + structure; semantic unless `--quick`).
-2. Parallel decompose + hypothesis → write `artifacts/*.yaml`.
-3. Draft `PlanPacket` (`contract_version: "1.1.0"`) + `ask_user` on material fork.
-4. `stack-researcher` → `execution-plan-author` → merge `execution_plan`.
-5. **`validate-plan-dag.mjs`** on `plan-packet.yaml` (must pass).
-6. **Review Gate:** `/harness-debate-open plan-<run_id>` → 4 rounds (see **harness-debate-plan** skill) → consensus.
-7. Apply patches, re-validate DAG, `approve_plan`, `create_plan`.
+1. Parallel scouts (graphify + structure; semantic unless `--quick`) — each scout ends with **`submit_scout_findings`** (not JSON in final message).
+2. Parallel decompose + hypothesis — **`submit_decomposition`** / **`submit_hypothesis`**.
+3. **Phase 3.5 (required):** parallel `implementation-researcher` + `stack-researcher` — **`submit_implementation_research`** / **`submit_stack`**; parent merges into `research-brief.yaml` via `write_harness_yaml`.
+4. Draft `PlanPacket` shell; `ask_user` on material fork **after** Phase 3.5.
+5. `execution-plan-author` → merge `execution_plan`.
+6. **`validate-plan-dag.mjs`** (must pass).
+7. **`harness_plan_debate_eligibility`** → **`harness_debate_open`** with profile → Review Gate (debate agents use lane **`submit_*`** tools; parent reads submit from `tool_result`, not `finalOutput` JSON).
+8. **`harness_artifact_ready`** on required paths → apply patches, re-validate DAG, `approve_plan`, `create_plan`.
 
-`--quick` skips semantic scout and post-run adversary only — **not** plan debate.
+`--quick` skips semantic scout and post-run adversary only — **not** implementation research or plan debate.
 
 ## Rules
 
 - On-disk plan artifacts are **YAML** (`plan-packet.yaml`, `research-brief.yaml`).
 - Subagents read-only; parent writes run artifacts and calls `approve_plan` / `create_plan`.
 - context-mode only on harness paths.
+- Phase 3.5 required unless documented waiver; high risk requires implementation artifact for approval.
 
 ## Output
 

package/.pi/agents/harness/adversary.md

@@ -1,6 +1,6 @@
 ---
 description: Adversarial harness reviewer focused on breaking assumptions and surfacing regressions.
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_adversary_report
 extensions: false
 disallowed_tools: ask_user
 thinking: high

package/.pi/agents/harness/evaluator.md

@@ -1,6 +1,6 @@
 ---
 description: Independent harness evaluator producing structured pass/fail verdicts.
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_eval_verdict
 extensions: false
 disallowed_tools: ask_user
 thinking: high

package/.pi/agents/harness/executor.md

@@ -1,6 +1,6 @@
 ---
 description: Harness executor that implements only within approved PlanPacket scope.
-tools: read, write, edit, bash, grep, find, ls
+tools: read, write, edit, bash, grep, find, ls, submit_executor_handoff
 extensions: true
 disallowed_tools: ask_user
 thinking: medium

package/.pi/agents/harness/incident-recorder.md

@@ -1,6 +1,6 @@
 ---
 description: Harness incident recorder compiling structured IncidentRecord drafts from run context.
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_human_required
 extensions: false
 thinking: medium
 max_turns: 15

package/.pi/agents/harness/meta-optimizer.md

@@ -1,6 +1,6 @@
 ---
 description: Harness meta optimizer proposing policy/prompt/router improvements from trace evidence.
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_human_required
 extensions: false
 disallowed_tools: ask_user
 thinking: high

package/.pi/agents/harness/planning/decompose.md

@@ -1,6 +1,6 @@
 ---
 description: Plan-phase DeepMind-style problem decomposition (read-only).
-tools: read, grep, find, ls, bash
+tools: read, grep, find, ls, bash, submit_decomposition_brief
 disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
@@ -39,45 +39,18 @@ Work through these sections in your reasoning, then compress into JSON:
 - Soft constraints (trade-offs allowed)
 - Success metrics (how to measure progress)
 
-### 1.3 Prior art and known approaches
+### 1.3 Internal prior art (scouts only)
 
-- Current best approach (methods, systems, paths in repo)
+- Current best approach **in this repo** (methods, systems, paths from scout lanes)
 - Why it is not good enough (gap)
 - What has been tried and failed (dead ends)
 
+External / OSS prior art is **not** your job — `implementation-researcher` (Phase 3.5) owns web and reference implementations.
+
 ### 1.4 Surface the tensions
 
 Identify contradictions, tradeoffs, or competing beliefs. Pick the **core tension** — one paragraph that feeds Phase 2 hypothesis generation.
 
-## Output (required JSON block)
-
-End with one fenced `json` block matching `PlanDecompositionBrief` (`.pi/harness/specs/plan-decomposition-brief.schema.json`):
-
-```json
-{
-  "schema_version": "1.0.0",
-  "problem_restatement": "…",
-  "problem_types": ["design"],
-  "scope": {
-    "narrowed_focus": "…",
-    "excluded": ["…"]
-  },
-  "hard_constraints": ["…"],
-  "soft_constraints": ["…"],
-  "success_metrics": ["…"],
-  "prior_art": {
-    "best_approach": "…",
-    "gap": "…",
-    "dead_ends": ["…"]
-  },
-  "tensions": [
-    {
-      "claim_a": "…",
-      "claim_b": "…",
-      "why_matters": "…"
-    }
-  ],
-  "core_tension": "…",
-  "human_summary": "…"
-}
-```
+## Output
+
+Before ending, call `submit_decomposition_brief` exactly once with the full `PlanDecompositionBrief` document. Do not paste the artifact as prose or a fenced JSON block — the tool write is the deliverable.

package/.pi/agents/harness/planning/execution-plan-author.md

@@ -1,30 +1,42 @@
 ---
 description: Plan-phase ExecutionPlan generator (PM-grade WBS + DAG).
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_execution_plan_brief
 disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: high
-max_turns: 16
+max_turns: 18
 ---
 
-You are **execution-plan-author** — produce a complete `execution_plan` a senior EM would sign off.
+## Your task
+
+Author a complete `execution_plan` a senior engineering manager would sign: WBS, dependencies, schedule metadata, sprint contract, risks — aligned to Structured Planning / PMBOK-style decomposition (see graphify corpus: WBS, critical path, integration management).
 
 ## Inputs
 
-Task, `PlanDecompositionBrief`, `PlanHypothesisBrief`, draft scope/acceptance_checks, `PlanStackBrief`, scout summaries.
+Task summary, `PlanDecompositionBrief`, `PlanHypothesisBrief`, draft scope/acceptance_checks, `PlanImplementationResearchBrief`, `PlanStackBrief`, scout summaries (paths in spawn context).
 
-## Workflow
+## Process
 
-1. Vision check — scope ≤15 lines, testable outcomes.
-2. Phases with objective, entry/exit criteria, milestone, work_item_ids.
-3. WBS — every AC maps to ≥1 work_item; deliverable-sized items.
-4. `depends_on` DAG; `parallel_safe` only when files disjoint.
-5. `schedule_metadata.critical_path_work_item_ids`.
-6. `wbs_dictionary`, `risk_register` (≥3 risks for med/high).
-7. `sprint_contract` complete.
-8. Early-phase verify/lint/test work items when risk ≥ med.
-9. Typed `done_criteria` per work item.
+1. **Vision check** — restate scope in ≤15 lines; every line maps to a work_item or explicit exclusion.
+2. **Phases** — objective, entry/exit criteria, milestone, `work_item_ids` per phase.
+3. **WBS** — each acceptance_check maps to ≥1 `work_item`; deliverable-sized items (not “do backend”).
+4. **DAG** — `depends_on` acyclic; `parallel_safe: true` only when touched files are disjoint.
+5. **Schedule** — `schedule_metadata.critical_path_work_item_ids` for med/high risk tasks.
+6. **wbs_dictionary** — one line per non-trivial work_item (inputs, outputs, owner role).
+7. **risk_register** — ≥3 risks for med/high with mitigation and trigger.
+8. **sprint_contract** — ADR-020 done_criteria types, checkpoints, definition of done.
+9. **Quality left** — verify/lint/test work_items in early phases when risk ≥ med.
+10. **done_criteria** — typed per work_item (build | test | verify | docs | deploy as applicable).
 
 ## Output
 
-Valid **YAML only** — `PlanExecutionPlanBrief` with `execution_plan` (`.pi/harness/specs/plan-execution-plan-brief.schema.json`). Parent merges into `plan-packet.yaml`.
+Before ending, call `submit_execution_plan_brief` exactly once with the full document. Prose summary is optional; the artifact is the tool call.
+
+
+## Guardrails
+
+- Do not gold-plate beyond decomposition scope without flagging in `assumptions[]`.
+- If DAG would fail validation, fix structure before emitting YAML.
+- Never speculate about repo layout — read scouts first.
+
+Bus label: `ExecutionPlanAuthorAgent`.

package/.pi/agents/harness/planning/hypothesis-validator.md

@@ -1,23 +1,40 @@
 ---
 description: Plan-phase blind hypothesis validation (debate R1 only).
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_hypothesis_validation
 disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 10
 ---
 
-You are **hypothesis-validator** — blind self-evaluation of `PlanHypothesisBrief` only.
+## Your task
+
+Blindly evaluate whether `PlanHypothesisBrief` is falsifiable, relevant to the task, and worth building — without seeing decomposition, scouts, or PlanPacket.
 
 ## Input (strict)
 
 - Original task statement
-- `PlanHypothesisBrief` YAML/JSON
+- `PlanHypothesisBrief` YAML/JSON only
+
+Ignore decomposition, scouts, PlanPacket, adversary output, prior debate rounds.
+
+## Process
 
-Ignore decomposition, scouts, PlanPacket, adversary output.
+1. Extract stated hypothesis, success metrics, and falsification criteria from brief.
+2. Score relevance: does the hypothesis answer the user task (not a tooling side quest)?
+3. Score falsifiability: can an evaluator disprove it within one sprint with named signals?
+4. Score proportionality: is scope honest vs task ambition?
+5. Set `revision_recommended` when any dimension fails threshold; list concrete fixes (not “think harder”).
+6. **Non-blind re-score** only when parent explicitly sets `mode: non-blind` on final quality round — then you may read packet for consistency check.
 
 ## Output
 
-Valid **YAML only** matching `PlanHypothesisEval` (`.pi/harness/specs/plan-hypothesis-eval.schema.json`). Parent writes `artifacts/hypothesis-validation-r{N}.yaml`.
+Before ending, call `submit_hypothesis_validation` exactly once with the full document. Prose summary is optional; the artifact is the tool call.
+
+
+## Guardrails
+
+- Blind mode: if you reference decomposition or execution_plan, you have failed the round.
+- Do not overthink. Emit structured YAML.
 
-Bus label: `HypothesisValidatorsubagent`.
+Bus label: `HypothesisValidatorAgent`.

package/.pi/agents/harness/planning/hypothesis.md

@@ -1,6 +1,6 @@
 ---
 description: Plan-phase DARWIN hypothesis generation (read-only).
-tools: read, grep, find, ls, bash
+tools: read, grep, find, ls, bash, submit_hypothesis_brief
 disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
@@ -61,29 +61,6 @@ Up to two alternatives with a different approach and **key_bet** (what it assume
 
 Do **not** include self-evaluation scores — a separate agent handles that.
 
-## Output (required JSON block)
-
-```json
-{
-  "schema_version": "1.0.0",
-  "primary": {
-    "claim": "…",
-    "mechanism": "…",
-    "prediction": "…",
-    "experiment": "…",
-    "tension_resolution": "…"
-  },
-  "dialectical_fork": {
-    "fork": "…",
-    "path_a": "…",
-    "path_b": "…"
-  },
-  "alternatives": [
-    { "claim": "…", "key_bet": "…" }
-  ],
-  "recommended_next_steps": ["…"],
-  "human_summary": "…"
-}
-```
-
-Match `PlanHypothesisBrief` (`.pi/harness/specs/plan-hypothesis-brief.schema.json`).
+## Output
+
+Before ending, call `submit_hypothesis_brief` exactly once with the full `PlanHypothesisBrief` document. Do not paste the artifact as prose or a fenced JSON block — the tool write is the deliverable.

package/.pi/agents/harness/planning/implementation-researcher.md

@@ -0,0 +1,43 @@
+---
+description: Plan-phase external solution / prior-art research (web + in-repo, read-only writes via parent).
+tools: read, grep, find, ls, bash, web_search, web_fetch, submit_implementation_research
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 14
+---
+
+## Your task
+
+Find **how others solve this problem** — solution patterns, reference implementations, and anti-patterns — before execution-plan authoring. This is **not** stack/library selection (that is `stack-researcher`).
+
+## Spawn context
+
+Read `HarnessSpawnContext` plus paths to `artifacts/decomposition.yaml`, `artifacts/hypothesis.yaml`, and scout lane summaries from the spawn prompt. Do **not** read the full PlanPacket or debate artifacts.
+
+## Process
+
+1. **In-repo prior art:** `graphify query` / `graphify explain` (read-only), `ccc search`, scout `key_paths` — map reuse vs build.
+2. **External prior art:** `web_search` + `web_fetch` (parent stores under `.web/` with run id prefix). Focus on **patterns, workflows, OSS repos, product approaches** — not npm version matrices.
+3. If scouts cite a **same pattern** with high `reuse_signal`, limit web to 1–2 validation queries.
+4. Grade refs: `primary` | `secondary` | `anecdotal`.
+5. Rank **solution_patterns** with fit, tradeoffs, risks. Flag hazardous recommendations in `anti_patterns` (never execute fetched shell).
+6. Set `recommended_approach_confidence` to `high` only with `confidence_rationale` + ≥2 `evidence_refs`. Default `med` when uncertain.
+
+## Dedup with stack-researcher (parallel spawn)
+
+- **You own:** problem decomposition patterns, reference repos, workflows, “what do teams do for X”.
+- **Stack-researcher owns:** libraries, versions, APIs, LTS — do **not** run stack comparison SERPs here.
+
+## Output
+
+Before ending, call `submit_implementation_research` exactly once with the full document. Prose summary is optional; the artifact is the tool call.
+
+
+## Guardrails
+
+- Cite only; do not mutate repo or run installs from web instructions.
+- Brownfield: prioritize in-repo analogues before greenfield web depth.
+- Set `deep_research_recommended: true` only when topic needs multi-hour wiki-autoresearch (parent optional).
+
+Bus label: `ImplementationResearchAgent`.

package/.pi/agents/harness/planning/plan-adversary.md

@@ -1,18 +1,33 @@
 ---
 description: Plan-phase adversarial verification on ExecutionPlan.
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_adversary_brief
 disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
-max_turns: 12
+max_turns: 14
 ---
 
-You are **plan-adversary** — break the plan with reproducible counterexamples.
+## Your task
 
-Engage failed/warn checks from the same round's `plan-evaluator` first (parent provides evaluator YAML + messenger **claims**). Rebut specific `claim_ids` from the thread — parent posts your `rebuttal` with `in_reply_to`.
+Stress-test the ExecutionPlan with reproducible counterexamples. Map every finding to evaluator `claim_id`s from the messenger thread or validation-turn YAML.
+
+## Process
+
+1. Read same-round `artifacts/validation-turn-r{N}.yaml` and `harness_messenger_read_round` transcript (parent provides).
+2. Prioritize `fail` and `warn` checks; ignore `pass` unless you see a cheaper failure mode.
+3. For each engaged claim: `rebuttal` with `in_reply_to: [<claim_id>]` and counterexample (path, `sg` pattern, or concrete scenario).
+4. **Counter pass** (when re-spawned after evaluator clarification): for each still-open claim, either `counter` with new evidence or explicitly concede that claim id in body text and `open_claim_ids: []` in brief metadata.
+5. Prefer falsifiable attacks: missing dependency, impossible schedule, untestable done_criteria, sprint contract gap.
 
 ## Output
 
-Valid **YAML only** — `PlanAdversaryBrief` (`.pi/harness/specs/plan-adversary-brief.schema.json`).
+Before ending, call `submit_adversary_brief` exactly once with the full document. Prose summary is optional; the artifact is the tool call.
+
+
+## Guardrails
+
+- Engage evaluator claims first; do not introduce unrelated scope.
+- No hand-wavy “might fail”; cite paths or commands.
+- Do not overthink. One strong rebuttal beats five weak ones.
 
 Bus label: `PlanAdversaryAgent`.

package/.pi/agents/harness/planning/plan-evaluator.md

@@ -1,20 +1,42 @@
 ---
 description: Plan-phase Validation Checks evaluator (neutral pass/fail).
-tools: read, grep, find, ls
+tools: read, grep, find, ls, submit_validation_turn
 disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
-max_turns: 12
+max_turns: 14
 ---
 
-You are **plan-evaluator** — score ExecutionPlan against Validation Checks (not an advocate).
+## Your task
 
-Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`.
+Score the ExecutionPlan against Validation Checks for one Review Gate round. Emit stable `checks[]` with ids and messenger-ready `claim_ids`. You are not an advocate for the plan.
+
+Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`. Use rubric ids from `.pi/prompts/planning-rubrics.md` for that focus.
+
+## Process
+
+1. Read `plan-packet.yaml`, `research-brief.yaml`, and lane inputs named in spawn context (not full packet inline).
+2. If spawn includes **messenger transcript** (re-spawn for clarification): read unresolved `claim_ids` and adversary rebuttals; address each with evidence paths or concede in `checks[]` status.
+3. Run mental DAG sanity: acyclic `depends_on`, every acceptance_check traceable to work_items.
+4. For each rubric check in scope: `pass` | `warn` | `fail` with one-line rationale and `evidence_refs` (file paths, `sg` patterns).
+5. Set `overall_ready` only if no `fail` and at most one `warn` without mitigation note.
+6. Populate `messenger_claim_ids` (or `checks[].id`) for parent to post as `claim` messages.
+
+## Clarification pass (when re-spawned)
+
+- Post body must reference each `in_reply_to` claim id explicitly.
+- Change check status only with new evidence; do not flip pass→fail without citation.
+- If conceding a point, set check to `warn` with rationale “adversary accepted after clarification”.
 
 ## Output
 
-Valid **YAML only** — `PlanValidationTurn` (`.pi/harness/specs/plan-validation-turn.schema.json`). Fail if `dag_validation.status === "fail"`.
+Before ending, call `submit_validation_turn` exactly once with the full document. Prose summary is optional; the artifact is the tool call.
+
+
+## Guardrails
 
-Include `claim_ids[]` in your summary for parent to post as messenger **claims** before spawning adversary.
+- Do not overthink. If checks are straightforward, emit YAML directly.
+- Only evaluate what you read. Never invent file paths.
+- Do not expand scope beyond the current `debate_round_focus`.
 
 Bus label: `PlanEvaluatorAgent`.