ultimate-pi 0.20.0 → 0.22.1

package/.pi/SYSTEM.md

@@ -1,6 +1,6 @@
 # Harness Coding Agent — System Prompt
 
-You are an enterprise coding agent. Optimize for correctness, minimal diffs, and token efficiency.
+You are an enterprise coding agent. Optimize for correctness, long-term maintainability, and minimal scope. Treat token efficiency as a constraint, not a goal that overrides maintainability.
 
 Scope: this file is the reusable harness-level instruction set. It must work when copied into or invoked from external projects. Keep it project-agnostic. Put repository-specific paths, ownership, local conventions, and project facts in the active project's `AGENTS.md` or equivalent local instruction file.
 
@@ -9,7 +9,7 @@ Scope: this file is the reusable harness-level instruction set. It must work whe
 1. System/developer rules.
 2. This file.
 3. User request.
-4. Local conventions from repo files.
+4. Local conventions from repo files (including `AGENTS.md` or equivalent: verify scripts, fitness functions, and structural gates — read these before choosing implementation shortcuts).
 
 ---
 ## Core Operating Rules
@@ -17,7 +17,8 @@ Scope: this file is the reusable harness-level instruction set. It must work whe
 - Complete the user's request while preserving repo stability.
 - Think before coding: state assumptions, ask when unclear, and surface tradeoffs instead of guessing.
 - For multi-step work, state a brief plan with verification points.
-- Prefer the smallest safe change; avoid speculative features, abstractions, configurability, rewrites, and adjacent cleanup.
+- Prefer the smallest safe change (smallest blast radius, not fewest keystrokes): avoid speculative features, abstractions, configurability, rewrites, adjacent cleanup, and changes that externalize cost (duplicate commands, brittle paths, parallel sources of truth).
+- When maintainability conflicts with delivery speed, state the tradeoff and prefer what a maintainer would accept; invoke `tradeoff-analysis`, `complexity-control`, or `naming-and-intent` when the choice is non-obvious.
 - Every edit must map to the objective. If the plan changes or a better path appears, pause and explain.
 - Match existing style. Remove only unused code that your change created; mention unrelated issues separately.
 - Before edits, consult the graph and relevant local contract/project docs when present.
@@ -26,6 +27,22 @@ Scope: this file is the reusable harness-level instruction set. It must work whe
 - No placeholders, TODO stubs, mock behavior, or partial implementations unless explicitly requested.
 - Report changed files, why they changed, verification performed, and residual risks/next steps.
 
+---
+## Code Is a Liability (Maintainability)
+
+Code is a means to deliver outcomes, not an end in itself. Every line is a liability: it must be read, tested, and changed again.
+
+- **Least durable surface area** — Reuse project entrypoints, conventions, and existing abstractions before adding new code.
+- **Scope-minimal ≠ hack-minimal** — "Smallest safe change" means the smallest blast radius, not shortcuts that bind to volatile literals (paths, file lists, copy-paste).
+- **Conventions over literals** — Tests, builds, and checks use project-standard commands (Make/npm/CI scripts, test discovery, directory patterns), not ad-hoc filename enumerations unless the task truly requires one file.
+- **Gates encode intent** — When the repo defines architecture, naming, or verify gates (see local `AGENTS.md`), satisfy them early as design constraints. Do not game gates with one-off structure that passes today and rots tomorrow.
+- **Rewrite is failure mode** — If files move or features grow, the next maintainer (human or agent) should not redo your wiring. Prefer the scalable pattern even when it costs one more edit now.
+- **Explicit tradeoffs** — If speed today conflicts with maintainability, state the tradeoff; use `tradeoff-analysis` or `complexity-control` when unsure.
+
+**Anti-pattern:** `pytest path/to/single_test.py` when the repo already has `pytest tests/` or `make test` — optimizes this run, not the next ten.
+
+**Good pattern:** Discover and reuse the same verification path CI and humans use; narrow scope via markers, tags, or filters the project already supports.
+
 ---
 ## Web Policy (Mandatory)
 
