ultimate-pi 0.19.1 → 0.22.0

package/.pi/harness/README.md

@@ -11,6 +11,7 @@ Phase 1–2 scaffold for the Pi harness runtime surfaces.
 - `evolution/` - self-healing rules and chaos drills (JSONL-first).
 - `corpus/` - ingest notes for graphify/raw sources.
 - `sentrux/` - `architecture.manifest.json` source for `.sentrux/rules.toml` ([ADR 0009](docs/adrs/0009-sentrux-rules-lifecycle.md)).
+- `ls-lint/` - `naming.manifest.json` source for `.ls-lint.yml` ([ADR 0052](docs/adrs/0052-ls-lint-naming-lifecycle.md)).
 
 This scaffold is intentionally minimal and safe to adopt incrementally.
 
@@ -21,6 +22,8 @@ UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.
 node "$UP_PKG/.pi/scripts/harness-verify.mjs"
 node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"       # idempotent bootstrap (/harness-setup)
 node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force   # after editing sentrux/architecture.manifest.json
+node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs"       # idempotent naming bootstrap
+node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs" --force   # after editing ls-lint/naming.manifest.json
 ```
 
 ## Governance Extensions
@@ -42,6 +45,7 @@ manifest (`package.json`).
 - `observation-bus.ts` - normalized HarnessObservation envelopes
 - `drift-monitor.ts` - interactive replan/proceed on high plan drift
 - `sentrux-rules-sync.ts` - sync `.sentrux/rules.toml` from `sentrux/architecture.manifest.json`
+- `ls-lint-rules-sync.ts` - sync `.ls-lint.yml` from `ls-lint/naming.manifest.json`
 - `review-integrity.ts` - executor/reviewer session-isolation enforcement
 - `test-diff-integrity.ts` - suspicious test-diff detection + adversary escalation
 - `debate-orchestrator.ts` - headless debate bus + consensus packet emission

package/.pi/harness/agents.manifest.json

@@ -1,9 +1,9 @@
 {
 	"schema_version": "1.0.0",
 	"package": "ultimate-pi",
-	"package_version": "0.19.0",
-	"generated_at": "2026-05-26T06:39:19.250Z",
-	"policy_sha256": "f0eb41bc6a877a237087e87762ce11908e93755a42d58f19d6573665b198665f",
+	"package_version": "0.21.0",
+	"generated_at": "2026-05-27T07:05:16.312Z",
+	"policy_sha256": "799782453e74a1d2d15a28715c985c1b5dc4566701ddcce475ec4725294437e4",
 	"agents": {
 		"pi-pi/agent-expert": {
 			"path": ".pi/agents/pi-pi/agent-expert.md",
@@ -31,7 +31,7 @@
 		},
 		"pi-pi/prompt-expert": {
 			"path": ".pi/agents/pi-pi/prompt-expert.md",
-			"sha256": "0d9f5e3e8ab162149cac8f08e159a7b2150a11f53ebe7021e72f8277fa004d0c"
+			"sha256": "043856946673ea7e655e31d71b544e1eac43705839669a3fd223dc16da12a71e"
 		},
 		"pi-pi/skill-expert": {
 			"path": ".pi/agents/pi-pi/skill-expert.md",
@@ -49,10 +49,18 @@
 			"path": ".pi/agents/harness/incident-recorder.md",
 			"sha256": "4efbdb9482b1038e2bd08cae9898aed9ef983903107ddab6c84d51436d5d3296"
 		},
+		"harness/ls-lint-steward": {
+			"path": ".pi/agents/harness/ls-lint-steward.md",
+			"sha256": "e35bf59adf2785e7369a7428793a26691cea43d630e02a9541398cb5a5b1f5dc"
+		},
 		"harness/sentrux-bootstrap": {
 			"path": ".pi/agents/harness/sentrux-bootstrap.md",
 			"sha256": "6132e83b400b6bc381841a09205eda00a2349ec127368f9d164631d73faadd1a"
 		},
+		"harness/sentrux-repair-advisor": {
+			"path": ".pi/agents/harness/sentrux-repair-advisor.md",
+			"sha256": "057618de561d90e597be7a319f3abfa2adaa128d4e92850c50b3e35a447f0371"
+		},
 		"harness/sentrux-steward": {
 			"path": ".pi/agents/harness/sentrux-steward.md",
 			"sha256": "d806cbf2c2e211c6b4c95e35893bc250c8a0fab6fae92190766eab16cd091d51"
@@ -87,7 +95,7 @@
 		},
 		"harness/running/executor": {
 			"path": ".pi/agents/harness/running/executor.md",
-			"sha256": "219c9307567acc95a9c1b1340f899fac860406fb2c2e84f51b4a8c3ba3a0e2ec"
+			"sha256": "0b602c27f8842af3b1bc702623649de8ba775e77fe59bc156bfabf91b5303d85"
 		},
 		"harness/reviewing/adversary": {
 			"path": ".pi/agents/harness/reviewing/adversary.md",
@@ -95,7 +103,7 @@
 		},
 		"harness/reviewing/evaluator": {
 			"path": ".pi/agents/harness/reviewing/evaluator.md",
-			"sha256": "5d6d34654d5c223e5549de9b7b0277b4e28745b2409545ecf3034bd0789c3fa3"
+			"sha256": "885dda59bbbc6193c485a90fa4a867d44f2d4278b6ab001dc548c67529d06452"
 		},
 		"harness/reviewing/tie-breaker": {
 			"path": ".pi/agents/harness/reviewing/tie-breaker.md",
@@ -103,7 +111,7 @@
 		},
 		"harness/planning/decompose": {
 			"path": ".pi/agents/harness/planning/decompose.md",
-			"sha256": "944c7221b7bf8e15cd8cf324c3d5ae135c643c6387d8f611cf9128f9ea922963"
+			"sha256": "ef552be75ff92667e6be90a85768e0804501d00e517b753ca37d174b2561618a"
 		},
 		"harness/planning/execution-plan-author": {
 			"path": ".pi/agents/harness/planning/execution-plan-author.md",

package/.pi/harness/agents.policy.yaml

@@ -9,11 +9,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_batch_execute
-      - ctx_tree
     extensions: false
     read_only: true
   executor:
@@ -26,6 +21,7 @@ kinds:
       - find
       - ls
     extensions: true
+    extension_bundle: executor
     read_only: false
   evaluator:
     tools:
@@ -33,11 +29,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_batch_execute
-      - ctx_tree
     extensions: false
     read_only: true
   adversary:
@@ -46,11 +37,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_batch_execute
-      - ctx_tree
     extensions: false
     read_only: true
   tie_breaker:
@@ -59,11 +45,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_batch_execute
-      - ctx_tree
     extensions: false
     read_only: true
   trace:
@@ -72,11 +53,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_batch_execute
-      - ctx_tree
     extensions: false
     read_only: true
   incident:
@@ -85,11 +61,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_batch_execute
-      - ctx_tree
     extensions: false
     read_only: true
   other:
@@ -98,10 +69,6 @@ kinds:
       - grep
       - find
       - ls
-      - ctx_read
-      - ctx_search
-      - ctx_execute
-      - ctx_tree
     extensions: false
     read_only: true
 agents:
@@ -113,17 +80,30 @@ agents:
     max_turns: 15
     thinking: medium
     submit_tool: submit_human_required
-  harness/sentrux-bootstrap:
+  harness/ls-lint-steward:
     kind: planner
     tools_add:
-      - bash
+      - submit_ls_lint_manifest_proposal
+    extensions: false
+    max_turns: 16
+    thinking: high
+    submit_tool: submit_ls_lint_manifest_proposal
+  harness/sentrux-bootstrap:
+    kind: planner
     extensions: true
     max_turns: 12
     thinking: low
+  harness/sentrux-repair-advisor:
+    kind: evaluator
+    tools_add:
+      - submit_sentrux_repair_plan
+    extensions: false
+    max_turns: 14
+    thinking: high
+    submit_tool: submit_sentrux_repair_plan
   harness/sentrux-steward:
     kind: planner
     tools_add:
-      - bash
       - submit_sentrux_manifest_proposal
     extensions: false
     max_turns: 16
@@ -137,11 +117,40 @@ agents:
     max_turns: 20
     thinking: medium
     submit_tool: submit_human_required
+  harness/web-retrieval/web-answerer:
+    kind: other
+    extensions: false
+    max_turns: 12
+    thinking: medium
+  harness/web-retrieval/web-criteria-verifier:
+    kind: other
+    extensions: false
+    max_turns: 14
+    thinking: medium
+  harness/web-retrieval/web-gap-analyzer:
+    kind: other
+    extensions: false
+    max_turns: 10
+    thinking: low
+  harness/web-retrieval/web-query-expander-fast:
+    kind: other
+    extensions: false
+    max_turns: 5
+    thinking: off
+  harness/web-retrieval/web-query-expander:
+    kind: other
+    extensions: false
+    max_turns: 8
+    thinking: low
+  harness/web-retrieval/web-summarizer:
+    kind: other
+    extensions: false
+    max_turns: 6
+    thinking: low
   harness/running/executor:
     kind: executor
     tools_add:
       - submit_executor_handoff
-    extensions: true
     max_turns: 20
     thinking: medium
     submit_tool: submit_executor_handoff
@@ -172,7 +181,6 @@ agents:
   harness/planning/decompose:
     kind: planner
     tools_add:
-      - bash
       - submit_decomposition_brief
       - submit_human_required
     extensions: false
@@ -197,50 +205,14 @@ agents:
   harness/planning/hypothesis:
     kind: planner
     tools_add:
-      - bash
       - submit_hypothesis_brief
     extensions: false
     max_turns: 14
     thinking: medium
     submit_tool: submit_hypothesis_brief
-  harness/web-retrieval/web-query-expander:
-    kind: other
-    extensions: false
-    max_turns: 8
-    thinking: low
-  harness/web-retrieval/web-query-expander-fast:
-    kind: other
-    extensions: false
-    max_turns: 5
-    thinking: off
-  harness/web-retrieval/web-gap-analyzer:
-    kind: other
-    extensions: false
-    max_turns: 8
-    thinking: low
-  harness/web-retrieval/web-answerer:
-    kind: other
-    extensions: false
-    max_turns: 12
-    thinking: medium
-  harness/web-retrieval/web-summarizer:
-    kind: other
-    extensions: false
-    max_turns: 6
-    thinking: low
-  harness/web-retrieval/web-criteria-verifier:
-    kind: other
-    extensions: false
-    max_turns: 14
-    thinking: medium
   harness/planning/implementation-researcher:
     kind: planner
     tools_add:
-      - bash
-      - web_search
-      - web_fetch
-      - web_find_similar
-      - web_contents
       - submit_implementation_research
     extensions: false
     max_turns: 14
@@ -272,7 +244,6 @@ agents:
   harness/planning/planning-context:
     kind: planner
     tools_add:
-      - bash
       - submit_planning_context
     extensions: false
     max_turns: 12
@@ -297,11 +268,6 @@ agents:
   harness/planning/stack-researcher:
     kind: planner
     tools_add:
-      - bash
-      - web_search
-      - web_fetch
-      - web_find_similar
-      - web_contents
       - submit_stack_brief
     extensions: false
     max_turns: 16

package/.pi/harness/docs/adrs/0051-hash-anchored-executor-edits.md

@@ -0,0 +1,41 @@
+# ADR 0051: Hash-anchored read/edit (Dirac-inspired)
+
+- **Status:** Accepted
+- **Date:** 2026-05-26
+
+## Context
+
+Harness executor sessions used Pi’s `oldText`/`newText` `edit` tool. Line-number and fuzzy-match edits fail when files drift between read and edit, causing retries and token waste. [Dirac](https://github.com/dirac-run/dirac) demonstrates stable **hash-anchored** line targeting with Myers-diff anchor reconciliation; user evaluation chose adoption for the harness.
+
+We already own adjacent concerns: **harness-lens** (LSP, indentation autopatch, format), **shell `sg`** (structural search per ADR 0045), **Sentrux** (architecture gate). We must not duplicate those layers.
+
+## Decision
+
+1. **First-class tools** — [`.pi/extensions/harness-anchored-edit.ts`](../../../extensions/harness-anchored-edit.ts) registers harness `read` and `edit`. No env toggle.
+2. **Vendored core** in [`.pi/lib/harness-anchored-edit/`](../../../lib/harness-anchored-edit/) (Apache-2.0 subset from Dirac: anchor state, line protocol, resolve/apply).
+3. **`read`** output: `AnchorWord§line` per line; anchor state scoped per session/task id.
+4. **`edit`** input: `anchor`, optional `end_anchor` (defaults to `anchor` for single-line replace), `edit_type`, `text`; batch `edits[]` per file.
+5. **Native apply** — `applyAnchoredEditsToFile` writes disk directly (Pi `edit-diff` for unified diff in tool result). No `resolve-to-pi-edit` / no delegation to `createEditTool`.
+6. **Lens** — `tool_call` autopatch corrects indentation on anchored `edits[].text` only ([`anchored-edit-autopatch.ts`](../../../lib/harness-lens/clients/anchored-edit-autopatch.ts)). Legacy `oldText` autopatch remains for non-harness agents that still use Pi edit.
+7. **Executor subprocess bundle** — `kinds.executor.extension_bundle: executor` loads `--no-extensions` plus curated `-e` modules only: `subagent-governance.ts`, `harness-anchored-edit.ts`, `harness-lens.ts` ([`resolveExtensionBundlePaths`](../../../lib/agents-policy.mjs)). Avoids loading the full `.pi/extensions` tree (parent orchestration, run-context phase hooks) while still providing hash-anchored read/edit and lens format-on-result.
+8. **Builtin suppression** — Executor subprocesses use `--no-builtin-tools` + tool allowlist ([`agents.policy.yaml`](../agents.policy.yaml) via `noBuiltinTools` when `extension_bundle` or full extensions apply).
+9. **Executor policy** (prompt + practice-map): batching discipline, post-edit verification before `submit_executor_handoff`, structural refactor via `sg -p` → anchored edit — **no** `replace_symbol` Pi tools.
+10. **Remove** `grep`/`find` from executor tool policy; use `bash` + `sg` for code search.
+
+## Consequences
+
+### Positive
+
+- More stable edits across multi-step executor and steer repair loops.
+- Single anchored edit surface; no Pi text-match shim on the hot path.
+
+### Negative
+
+- Models must learn anchor `§` protocol.
+- Vendored Dirac code must be kept in sync for security fixes (small surface).
+
+## References
+
+- [practice-map.md](../practice-map.md) — Executor edit discipline
+- [ADR 0045](0045-harness-lens-minimal-contract.md) — lens vs sg vs Sentrux
+- [ADR 0044](0044-harness-steer-loop.md) — repair mode uses same edit rules

package/.pi/harness/docs/adrs/0052-ls-lint-naming-lifecycle.md

@@ -0,0 +1,45 @@
+# ADR 0052: ls-lint naming lifecycle
+
+- **Status:** Accepted
+- **Date:** 2026-05-26
+
+## Context
+
+Harness projects need deterministic **filesystem naming** fitness functions alongside Sentrux (code architecture). [ls-lint](https://ls-lint.org/) validates file and directory names from `.ls-lint.yml`. The harness must keep naming rules aligned when conventions evolve — not only on initial setup.
+
+## Decision
+
+1. **Canonical source:** [`.pi/harness/ls-lint/naming.manifest.json`](../../ls-lint/naming.manifest.json) — `global_rules`, `scoped_rules`, `ignores`.
+2. **Generated artifact:** `.ls-lint.yml` at repo root — committed to git; managed block between `harness:managed:start/end` markers.
+3. **Bootstrap (idempotent):** `node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs"` — seeds manifest when missing, runs sync without `--force` when unchanged.
+4. **Re-sync:** `node "$UP_PKG/.pi/scripts/ls-lint-rules-sync.mjs" --force` or `harness-ls-lint-bootstrap.mjs --force`.
+5. **Pi command:** `/harness-ls-lint-sync` via `ls-lint-rules-sync.ts` extension.
+6. **When to sync:**
+   - `/harness-setup` Step 4.3 (after ls-lint CLI install in Step 2.9)
+   - After editing `naming.manifest.json`
+   - On `agent_end` when harness phase is `plan` or `merge`, or `harness-naming-changed`
+   - `harness-verify.mjs` fails if manifest hash ≠ last sync (`--check`)
+7. **Custom rules:** YAML outside the managed block is preserved on sync.
+8. **Skill:** `harness-ls-lint-setup` documents bootstrap vs steward vs sync vs observation.
+9. **Intent evolution:** `harness/ls-lint-steward` proposes JSON Merge Patches via `submit_ls_lint_manifest_proposal` → `artifacts/ls-lint-manifest-proposal.yaml`. Chair applies manifest edits; never silent auto-merge from directory trees.
+10. **Observation vs intent:** `/harness-run` + `/harness-review` run `harness-ls-lint-cli.mjs` → `artifacts/ls-lint-signal.yaml`. Violations after execute → steer/repair. Manifest changes → steward + ADR when material.
+
+## Consequences
+
+### Positive
+
+- Filename drift is caught before merge with millisecond lint cost.
+- Complements Sentrux without conflating path naming with import-layer architecture.
+
+### Negative
+
+- Strict global kebab-case may require scoped rules or ignores for legacy third-party trees (handled via `ignores` and `scoped_rules`).
+
+## References
+
+- ADR 0009 (Sentrux rules lifecycle — parallel pattern)
+- `.pi/agents/harness/ls-lint-steward.md`, `.pi/prompts/harness-ls-lint-steward.md`
+- `.pi/harness/specs/ls-lint-manifest-proposal.schema.json`, `ls-lint-signal.schema.json`
+- `.pi/scripts/harness-ls-lint-bootstrap.mjs`, `ls-lint-rules-sync.mjs`, `harness-ls-lint-cli.mjs`
+- `.agents/skills/harness-ls-lint-setup/SKILL.md`
+- `.pi/extensions/ls-lint-rules-sync.ts`

