ultimate-pi 0.11.0 → 0.12.0

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

@@ -0,0 +1,44 @@
+---
+name: harness-debate-plan
+description: Plan-phase Review Gate debate — assemble rounds, token caps, bus envelopes for parent orchestrator.
+---
+
+# harness-debate-plan
+
+Use when running **Phase 5** of `/harness-plan` — four Review Gate rounds on the plan debate bus.
+
+## Open
+
+```
+/harness-debate-open plan-<run_id>
+```
+
+Budget profile **plan**: `max_rounds=4`, `round_token_cap=2000`, `debate_global_cap=12000`.
+
+## Per-round spawn order
+
+1. Round-specific extras (R1: `hypothesis-validator` first, blind)
+2. `plan-evaluator`
+3. `plan-adversary`
+4. R4: `sprint-contract-auditor` (required)
+5. `review-integrator`
+
+## Artifacts (YAML)
+
+| Agent | Output path |
+|-------|-------------|
+| hypothesis-validator | `artifacts/hypothesis-validation-r{N}.yaml` |
+| plan-evaluator | `artifacts/validation-turn-r{N}.yaml` |
+| plan-adversary | `artifacts/adversary-brief-r{N}.yaml` |
+| sprint-contract-auditor | `artifacts/sprint-audit-r{N}.yaml` |
+| review-integrator | `artifacts/review-round-r{N}.yaml` |
+
+## Bus envelope
+
+Load `review-round-r{N}.yaml`, validate, then `buildPlanReviewRoundEnvelope` (`.pi/extensions/lib/plan-debate-envelope.ts`) → `/harness-debate-round '<json>'`.
+
+Plan participants only. `StackResearchAgent` uses `artifacts/stack.yaml` claims — no spawn.
+
+## Close
+
+After round 4: `/harness-debate-consensus`. Do not `approve_plan` on `policy_decision: block`.

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

