ultimate-pi 0.3.1 → 0.4.0

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

@@ -0,0 +1,37 @@
+---
+name: harness-decisions
+description: Structured user decisions via ask_user for harness setup, planning, and governance forks. Use with /harness-setup, /harness-plan, harness-auto plan phase, and when agents emit human_required.
+---
+
+# harness-decisions
+
+## When to use
+
+- `/harness-setup` — missing project `.env`, other bootstrap forks
+- `/harness-plan` or harness-auto **plan** phase — scope, risk, acceptance ambiguity
+- Orchestrator receives `human_required` from evaluator, adversary, tie-breaker, or meta-optimizer
+- `/harness-router-tune` — approve / reject / edit a router proposal before apply
+
+## Decision handshake
+
+1. **One focused `ask_user` call** per blocking fork (2–4 options with short descriptions).
+2. **Never guess** on `.env` creation, risk level, scope boundaries, or merge policy.
+3. If the user **cancels** (Esc), stop with `needs_clarification` / `human_required` — do not assume defaults.
+4. **CI / automation only:** pass `--non-interactive` to `/harness-setup` to skip prompts and use documented defaults.
+
+## Example (plan — scope)
+
+```json
+{
+  "question": "What should be in scope for this plan?",
+  "options": [
+    { "title": "Backend API only", "description": "No UI or infra changes" },
+    { "title": "Full stack including UI", "description": "API + frontend + tests" }
+  ],
+  "allowFreeform": true
+}
+```
+
+## Who must NOT call ask_user
+
+- `harness/evaluator` and `harness/adversary` — emit `human_required` in structured verdicts; the **parent orchestrator** calls `ask_user`.

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

@@ -25,7 +25,7 @@ When refining plans from noisy requirements:
 
 1. Distill user intent into acceptance criteria and non-goals (bullet list).
 2. Map criteria to `plan-packet` fields and testable checks.
-3. Flag ambiguities as human_required in eval verdict — do not guess scope.
+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.
 
 ## Rules

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

@@ -0,0 +1,54 @@
+---
+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.
+---
+
+# Harness orchestration
+
+## Agent IDs (namespaced)
+
+Spawn with the `Agent` tool using **path ids** from the installed package:
+
+| Phase | `subagent_type` | Policy |
+|-------|-----------------|--------|
+| Plan | `harness/planner` | May use `ask_user` |
+| Execute | `harness/executor` | `ask_user` for in-scope forks only |
+| Verify | `harness/evaluator`, `harness/adversary`, `harness/tie-breaker` | `disallowed_tools: ask_user` on L4 agents |
+| Meta | `harness/meta-optimizer`, `harness/trace-librarian` | Parent calls `ask_user` for approvals |
+
+Pi-pi experts: `pi-pi/agent-expert`, `pi-pi/cli-expert`, etc.
+
+Project override: `.pi/agents/harness/planner.md` replaces package `harness/planner` only.
+
+## Tools
+
+- `Agent` — spawn (prefer `run_in_background: true` for parallel work)
+- `get_subagent_result` / `steer_subagent` — background agents
+- `blackboard` — orchestrator handoffs (`list`, `read`, `query`, `wait`, `delete`)
+- `ask_user` — **parent orchestrator only** on L4 paths
+
+Subagents cannot spawn sub-subagents (`Agent`, `blackboard`, `ask_user` blocked).
+
+## Blackboard + bus
+
+1. Scouts/workers post findings to `blackboard` (namespaced keys).
+2. Spawn with `context: { keys: ["scout:*"] }` or `{ agent_name: "…" }` (~8k cap).
+3. On completion, `harness-subagents` appends `harness-observation` entries for `observation-bus`.
+4. Durable artifacts (PlanPacket, EvalVerdict, debate envelopes) still go to trace/run files per harness specs.
+
+## Pipeline rules (V2-aligned)
+
+- **Plan gate first** — no implementation without an approved `PlanPacket`.
+- **L4 external verification** — evaluator ≠ executor; use `harness/adversary` when policy requires.
+- **Turn budgets** — set `max_turns` on spawn or rely on agent frontmatter defaults.
+- **Parallelism** — parallelize by file/module with explicit ownership in the plan.
+- **Debate** — use `debate-orchestrator` commands; parent handles `human_required` via `ask_user`.
+
+## References
+
+- Package agents: `$UP_PKG/.pi/agents/`
+- Manifest drift: `node "$UP_PKG/.pi/scripts/harness-agents-manifest.mjs" --check`
+- Reference playbook: `raw/references/subagents/AGENTS.md` (design only)

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