package/.pi/harness/docs/adrs/0052-sentrux-structured-repair.md

@@ -0,0 +1,38 @@
+# ADR 0052: Sentrux structured repair (OSS diagnostics, no MCP/Pro)
+
+- **Status:** Accepted
+- **Date:** 2026-05-27
+
+## Context
+
+Sentrux OSS `check` / `gate` already compute a full `HealthReport` internally, but the free CLI prints violations and a quality line while dropping rich lists (god files, hotspots, complex functions). Sentrux Pro exposes the same shape via MCP `health`. Ultimate-pi harness needs **actionable “what to fix”** for steer/executor without Pro, MCP, or duplicate scans per review phase.
+
+ADR 0006/0009 cover dual-layer trust and manifest lifecycle; ADR 0044 covers steer via `repair-brief.yaml`. Prior `sentrux-signal.yaml` (v1.0.0) was too thin for repair routing.
+
+## Decision
+
+1. **Single scan per run** — Parent runs `harness-sentrux-report.mjs` once (check + gate capture → `artifacts/sentrux-report.json`). Review reuses artifacts unless missing or `HARNESS_SENTRUX_RESCAN=1`.
+2. **OSS synthesis** — `harness-sentrux-diagnostics.mjs` builds Pro-shaped `artifacts/sentrux-diagnostics.json` from the report (+ optional git churn, graphify refs). `bottleneck_inferred: true` when not from upstream JSON.
+3. **Signal v1.1.0** — `sentrux-signal.yaml` adds `quality_signal`, `violation_count`, `report_path`, `diagnostics_path`, `degraded_reasons`.
+4. **Repair advisor subagent** — `harness/sentrux-repair-advisor` (read-only, no bash) submits `artifacts/sentrux-repair-plan.yaml` via `submit_sentrux_repair_plan`. Spawned in `/harness-review` **Phase 1b** before benchmark evaluator when violations or gate degradation exist.
+5. **Steer merge** — `synthesizeRepairBrief` prepends `[sentrux:…]` directives from the repair plan into `repair-brief.yaml`.
+6. **Upstream optional** — Report script probes `sentrux check --format json`; when available, prefer parsed JSON over stdout heuristics. Track upstream contribution separately (`raw/sentrux-upstream-json-format.md`).
+
+## Consequences
+
+### Positive
+
+- Pro-style repair context without Pro/MCP.
+- One CLI scan per run; review/advisor read paths only.
+- Clear separation: steward = manifest intent; repair advisor = code fixes.
+
+### Negative
+
+- Stdout parsers must track CLI formatting changes until upstream JSON ships.
+- Inferred diagnostics are weaker than native HealthReport serialization.
+
+## References
+
+- [ADR 0006](0006-sentrux-dual-layer.md), [ADR 0009](0009-sentrux-rules-lifecycle.md), [ADR 0044](0044-harness-steer-loop.md)
+- `.pi/scripts/harness-sentrux-report.mjs`, `harness-sentrux-diagnostics.mjs`
+- `.pi/agents/harness/sentrux-repair-advisor.md`