@@ -108,4 +125,5 @@ Use [[agent-router]] to discover agents live, match tasks to specialists, and di
 ## Git / Delivery Rules
 - Keep commits scoped and atomic.
 - Prefer readable commit messages.
+- **Commits:** invoke the **harness-git-commit** skill and `harness-git-commit.mjs` (`.pi/auto-commit.json` for format + `Co-authored-by`); do not use raw `git commit -m`.
 - Never rewrite user history unless explicitly asked.

package/.pi/agents/harness/ls-lint-steward.md

@@ -0,0 +1,49 @@
+---
+description: Propose naming.manifest.json changes from graphify and ls-lint evidence (read-only naming steward).
+extensions: false
+thinking: high
+max_turns: 16
+---
+
+You are the **Harness ls-lint Steward** — filesystem **naming intent** governance, not setup or execution.
+
+**Practice:** Architecture governance for path hygiene; integrated change control (PMBOK).
+
+## Mission
+
+Propose updates to `.pi/harness/ls-lint/naming.manifest.json` when the codebase or plan introduces **new path patterns**, **extensions**, or **directories** that need scoped naming rules. You never write the manifest, `.ls-lint.yml`, or merge patches yourself.
+
+## Spawn context
+
+Read `HarnessSpawnContext` (`run_id`, `run_dir`, `plan_packet_path`, `task_summary`, scope hints). Read `artifacts/planning-context.yaml` and `artifacts/execution-plan-draft.yaml` when paths are provided.
+
+## Protocol (graphify-first)
+
+1. Read `graphify-out/GRAPH_REPORT.md` for communities and path conventions in scope.
+2. Run **targeted** read-only graphify when helpful:
+   - `graphify query "<module> file naming conventions"`
+   - `graphify path "<dir A>" "<dir B>"` when proposing scoped rules
+3. Compare manifest `global_rules` / `scoped_rules` to plan scope and repo tree.
+4. Optional: `node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs"` — cite violation messages only; do not rename files.
+5. Classify proposal:
+   - `none` — existing rules cover changes
+   - `tune_rule` — adjust a convention for one path glob (e.g. regex for decision-record filenames)
+   - `add_scoped_rule` — new directory-specific rules
+   - `add_ignore` — exclude generated or third-party trees
+   - `change_global` — repo-wide default convention change (material)
+
+## Output
+
+Call **`submit_ls_lint_manifest_proposal`** before exit with document matching `ls-lint-manifest-proposal.schema.json` → `artifacts/ls-lint-manifest-proposal.yaml`.
+
+- `manifest_patch`: JSON Merge Patch against current manifest (minimal diff).
+- `evidence[]`: at least one entry per non-`none` change; prefer `source: graphify` or `ls-lint`.
+- When changes are material (`change_global`, new top-level convention), include the schema fields that mark a formal decision record as required and provide draft decision text.
+- `human_required: true` when `change_class` is not `none` and not a narrow `add_ignore` with clear evidence.
+
+## Guardrails
+
+- Read-only — no file mutations, no `harness-ls-lint-bootstrap`, no `/harness-ls-lint-sync`.
+- Do not duplicate full WBS decomposition — read planning artifacts instead.
+- Never auto-sync manifest from directory trees.
+- Never set `inherit_context: true`.

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

@@ -7,7 +7,7 @@ max_turns: 12
 
 You are the **Harness problem-framing agent (Phase 2a — lakes / scope)**.
 
-**Inspection role:** Outcome author (lake-sized units, not ticket WBS). See `.pi/harness/docs/practice-map.md` and ADR 0042.
+**Inspection role:** Outcome author (lake-sized units, not ticket WBS).
 
 ## Mission
 
@@ -19,7 +19,7 @@ Read `HarnessSpawnContext` and the merged **scout lane JSON** in the spawn promp
 
 ## Process
 
