ultimate-pi 0.20.0 → 0.22.0

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

@@ -54,7 +54,73 @@ Parent orchestrator calls **`approve_plan`** with the full `plan_packet` (scroll
 }
 ```
 
-## Example (plan — scope)
+## Phase 0 — task contract (before reconnaissance)
+
+Use during **`/harness-plan` Phase 0** only. Purpose: disambiguate the **task** (scope, success, risk) — not research-backed implementation forks (those are Phase 4 after Phase 3.5).
+
+### Example (Phase 0 — success criteria)
+
+```json
+{
+  "question": "What does done look like for this task?",
+  "context": "The request could mean harness-only changes, product code, or docs. Phase 0 must lock acceptance before reconnaissance.",
+  "options": [
+    { "title": "Harness contract only", "description": "Changes under .pi/harness and prompts; harness-verify passes" },
+    { "title": "End-to-end feature", "description": "User-visible behavior + tests in the app repo" },
+    { "title": "Docs / ADR only", "description": "No runtime code changes" }
+  ],
+  "allowFreeform": true
+}
+```
+
+### Example (Phase 0 — risk when `--risk` omitted)
+
+```json
+{
+  "question": "What risk level should tailor debate and research depth?",
+  "options": [
+    { "title": "Low", "description": "Small, localized change; fast plan-verify profile" },
+    { "title": "Med (default)", "description": "Typical feature or multi-file harness work" },
+    { "title": "High", "description": "Architecture, security, or broad blast radius" }
+  ],
+  "allowFreeform": false
+}
+```
+
+### Example (Phase 0 — questionnaire: scope + success in one call)
+
+Use **`questions[]`** when ≥2 independent dimensions must be resolved together. One tool call per clarification round (not one sub-question per round). After the user answers, merge into `artifacts/task-clarification.yaml` — do not hand-edit YAML for structured fields.
+
+```json
+{
+  "question": "Lock the task contract before reconnaissance",
+  "context": "Phase 0 (ADR 0053). Answer both forks to set scope and acceptance.",
+  "questions": [
+    {
+      "title": "Scope surface",
+      "options": [
+        { "title": "Harness only", "description": ".pi/harness, prompts, verify" },
+        { "title": "Product code", "description": "App/runtime changes + tests" }
+      ]
+    },
+    {
+      "title": "Done means",
+      "options": [
+        { "title": "Tests green", "description": "CI + harness-verify pass" },
+        { "title": "Docs shipped", "description": "User-facing docs updated" }
+      ],
+      "allowMultiple": true
+    }
+  ],
+  "allowComment": true
+}
+```
+
+Parent: map the tool result with `applyAskUserToTaskClarification` (see `.pi/lib/ask-user/merge-task-clarification.ts`) before `write_harness_yaml`.
+
+**Rich UI:** `HARNESS_ASK_USER_UI=auto` tries Glimpse when available; WSL without a display falls back to TUI (`ui_degraded` in tool details). Use `displayMode: "inline"` only for transcript-inline prompts (e.g. under a plan block).
+
+## Example (plan — scope) — Phase 4 fork, not Phase 0
 
 ```json
 {
@@ -69,6 +135,6 @@ 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.
+- **Parent orchestrator** during `/harness-plan` — Phase 0: `ask_user` for **task contract** → `artifacts/task-clarification.yaml`; later: **`approve_plan`** then **`create_plan`** for the plan file; Phase 4: `ask_user` for **dialectical forks** only.
 - `harness/planning/*` (scouts, decompose, hypothesis, hypothesis-eval) — JSON only; no `ask_user` / `approve_plan` / `create_plan`.
 - `harness/reviewing/evaluator`, `harness/reviewing/adversary`, and `harness/reviewing/tie-breaker` — emit `human_required`; the **parent orchestrator** calls `ask_user`.

package/.agents/skills/harness-git-commit/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: harness-git-commit
+description: Commit staged git changes with configurable message format and Co-authored-by trailer from .pi/auto-commit.json. Use when the user asks to commit, when /harness-auto or harness run completion requires a commit, or before any git commit — never use raw git commit -m.
+---
+
+# harness-git-commit
+
+Deterministic commits via bundled CLI. Config merges **project** `.pi/auto-commit.json` over **package** defaults (`$UP_PKG/.pi/auto-commit.json`). Project `coAuthor` fully replaces the package default after merge.
+
+## When to use
+
+- User explicitly asks to create a git commit
+- Harness pipeline step says commit after review pass
+- You are about to run `git commit`, `git commit -m`, or `git commit --amend`
+
+## Forbidden
+
+- **Do not** run raw `git commit` / `git commit -m` / `git commit --amend` in shell
+- **Do not** hardcode `Co-authored-by:` lines in shell or HEREDOC — use this skill's CLI instead of HEREDOC `git commit` when committing harness work
+- **Do not** `git push` unless the user asked
+- **Do not** commit unless the user asked (or harness-auto locked gate explicitly requires it)
+
+## Workflow
+
+1. Resolve `UP_PKG` — see [`$UP_PKG/.pi/scripts/README.md`](../../.pi/scripts/README.md) (`harness-resolve-up-pkg.mjs`).
+2. From **project root** (repo that owns `.pi/auto-commit.json`, not a submodule):
+   ```bash
+   node "$UP_PKG/.pi/scripts/harness-auto-commit-bootstrap.mjs"
+   ```
+3. Stage files: `git add …` (CLI does not stage).
+4. Commit via CLI (examples):
+   ```bash
+   # Conventional subject from config template
+   node "$UP_PKG/.pi/scripts/harness-git-commit.mjs" \
+     --type fix --scope my-app --subject "short description"
+
+   # Full message override (--message wins over --subject)
+   node "$UP_PKG/.pi/scripts/harness-git-commit.mjs" \
+     --message "chore(release): bump version" --body "- detail lines"
+
+   # Amend: preserve body, ensure trailer
+   node "$UP_PKG/.pi/scripts/harness-git-commit.mjs" --amend --message "$(git log -1 --format=%B)"
+
+   # Preview only
+   node "$UP_PKG/.pi/scripts/harness-git-commit.mjs" --dry-run --subject "preview"
+   ```
+
+## Config (project `.pi/auto-commit.json`)
+
+| Field | Purpose |
+|-------|---------|
+| `message.template` | `{type}({scope}): {subject}` when scope set |
+| `message.templateNoScope` | `{type}: {subject}` when scope empty |
+| `message.typeDefault` / `scopeDefault` | Defaults for omitted CLI flags |
+| `message.coAuthorTrailer` | `Co-authored-by: {login} <{email}>` |
+| `coAuthor.login` / `coAuthor.email` | Attribution (project overrides package) |
+| `coAuthor.required` | When false, skip trailer (default true) |
+
+Edit project file to change format or co-author for external repos.
+
+## Limitations
+
+- Skill + CLI only — humans or bypassing agents can still run raw `git commit`
+- Submodule/nested repos: commit from the root that owns `.pi/auto-commit.json`
+- Squash/rebase on GitHub may drop co-author trailers — not fixable here
+- Signed commits: pass `--signoff` on CLI if needed; GPG `-S` is caller responsibility
+
+## References
+
+- ADR 0055 — `.pi/harness/docs/adrs/0055-auto-commit-coauthor-lifecycle.md`
+- Scripts — `harness-git-commit.mjs`, `harness-auto-commit-bootstrap.mjs`
+- Library — `.pi/lib/harness-auto-commit-config.mjs`

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

@@ -17,8 +17,8 @@ description: Enforce harness governance phases, policy gates, budgets, and promo
 2. Check ADRs: constitution (0001), eval promotion (0003), Sentrux (0006), drift (0007), rules lifecycle (0009), AGT policy (0046), AGT security layers (0047).
 3. Tool allow/deny is enforced by AGT `PolicyEngine` + `.pi/harness/policies/*.yaml` (parent `policy-gate`, subprocess `harness-subagent-governance`). Disable with `HARNESS_AGT_POLICY=0`. Audit: `.pi/harness/runs/<run_id>/agt-audit.jsonl`.
 4. For promotion: require eval pass, no abort lock, debate consensus if escalated, Sentrux when `HARNESS_SENTRUX_REQUIRED=true` (`artifacts/sentrux-signal.yaml` from `/harness-run`, not executor self-report).
-5. **Intent vs observation:** Manifest/layer/boundary changes → `/harness-sentrux-steward` proposal + chair approval + ADR when material, then `sentrux-rules-sync --force`. `sentrux check`/`gate` degradation after execute → replan or fix code — do not tune manifest on a single noisy gate.
-6. After approved manifest edits: `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force` or `/harness-sentrux-sync`; emit `harness-architecture-changed` for the extension.
+5. **Intent vs observation:** Sentrux manifest changes → `/harness-sentrux-steward` + chair + ADR when material, then `sentrux-rules-sync --force`. Naming manifest changes → `/harness-ls-lint-steward` + chair, then `ls-lint-rules-sync --force`. CLI degradation after execute → fix paths or replan — do not tune manifest on a single noisy run.
+6. After approved Sentrux edits: `harness-sentrux-bootstrap.mjs --force` or `/harness-sentrux-sync`; emit `harness-architecture-changed`. After naming edits: `harness-ls-lint-bootstrap.mjs --force` or `/harness-ls-lint-sync`; emit `harness-naming-changed`.
 7. Run `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` before claiming release readiness (includes AGT policy doctor).
 
 ## Spec Distiller integration

package/.agents/skills/harness-ls-lint-setup/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: harness-ls-lint-setup
+description: Bootstrap ls-lint filename rules for harness projects — seed naming.manifest.json, generate merge-safe .ls-lint.yml, and document bootstrap vs --force sync. Use during /harness-setup, when adding ls-lint to a repo, or when .ls-lint.yml is missing or out of date.
+---
+
+# harness-ls-lint-setup
+
+## When to use
+
+- `/harness-setup` Step 4.3 (ls-lint naming bootstrap)
+- Target repo has no `.ls-lint.yml` or `harness-verify` reports naming config drift
+- User edited `.pi/harness/ls-lint/naming.manifest.json` (`global_rules`, `scoped_rules`, `ignores`)
+
+## Roles (do not conflate)
+
+| Role | Agent / command | Layer |
+|------|-----------------|-------|
+| **Bootstrap** | `harness-ls-lint-bootstrap.mjs` | Greenfield seed + first sync |
+| **Steward** | `harness/ls-lint-steward`, `/harness-ls-lint-steward` | Proposes manifest changes (`artifacts/ls-lint-manifest-proposal.yaml`); chair applies |
+| **Sync** | `ls-lint-rules-sync.mjs`, `/harness-ls-lint-sync` | Regenerates `.ls-lint.yml` from manifest after intent change |
+| **Observation** | `/harness-run`, `/harness-review` | `harness-ls-lint-cli.mjs` → `artifacts/ls-lint-signal.yaml` |
+
+Never auto-sync manifest from directory trees. Material manifest edits need steward evidence + chair approval (ADR 0052).
+
+## Canonical layout
+
+| Path | Role |
+|------|------|
+| `.pi/harness/ls-lint/naming.manifest.json` | Source of truth |
+| `.ls-lint.yml` | Generated ls-lint config (commit to git) |
+| `.ls-lint/.harness-naming-meta.json` | Sync metadata (gitignored) |
+
+Custom YAML **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-ls-lint-bootstrap.mjs"` |
+| After manifest edits | `node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs" --force` |
+| CI / verify only | `node "$UP_PKG/.pi/scripts/ls-lint-rules-sync.mjs" --check` |
+| Run/review observation | `node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs"` or `--json` |
+| In pi session | `/harness-ls-lint-sync` (extension; uses `--force`) |
+
+## Workflow
+
+1. Ensure ls-lint CLI is installed (`harness-setup` Step 2.9 or `harness-cli-verify.sh`).
+2. Run bootstrap from **project root**:
+   ```bash
+   node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs"
+   ```
+3. `node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs"` — fix violations or tune manifest rules/ignores.
+4. Commit `.ls-lint.yml` and project-specific `naming.manifest.json`.
+
+## References
+
+- ADR 0052 — `.pi/harness/docs/adrs/0052-ls-lint-naming-lifecycle.md`
+- Scripts — `ls-lint-rules-sync.mjs`, `harness-ls-lint-bootstrap.mjs`, `harness-ls-lint-cli.mjs`
+- Agent — `harness/ls-lint-steward`

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

@@ -16,26 +16,28 @@ description: Agent-native harness plans — lakes/context bundles, planning cont
 1. **Parallelism law** — Parallel `tasks` only for independent lanes (implementation ∥ stack ≤2). Never parallelize debate or decompose ∥ hypothesis.
 2. **Two-pizza cap** — Max 1 debate agent, 1 optional planning-context subagent, per `subagent` call.
 3. **No redundant thinkers** — Read upstream YAML; do not re-run graphify in decompose when `planning-context` architecture coverage is ok.
-4. **Sequential chain** — planning context → decompose → hypothesis → research → author → DAG → debate → approve.
+4. **Sequential chain** — task clarification → planning context → decompose → hypothesis → research → author → DAG → debate → approve.
 5. **Tool intelligence** — Parent picks graphify, sg, ccc by task; no mandatory tool-tied scout subprocesses.
 
 ## Workflow (parent orchestrator)
 
-1. **Phase 1:** Compile `artifacts/planning-context.yaml` with tools (default) or optional `planning-context` subagent.
-2. **Sequential** decompose → gate `artifacts/decomposition.yaml`.
-3. **Sequential** hypothesis (requires decomposition).
-4. **Phase 3.5:** `implementation-research.yaml` + `stack.yaml` (parent inline and/or parallel researchers).
-5. Draft `PlanPacket` shell; `ask_user` on material fork **after** Phase 3.5.
-6. `execution-plan-author` → merge `execution_plan`.
-7. **`validate-plan-dag.mjs`** (must pass).
-8. **`harness_plan_debate_eligibility`** — `parallel_probes` spawns plan-evaluator ∥ plan-adversary, then integrator round.
-9. **`approve_plan({ human_summary? })`** / **`create_plan()`** — packet from `plan_packet_path` on disk (path-first).
+1. **Phase 0:** `artifacts/task-clarification.yaml` — investigate (code + web OK), `ask_user` until unambiguous, gate before any planning subagent (**ADR 0053**).
+2. **Phase 1:** Compile `artifacts/planning-context.yaml` with tools (default) or optional `planning-context` subagent; inherit Phase 0 grounding.
+3. **Sequential** decompose → gate `artifacts/decomposition.yaml`.
+4. **Sequential** hypothesis (requires decomposition).
+5. **Phase 3.5:** `implementation-research.yaml` + `stack.yaml` (parent inline and/or parallel researchers).
+6. Draft `PlanPacket` shell; `ask_user` on material fork **after** Phase 3.5 (research-backed; not Phase 0).
+7. `execution-plan-author` → merge `execution_plan`.
+8. **`validate-plan-dag.mjs`** (must pass).
+9. **`harness_plan_debate_eligibility`** — `parallel_probes` spawns plan-evaluator ∥ plan-adversary, then integrator round.
+10. **`approve_plan({ human_summary? })`** / **`create_plan()`** — packet from `plan_packet_path` on disk (path-first).
 
 `--quick` skips semantic coverage in planning context and post-run adversary only — **not** adequate reconnaissance, implementation/stack artifacts (med/high risk), or plan debate.
 
 ## Rules
 
-- On-disk plan artifacts are **YAML** (`plan-packet.yaml`, `research-brief.yaml`, `planning-context.yaml`).
+- On-disk plan artifacts are **YAML** (`task-clarification.yaml`, `plan-packet.yaml`, `research-brief.yaml`, `planning-context.yaml`).
+- Phase 0 allows codebase + web reads; blocks planning subagents and plan artifacts until clarification is `ready`.
 - Subagents read-only; parent writes run artifacts and calls `approve_plan` / `create_plan`.
 - context-mode only on harness paths.
 - Phase 3.5 artifacts required for med/high risk unless documented waiver.

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

@@ -21,7 +21,7 @@ description: >-
 
 | Phase | Practice | Actor | Artifact |
 |-------|----------|-------|----------|
-| 1 | Automated QC + Sentrux fitness functions | Parent | `harness-verify.mjs`, `harness-sentrux-cli.mjs gate`, `benchmark-log.yaml`, `sentrux-signal.yaml` |
+| 1 | Automated QC + fitness functions | Parent | `harness-verify.mjs`, Sentrux gate, ls-lint CLI, `benchmark-log.yaml`, `sentrux-signal.yaml`, `ls-lint-signal.yaml` |
 | 2 | Measure actuals (EVM) | `harness/reviewing/evaluator` benchmark | `eval-verdict.yaml` |
 | 2b | Controlling | Parent | Write `review-outcome.yaml`; route via `remediation_class` (not fail-fast abort) |
 | 6 | Outcome | Parent | `review-outcome.yaml` → `/harness-steer` or replan |

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

@@ -0,0 +1,48 @@
+---
+name: harness-sentrux-repair
+description: |
+  OSS Sentrux capture, diagnostics synthesis, and repair-plan loop for harness runs.
+  Use during /harness-run post-work, /harness-review Phase 1/1b, /harness-steer, or when
+  artifacts/sentrux-report.json or sentrux-repair-plan.yaml are mentioned. No Sentrux Pro or MCP.
+---
+
+# harness-sentrux-repair
+
+Structured structural feedback for ultimate-pi harness (ADR 0052). **OSS CLI only.**
+
+## Artifacts (per run)
+
+| File | Producer |
+|------|----------|
+| `artifacts/sentrux-report.json` | `harness-sentrux-report.mjs` (single check+gate scan) |
+| `artifacts/sentrux-diagnostics.json` | `harness-sentrux-diagnostics.mjs` |
+| `artifacts/sentrux-signal.yaml` | report script `--signal` (schema 1.1.0) |
+| `artifacts/sentrux-repair-plan.yaml` | `harness/sentrux-repair-advisor` via `submit_sentrux_repair_plan` |
+
+## Commands
+
+```bash
+node "$UP_PKG/.pi/scripts/harness-sentrux-report.mjs" --out "<run_dir>" --run-id "<id>" --signal
+node "$UP_PKG/.pi/scripts/harness-sentrux-diagnostics.mjs" --report "<run_dir>/artifacts/sentrux-report.json" --out "<run_dir>" --churn
+```
+
+Re-run capture only when artifacts are missing or `HARNESS_SENTRUX_RESCAN=1`.
+
+## Phase wiring
+
+- **`/harness-run`** — post-executor capture (replaces separate check+gate + hand-written signal).
+- **`/harness-review`** — Phase 1: reuse or capture; Phase 1b: spawn `harness/sentrux-repair-advisor` when violations/degradation.
+- **`/harness-steer`** — `repair-brief.yaml` merges `[sentrux:…]` directives from repair plan.
+
+## Agent boundaries
+
+| Agent | Role |
+|-------|------|
+| `harness/sentrux-steward` | Manifest intent proposals (`submit_sentrux_manifest_proposal`) |
+| `harness/sentrux-repair-advisor` | Code repair plan only (`submit_sentrux_repair_plan`); no bash |
+
+## Related
+
+- **sentrux** skill — CLI install, rules sync, gate loop
+- **harness-sentrux-setup** — bootstrap manifest/rules
+- **harness-review** / **harness-steer** prompts

package/.agents/skills/sentrux/SKILL.md

@@ -42,6 +42,7 @@ Run from the **target repo root** (where `.sentrux/rules.toml` lives), or prefer
 | CI / pre-commit | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check` | Exit 0 = pass, 1 = violations |
 | Before agent work | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save` | Save session baseline |
 | After agent work | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate` | Detect degradation vs baseline |
+| Harness run/review capture | `harness-sentrux-report.mjs` + `harness-sentrux-diagnostics.mjs` | Single scan → JSON artifacts (ADR 0052) |
 | Explore structure | `sentrux` or `sentrux .` | GUI treemap (optional) |
 
 Typical agent loop:
@@ -75,9 +76,10 @@ Custom TOML outside `# --- harness:managed:start/end ---` is preserved on sync.
 | `/harness-sentrux-sync` | Force-regenerate rules from manifest (pi command) |
 | `harness-verify.mjs` | Runs rules sync and Sentrux checks when rules are present |
 | **observation-bus** | Maps `harness-sentrux-signal` custom entries → evaluator observations |
-| **harness-eval** | Evaluate phase may require a Sentrux quality signal (stub or future MCP) per ADR 0006 |
+| **harness-sentrux-repair** skill | Report/diagnostics scripts + `sentrux-repair-advisor` + repair plan artifact |
+| **harness-eval** | Evaluate phase may require a Sentrux quality signal per ADR 0006 |
 
-High level: **execute** uses CLI gate/check around edits; **evaluate** consumes observation-bus quality signals (`harness-sentrux-signal`) alongside tests and policy. Record CLI outcomes in session notes when no bus entry exists yet.
+High level: **execute** runs one capture (`sentrux-report.json`, `sentrux-diagnostics.json`, signal v1.1.0); **review** may spawn **sentrux-repair-advisor** (Phase 1b); **steer** merges repair plan into `repair-brief.yaml`. No Sentrux Pro or MCP in Pi sessions.
 
 ## Related skills
 

package/.agents/skills/wiki-save/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Save the current conversation, answer, or insight into the Obsidian wiki vault as a
   structured note. Analyzes the chat, determines the right note type, creates frontmatter,
   files it in the correct wiki folder, and updates index, log, and hot cache.
-  Triggers on: "save this", "save that answer", "/save", "file this",
+  Triggers on: "save this", "save that answer", "/wiki-save", "/save", "file this",
   "save to wiki", "save this session", "file this conversation", "keep this",
   "save this analysis", "add this to the wiki".
 allowed-tools: Read Write Edit Glob Grep

package/.pi/PACKAGING.md

@@ -10,6 +10,12 @@ Aligned with [pi packages](https://github.com/badlogic/pi-mono/blob/main/package
 | `skills` | `.agents/skills`, `.pi/skills` | Agent Skills + pi-local skills |
 | `prompts` | `.pi/prompts` | Slash-command prompt templates |
 
+### Slash autocomplete
+
+- **Prompt templates** (`.pi/prompts/*.md`): YAML `description` + optional `argument-hint` per [Pi prompt-templates](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/prompt-templates.md). Filename → `/command` (e.g. `harness-plan.md` → `/harness-plan`). `release.md` is dev-only and excluded from npm `files`.
+- **Extension commands** (`.pi/extensions/*.ts`): `pi.registerCommand({ description, getArgumentCompletions? })` for dynamic args (run IDs, `--strict`, etc.). Shared helpers: `.pi/lib/harness-slash-completions.ts`.
+- **Contract:** `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` validates shipped prompt frontmatter.
+
 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`

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). See `.pi/harness/docs/practice-map.md` phase 4e.
+
+## 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 ADRs)
+   - `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`.
+- `adr_required: true` and `adr_draft` when material (`change_global`, new top-level convention).
+- `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

@@ -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/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
 

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. See `.pi/harness/docs/practice-map.md` phase 4e and ADR 0052.
+
+## 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/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