package/.pi/harness/docs/adrs/0053-plan-task-clarification-gate.md

@@ -0,0 +1,39 @@
+# ADR 0053: Plan-phase task clarification gate
+
+- **Status:** Accepted
+- **Date:** 2026-05-26
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+`/harness-plan` began with Phase 1 reconnaissance (graphify, ccc, optional planning-context subprocess) before the user’s intent was unambiguous. That burned tokens and subagent time on the wrong problem. `ask_user` appeared only after expensive work (Phase 3.5 forks, debate, approval). Decompose §1.1 duplicated problem clarification too late.
+
+## Decision
+
+Insert **Phase 0 — Task clarification** before full planning:
+
+1. Parent writes `artifacts/task-clarification.yaml` with a canonical `clarified_task`, scope boundaries, draft acceptance checks, and empty `unresolved_questions` when `status: ready`.
+2. Codebase reads and web-retrieval are **allowed** during Phase 0 when they help disambiguate the task; the boundary is **phase scope** (no planning subagents, no `planning-context.yaml` or downstream plan artifacts), not a tool ban.
+3. Enforce readiness via `harness_artifact_ready`, `write_harness_yaml` / `merge_harness_yaml` write-order, spawn topology, and `validatePlanApprovalReadiness`.
+4. Phase 1 inherits Phase 0 `grounding` / `evidence_refs` and sets `planning-context.task_ref` to the clarification artifact.
+
+## Consequences
+
+### Positive
+
+- Ambiguity resolved before reconnaissance, decomposition, research, and debate.
+- Single task contract artifact for spawn context and scope checks (`task_summary` syncs on gate pass).
+- Prompt-only bypass closed by write-order and spawn guards.
+
+### Negative / trade-offs
+
+- Extra `ask_user` latency on vague tasks (intentional).
+- Overlap between Phase 0 investigation and Phase 1 recon unless orchestrator deduplicates via `grounding`.
+- Three status vocabularies (`task-clarification.status`, `plan-phase-status`, `last_outcome`) — document which applies when.
+
+## References
+
+- [practice-map.md](../practice-map.md) — Phase 0 / 0a rows
+- [.pi/prompts/harness-plan.md](../../../prompts/harness-plan.md)
+- [.pi/lib/plan-task-clarification.ts](../../../lib/plan-task-clarification.ts)
+- [.pi/harness/specs/plan-task-clarification.schema.json](../specs/plan-task-clarification.schema.json)