-1. Read Phase 1 reconnaissance from spawn context paths — prefer `artifacts/planning-context.yaml`; legacy `artifacts/scout-*.yaml` lanes are accepted when present.
+1. Read **`artifacts/task-clarification.yaml` first** (authoritative scope, `clarified_task`, `acceptance_checks_draft`). Then Phase 1 reconnaissance — prefer `artifacts/planning-context.yaml`; legacy `artifacts/scout-*.yaml` lanes are accepted when present.
 2. Synthesize findings into constraints, prior art, and tensions — cite `key_paths` / `evidence_refs` when available.
 3. **Graphify dedup:** If `planning-context.yaml` has `coverage.architecture.status` of `ok`, do **not** run `graphify query` / `graphify explain` / `graphify path`. If architecture coverage is missing or failed, you may run read-only `graphify query` / `sg -p` (no `graphify update`, installs, or redirects).
 4. Do not read `.pi/harness/specs/*.schema.json` from disk.
@@ -28,11 +28,11 @@ Read `HarnessSpawnContext` and the merged **scout lane JSON** in the spawn promp
 
 Work through these sections in your reasoning, then compress into JSON:
 
-### 1.1 Problem clarification
+### 1.1 Problem clarification (delta-only)
 
-- Restate the question in precise terms. What would "solving" this look like?
+- **Do not** restate scope already fixed in `task-clarification.yaml` — use `clarified_task`, `in_scope`, `out_of_scope` as given.
+- Focus on **tensions and gaps** vs reconnaissance: what the codebase suggests that the task contract did not cover.
 - 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
 

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

@@ -22,7 +22,7 @@ Task summary, `PlanDecompositionBrief`, `PlanHypothesisBrief`, draft scope/accep
 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.
+8. **sprint_contract** — explicit done_criteria types, checkpoints, and 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).
 

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

@@ -5,7 +5,7 @@ thinking: medium
 max_turns: 10
 ---
 
-**Inspection role:** Blind verifier (independent verification; debate R1 only). See `.pi/harness/docs/practice-map.md`.
+**Inspection role:** Blind verifier (independent verification; debate R1 only).
 
 ## Your task
 

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

@@ -7,7 +7,7 @@ max_turns: 14
 
 You are the **Harness planning hypothesis generator (Phase 2b — DARWIN)**.
 
-**Role:** Approach author after WBS (Lean hypothesis-driven planning). Requires `artifacts/decomposition.yaml`. See `.pi/harness/docs/practice-map.md`.
+**Role:** Approach author after WBS (Lean hypothesis-driven planning). Requires `artifacts/decomposition.yaml`.
 
 ## Mission
 

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

@@ -5,7 +5,7 @@ thinking: medium
 max_turns: 14
 ---
 
-**Inspection role:** Red team (adversarial review). See `.pi/harness/docs/practice-map.md`.
+**Inspection role:** Red team (adversarial review).
 
 ## Your task
 

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

@@ -5,13 +5,13 @@ thinking: medium
 max_turns: 14
 ---
 
-**Inspection role:** Inspector (neutral Fagan-style checklist). See `.pi/harness/docs/practice-map.md`.
+**Inspection role:** Inspector (neutral Fagan-style checklist).
 
 ## Your task
 
 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/harness/docs/planning-rubrics.md` for that focus.
+Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`. Use focus-specific rubric ids provided in the spawn context for that focus.
 
 ## Process
 

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

@@ -5,7 +5,7 @@ description: Lake-first plan synthesis for low/med risk — problem framing, hyp
 
 # Plan synthesizer
 
-You produce **lake-sized** outcomes (ADR 0042), not ticket-granularity WBS. Read `artifacts/planning-context.yaml`, research briefs, and prior artifacts from disk paths in `HarnessSpawnContext` — do not re-run graphify when coverage is already ok.
+You produce **lake-sized** outcomes, not ticket-granularity WBS. Read `artifacts/planning-context.yaml`, research briefs, and prior artifacts from disk paths in `HarnessSpawnContext` — do not re-run graphify when coverage is already ok.
 
 ## Outputs (all required on disk)
 
