ultimate-pi 0.20.0 → 0.22.1

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.1",
-	"generated_at": "2026-05-26T07:37:49.163Z",
-	"policy_sha256": "5a1e71f380df7dde8f6d1f33b366da8bba191689476a6440b3bcdbd776dc617a",
+	"package_version": "0.22.0",
+	"generated_at": "2026-05-27T12:07:19.624Z",
+	"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,13 +49,21 @@
 			"path": ".pi/agents/harness/incident-recorder.md",
 			"sha256": "4efbdb9482b1038e2bd08cae9898aed9ef983903107ddab6c84d51436d5d3296"
 		},
+		"harness/ls-lint-steward": {
+			"path": ".pi/agents/harness/ls-lint-steward.md",
+			"sha256": "abbb43da45a2c9c080cd2043384d481a143acaf440e52b657493425218cb951f"
+		},
 		"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": "3c9722806338f680db3d165e633a877e087c1485ad74c2b38781d7ba989b48f0"
+		},
 		"harness/sentrux-steward": {
 			"path": ".pi/agents/harness/sentrux-steward.md",
-			"sha256": "d806cbf2c2e211c6b4c95e35893bc250c8a0fab6fae92190766eab16cd091d51"
+			"sha256": "019740bd4313426edaa36f7fa96471088731abe616282a6e5109e9c538ae34eb"
 		},
 		"harness/trace-librarian": {
 			"path": ".pi/agents/harness/trace-librarian.md",
@@ -87,7 +95,7 @@
 		},
 		"harness/running/executor": {
 			"path": ".pi/agents/harness/running/executor.md",
-			"sha256": "1b8aa6e05ffacc8550569465d47cc8525902b53431e36b1c0f973ca633eab450"
+			"sha256": "e8710179def62a9adaa63ba5b05c3f36dee95da6fd751ef34be773bbee65a5c2"
 		},
 		"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,19 +111,19 @@
 		},
 		"harness/planning/decompose": {
 			"path": ".pi/agents/harness/planning/decompose.md",
-			"sha256": "944c7221b7bf8e15cd8cf324c3d5ae135c643c6387d8f611cf9128f9ea922963"
+			"sha256": "35965f8f8eaa19caee72de1b708178f5ce7bba185f25bed28b9b2ff66c51eaed"
 		},
 		"harness/planning/execution-plan-author": {
 			"path": ".pi/agents/harness/planning/execution-plan-author.md",
-			"sha256": "3b83edca1eb393941e04213c5cabe0e4b180e52df59169ba24904341a369ead5"
+			"sha256": "f0251ac5fb423dda3d6b0b4cff1f63a8e5adfa40806b99454a649c1b0fe3adae"
 		},
 		"harness/planning/hypothesis-validator": {
 			"path": ".pi/agents/harness/planning/hypothesis-validator.md",
-			"sha256": "ee68aa5c04b903320116cfa21cea8f130199fd21e1fd1a8a747830bf53920fdb"
+			"sha256": "70d755da14e146755932c2cb3eb9b828ccd6406b4962d61baeba27c38d9f73dc"
 		},
 		"harness/planning/hypothesis": {
 			"path": ".pi/agents/harness/planning/hypothesis.md",
-			"sha256": "c974f5381aa562589942e8d52b48bdace6663e10caed6bf5f2fb9ce11d84b0bc"
+			"sha256": "5dac1020bc1d5a4100150959d52d983a4860210aa9cbda9120214191c2a17f1d"
 		},
 		"harness/planning/implementation-researcher": {
 			"path": ".pi/agents/harness/planning/implementation-researcher.md",
@@ -123,15 +131,15 @@
 		},
 		"harness/planning/plan-adversary": {
 			"path": ".pi/agents/harness/planning/plan-adversary.md",
-			"sha256": "305cfa6cd0d4e6493a2dad2f01d8cb0b0dddc06df11f871746f6da7124c9d16b"
+			"sha256": "0c9abc088ced31705598baff143df992d435df751b01a9faad9d4af94df16c5a"
 		},
 		"harness/planning/plan-evaluator": {
 			"path": ".pi/agents/harness/planning/plan-evaluator.md",
-			"sha256": "1a6f465f4d400bcf32b9e82a1032ae789354f264af31c8d358b2a0dde7df81bf"
+			"sha256": "f85aba0adbbc7e726a51bfe2d6aa857ab39c8240cd08f06493bc1883ff387c5e"
 		},
 		"harness/planning/plan-synthesizer": {
 			"path": ".pi/agents/harness/planning/plan-synthesizer.md",
-			"sha256": "5bc3ec109179790c196df1328d362c1485cd5ff9295c31c3de93c050330295da"
+			"sha256": "3508126385d338b03f583aaa1f5d75f1cd1fcac8559fed52cd7db11ba1205536"
 		},
 		"harness/planning/planning-context": {
 			"path": ".pi/agents/harness/planning/planning-context.md",
@@ -139,11 +147,11 @@
 		},
 		"harness/planning/review-integrator": {
 			"path": ".pi/agents/harness/planning/review-integrator.md",
-			"sha256": "3f60c41768cad24150718b4a415b9636b0df6892195986a90fc77e2d0a6be537"
+			"sha256": "ea810e3ecf50afe16cf70d12ca3107af94f2272434a72acc5f206bdf7ee89699"
 		},
 		"harness/planning/sprint-contract-auditor": {
 			"path": ".pi/agents/harness/planning/sprint-contract-auditor.md",
-			"sha256": "402c585168c5510b5f22837d2fb157726b928fa59108a8580437ac6ac08d04f5"
+			"sha256": "615feafa48481af0a94b3d6ea9903d58b532575447f5482e60c65e6eb780bfc0"
 		},
 		"harness/planning/stack-researcher": {
 			"path": ".pi/agents/harness/planning/stack-researcher.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:
@@ -22,10 +17,11 @@ kinds:
       - write
       - edit
       - bash
+      - grep
+      - find
       - ls
-    # Subprocess bundle (governance + anchored read/edit + lens) — not full .pi/extensions (parent phase hooks).
+    extensions: true
     extension_bundle: executor
-    extensions: false
     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,6 +117,36 @@ 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:
@@ -171,7 +181,6 @@ agents:
   harness/planning/decompose:
     kind: planner
     tools_add:
-      - bash
       - submit_decomposition_brief
       - submit_human_required
     extensions: false
@@ -196,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
@@ -271,7 +244,6 @@ agents:
   harness/planning/planning-context:
     kind: planner
     tools_add:
-      - bash
       - submit_planning_context
     extensions: false
     max_turns: 12
@@ -296,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/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

@@ -38,6 +38,11 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [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
 

package/.pi/harness/docs/practice-map.md

@@ -23,7 +23,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 1. **Parallelism law** — Parallel `subagent` `tasks` only when outputs are independent inputs to a later merge (implementation ∥ stack research; inspector ∥ adversary in `parallel_probes`). Never parallelize decompose ∥ hypothesis.
 2. **Two-pizza cap per batch** — Max 2 research lanes, max 1 optional `planning-context` subagent, max 1 executor, max 1 debate lane agent per `subagent` call (plan-verify may use 2 probes + integrator in separate batches).
 3. **No redundant thinkers** — If artifact X exists, downstream agents read it; they do not re-derive (e.g. decompose after `planning-context.yaml`).
-4. **Sequential dependency chain** — planning context → problem framing / decompose → hypothesis → research → synthesis/author → DAG → plan-verify → approve → execute → review → (steer)* → policy.
+4. **Sequential dependency chain** — task clarification → planning context → problem framing / decompose → hypothesis → research → synthesis/author → DAG → plan-verify → approve → execute → review → (steer)* → policy.
 5. **Plan-verify (agent-native)** — For `fast`/`standard`, parallel probes then integrator; parent is chair, not participant. Threaded debate remains for `full` until parity.
 6. **Tool intelligence** — Parent chooses graphify, sg, ccc; subprocesses optional. **Path-first:** disk is source of truth; tool args are pointers (ADR 0043).
 
@@ -31,8 +31,9 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 
 | Phase | Practice | Agent translation | Actor | Spawn |
 |-------|----------|---------------------|-------|-------|
-| 0 | Tooling / fast feedback | Pre-index once | Parent + `ccc` | Automatic |
-| 1 | Reconnaissance before WBS | **ContextPack** on disk | Parent tools or optional `planning-context` | No default subprocess |
+| 0 | Task clarification | Task contract on disk; code + web OK | Parent + `ask_user` | No subprocess |
+| 0a | Tooling / fast feedback | Pre-index once | Parent + `ccc` | Automatic |
+| 1 | Reconnaissance before WBS | **ContextPack** on disk | Parent tools or optional `planning-context` | After task-clarification gate |
 | 2a | Problem framing / lakes | Lake outcomes, not ticket tree | `decompose` or synthesizer section | Sequential after context gate |
 | 2b | Hypothesis-driven approach | Falsifiable claim grounded in framing | `hypothesis` or synthesizer | After `artifacts/decomposition.yaml` |
 | 3.5 | Spike / external research | Paths in research brief | Researchers optional | Artifacts required |
@@ -41,6 +42,8 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 | 4c | Deterministic quality gate | Script, not LLM | `validate-plan-dag.mjs` | Parent; hard stop |
 | 4d | Tailor process to risk | Probe depth, not meeting count | `harness_plan_debate_eligibility` | Pre plan-verify |
 | 4e | Architectural intent | Fitness-function spec | `harness/sentrux-steward` optional | When structural risk |
+| 4e″ | Structural repair plan | OSS diagnostics → actions | `harness/sentrux-repair-advisor` | `/harness-review` when violations/degraded |
+| 4e′ | Naming intent | Filename convention spec | `harness/ls-lint-steward` optional | New paths/extensions |
 | 5 | Plan-verify (Review Gate) | Parallel probes + integrator | Debate cast / probes | `parallel_probes` or threaded |
 | 6 | Baseline + approve | Path-only `approve_plan` | Parent | `approve_plan`, `create_plan` |
 
@@ -69,9 +72,9 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 | Step | Practice | Agent translation | Actor |
 |------|----------|-------------------|-------|
 | Gate | Change control | `plan_ready` required | Parent |
-| Pre-work | Fitness baseline | `sentrux gate --save` | Parent |
+| Pre-work | Fitness baseline | `sentrux gate --save` + ls-lint pre-check | Parent |
 | Work | Single implementer | `executor_strategy` | `harness/running/executor` |
-| Post-work | Observation | `sentrux check` / signal artifact | Parent |
+| Post-work | Observation | `harness-sentrux-report.mjs` + diagnostics; ls-lint signal | Parent |
 | Handoff | Generator–evaluator | `submit_executor_handoff` | Executor |
 | Next | Always verify | **`/harness-review`** (not replan on blocked) | Parent routing |
 
@@ -91,6 +94,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 | Phase | Practice | Agent translation | Actor |
 |-------|----------|-------------------|-------|
 | 1 | Automated QC + fitness | Deterministic first | Parent scripts |
+| 1b | Structural repair plan | OSS diagnostics → actions | `sentrux-repair-advisor` |
 | 2 | Measure vs plan | Benchmark on disk | `evaluator` benchmark |
 | 3 | Policy audit | Verdict (no fail-fast skip) | `evaluator` verdict |
 | 4 | Red team | Tiered: full attempt 1, lite 2+ steer | `adversary` |
@@ -111,6 +115,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 
 ## Anti-patterns
 
+- **Do not** write `planning-context.yaml` or spawn planning subagents before `artifacts/task-clarification.yaml` is `ready` (enforced in `write_harness_yaml`, spawn topology, `approve_plan`).
 - **Do not** spawn `decompose` and `hypothesis` in the same parallel `tasks` batch.
 - **Do not** run `graphify query` in `decompose` when planning-context coverage is ok (ADR 0041).
 - **Do not** parallelize threaded debate lanes in one batch (except `parallel_probes` inspector ∥ adversary per ADR 0042).