ultimate-pi 0.3.1 → 0.4.0

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

@@ -0,0 +1,80 @@
+{
+	"schema_version": "1.0.0",
+	"package": "ultimate-pi",
+	"package_version": "0.3.1",
+	"generated_at": "2026-05-16T08:44:48.417Z",
+	"agents": {
+		"pi-pi/agent-expert": {
+			"path": ".pi/agents/pi-pi/agent-expert.md",
+			"sha256": "f52f7310adc28c3e51fc21f7e82eb3c0ec8abf33a1936518355c673b21b9a706"
+		},
+		"pi-pi/cli-expert": {
+			"path": ".pi/agents/pi-pi/cli-expert.md",
+			"sha256": "6ecdbc37c60f1da7c68d504187454c95197dd19bd7091d97d136c6fb9e866838"
+		},
+		"pi-pi/config-expert": {
+			"path": ".pi/agents/pi-pi/config-expert.md",
+			"sha256": "c23b9b70a4c326cca2d139f18de48f8db2e0e28fa5ceb8205600f25430822a40"
+		},
+		"pi-pi/ext-expert": {
+			"path": ".pi/agents/pi-pi/ext-expert.md",
+			"sha256": "ae71ccf598217c830ac99e3150365a075bde931778d8bc6305d0270ac959a8a9"
+		},
+		"pi-pi/keybinding-expert": {
+			"path": ".pi/agents/pi-pi/keybinding-expert.md",
+			"sha256": "d8c3d645a507b453d9b338f7a5435232a23e4a00cb7981e3b81a4ce2a0df6bba"
+		},
+		"pi-pi/pi-orchestrator": {
+			"path": ".pi/agents/pi-pi/pi-orchestrator.md",
+			"sha256": "1323fc262112030320bdd7d7866fd69e1b861377bb30fd3553a5e3a4398f9090"
+		},
+		"pi-pi/prompt-expert": {
+			"path": ".pi/agents/pi-pi/prompt-expert.md",
+			"sha256": "0d9f5e3e8ab162149cac8f08e159a7b2150a11f53ebe7021e72f8277fa004d0c"
+		},
+		"pi-pi/skill-expert": {
+			"path": ".pi/agents/pi-pi/skill-expert.md",
+			"sha256": "91732a2479097a2645b6af56171d5cdc1ed67a0896ca54bc4badba250341698f"
+		},
+		"pi-pi/theme-expert": {
+			"path": ".pi/agents/pi-pi/theme-expert.md",
+			"sha256": "3d256049203356d87c36eac2232c0ad6261fec8af02eb15d3144b18a400ed64d"
+		},
+		"pi-pi/tui-expert": {
+			"path": ".pi/agents/pi-pi/tui-expert.md",
+			"sha256": "cd6aaf6ca28e6e65a72ef1dc3c96e3315669ec0f859c148f0f15d0ee74a263d7"
+		},
+		"harness/adversary": {
+			"path": ".pi/agents/harness/adversary.md",
+			"sha256": "17c29621d99dd46cf6ea6566845b502c5e825338b61f073a28cb53f297b2f208"
+		},
+		"harness/evaluator": {
+			"path": ".pi/agents/harness/evaluator.md",
+			"sha256": "71cfb070ec3bbec9d764052ba03fee8692f2db385ad19f15c2f3a157422c1c2b"
+		},
+		"harness/executor": {
+			"path": ".pi/agents/harness/executor.md",
+			"sha256": "02cd2f438d97abb9f35ca6cdab51b3733fc6a9076427cf9c2c93fd4593052539"
+		},
+		"harness/meta-optimizer": {
+			"path": ".pi/agents/harness/meta-optimizer.md",
+			"sha256": "faf81af85d273796f059395287058d2f16fe70903c70b8c6ac9b3c5f12fca69c"
+		},
+		"harness/planner": {
+			"path": ".pi/agents/harness/planner.md",
+			"sha256": "58d9c983bddddd37070f33742409f16474bf7c54bdccb8808fca4926f4adfdad"
+		},
+		"harness/sentrux-bootstrap": {
+			"path": ".pi/agents/harness/sentrux-bootstrap.md",
+			"sha256": "3a0b43b94386a7c541b8a806a37524a5e53f1c8049270db7a420680df5799eeb"
+		},
+		"harness/tie-breaker": {
+			"path": ".pi/agents/harness/tie-breaker.md",
+			"sha256": "c8fd02b3423760d9503e20ea27d3a90aa11326fc38c98f1e7253e67676b15e42"
+		},
+		"harness/trace-librarian": {
+			"path": ".pi/agents/harness/trace-librarian.md",
+			"sha256": "f44439758317b5fbae66b760bb6a1b6df19787d344bf7038712368e8fe0594ee"
+		}
+	}
+}