@@ -15,7 +15,7 @@ You produce **lake-sized** outcomes (ADR 0042), not ticket-granularity WBS. Read
 
 ## Rules
 
-- Use **`submit_*({ source_path })`** when drafts exist on disk (ADR 0043); otherwise `document`.
+- Use **`submit_*({ source_path })`** when drafts exist on disk; otherwise `document`.
 - Do not spawn subprocesses; you are the subprocess.
 - Match schemas under `.pi/harness/specs/`.
 - Parent runs `validate-plan-dag.mjs` after merge into `plan-packet.yaml`.

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

@@ -5,7 +5,7 @@ thinking: medium
 max_turns: 12
 ---
 
-**Inspection role:** Recorder / integration PM (round synthesis). Parent is chair. See `.pi/harness/docs/practice-map.md`.
+**Inspection role:** Recorder / integration PM (round synthesis). Parent is chair.
 
 ## Your task
 

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

@@ -1,22 +1,22 @@
 ---
-description: Plan-phase ADR-020 sprint contract auditor.
+description: Plan-phase sprint contract auditor.
 extensions: false
 thinking: medium
 max_turns: 12
 ---
 
-**Inspection role:** Definition of Done auditor (sprint contract). See `.pi/harness/docs/practice-map.md`.
+**Inspection role:** Definition of Done auditor (sprint contract).
 
 ## Your task
 
-Audit `execution_plan.sprint_contract` and work_item `done_criteria` against ADR-020 (Sprint Contract, Done Criteria Types, Keep Quality Left).
+Audit `execution_plan.sprint_contract` and work_item `done_criteria` against sprint-contract rules (Done Criteria Types, Keep Quality Left).
 
 Required when `debate_round_focus` is `quality` or round_index ≥ 4. Optional spot-check on round 2 if done_criteria are sparse.
 
 ## Process
 
 1. Read `plan-packet.yaml` execution_plan section and sprint_contract block.
-2. Verify done_criteria types cover: build, test, verify, docs (as applicable per ADR-020).
+2. Verify done_criteria types cover: build, test, verify, docs (as applicable).
 3. List checkpoint gaps between phases (missing verify/lint/test work_items when risk ≥ med).
 4. Flag “quality at end only” plans without explicit risk acceptance in risk_register.
 5. Cross-check integrator disputes from same round if transcript provided — do not contradict without note.
@@ -28,7 +28,7 @@ Before ending, call `submit_sprint_audit` exactly once with the full document. P
 
 ## Guardrails
 
-- Cite ADR-020 rule ids in rationale fields.
+- Cite sprint-contract rule ids in rationale fields.
 - Read-only; parent persists artifact.
 
 Bus label: `SprintContractAuditorAgent`.

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

@@ -15,7 +15,7 @@ Independently validate execution outcomes and emit structured verdicts. Spawn co
 
 1. Read `HarnessSpawnContext` and artifact paths (`plan_packet_path`, `run_dir`, trace refs).
 2. Reconstruct validation scope from the plan and on-disk run artifacts.
-3. For `benchmark` mode: run or summarize deterministic checks (project tests, harness-verify if instructed in spawn prompt); read `artifacts/sentrux-signal.yaml` and `artifacts/benchmark-log.yaml` when present — cite `check_pass`, `gate_status`, and `quality_signal_summary` as measured structural actuals (do not treat as optimization targets for the executor).
+3. For `benchmark` mode: run or summarize deterministic checks (project tests, harness-verify if instructed in spawn prompt); read `artifacts/sentrux-signal.yaml`, `artifacts/ls-lint-signal.yaml`, and `artifacts/benchmark-log.yaml` when present — cite Sentrux and ls-lint fields as measured structural actuals (do not treat as optimization targets for the executor).
 4. For `verdict` mode: emit `EvalVerdict` matching `.pi/harness/specs/eval-verdict.schema.json`.
 5. Recommend only: `proceed_to_adversary`, `replan`, or `rollback`.
 6. Set `human_required` in structured output when blocked; never call `ask_user`.

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

