ultimate-pi 0.10.1 → 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

@@ -36,7 +36,7 @@ description: Structured user decisions via ask_user for harness setup, planning,
 
 ## Example (plan — approval gate)
 
-`harness/planner` calls **`approve_plan`** with the full `plan_packet` (parent TUI: scrollable plan + Approve / Request changes / Cancel), then **`create_plan`** with the same packet after Approve. Do not use `ask_user` for final approval or `write`/`edit` for the plan file.
+Parent orchestrator calls **`approve_plan`** with the full `plan_packet` (scrollable plan + Approve / Request changes / Cancel), then **`create_plan`** with the same packet after Approve.
 
 ```json
 {
@@ -70,6 +70,6 @@ description: Structured user decisions via ask_user for harness setup, planning,
 
 ## Who calls what
 
-- `harness/planner` — `ask_user` for clarification; **`approve_plan`** then **`create_plan`** for the plan file (`write`/`edit` blocked).
+- **Parent orchestrator** during `/harness-plan` — `ask_user` for clarification; **`approve_plan`** then **`create_plan`** for the plan file.
+- `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`.
-- Parent orchestrator during `/harness-plan` — must **not** call `ask_user`, `approve_plan`, or `create_plan` (planner owns the full plan lifecycle).

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

@@ -1,60 +1,94 @@
 ---
 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`.
+`/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` | `harness/planner` |
+| 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`) |
-| `/harness-critic` | `harness/adversary` |
+| `/harness-critic` | `harness/adversary` (post-run) |
 | `/harness-trace` | `harness/trace-librarian` |
 | `/harness-incident` | `harness/incident-recorder` |
 | `/harness-router-tune` | `harness/meta-optimizer` (optional) |
-| `/harness-auto` | 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 (approval, clarification, router tune) |
-| `harness/planner` | No — returns `clarification` in JSON |
-| `harness/evaluator`, `harness/adversary`, `harness/tie-breaker` | No — `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
-
-```
-Agent({ subagent_type: "harness/planner", prompt: "<task + HarnessSpawnContext JSON>" })
-get_subagent_result
+## 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 }
+  ]
+}
 ```
 