@@ -71,5 +71,5 @@ Parent orchestrator calls **`approve_plan`** with the full `plan_packet` (scroll
 ## Who calls what
 
 - **Parent orchestrator** during `/harness-plan` — `ask_user` for clarification; **`approve_plan`** then **`create_plan`** for the plan file.
-- `harness/planning/*` (scouts, decompose, hypothesis, plan-adversary, hypothesis-eval) — JSON only; no `ask_user` / `approve_plan` / `create_plan`.
+- `harness/planning/*` (scouts, decompose, hypothesis, hypothesis-eval) — JSON only; no `ask_user` / `approve_plan` / `create_plan`.
 - `harness/evaluator`, `harness/adversary`, and `harness/tie-breaker` — emit `human_required`; the **parent orchestrator** calls `ask_user`.

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

@@ -1,24 +1,48 @@
 ---
 name: harness-orchestration
 description: >-
-  Orchestrate ultimate-pi harness phases with Agent spawns, blackboard handoffs,
-  and observation-bus artifacts. Use for plan/execute/evaluate pipelines, L4
-  verification, parallel scouts, and debate prep.
+  Orchestrate ultimate-pi harness phases with the native `subagent` tool
+  (isolated `pi --mode json` subprocesses). Use for plan/execute/evaluate
+  pipelines, L4 verification, parallel scouts, and debate prep.
 ---
 
 # Harness orchestration
 
 ## Slash commands = orchestrators
 
-`/harness-*` prompts parse args, spawn agents, run `ask_user`, write policy-gated artifacts. Phase logic lives in `.pi/agents/harness/*.md` and `.pi/agents/harness/planning/*.md`.
+`/harness-*` prompts parse args, call `subagent`, run `ask_user`, write policy-gated artifacts. Phase logic lives in `.pi/agents/harness/*.md` and `.pi/agents/harness/planning/*.md`.
 
-Every spawn includes **HarnessSpawnContext** JSON (subagents do not get `[HarnessActivePlan]` injection). Use `inherit_context: false`.
+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.
+
+## Subprocess telemetry
+
+Harness bridge emits `harness_subagent_spawned` / `harness_subagent_completed` (replaces in-process setup/blackboard events).
+
+```sql
+SELECT
+  properties.agent as agent,
+  count() as n,
+  round(avg(toFloat(properties.duration_ms)), 0) as avg_ms
+FROM events
+WHERE event = 'harness_subagent_completed'
+  AND timestamp >= now() - INTERVAL 7 DAY
+GROUP BY agent
+ORDER BY avg_ms DESC
+LIMIT 30
+```
+
+## Latency rules
+
+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.
+4. **Spawn caps** — bridge enforces **8** active + **12** total harness spawns per session (`PI_SUBAGENT_TIMEOUT_MS` / per-task `timeoutMs` for backstop).
 
 ## Command → agent
 
-| Command | `subagent_type` |
-|---------|-----------------|
-| `/harness-plan` | Parent: parallel `scout-*` → `decompose` → `hypothesis` → PlanPacket → parallel `plan-adversary` + `hypothesis-eval`; `approve_plan` + `create_plan` |
+| Command | `agent` |
+|---------|---------|
+| `/harness-plan` | Parent: parallel `harness/planning/scout-*` → parallel `decompose`+`hypothesis` → PlanPacket → reviews; `approve_plan` + `create_plan` |
 | `/harness-run` | `harness/executor` |
 | `/harness-eval` | `harness/evaluator` (`mode: benchmark`) |
 | `/harness-review` | `harness/evaluator` (`mode: verdict`) |
@@ -26,41 +50,43 @@ Every spawn includes **HarnessSpawnContext** JSON (subagents do not get `[Harnes
 | `/harness-trace` | `harness/trace-librarian` |
 | `/harness-incident` | `harness/incident-recorder` |
 | `/harness-router-tune` | `harness/meta-optimizer` (optional) |
-| `/harness-auto` | plan phases per `/harness-plan`, then sequential spawns above |
+| `/harness-auto` | plan per `/harness-plan`; `--quick` skips adversary + tie-breaker |
 
 ## Review isolation
 
-Spawn `harness/evaluator` / `harness/adversary` in the **same** parent session — isolated subagent context replaces session fork (ADR 0032).
+Spawn `harness/evaluator` / `harness/adversary` via `subagent` in the **same** parent session. `review-integrity` allows `subagent` when `agent` is in the review set; blocks executor from spawning review agents during evaluate.
 
 ## ask_user policy
 
-| Agent | `ask_user` |
-|-------|------------|
-| Parent orchestrator | Yes (plan clarification, approval via `approve_plan`, router tune) |
-| `harness/planning/*` | No — JSON only |
-| `harness/evaluator`, `harness/adversary`, `harness/tie-breaker` | Bridged or `human_required` in output |
+| Role | `ask_user` |
+|------|------------|
+| Parent orchestrator | Yes (plan clarification, `approve_plan`, router tune) |
+| `harness/planning/*` | No — JSON only (`human_required` in output if stuck) |
+| `harness/evaluator`, `harness/adversary`, `harness/tie-breaker` | `human_required` in subprocess JSON |
 | `harness/executor` | No — parent handles governance |
 
 ## Spawn pattern (`/harness-plan`)
 
+```json
+{
+  "agentScope": "both",
+  "tasks": [
+    { "agent": "harness/planning/scout-graphify", "task": "…", "timeoutMs": 90000 },
+    { "agent": "harness/planning/scout-structure", "task": "…", "timeoutMs": 90000 },
+    { "agent": "harness/planning/scout-semantic", "task": "…", "timeoutMs": 90000 }
+  ]
+}
 ```
-Agent({ subagent_type: "harness/planning/scout-graphify", prompt: "…", run_in_background: true })
-Agent({ subagent_type: "harness/planning/scout-structure", prompt: "…", run_in_background: true })
-get_subagent_result  # scouts
-Agent({ subagent_type: "harness/planning/decompose", prompt: "…" })
-Agent({ subagent_type: "harness/planning/hypothesis", prompt: "…" })
-# parent: PlanPacket, ask_user on fork
-Agent({ subagent_type: "harness/planning/plan-adversary", run_in_background: true })
-Agent({ subagent_type: "harness/planning/hypothesis-eval", run_in_background: true })
-approve_plan({ plan_packet, research_brief }); create_plan
-```
+
+Then parallel decompose + hypothesis, parent PlanPacket + `ask_user`, debate rounds via `subagent` or `debate-orchestrator`, 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`.
 
 ## Tools
 
-- `Agent`, `get_subagent_result`, `steer_subagent`
+- `subagent` — harness subprocess spawns (modes: `single`, `tasks`, `chain`, `aggregator`)
 - `approve_plan`, `create_plan` — parent orchestrator only
-- `blackboard` — parent only
-- Subagents cannot nest spawns
+- Subprocess agents cannot nest `subagent` (`subagent` stripped from child `--tools`)
 
 ## References
 

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

@@ -1,37 +1,32 @@
 ---
 name: harness-plan
-description: Produce PlanPacket-aligned harness plans via decomposition + DARWIN hypothesis before execute phase. Use with /harness-plan, harness-auto plan phase, or when policy-gate requires an approved plan.
+description: PM-grade harness plans — scouts, ExecutionPlan, DAG validation, 4-round Review Gate debate, then approve/create_plan.
 ---
 
 # harness-plan
 
 ## When to use
 
-- User invokes `/harness-plan` or harness-auto planning phase
-- Policy gate blocks mutate tools without approved plan
-- Drift monitor requests replan (`harness-drift-replan`)
-- User replies with clarification after `needs_clarification`
+- `/harness-plan`, harness-auto plan phase, drift replan, policy-gate without approved plan
 
 ## Workflow (parent orchestrator)
 
-1. Use `HarnessSpawnContext` from injected `[HarnessRunContext]` — do not read spec files from disk.
-2. Spawn planning scouts in parallel (`run_in_background: true`, `inherit_context: false`):
-   - `harness/planning/scout-graphify` (required)
-   - `harness/planning/scout-structure` (required)
-   - `harness/planning/scout-semantic` (skip when `--quick`)
-3. `get_subagent_result` for each; parse scout JSON.
-4. Spawn `harness/planning/decompose` with merged scout JSON → `PlanDecompositionBrief`.
-5. Spawn `harness/planning/hypothesis` with decomposition + scouts → `PlanHypothesisBrief`.
-6. Parent synthesizes draft `PlanPacket` from hypothesis; `ask_user` when dialectical fork is material.
-7. Parallel: `harness/planning/plan-adversary` + `harness/planning/hypothesis-eval` (eval gets task + hypothesis only).
-8. Parent calls `approve_plan({ plan_packet, human_summary, research_brief })` then `create_plan`.
+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`.
+
+`--quick` skips semantic scout and post-run adversary only — **not** plan debate.
 
 ## Rules
 
-- Planning subagents are read-only; they never call `ask_user`, `approve_plan`, or `create_plan`.
-- Do not spawn `harness/planner` or `harness/planning/planner` (deprecated).
-- context-mode only on harness paths; never lean-ctx.
+- 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.
 
 ## Output
 
-- `plan_status`, `risk_level`, `plan_review_path`, `next_command`: `/harness-run` when ready
+`plan_status`, `plan_review_path`, `next_command: /harness-run` when ready.

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

@@ -5,7 +5,6 @@ extensions: false
 disallowed_tools: ask_user
 thinking: high
 max_turns: 20
-inherit_context: false
 ---
 
 You are the Harness Adversary.

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

@@ -5,7 +5,6 @@ extensions: false
 disallowed_tools: ask_user
 thinking: high
 max_turns: 20
-inherit_context: false
 ---
 
 You are the Harness Evaluator.

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

@@ -4,8 +4,7 @@ tools: read, write, edit, bash, grep, find, ls
 extensions: true
 disallowed_tools: ask_user
 thinking: medium
-max_turns: 30
-inherit_context: false
+max_turns: 20
 ---
 
 You are the Harness Executor.

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

@@ -4,7 +4,6 @@ tools: read, grep, find, ls
 extensions: false
 thinking: medium
 max_turns: 15
-inherit_context: false
 ---
 
 You are the Harness Incident Recorder.

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

@@ -5,7 +5,6 @@ extensions: false
 disallowed_tools: ask_user
 thinking: high
 max_turns: 25
-inherit_context: false
 ---
 
 You are the Harness Meta Optimizer.

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

@@ -1,11 +1,10 @@
 ---
 description: Plan-phase DeepMind-style problem decomposition (read-only).
 tools: read, grep, find, ls, bash
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, Agent
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
-thinking: high
-max_turns: 18
-inherit_context: false
+thinking: medium
+max_turns: 12
 ---
 
 You are the **Harness planning decomposer (Phase 1)**.

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

@@ -0,0 +1,30 @@
+---
+description: Plan-phase ExecutionPlan generator (PM-grade WBS + DAG).
+tools: read, grep, find, ls
+disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: high
+max_turns: 16
+---
+
+You are **execution-plan-author** — produce a complete `execution_plan` a senior EM would sign off.
+
+## Inputs
+
+Task, `PlanDecompositionBrief`, `PlanHypothesisBrief`, draft scope/acceptance_checks, `PlanStackBrief`, scout summaries.
+
+## Workflow
+
+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.
+
+## Output
+
+Valid **YAML only** — `PlanExecutionPlanBrief` with `execution_plan` (`.pi/harness/specs/plan-execution-plan-brief.schema.json`). Parent merges into `plan-packet.yaml`.

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

@@ -0,0 +1,23 @@
+---
+description: Plan-phase blind hypothesis validation (debate R1 only).
+tools: read, grep, find, ls
+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.
+
+## Input (strict)
+
+- Original task statement
+- `PlanHypothesisBrief` YAML/JSON
+
+Ignore decomposition, scouts, PlanPacket, adversary output.
+
+## Output
+
+Valid **YAML only** matching `PlanHypothesisEval` (`.pi/harness/specs/plan-hypothesis-eval.schema.json`). Parent writes `artifacts/hypothesis-validation-r{N}.yaml`.
+
+Bus label: `HypothesisValidatorsubagent`.

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

@@ -1,11 +1,10 @@
 ---
 description: Plan-phase DARWIN hypothesis generation (read-only).
 tools: read, grep, find, ls, bash
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, Agent
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
-thinking: high
-max_turns: 20
-inherit_context: false
+thinking: medium
+max_turns: 14
 ---
 
 You are the **Harness planning hypothesis generator (Phase 2 — DARWIN)**.

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

@@ -1,50 +1,18 @@
 ---
-description: Plan adversary (pre-approval) — edge cases and acceptance gaps on a draft PlanPacket.
-tools: read, grep, find, ls, bash
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, Agent
+description: Plan-phase adversarial verification on ExecutionPlan.
+tools: read, grep, find, ls
+disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
-thinking: high
-max_turns: 15
-inherit_context: false
+thinking: medium
+max_turns: 12
 ---
 
-You are the **Harness plan adversary (pre-approval)**. Not the post-run `harness/adversary`.
+You are **plan-adversary** — break the plan with reproducible counterexamples.
 
-## Mission
+Engage failed/warn checks from the same round's `plan-evaluator` first, then independent attacks. Cite `work_item_id` / `phase_id`.
 
-Pressure-test a **draft** `PlanPacket` for **execution risk** before the user approves. Surface edge cases, failure modes, and missing acceptance checks tied to hypothesis-derived `acceptance_checks`. Read-only — no mutations.
+## Output
 
-Do **not** re-score DARWIN novelty or duplicate hypothesis-eval work.
+Valid **YAML only** — `PlanAdversaryBrief` (`.pi/harness/specs/plan-adversary-brief.schema.json`).
 
-## Input
-
-The spawn prompt includes:
-
-- `HarnessSpawnContext`
-- Draft `PlanPacket` JSON
-- Scout lane summaries (graphify, structure, semantic)
-
-## Process
-
-1. Assume the plan has hidden gaps until you justify `recommendation: proceed`.
-2. Tie every finding to evidence (paths, APIs, or scout findings) — no speculation without a probe path.
-3. Propose concrete `mitigations` the parent can merge into scope, assumptions, or `acceptance_checks`.
-4. Empty arrays are allowed when no material gaps exist; say so in `human_summary`.
-
-## Output (required JSON block)
-
-Match `PlanAdversaryBrief` (`.pi/harness/specs/plan-adversary-brief.schema.json`):
-
-```json
-{
-  "schema_version": "1.0.0",
-  "edge_cases": ["…"],
-  "failure_modes": ["…"],
-  "acceptance_gaps": ["…"],
-  "mitigations": ["…"],
-  "recommendation": "proceed",
-  "human_summary": "…"
-}
-```
-
-Use `"recommendation": "revise"` when scope or acceptance must change before execution.
+Bus label: `PlanAdversarysubagent`.

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

@@ -0,0 +1,18 @@
+---
+description: Plan-phase Validation Checks evaluator (neutral pass/fail).
+tools: read, grep, find, ls
+disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 12
+---
+
+You are **plan-evaluator** — score ExecutionPlan against Validation Checks (not an advocate).
+
+Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`.
+
+## Output
+
+Valid **YAML only** — `PlanValidationTurn` (`.pi/harness/specs/plan-validation-turn.schema.json`). Fail if `dag_validation.status === "fail"`.
+
+Bus label: `PlanEvaluatorsubagent`.

package/.pi/agents/harness/planning/review-integrator.md

@@ -0,0 +1,23 @@
+---
+description: Plan-phase Review Gate integrator (round → debate bus).
+tools: read, grep, find, ls
+disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 10
+---
+
+You are **review-integrator** — merge evaluator, adversary, sprint audit, and hypothesis-validator outputs into a Review Gate draft.
+
+## Output
+
+Valid **YAML only** — `PlanReviewRoundDraft` (`.pi/harness/specs/plan-review-round-draft.schema.json`) with:
+
+- `round_summary`, `validation_summary`, `adversary_summary`
+- `disputes[]`, `recommended_packet_patches[]` (JSON Pointer paths)
+- `review_gate_ready` boolean
+- `participants`, `claims`, `rebuttals`, `evidence_refs`, `token_usage`, `severity_scores`
+
+Parent runs `buildPlanReviewRoundEnvelope` → `/harness-debate-round`.
+
+Bus label: `ReviewIntegratorsubagent`.

package/.pi/agents/harness/planning/scout-graphify.md

@@ -1,11 +1,10 @@
 ---
 description: Plan-phase scout — graphify graph and wiki navigation (read-only).
-tools: read, grep, find, ls, bash
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, Agent
+tools: read, bash, ls
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
-thinking: medium
-max_turns: 12
-inherit_context: false
+thinking: low
+max_turns: 6
 ---
 
 You are the **Harness planning scout (graphify lane)**.
@@ -25,11 +24,18 @@ Read `HarnessSpawnContext` in the spawn prompt (`task_summary`, `mode`, `plan_pa
 1. Read `graphify-out/GRAPH_REPORT.md` when present; use `graphify query`, `graphify path`, or `graphify explain` for the task (read-only CLI only).
 2. If `graphify-out/` is missing, say so in `findings` and `open_questions` — do not run `graphify update` or installs.
 3. Do not read `.pi/harness/specs/*.schema.json` from disk.
+4. **Stop early** — target ≤6 tool calls when possible.
 
 ## Bash guardrails
 
 Read-only only: no `graphify update`, `graphify extract`, `pip install`, redirects (`>`, `>>`), or file creation. Allowed: `graphify query`, `graphify path`, `graphify explain`, `ls`, `cat`, `head`.
 
+## Output limits
+
+- `findings`: at most **8** bullets, each ≤2 sentences
+- `key_paths`: at most **10** absolute paths
+- `open_questions`: at most **5** items
+
 ## Output (required JSON block)
 
 End with one fenced `json` block:

package/.pi/agents/harness/planning/scout-semantic.md

@@ -1,11 +1,10 @@
 ---
 description: Plan-phase scout — ck semantic code search (read-only).
-tools: read, grep, find, ls, bash
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, Agent
+tools: read, bash, ls
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
-thinking: medium
-max_turns: 12
-inherit_context: false
+thinking: low
+max_turns: 6
 ---
 
 You are the **Harness planning scout (semantic lane)**.
@@ -22,12 +21,18 @@ Read `HarnessSpawnContext` in the spawn prompt. For `mode: revise`, bias searche
 
 1. Use `ck search` or `ck query` (or project-documented ck CLI) with task-focused queries.
 2. If ck is unavailable, set `status: partial` and document in `findings`.
-3. Cap output — prefer the top 5–10 most relevant paths.
+3. **Stop early** — top **5** most relevant paths only.
 
 ## Bash guardrails
 
 Read-only only: no installs, index rebuilds that mutate disk, or redirects.
 
+## Output limits
+
+- `findings`: at most **6** bullets
+- `key_paths`: at most **8** absolute paths
+- `open_questions`: at most **4** items
+
 ## Output (required JSON block)
 
 ```json

package/.pi/agents/harness/planning/scout-structure.md

@@ -1,11 +1,10 @@
 ---
 description: Plan-phase scout — ast-grep structural code search (read-only).
-tools: read, grep, find, ls, bash
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, Agent
+tools: read, bash, ls
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
-thinking: medium
-max_turns: 12
-inherit_context: false
+thinking: low
+max_turns: 6
 ---
 
 You are the **Harness planning scout (structure lane)**.
@@ -22,14 +21,21 @@ Read `HarnessSpawnContext` in the spawn prompt. For `mode: revise`, read the exi
 
 ## Process
 
-1. Run `sg -p '…'` with patterns tied to the task (handlers, types, exports, call sites).
+1. Run `sg -p '…'` with patterns tied to the task (handlers, types, exports, call sites). **Do not use `find` or `grep`.**
 2. Prefer absolute paths in `key_paths`.
 3. If `sg` is not on PATH, set `status: partial` and note the tooling gap in `findings`.
+4. **Stop early** — target ≤6 tool calls when possible.
 
 ## Bash guardrails
 
 Read-only only: no installs, redirects, or mutating git/npm commands.
 
+## Output limits
+
+- `findings`: at most **8** bullets
+- `key_paths`: at most **10** absolute paths
+- `open_questions`: at most **5** items
+
 ## Output (required JSON block)
 
 ```json

package/.pi/agents/harness/planning/sprint-contract-auditor.md

@@ -0,0 +1,18 @@
+---
+description: Plan-phase ADR-020 sprint contract auditor.
+tools: read, grep, find, ls
+disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 10
+---
+
+You are **sprint-contract-auditor** — ADR-020 Sprint Contract, Done Criteria Types, checkpoints, Keep Quality Left.
+
+Required on debate **round 4**; optional spot-check round 2 if done_criteria sparse.
+
+## Output
+
+Valid **YAML only** — `PlanSprintAuditTurn` (`.pi/harness/specs/plan-sprint-audit-turn.schema.json`).
+
+Bus label: `SprintContractAuditorsubagent`.

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

@@ -0,0 +1,24 @@
+---
+description: Plan-phase stack research (ctx7 + web, read-only file writes via parent).
+tools: read, grep, find, ls, bash, web_search, web_fetch
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 14
+---
+
+You are **stack-researcher** — evidence-backed stack recommendations for harness planning.
+
+## Mission
+
+Produce `PlanStackBrief` with ranked options. For brownfield tasks, always include **extend current stack** as one ranked option.
+
+## Protocol
+
+1. **Libraries / APIs:** `ctx7 library` → `ctx7 docs` (read context7-cli skill). Cite library IDs in `evidence_refs`.
+2. **Comparisons / landscape:** `web_search` + `web_fetch` (`.web/` artifacts).
+3. **Greenfield:** ≥3 distinct options with pros/cons/risks.
+
+## Output
+
+Return valid **YAML only** (no fences) matching `PlanStackBrief` (`.pi/harness/specs/plan-stack-brief.schema.json`). Parent writes `artifacts/stack.yaml`.

package/.pi/agents/harness/tie-breaker.md

@@ -5,7 +5,6 @@ extensions: false
 disallowed_tools: ask_user
 thinking: high
 max_turns: 15
-inherit_context: false
 ---
 
 You are the Harness Tie-Breaker.

package/.pi/agents/harness/trace-librarian.md

@@ -4,7 +4,6 @@ tools: read, grep, find, ls
 extensions: false
 thinking: medium
 max_turns: 20
-inherit_context: false
 ---
 
 You are the Harness Trace Librarian.