package/.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md

@@ -11,14 +11,16 @@ Sentrux enforces architecture via [`.sentrux/rules.toml`](https://sentrux.dev/do
 
 1. **Canonical source:** [`.pi/harness/sentrux/architecture.manifest.json`](../../sentrux/architecture.manifest.json) — layers, boundaries, global constraints.
 2. **Generated artifact:** `.sentrux/rules.toml` — committed to git; managed block between `harness:managed:start/end` markers.
-3. **Sync command:** `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force` (resolve `$UP_PKG` via [.pi/scripts/README.md](../../../scripts/README.md)).
-4. **Pi command:** `/harness-sentrux-sync` via `sentrux-rules-sync.ts` extension.
-5. **When to sync:**
-   - `/harness-setup` Step 2.8 (after sentrux install)
+3. **Bootstrap (idempotent):** `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"` — seeds manifest when missing, runs sync without `--force` when unchanged.
+4. **Re-sync command:** `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force` or `harness-sentrux-bootstrap.mjs --force` (resolve `$UP_PKG` via [.pi/scripts/README.md](../../../scripts/README.md)).
+5. **Pi command:** `/harness-sentrux-sync` via `sentrux-rules-sync.ts` extension.
+6. **When to sync:**
+   - `/harness-setup` Step 4.3 (after sentrux CLI install in Step 2.8)
    - After editing `architecture.manifest.json`
    - On `agent_end` when harness phase is `plan` or `merge`
    - `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` fails if manifest hash ≠ last sync (`--check`)
-6. **Custom rules:** TOML outside the managed block is preserved on sync.
+7. **Custom rules:** TOML outside the managed block is preserved on sync.
+8. **Skill:** `harness-sentrux-setup` documents bootstrap vs `--force`.
 
 ## Consequences
 
@@ -34,5 +36,7 @@ Sentrux enforces architecture via [`.sentrux/rules.toml`](https://sentrux.dev/do
 ## References
 
 - ADR 0006 (Sentrux dual layer)
+- `.pi/scripts/harness-sentrux-bootstrap.mjs`
 - `.pi/scripts/sentrux-rules-sync.mjs`
+- `.agents/skills/harness-sentrux-setup/SKILL.md`
 - `.pi/extensions/sentrux-rules-sync.ts`

package/.pi/harness/env.harness.template

@@ -0,0 +1,28 @@
+# ultimate-pi harness — local secrets and paths (gitignored .env)
+# Fill in values below; re-run /harness-setup to add newly introduced keys only.
+
+# Telemetry (set false to disable harness PostHog events)
+HARNESS_TELEMETRY_ENABLED=true
+
+# harness-web (Scrapling) — local fetch/search; no API key
+HARNESS_WEB_FETCH_MODE=stealth
+HARNESS_WEB_SEARCH_ENGINE=ddg_html
+# HARNESS_WEB_PROXY=
+# HARNESS_WEB_RATE_LIMIT_MS=2000
+# HARNESS_WEB_TIMEOUT_MS=30000
+
+# PostHog (optional)
+# POSTHOG_API_KEY=
+# POSTHOG_PROJECT_NAME=ultimate-pi
+# POSTHOG_PRIVACY_MODE=false
+
+# Graphify semantic extract (optional; `graphify update .` needs no key)
+# GEMINI_API_KEY=
+# GOOGLE_API_KEY=
+# OPENAI_API_KEY=
+
+# Pi VCC compaction config path (project-relative)
+PI_VCC_CONFIG_PATH=.pi/pi-vcc-config.json
+
+# Wiki / vault (optional — Obsidian layer)
+# VAULT_WIKI_PATH=vault/wiki

package/.pi/harness/sentrux/architecture.manifest.json

@@ -28,7 +28,12 @@
 		},
 		{
 			"name": "agents",
-			"paths": [".pi/agents/*", ".pi/prompts/*", ".agents/skills/*"],
+			"paths": [
+				".pi/agents/*",
+				".pi/harness/agents.manifest.json",
+				".pi/prompts/*",
+				".agents/skills/*"
+			],
 			"order": 3,
 			"description": "Agent definitions, prompts, and skills"
 		},

package/.pi/prompts/harness-auto.md

@@ -34,7 +34,7 @@ If task is missing, stop and return:
 - Adversarial review is always required.
 - Merge blocking authority is severity-policy-engine.
 - Router tuning is propose-and-approve only.
-- Plan ambiguity must request clarification (no silent guessing).
+- Plan ambiguity must use `ask_user` (harness-decisions skill) — no silent guessing.
 - Rollback artifact must be revert-commit-ready and include:
   - revert command
   - prepared revert branch
@@ -69,7 +69,7 @@ Block commit/PR if any gate fails:
 
 - `--quick` may reduce breadth, never safety gates.
 - `--risk` can tighten behavior, never disable adversary.
-- If risk/ambiguity is high, auto-fallback to manual `harness-plan` and wait for clarification.
+- If risk/ambiguity is high, auto-fallback to manual `harness-plan` and use `ask_user` for blocking forks.
 - If execution must be interrupted safely, run `/harness-abort [reason]`, then restart with `/harness-plan "<task>"`.
 - Always output trace bundle ID and incident/rollback references.
 

package/.pi/prompts/harness-plan.md

@@ -21,14 +21,14 @@ If task is missing, stop and return:
 ## Process
 
 1. Parse the requested task and extract concrete scope and constraints.
-2. If ambiguity blocks safe execution planning, request clarification and stop.
+2. If ambiguity blocks safe execution planning, call `ask_user` (harness-decisions skill). Stop with `needs_clarification` if the user cancels.
 3. Build a `PlanPacket` that is valid against `.pi/harness/specs/plan-packet.schema.json`.
 4. Include rollback artifacts in all required forms.
 
 ## Hard requirements
 
 - Do not run mutating tools in this command.
-- If task scope is ambiguous, request clarification and stop.
+- If task scope is ambiguous, call `ask_user` — do not guess or use prose-only clarification.
 - Produce a `PlanPacket` matching `.pi/harness/specs/plan-packet.schema.json`.
 - Include rollback artifacts in all three forms:
   - revert command

package/.pi/prompts/harness-router-tune.md

@@ -39,8 +39,8 @@ node .pi/harness/router/propose-router-tuning.mjs \
   --proposal-out .pi/harness/router/proposals/<id>.json
 ```
 
-2. Review proposal (human approval required).
-3. Apply only with explicit approver + justification:
+2. Call `ask_user` to approve / reject / request edits before apply (harness-decisions skill).
+3. Apply only after approval, with explicit approver + justification:
 
 ```bash
 node .pi/harness/router/apply-router-proposal.mjs \

package/.pi/prompts/harness-run.md

@@ -34,6 +34,7 @@ If `--plan` is missing, stop and return:
 - Refuse execution if no valid plan packet is provided.
 - Keep edits strictly within approved scope.
 - If scope drift appears, stop and return to `harness-plan`.
+- For **implementation forks** inside approved scope, call `ask_user` with 2–4 options. For plan-level ambiguity, stop and return to `harness-plan`.
 - Record evaluator/adversary prerequisites for downstream gates.
 - Always prepare rollback artifacts as part of execution output.