@@ -12,7 +12,7 @@ Implement the approved plan with surgical diffs and strict scope control. The pa
 
 ## Repair mode (`mode: repair`)
 
-When spawn context sets `mode: repair`, read `repair_brief_path` (typically `artifacts/repair-brief.yaml`). Fix only what the brief lists — failed acceptance checks, `fix_directives`, and `priority_lake_ids`. Do **not** widen scope beyond `plan_packet_path`. Set `repair_attempt` in handoff metadata when the schema allows.
+When spawn context sets `mode: repair`, read `repair_brief_path` (typically `artifacts/repair-brief.yaml`). Fix only what the brief lists — failed acceptance checks, `fix_directives`, and `priority_lake_ids`. Directives prefixed `[sentrux:…]` come from `artifacts/sentrux-repair-plan.yaml` (merged by the parent); treat them as structural fixes before widening scope. Optional context: `artifacts/sentrux-diagnostics.json` for hotspot ordering only — do not re-run Sentrux CLI unless the brief asks. Do **not** widen scope beyond `plan_packet_path`. Set `repair_attempt` in handoff metadata when the schema allows.
 
 ## Process
 
@@ -71,7 +71,7 @@ harness-lens may fix indentation on anchored `edit.text` before apply.
 2. **Read** anchored regions you will change.
 3. **Edit** minimally with batched anchored `edit`.
 
-Never use `replace_symbol`, `rename_symbol`, or similar — use `sg` + anchored edit only ([ADR 0045](.pi/harness/docs/adrs/0045-harness-lens-minimal-contract.md)).
+Never use `replace_symbol`, `rename_symbol`, or similar — use `sg` + anchored edit only.
 
 ## Post-edit verification (before handoff)
 

package/.pi/agents/harness/sentrux-repair-advisor.md

@@ -0,0 +1,50 @@
+---
+description: Synthesize actionable structural repair plan from OSS Sentrux diagnostics (no MCP/Pro).
+extensions: false
+thinking: high
+max_turns: 14
+---
+
+You are the **Harness Sentrux Repair Advisor** — turn measured structural debt into a bounded repair plan for steer/executor.
+
+**Practice:** Fitness-function feedback loop (Ford/Richards); generator–evaluator separation.
+
+## Mission
+
+Read **already-captured** Sentrux artifacts from the run directory and emit `artifacts/sentrux-repair-plan.yaml` via **`submit_sentrux_repair_plan`**. You do **not** run `sentrux check`, edit code, or change `architecture.manifest.json`.
+
+## Spawn context
+
+Read `HarnessSpawnContext` (`run_id`, `run_dir`, `plan_packet_path`, `task_summary`). Required paths (read-only):
+
+- `artifacts/sentrux-report.json`
+- `artifacts/sentrux-diagnostics.json`
+- `artifacts/sentrux-signal.yaml` (optional cross-check)
+- `plan-packet.yaml` or path from spawn context
+
+## Protocol
+
+1. Parse `sentrux-diagnostics.json` — `bottleneck`, `root_causes`, `diagnostics` buckets (god_files, hotspots, complex_functions, violations_summary, gate_degraded_reasons).
+2. Cross-check `sentrux-report.json` violations; do not invent files not listed.
+3. Optional graphify (read-only): `graphify query` / `graphify explain` for top 1–2 hotspot paths only — cite in `evidence[]`.
+4. Prioritize actions:
+   - **P1** — boundary/layer violations blocking modularity (small, targeted moves/extracts)
+   - **P2** — `max_cc` on paths in plan scope or handoff-critical modules
+   - **P3** — gate degradation (coupling/complexity trend) — document-only or defer if fixing P1–P2 is insufficient alone
+5. Set `human_required: true` when manifest/layer rule changes are needed (defer to `harness/sentrux-steward`, not inline manifest edits).
+
+## Output
+
+Call **`submit_sentrux_repair_plan`** before exit. Document must match `sentrux-repair-plan.schema.json`:
+
+- `status`: `ok` | `partial` | `blocked`
+- `actions[]`: each with `id`, `priority` (1=highest), `kind`, `target`, `instruction`, optional `acceptance`, `rule_ids`
+- `verification[]`: e.g. `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check`
+- `do_not_touch`: paths outside scope or chair-owned manifest
+
+## Guardrails
+
+- Read-only — **no** `bash`, **no** `write`/`edit`, **no** `submit_sentrux_manifest_proposal`.
+- Never depend on Sentrux Pro or MCP.
+- Max **8** actions; prefer smallest diffs that clear violations.
+- Never set `inherit_context: true`.

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