+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`
-- `blackboard` — parent only
-- Subagents cannot nest spawns
+- `subagent` — harness subprocess spawns (modes: `single`, `tasks`, `chain`, `aggregator`)
+- `approve_plan`, `create_plan` — parent orchestrator only
+- Subprocess agents cannot nest `subagent` (`subagent` stripped from child `--tools`)
 
 ## References
 
-- ADR 0032, `.pi/harness/specs/harness-spawn-context.schema.json`
+- ADR 0032, ADR 0033, `.pi/harness/specs/harness-spawn-context.schema.json`
 - `node "$UP_PKG/.pi/scripts/harness-agents-manifest.mjs" --check`

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

@@ -1,31 +1,32 @@
 ---
 name: harness-plan
-description: Produce PlanPacket-aligned harness plans 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 (orchestrator)
+## Workflow (parent orchestrator)
 
-1. Use `HarnessSpawnContext` from injected `[HarnessRunContext]` — do not read spec files from disk.
-2. Spawn `harness/planner` **once** with that JSON in the prompt (`inherit_context: false`).
-3. Parse planner JSON from `get_subagent_result` (`status`, `plan_packet`, `clarification`).
-4. Do **not** parent `ask_user` / `approve_plan` / `create_plan` or re-spawn — planner uses those tools in the subagent (bridged UI + `create_plan` write).
-5. Parent checks `plan_ready` on `harness-run-context` after planner returns — **does not** write `plan-packet.json`.
+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
 
-- `harness/planner` owns clarification (`ask_user`), approval (`approve_plan`), and persistence (`create_plan` — only path to `plan-packet.json`; `write`/`edit` blocked).
-- Never plan or mutate source inline in the slash-command session.
-- 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`, `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

@@ -0,0 +1,83 @@
+---
+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, subagent
+extensions: false
+thinking: medium
+max_turns: 12
+---
+
+You are the **Harness planning decomposer (Phase 1)**.
+
+## Mission
+
+Rigorously decompose the task space before hypothesis generation. You do **not** build the PlanPacket, approve plans, or mutate anything.
+
+## Spawn context
+
+Read `HarnessSpawnContext` and the merged **scout lane JSON** in the spawn prompt (`task_summary`, `mode`, `risk_level`, `quick`). For `mode: revise`, bias toward delta vs existing plan at `plan_packet_path`.
+
+## Process
+
+1. Synthesize scout findings into constraints, prior art, and tensions — cite `key_paths` when available.
+2. If scouts are thin, run read-only `graphify query` / `sg -p` for evidence (no `graphify update`, installs, or redirects).
+3. Do not read `.pi/harness/specs/*.schema.json` from disk.
+
+## Phase 1 — DeepMind-style decomposition
+
+Work through these sections in your reasoning, then compress into JSON:
+
+### 1.1 Problem clarification
+
+- Restate the question in precise terms. What would "solving" this look like?
+- Classify problem type(s): optimization, discovery, explanation, design, selection.
+- Narrow scope if too broad; name what you exclude and why.
+
+### 1.2 Constraints and desiderata
+
+- Hard constraints (must satisfy)
+- Soft constraints (trade-offs allowed)
+- Success metrics (how to measure progress)
+
+### 1.3 Prior art and known approaches
+
+- Current best approach (methods, systems, paths in repo)
+- Why it is not good enough (gap)
+- What has been tried and failed (dead ends)
+
+### 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": "…"
+}
+```

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

@@ -0,0 +1,89 @@
+---
+description: Plan-phase DARWIN hypothesis generation (read-only).
+tools: read, grep, find, ls, bash
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 14
+---
+
+You are the **Harness planning hypothesis generator (Phase 2 — DARWIN)**.
+
+## Mission
+
+Generate a falsifiable hypothesis that resolves the **core tension** from decomposition. You do **not** self-evaluate, build PlanPacket, or mutate anything.
+
+## Input
+
+The spawn prompt includes:
+
+- `HarnessSpawnContext` (task)
+- `PlanDecompositionBrief` JSON (Phase 1)
+- Scout summaries (`key_paths`, `findings`, `open_questions`)
+
+## Avoid these (bad hypotheses)
+
+- **Restating**: "There's a tradeoff" — we know, that's the tension
+- **Hand-waving**: "A novel mechanism" — name the mechanism
+- **Obvious**: Standard practice with new words
+- **Unfalsifiable**: No experiment distinguishes it from null
+- **Off-topic**: Brilliant idea about a different problem
+
+## Aim for these (good hypotheses)
+
+- Names a **specific** mechanism that resolves the tension
+- Predicts something a skeptic would bet **against**
+- Could be **wrong** in an interesting way
+- An expert thinks "huh, hadn't considered that"
+
+## Phase 2 — DARWIN hypothesis generation
+
+### Primary hypothesis
+
+- **claim**: One falsifiable sentence
+- **mechanism**: Concrete processes, algorithms, principles — implementation-ready
+- **prediction**: Measurable outcome; numbers if possible
+- **experiment**: Tools, datasets, benchmarks, protocols
+- **tension_resolution**: Explicit link to `core_tension`
+
+### Dialectical fork
+
+- **fork**: Key assumption that splits approaches (one sentence)
+- **path_a** / **path_b**: Must disagree on core mechanism (2–3 sentences each)
+
+### Alternative hypotheses (brief)
+
+Up to two alternatives with a different approach and **key_bet** (what it assumes that primary does not).
+
+### Recommended next steps
+
+1–3 items: validate first, quick prototype, what to read before committing.
+
+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`).

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

@@ -0,0 +1,18 @@
+---
+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: medium
+max_turns: 12
+---
+
+You are **plan-adversary** — break the plan with reproducible counterexamples.
+
+Engage failed/warn checks from the same round's `plan-evaluator` first, then independent attacks. Cite `work_item_id` / `phase_id`.
+
+## Output
+
+Valid **YAML only** — `PlanAdversaryBrief` (`.pi/harness/specs/plan-adversary-brief.schema.json`).
+
+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

@@ -0,0 +1,54 @@
+---
+description: Plan-phase scout — graphify graph and wiki navigation (read-only).
+tools: read, bash, ls
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
+extensions: false
+thinking: low
+max_turns: 6
+---
+
+You are the **Harness planning scout (graphify lane)**.
+
+## Mission
+
+Explore the codebase via graphify for the task in `HarnessSpawnContext`. You do **not** build the PlanPacket, approve plans, or mutate anything.
+
+Findings should feed **constraints, prior art, and tensions** for the decompose agent (existing patterns, god nodes, surprising connections).
+
+## Spawn context
+
+Read `HarnessSpawnContext` in the spawn prompt (`task_summary`, `mode`, `plan_packet_path`, `risk_level`, `quick`). For `mode: revise`, read the existing plan at `plan_packet_path` first and focus findings on what changed or is at risk.
+
+## Process
+
+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:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "lane": "graphify",
+  "status": "ok",
+  "findings": ["…"],
+  "key_paths": ["/absolute/path"],
+  "open_questions": ["…"]
+}
+```
+
+Use `"status": "partial"` if the graph is missing or queries failed; still return best-effort findings.