@@ -14,9 +14,10 @@ description: Produce PlanPacket-aligned harness plans before execute phase. Use
 ## Workflow
 
 1. Read `.pi/harness/specs/plan-packet.schema.json`.
-2. Capture scope, risks, acceptance criteria, and explicit `plan_id`.
-3. Persist plan reference in prompt (`plan_id=...`) so policy-gate sets `approvedPlan`.
-4. Do not mutate production files in plan phase unless user explicitly requests draft-only outputs.
+2. When scope, risk, or acceptance is ambiguous, call `ask_user` (see harness-decisions skill) before finalizing the packet.
+3. Capture scope, risks, acceptance criteria, and explicit `plan_id`.
+4. Persist plan reference in prompt (`plan_id=...`) so policy-gate sets `approvedPlan`.
+5. Do not mutate production files in plan phase unless user explicitly requests draft-only outputs.
 
 ## Output
 

package/.agents/skills/harness-sentrux-setup/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: harness-sentrux-setup
+description: Bootstrap Sentrux architectural rules for harness projects — seed architecture.manifest.json, generate merge-safe .sentrux/rules.toml, and document bootstrap vs --force sync. Use during /harness-setup, when adding Sentrux to a repo, or when rules.toml is missing or out of date.
+---
+
+# harness-sentrux-setup
+
+## When to use
+
+- `/harness-setup` Step 4.4 (Sentrux rules bootstrap)
+- Target repo has no `.sentrux/rules.toml` or `harness-verify` reports rules out of date
+- User edited `.pi/harness/sentrux/architecture.manifest.json` (layers, boundaries, constraints)
+
+## Canonical layout
+
+| Path | Role |
+|------|------|
+| `.pi/harness/sentrux/architecture.manifest.json` | Source of truth (layers, boundaries, constraints) |
+| `.sentrux/rules.toml` | Generated Sentrux rules (commit to git) |
+| `.sentrux/.harness-rules-meta.json` | Sync metadata (gitignored) |
+
+Custom TOML **outside** `# --- harness:managed:start/end ---` is preserved on every sync.
+
+## Commands (resolve `UP_PKG` via `.pi/scripts/README.md`)
+
+| Situation | Command |
+|-----------|---------|
+| First-time / harness-setup (idempotent) | `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"` |
+| After manifest edits | `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force` |
+| CI / verify only | `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --check` |
+| In pi session | `/harness-sentrux-sync` (extension; uses `--force`) |
+
+**Bootstrap vs `--force`:** Default bootstrap/sync skips rewriting `rules.toml` when the manifest hash is unchanged. Use `--force` (or `/harness-sentrux-sync`) after changing `architecture.manifest.json` or when verify reports drift.
+
+## Workflow
+
+1. Ensure Sentrux CLI is installed (`harness-setup` Step 2.8 or `harness-cli-verify.sh`).
+2. Run bootstrap from **project root** (not `UP_PKG`):
+   ```bash
+   node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"
+   ```
+3. Optional: `sentrux plugin add-standard` (language plugins; harness-setup Step 2.8).
+4. Merge sentrux MCP into `.pi/mcp.json` if missing (harness-setup Step 4.2).
+5. `sentrux check .` — fix violations or tune manifest `max_cc` / layers.
+6. Commit `.sentrux/rules.toml` and project-specific `architecture.manifest.json`.
+
+## External repos
+
+`harness-seed-project-contracts.mjs` (Step 0.5) copies JSON schemas; bootstrap seeds the Sentrux manifest template when absent and sets `project` from `package.json`.
+
+Do **not** copy ultimate-pi's layer paths blindly into unrelated layouts — edit manifest layers/boundaries for the target repo, then `--force` sync.
+
+## References
+
+- ADR 0009 — `.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md`
+- Scripts — `.pi/scripts/sentrux-rules-sync.mjs`, `harness-sentrux-bootstrap.mjs`
+- Agent — `harness/sentrux-bootstrap` (optional delegate for setup-only runs)