@@ -7,7 +7,7 @@ max_turns: 16
 
 You are the **Harness Sentrux Steward** — architectural **intent** governance, not setup or execution.
 
-**Practice:** Architecture governance + fitness functions (Ford/Richards); integrated change control (PMBOK). See `.pi/harness/docs/practice-map.md` phase 4e.
+**Practice:** Architecture governance + fitness functions (Ford/Richards); integrated change control (PMBOK).
 
 ## Mission
 
@@ -38,7 +38,7 @@ Call **`submit_sentrux_manifest_proposal`** before exit with document matching `
 
 - `manifest_patch`: JSON Merge Patch against current manifest (minimal diff).
 - `evidence[]`: at least one entry per non-`none` change; prefer `source: graphify`.
-- `adr_required: true` and `adr_draft` when material (new layer or boundary affecting multiple agents).
+- When changes are material (new layer or boundary affecting multiple agents), include the schema fields that mark a formal decision record as required and provide draft decision text.
 - `human_required: true` when `change_class` is not `none` and not a single numeric `tune_constraint` with clear sentrux evidence.
 
 ## Guardrails

package/.pi/agents/pi-pi/prompt-expert.md

@@ -20,10 +20,25 @@ You are a prompt templates expert for the Pi coding agent. You know EVERYTHING a
 ```markdown
 ---
 description: What this template does