package/.pi/harness/docs/adrs/0054-harness-native-ask-user.md

@@ -0,0 +1,40 @@
+# ADR 0054: Harness-native ask_user with Glimpse presenters
+
+- **Status:** Accepted
+- **Date:** 2026-05-27
+
+## Context
+
+Harness orchestrators need structured human decisions (`ask_user`) during setup, Phase 0 task clarification, and governance forks. Terminal-only prompts are hard to scan for multi-dimensional forks. [@alexleekt/pi-ask-user-glimpse](https://www.npmjs.com/package/@alexleekt/pi-ask-user-glimpse) ships a rich WebView UI, but installing it as a second Pi extension would duplicate tool registration and couple harness policy to upstream extension lifecycle.
+
+## Decision
+
+1. **Single tool registration** — [`.pi/extensions/harness-ask-user.ts`](../../../extensions/harness-ask-user.ts) registers `ask_user` and delegates to [`runAskUser`](../../../lib/ask-user/index.ts).
+2. **Domain module** — [`.pi/lib/ask-user/`](../../../lib/ask-user/): `types`, `schema`, `validate`, `format`, `policy`, `merge-task-clarification`, `core/questionnaire`.
+3. **Presenter stack** (UI only) — `presenters/tui.ts`, `presenters/headless.ts`, `presenters/glimpse.ts`, routed by `presenters/select.ts`.
+4. **Glimpse as npm dependency** — pinned in [`.pi/npm/package.json`](../../../npm/package.json) (`@alexleekt/pi-ask-user-glimpse`, `glimpseui`). Harness-owned payload builder + parser in `contracts/`; no import of glimpse’s private `tool/ask-user.ts`.
+5. **Response shape** — `AskResponse` includes `kind: "questionnaire"` with `questionnaireDetails[]` (aligned with glimpse, not a parallel `answers` array).
+6. **Routing** — `HARNESS_ASK_USER_UI=auto|tui|glimpse|headless`. `displayMode: "inline"` always uses TUI. Glimpse failure degrades to TUI with `details.ui_degraded: true`. Non-interactive sessions short-circuit via `isHarnessNonInteractive()`.
+7. **Plan approval** — remains on `approve_plan` only; `isPlanApprovalAskUser` in `policy.ts` rejects mistaken plan-approval-shaped `ask_user` calls.
+8. **Formatting** — only [`format.ts`](../../../lib/ask-user/format.ts) emits tool `content` text; presenters return structured `DialogResult`.
+
+## Consequences
+
+### Positive
+
+- One `ask_user` contract for agents; swappable UI without policy forks.
+- Questionnaire mode supports Phase 0 multi-fork clarification in one tool call.
+- WSL/CI can force TUI or headless without removing glimpse for desktop users.
+
+### Negative
+
+- Glimpse bundle adds weight to `.pi/npm` installs (~3.5 MB web assets).
+- `timeout` applies to TUI/headless only in v1; glimpse relies on user Cancel.
+- `approve_plan` still uses TUI inline flow (v1.5: shared presenter + plan markdown context).
+
+## References
+
+- ADR 0053 (task clarification gate)
+- `.agents/skills/harness-decisions/SKILL.md`
+- `test/harness-ask-user.test.mjs`
+- `.pi/lib/ask-user/merge-task-clarification.ts`

package/.pi/harness/docs/adrs/0055-auto-commit-coauthor-lifecycle.md

@@ -0,0 +1,40 @@
+# ADR 0055: Auto-commit co-author lifecycle
+
+- **Status:** Accepted
+- **Date:** 2026-05-27
+
+## Context
+
+Harness agents and `/harness-auto` frequently commit after review. Attribution should credit **pi-mono** (or a project-configured bot) via GitHub `Co-authored-by` trailers. Message shape should be consistent and configurable for external repos installing `ultimate-pi` via npm.
+
+Prior state: `.pi/auto-commit.json` existed with `coAuthor` and `scopeDefault`, but agents used ad-hoc `git commit -m` (e.g. `release.md` hardcoded trailers). No deterministic formatter or skill contract.
+
+## Decision
+
+1. **Canonical config:** `.pi/auto-commit.json` at project root (seeded from package template on bootstrap).
+2. **Merge:** Project file deep-merges over `$UP_PKG/.pi/auto-commit.json`; project `coAuthor` **fully replaces** package co-author fields after merge (no forced pi-mono when project overrides).
+3. **CLI:** `harness-git-commit.mjs` — format message, append trailer idempotently, `git commit -F` (argv spawn, no shell), supports `--amend`, `--dry-run`, `--print-message`, `--root`.
+4. **Bootstrap:** `harness-auto-commit-bootstrap.mjs` seeds project config when missing; personalizes `message.scopeDefault`.
+5. **Skill:** `harness-git-commit` — agents must use CLI; raw `git commit` forbidden in skill text.
+6. **Enforcement:** Skill + prompts + `harness-verify` contract only — **no** `commit-msg` git hook (v1).
+7. **Schema:** `.pi/harness/specs/auto-commit.schema.json` for validation and seeding.
+
+## Consequences
+
+### Positive
+
+- One path for agent commits with configurable conventional-commit templates.
+- External projects customize format and co-author without forking the package.
+
+### Negative
+
+- Bypass remains possible (raw git, subagents, gstack `/ship`, humans).
+- Submodule commits at nested roots do not pick up project config unless `--root` points at owner repo.
+- Squash merges on GitHub may drop co-authors — documented limitation.
+
+## References
+
+- `.pi/auto-commit.json`, `.pi/lib/harness-auto-commit-config.mjs`
+- `.pi/scripts/harness-git-commit.mjs`, `harness-auto-commit-bootstrap.mjs`
+- `.agents/skills/harness-git-commit/SKILL.md`
+- ADR 0052 (parallel bootstrap/sync pattern for ls-lint)

package/.pi/harness/docs/adrs/README.md

@@ -36,6 +36,13 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0047](0047-agt-layered-security.md) | AGT layered security (rings, prompt defense, CI) | Accepted |
 | [0048](0048-tool-call-hook-order.md) | tool_call hook interaction matrix | Accepted |
 | [0049](0049-agents-policy-manifest.md) | agents.policy.yaml SSOT + native discovery | Accepted |
+| [0050](0050-agentic-web-retrieval-stack.md) | Agentic Web Retrieval Stack (WRS) | Accepted |
+| [0051](0051-hash-anchored-executor-edits.md) | Hash-anchored read/edit (Dirac-inspired) | Accepted |
+| [0052](0052-sentrux-structured-repair.md) | Sentrux structured repair (OSS diagnostics) | Accepted |
+| [0052](0052-ls-lint-naming-lifecycle.md) | ls-lint naming lifecycle | Accepted |
+| [0053](0053-plan-task-clarification-gate.md) | Plan-phase task clarification gate | Accepted |
+| [0054](0054-harness-native-ask-user.md) | Harness-native ask_user + Glimpse presenters | Accepted |
+| [0055](0055-auto-commit-coauthor-lifecycle.md) | Auto-commit co-author + message format lifecycle | Accepted |
 
 ## Practice map