package/.agents/skills/scrapling-web/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: scrapling-web
+description: |
+  Harness web search and scrape via the local harness-web CLI (Scrapling). Use for any
+  non-API web task: search, scrape URLs, map site links, bulk research fetches.
+  Replaces Firecrawl in ultimate-pi harness agents. Triggers on: search the web,
+  scrape URL, fetch page, research online, harness-web, .web/ artifacts.
+allowed-tools:
+  - Bash(python3 *harness-web.py *)
+  - Bash(python3 .pi/scripts/harness-web.py *)
+  - Bash(scrapling *)
+---
+
+# scrapling-web (harness-web)
+
+Local web layer for harness agents — **no API keys**, no Docker compose stack.
+Uses [Scrapling](https://scrapling.readthedocs.io/) under `node $UP_PKG/.pi/scripts/harness-web.py`.
+
+## Install (once per machine)
+
+```bash
+command -v uv &>/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install "scrapling[fetchers]"
+scrapling install   # browser binaries for default stealth scrape
+```
+
+Verify: `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"`
+
+## Output directory
+
+Write artifacts under **`.web/`** (gitignored), not `.firecrawl/`:
+
+| Task | Command |
+|------|---------|
+| Search | `python3 "$UP_PKG/.pi/scripts/harness-web.py" search "query" -o .web/search.json --limit 5` |
+| Scrape URL | `python3 "$UP_PKG/.pi/scripts/harness-web.py" scrape "<url>" -o .web/page.md` |
+| Fast/static scrape | add `--fast` (example.com, raw docs, localhost) |
+| Map same-host links | `python3 "$UP_PKG/.pi/scripts/harness-web.py" map "<url>" -o .web/map.json --limit 50` |
+| Bulk | `python3 "$UP_PKG/.pi/scripts/harness-web.py" bulk-scrape "query" -o .web/bulk/ --limit 3` |
+
+## Search JSON shape (Firecrawl-compatible)
+
+```bash
+jq -r '.data.web[].url' .web/search.json
+jq -r '.data.web[] | "\(.title): \(.url)"' .web/search.json
+```
+
+Each entry: `url`, `title`, `description`.
+
+## Fetch modes
+
+| Mode | When |
+|------|------|
+| **stealth** (default scrape) | Arbitrary URLs, JS-heavy sites |
+| **fast** (`--fast` or `HARNESS_WEB_FETCH_MODE=fast`) | Static docs, example.com, localhost |
+| **auto** (`HARNESS_WEB_FETCH_MODE=auto`) | fast for known-static hosts, else stealth |
+
+Search always uses lightweight HTTP to `html.duckduckgo.com/html/`; on 403/challenge, **one** stealth retry then fail clearly.
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HARNESS_WEB_FETCH_MODE` | `stealth` | `stealth` \| `fast` \| `auto` |
+| `HARNESS_WEB_SEARCH_ENGINE` | `ddg_html` | SERP backend |
+| `HARNESS_WEB_PROXY` | (unset) | Proxy URL for fetch/search |
+| `HARNESS_WEB_RATE_LIMIT_MS` | `2000` | Delay between bulk scrapes |
+| `HARNESS_WEB_TIMEOUT_MS` | `30000` | Per-request timeout |
+
+## Escalation
+
+1. `harness-web search` (HTTP SERP)
+2. `harness-web scrape` (stealth default)
+3. `harness-web scrape --fast` when the target is known static
+4. `scrapling extract …` only when harness-web flags are insufficient
+
+## Gaps vs old Firecrawl
+
+| Firecrawl | Harness path |
+|-----------|----------------|
+| `interact` | No 1:1 — rare flows use gstack browse or Scrapling MCP session |
+| `agent` (structured extract) | Agent reasoning + graphify, or site-specific selectors |
+| `parse` (local PDF) | Dedicated doc tools (pypdf, markitdown) |
+| `crawl` (site-wide) | `map` + `bulk-scrape` or future Spiders integration |
+
+## Ethics
+
+Respect site terms and rate limits. SERP scraping is for dev research, not high-volume harvesting.
+See [Scrapling ethical considerations](https://scrapling.readthedocs.io/en/latest/cli/extract-commands.html#legal-and-ethical-considerations).
+
+## Drawbacks of default stealth scrape
+
+Higher latency and RAM (Chromium per session). Use `--fast` for static docs; reuse one `bulk-scrape` run (single `StealthySession`) instead of many cold starts.

package/.pi/PACKAGING.md

@@ -13,14 +13,14 @@ Aligned with [pi packages](https://github.com/badlogic/pi-mono/blob/main/package
 Pi does **not** define `scripts`, `agents`, or `providers` in the manifest.
 
 - **Harness scripts** → `.pi/scripts/` — run via `node` / `bash` and `$UP_PKG` (see `.pi/scripts/README.md`); do not require npm script aliases in consumer `package.json`
-- **Subagent agents** → `.pi/agents/**/*.md` (loaded by `@tintinweb/pi-subagents` from the **project** `.pi/agents/`; `/harness-setup` seeds them from the installed package)
+- **Subagent agents** → `.pi/agents/**/*.md` on the installed package (`harness/planner`, `pi-pi/agent-expert`, …) via `harness-subagents.ts`; optional **project overrides** at the same relative path under `.pi/agents/`. Version drift: `.pi/harness/agents.manifest.json` (regenerate with `harness-agents-manifest.mjs --write`)
 - **Providers** → install via `bundledDependencies` + user settings, not a separate manifest directory
 
 ## npm `files` allowlist
 
 We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts never ship:
 
-- No `.pi/harness/runs/`, local `model-router.json`, or `firecrawl/.env`
+- No `.pi/harness/runs/`, local `model-router.json`, or `.web/` scrape artifacts
 - Ship `.pi/settings.example.json`, not `.pi/settings.json` (dev checkout uses `".."` local package)
 - Include **`vendor/pi-model-router/`** ([`pi-model-router`](https://github.com/yeliu84/pi-model-router), MIT) — see repo [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md); refresh with `npm run vendor:sync-router`
 

package/.pi/SYSTEM.md

@@ -23,33 +23,31 @@ You are an enterprise coding agent. Optimize for correctness, minimal diffs, and
 ## Web Policy (Mandatory)
 
 > [!warning] No raw HTTP
-> Route **all** web fetches through [[context7]] (API/library docs) or [[firecrawl|Firecrawl CLI]] (all other). No `curl`, `wget`, or raw bash HTTP.
+> Route **all** web fetches through [[context7]] (API/library docs) or **harness-web** / [[scrapling-web]] (all other). No `curl`, `wget`, or raw bash HTTP.
 
 ### API / Library Docs — context7 ONLY
 - `ctx7 library <name> <query>` then `ctx7 docs <id> <query>`
 - context7 owns: function signatures, class APIs, config options, stdlib, framework specs.
 - **Never** use quality-sites for API docs.
 
-### All Non-API Web Fetch — Firecrawl CLI
-See `.agents/skills/firecrawl/SKILL.md` for workflow escalation.
+### All Non-API Web Fetch — harness-web (Scrapling)
+See `.agents/skills/scrapling-web/SKILL.md` for workflow escalation.
 
 | Task | Command |
 |------|---------|
-| Search (no URL) | `firecrawl search "query" --scrape --limit 5 -o .firecrawl/search.json --json` |
-| Scrape (have URL) | `firecrawl scrape "<url>" -o .firecrawl/page.md --only-main-content` |
-| JS-rendered page | `firecrawl scrape "<url>" --wait-for 3000 -o .firecrawl/page.md` |
-| Bulk crawl | `firecrawl crawl "<url>" -o .firecrawl/crawl/` |
-| Interact (clicks/forms) | scrape first, then `firecrawl interact <scrape-id>` |
-| Download site | `firecrawl download <url> -o .firecrawl/download/` |
-| Parse local docs | `firecrawl parse <file> -o .firecrawl/parsed.md` |
-
-- **Search:** firecrawl search only (no DuckDuckGo).
-- **Post-clean (optional):** `firecrawl parse <file> -o .firecrawl/parsed.md` if output has boilerplate.
+| Search (no URL) | `python3 "$UP_PKG/.pi/scripts/harness-web.py" search "query" -o .web/search.json --limit 5` |
+| Scrape (have URL) | `python3 "$UP_PKG/.pi/scripts/harness-web.py" scrape "<url>" -o .web/page.md` |
+| Static / known-simple | add `--fast` to scrape |
+| Map same-host links | `python3 "$UP_PKG/.pi/scripts/harness-web.py" map "<url>" -o .web/map.json` |
+| Bulk search + scrape | `python3 "$UP_PKG/.pi/scripts/harness-web.py" bulk-scrape "query" -o .web/bulk/` |
+
+- **Artifacts:** always write under `.web/` with `-o` (token discipline).
+- **Default scrape:** stealth browser; opt out with `--fast` or `HARNESS_WEB_FETCH_MODE=fast`.
 - **Quality sites:** check `.agents/skills/wiki-autoresearch/references/quality-sites.md` before citing non-API sources. Prefer Tier 1 (StackOverflow, GitHub issues, engineering blogs, arxiv). Exclude AI content farms, mirrors, stale packages.
 - **Research:** use `/wiki-autoresearch <topic>` for deep research. Results are graphified into `graphify-out/`.
 
 ### Missing CLI fallbacks
-- Firecrawl missing: `npx firecrawl --help || npm install -g firecrawl-cli@latest`
+- harness-web / Scrapling missing: `uv tool install "scrapling[fetchers]" && scrapling install` then re-run `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"`
 - Context7 missing: `npm install -g ctx7@latest`
 
 ---
@@ -133,7 +131,7 @@ for conceptual code search before falling back to `ck`:
 ## Prompt-Engineering Execution Rules
 1. Restate objective + constraints before major changes.
 2. Make an explicit plan for multi-step tasks.
-3. Ask only blocking clarifications.
+3. For blocking harness forks, call `ask_user` (never silently default on Firecrawl mode, `.env` creation, scope, or risk).
 4. Prefer deterministic commands and pinned paths.
 5. Validate outcomes with targeted checks/tests.
 6. Report: changed files, why, verification, risks/next steps.

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

@@ -1,6 +1,8 @@
 ---
 description: Adversarial harness reviewer focused on breaking assumptions and surfacing regressions.
 tools: read, bash, grep, find, ls
+extensions: true
+disallowed_tools: ask_user
 thinking: high
 max_turns: 20
 ---
@@ -25,6 +27,7 @@ Pressure test the candidate with adversarial reasoning and reproducible attacks.
 - Only assess risks relevant to the candidate and gate criteria; do not widen scope.
 - Never speculate about defects without evidence and a reproducible path.
 - Severity ordering must be evidence-backed.
+- **Never** call `ask_user`. Emit findings only; parent orchestrator resolves `human_required` via `ask_user`.
 
 ## Output
 

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

@@ -1,6 +1,8 @@
 ---
 description: Independent harness evaluator producing structured pass/fail verdicts.
 tools: read, bash, grep, find, ls
+extensions: true
+disallowed_tools: ask_user
 thinking: high
 max_turns: 20
 ---
@@ -25,6 +27,7 @@ Independently validate execution outcomes and emit structured verdicts.
 - Only evaluate the candidate and gates requested; do not propose unrelated refactors.
 - Never speculate about checks you did not run or artifacts you did not read.
 - Prefer reproducible findings over subjective opinions.
+- **Never** call `ask_user` — review isolation. Set `human_required` in `EvalVerdict`; the parent orchestrator calls `ask_user`.
 
 ## Output
 

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

@@ -1,6 +1,7 @@
 ---
 description: Harness executor that implements only within approved PlanPacket scope.
 tools: read, write, edit, bash, grep, find, ls
+extensions: true
 thinking: medium
 max_turns: 30
 ---
@@ -17,7 +18,9 @@ Implement the approved plan with surgical diffs and strict scope control.
 2. Implement only the approved scope with minimal, reversible diffs.
 3. Run focused validations that map to plan acceptance checks.
 4. Prepare rollback artifacts in all required forms.
-5. Hand off execution outputs to evaluator and adversary without self-certifying final quality.
+5. For **implementation forks** inside approved scope (library choice, flag, rollback tactic), call `ask_user` with 2–4 options — do not guess.
+6. For **plan-level ambiguity** (wrong scope, missing acceptance), stop and recommend `/harness-plan` — do not widen scope.
+7. Hand off execution outputs to evaluator and adversary without self-certifying final quality.
 
 ## Guardrails
 

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

@@ -1,6 +1,7 @@
 ---
 description: Harness meta optimizer proposing policy/prompt/router improvements from trace evidence.
 tools: read, bash, grep, find, ls
+extensions: true
 thinking: high
 max_turns: 25
 ---
@@ -16,7 +17,7 @@ Generate conservative, evidence-backed optimization proposals for harness qualit
 1. Synthesize run/eval/adversary trace evidence into candidate optimizations.
 2. Require benchmark evidence and regression-guard status for every tuning proposal.
 3. Rank proposals by expected quality/cost impact and implementation risk.
-4. Route router edits through proposal artifacts and explicit human approval only.
+4. Route router edits through proposal artifacts and explicit human approval only — use `ask_user` to approve / reject / defer ranked proposals before any apply.
 5. Prefer reversible, minimal changes with explicit risk notes.
 
 ## Guardrails

package/.pi/agents/harness/planner.md

@@ -1,6 +1,7 @@
 ---
 description: Harness planner that compiles strict PlanPacket contracts before execution.
 tools: read, bash, grep, find, ls
+extensions: true
 thinking: medium
 max_turns: 20
 ---
@@ -14,7 +15,7 @@ Compile a strict, machine-readable `PlanPacket` before any implementation happen
 ## Process
 
 1. Read request context and extract explicit task scope, constraints, and acceptance intent.
-2. If scope is ambiguous or contradictory, request clarification and stop without producing an executable plan.
+2. If scope is ambiguous or contradictory, **call `ask_user`** with 2–4 clear options (see harness-decisions skill). Do not emit an executable `PlanPacket` until answered or the user cancels.
 3. Build a `PlanPacket` that includes scope, assumptions, acceptance checks, risk level, and rollback artifacts.
 4. Validate that the output matches `.pi/harness/specs/plan-packet.schema.json`.
 5. Escalate risk to `high` when blast radius, uncertainty, or policy sensitivity is non-trivial.
@@ -26,6 +27,26 @@ Compile a strict, machine-readable `PlanPacket` before any implementation happen
 - Never speculate about repository state you have not read.
 - Do not mutate files.
 - Do not hand off an executable path if plan ambiguity remains unresolved.
+- Use `ask_user` for blocking forks; never guess risk level or scope boundaries.
+
+## ask_user example
+
+When risk or scope is unclear:
+
+```json
+{
+  "question": "What risk level fits this change?",
+  "context": "High risk triggers extra gates and rollback requirements.",
+  "options": [
+    { "title": "low", "description": "Localized change, easy revert" },
+    { "title": "med", "description": "Multiple files or moderate blast radius" },
+    { "title": "high", "description": "Auth, data, infra, or uncertain impact" }
+  ],
+  "allowFreeform": false
+}
+```
+
+If `ask_user` returns cancelled, stop with `needs_clarification` and no `PlanPacket`.
 
 ## Output
 

package/.pi/agents/harness/sentrux-bootstrap.md

@@ -0,0 +1,42 @@
+---
+description: Bootstrap Sentrux rules for a harness project — seed architecture manifest, sync merge-safe rules.toml, verify sentrux check.
+tools: read, bash, grep, find, ls
+extensions: true
+thinking: low
+max_turns: 12
+---
+
+You are the Harness Sentrux Bootstrap agent.
+
+## Mission
+
+Configure initial Sentrux architectural rules for the current project without destroying user customizations.
+
+## Process
+
+1. Resolve `UP_PKG` via `node "$UP_PKG/.pi/scripts/harness-resolve-up-pkg.mjs"` (or `require.resolve('ultimate-pi/package.json')`).
+2. Read **harness-sentrux-setup** skill (package `.agents/skills/harness-sentrux-setup/SKILL.md`).
+3. From **project root** (cwd), run:
+   ```bash
+   node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"
+   ```
+4. If `sentrux` is on PATH, run `sentrux check .` and summarize pass/fail.
+5. Report paths: manifest, `rules.toml`, and whether bootstrap seeded or skipped (up to date).
+
+## When to use `--force`
+
+- User edited `.pi/harness/sentrux/architecture.manifest.json`
+- `sentrux-rules-sync --check` or harness-verify reports drift
+
+Then:
+
+```bash
+node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force
+```
+
+## Guardrails
+
+- Never delete custom TOML outside `harness:managed` markers.
+- Do not overwrite an existing `architecture.manifest.json` — only seed when missing.
+- Do not run `graphify codex install` or unrelated harness-setup steps unless asked.
+- Prefer bundled scripts over hand-editing `rules.toml`.

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

@@ -1,6 +1,7 @@
 ---
 description: Final arbiter for unresolved evaluator vs adversary debates within budget limits.
 tools: read, bash, grep, find, ls
+extensions: true
 thinking: high
 max_turns: 15
 ---
@@ -21,6 +22,7 @@ Resolve unresolved debate outcomes when evaluator and adversary cannot converge
    - agreement=0.40
 4. Respect aggressive debate caps and budget exhaustion rules.
 5. Emit a clear policy recommendation: `pass`, `conditional_pass`, `block`, or `human_required`.
+6. When recommendation is `human_required`, call `ask_user` with structured options (`pass`, `conditional_pass`, `block`, `defer`) instead of free-text-only escalation.
 
 ## Guardrails
 

package/.pi/extensions/harness-ask-user.ts

@@ -0,0 +1,74 @@
+/**
+ * harness-ask-user — structured user decisions for harness planning and setup.
+ * Design references: pi-ask-user, @pi-unipi/ask-user, rpiv-ask-user-question (not vendored).
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { runAskDialog } from "./lib/ask-user/dialog.js";
+import { runAskFallback } from "./lib/ask-user/fallback.js";
+import { renderAskCall, renderAskResult } from "./lib/ask-user/render.js";
+import {
+	AskUserParamsSchema,
+	PROMPT_GUIDELINES,
+	PROMPT_SNIPPET,
+} from "./lib/ask-user/schema.js";
+import type { AskUserParams, DialogResult } from "./lib/ask-user/types.js";
+import {
+	formatResultText,
+	toToolDetails,
+	validateAskParams,
+} from "./lib/ask-user/validate.js";
+
+export default function harnessAskUser(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask User",
+		description:
+			"Ask the user a structured question with options. Use for ambiguous or high-impact harness decisions instead of guessing.",
+		promptSnippet: PROMPT_SNIPPET,
+		promptGuidelines: PROMPT_GUIDELINES,
+		parameters: AskUserParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const validated = validateAskParams(params as AskUserParams);
+			if (typeof validated === "string") {
+				return {
+					content: [{ type: "text", text: validated }],
+					details: {
+						question: params.question ?? "",
+						options: [],
+						response: null,
+						cancelled: true,
+					},
+				};
+			}
+
+			let outcome: DialogResult;
+			if (ctx.hasUI) {
+				outcome = await runAskDialog(ctx.ui, validated);
+			} else {
+				outcome = await runAskFallback(ctx.ui, validated);
+			}
+
+			const details = toToolDetails(
+				validated,
+				outcome.response,
+				outcome.cancelled,
+			);
+			const text = formatResultText(outcome.response, outcome.cancelled);
+
+			return {
+				content: [{ type: "text", text }],
+				details,
+			};
+		},
+
+		renderCall(args, theme) {
+			return renderAskCall(args, theme);
+		},
+
+		renderResult(result, options, theme) {
+			return renderAskResult(result, options, theme);
+		},
+	});
+}

package/.pi/extensions/harness-subagents.ts

@@ -0,0 +1,9 @@
+/**
+ * harness-subagents — package-resolved agents, blackboard, observation-bus handoffs.
+ */
+import { getHarnessPackageRoot } from "./lib/harness-paths.js";
+import { createHarnessSubagentsExtension } from "./lib/harness-subagents/vendored/index.js";
+
+export default createHarnessSubagentsExtension(
+	getHarnessPackageRoot(import.meta.url),
+);