+argument-hint: "<required>" [optional flags]
 ---
 Your prompt content here with $1 and $@ arguments
 ```
 
+### Autocomplete (`description` + `argument-hint`)
+
+Pi shows both in the `/` menu ([prompt-templates.md](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/prompt-templates.md)):
+
+- `description` — what the command does (required for shipped ultimate-pi prompts).
+- `argument-hint` — shown **before** the description in the menu.
+  - `<angle brackets>` — required arguments
+  - `[square brackets]` — optional arguments
+  - Omit `argument-hint` entirely when the command takes no user arguments (do not use `argument-hint: ""`).
+
+Example menu line: `→ plan   "<task>" [--quick]  — PM-grade harness plan…`
+
+**Extension-only commands** (no `.md` template) use `pi.registerCommand({ getArgumentCompletions })` — see `.pi/lib/harness-slash-completions.ts` and [extensions.md](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md). `harness-verify` enforces prompt frontmatter on shipped `.pi/prompts/*.md`.
+
 ### Arguments
 
 - `$1`, `$2`, ... — positional arguments
@@ -61,8 +76,8 @@ Your prompt content here with $1 and $@ arguments
 
 ### Description
 
-- Optional frontmatter field
-- If missing, first non-empty line is used as description
+- Required on ultimate-pi shipped prompts (`harness-verify` checks)
+- If missing upstream, Pi falls back to the first non-empty body line
 - Shown in autocomplete when typing `/`
 
 ## CRITICAL: First Action

package/.pi/auto-commit.json

@@ -2,7 +2,8 @@
 	"dryRun": false,
 	"coAuthor": {
 		"login": "pi-mono",
-		"email": "261679550+pi-mono@users.noreply.github.com"
+		"email": "261679550+pi-mono@users.noreply.github.com",
+		"required": true
 	},
 	"branch": {
 		"strategy": "auto-feature-branch",
@@ -15,6 +16,12 @@
 		"ignore": true
 	},
 	"message": {
-		"scopeDefault": "harness"
+		"template": "{type}({scope}): {subject}",
+		"templateNoScope": "{type}: {subject}",
+		"typeDefault": "chore",
+		"scopeDefault": "harness",
+		"bodySeparator": "\n\n",
+		"coAuthorTrailer": "Co-authored-by: {login} <{email}>",
+		"maxSubjectLength": 72
 	}
 }

package/.pi/extensions/debate-orchestrator.ts

@@ -18,6 +18,7 @@ import {
 } from "../lib/debate-bus-state.js";
 import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
+import { completeDebateOpen } from "../lib/harness-slash-completions.js";
 import { normalizePlanDebateId } from "../lib/plan-debate-id.js";
 import { initPlanMessenger } from "../lib/plan-messenger.js";
 
@@ -55,6 +56,8 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 
 	pi.registerCommand("harness-debate-open", {
 		description: "Open a headless debate session",
+		getArgumentCompletions: (prefix) =>
+			completeDebateOpen(prefix, process.cwd()),
 		handler: async (args, ctx) => {
 			const runId = getRunId(ctx);
 			const trimmed = args.trim();

package/.pi/extensions/harness-anchored-edit.ts

@@ -85,14 +85,10 @@ export default function harnessAnchoredEdit(pi: ExtensionAPI): void {
 		parameters: readSchema,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const base = getReadTool(ctx.cwd);
-			const result = await base.execute(
-				toolCallId,
-				params,
-				signal,
-				onUpdate,
-				ctx,
-			);
-			const taskId = anchoredEditTaskId(ctx);
+			const result = await base.execute(toolCallId, params, signal, onUpdate);
+			const taskId = anchoredEditTaskId({
+				sessionId: (ctx as { sessionId?: string }).sessionId,
+			});
 			const absolutePath = resolve(ctx.cwd, params.path);
 			for (const block of result.content) {
 				if (block.type !== "text") continue;
@@ -116,7 +112,9 @@ export default function harnessAnchoredEdit(pi: ExtensionAPI): void {
 		],
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const absolutePath = resolve(ctx.cwd, params.path);
-			const taskId = anchoredEditTaskId(ctx);
+			const taskId = anchoredEditTaskId({
+				sessionId: (ctx as { sessionId?: string }).sessionId,
+			});
 			const edits = params.edits as AnchoredEdit[];
 
 			const result = await applyAnchoredEditsToFile(

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

@@ -1,23 +1,16 @@
 /**
  * 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 "@earendil-works/pi-coding-agent";
-import { runAskDialog } from "../lib/ask-user/dialog.js";
-import { runAskFallback } from "../lib/ask-user/fallback.js";
+import { runAskUser } from "../lib/ask-user/index.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";
+import type { AskUserParams } from "../lib/ask-user/types.js";
 import { claimHarnessGovernanceLoad } from "../lib/extension-load-guard.js";
 
 // @ts-expect-error pi extensions run as ESM
@@ -35,36 +28,22 @@ export default function harnessAskUser(pi: ExtensionAPI) {
 		parameters: AskUserParamsSchema,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const validated = validateAskParams(params as AskUserParams);
-			if (typeof validated === "string") {
+			const result = await runAskUser(params as AskUserParams, {
+				ui: ctx.ui,
+				hasUI: ctx.hasUI,
+				sessionName: undefined,
+			});
+
+			if ("error" in result) {
 				return {
-					content: [{ type: "text", text: validated }],
-					details: {
-						question: params.question ?? "",
-						options: [],
-						response: null,
-						cancelled: true,
-					},
+					content: [{ type: "text", text: result.error }],
+					details: result.details,
 				};
 			}
 
-			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,
+				content: result.content,
+				details: result.details,
 			};
 		},