ultimate-pi 0.3.1 → 0.4.1

package/.pi/extensions/lib/harness-vcc-settings.ts

@@ -0,0 +1,50 @@
+/**
+ * ultimate-pi VCC configuration — env only (no config files).
+ *
+ * @see https://github.com/sting8k/pi-vcc (vendored algorithm)
+ * @see https://github.com/lllyasviel/VCC
+ */
+
+export interface PiVccSettings {
+	/** When true, VCC handles /compact, auto-threshold, and overflow compaction. */
+	overrideDefaultCompaction: boolean;
+	/** Write debug snapshot to /tmp/pi-vcc-debug.json on each compaction. */
+	debug: boolean;
+}
+
+const FALSE_VALUES = new Set(["false", "0", "off", "no"]);
+const TRUE_VALUES = new Set(["true", "1", "on", "yes"]);
+
+function parseHarnessBool(envName: string, defaultValue: boolean): boolean {
+	const raw = process.env[envName]?.trim().toLowerCase();
+	if (!raw) {
+		return defaultValue;
+	}
+	if (FALSE_VALUES.has(raw)) {
+		return false;
+	}
+	if (TRUE_VALUES.has(raw)) {
+		return true;
+	}
+	return defaultValue;
+}
+
+/** Whether VCC overrides Pi built-in LLM compaction (default: true). */
+export function resolveOverrideDefaultCompaction(): boolean {
+	return parseHarnessBool("HARNESS_VCC_COMPACTION", true);
+}
+
+/** Compaction debug snapshots (default: false). */
+export function resolveVccDebug(): boolean {
+	return parseHarnessBool("HARNESS_VCC_DEBUG", false);
+}
+
+export function loadSettings(): PiVccSettings {
+	return {
+		overrideDefaultCompaction: resolveOverrideDefaultCompaction(),
+		debug: resolveVccDebug(),
+	};
+}
+
+/** No-op — harness VCC does not scaffold or read JSON config files. */
+export function scaffoldSettings(): void {}

package/.pi/extensions/ultimate-pi-vcc.ts

@@ -0,0 +1,17 @@
+/**
+ * In-house VCC compaction for ultimate-pi.
+ *
+ * Vendored compaction core from [pi-vcc](https://github.com/sting8k/pi-vcc),
+ * inspired by [VCC](https://github.com/lllyasviel/VCC).
+ *
+ * Configuration is **env-only** (no JSON config files):
+ * - `HARNESS_VCC_COMPACTION` — default on; set `false` for Pi LLM compaction on /compact + auto-compact
+ * - `HARNESS_VCC_DEBUG` — set `true` to write `/tmp/pi-vcc-debug.json` on compaction
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import registerVcc from "../../vendor/pi-vcc/index.js";
+
+export default function ultimatePiVcc(pi: ExtensionAPI): void {
+	registerVcc(pi);
+}

package/.pi/harness/README.md

@@ -19,7 +19,8 @@ This scaffold is intentionally minimal and safe to adopt incrementally.
 ```bash
 UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
 node "$UP_PKG/.pi/scripts/harness-verify.mjs"
-node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force   # after editing sentrux/architecture.manifest.json
+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
 ```
 
 ## Governance Extensions

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/docs/adrs/0030-inhouse-vcc-compaction.md

@@ -0,0 +1,40 @@
+# ADR 0030: In-house VCC compaction (vendored pi-vcc)
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+ultimate-pi depended on the npm package `@sting8k/pi-vcc` for deterministic, view-oriented session compaction (no LLM summarization call). We need that behavior by default for harness sessions, without an external package coupling, while preserving attribution to upstream [pi-vcc](https://github.com/sting8k/pi-vcc) and the conceptual [VCC](https://github.com/lllyasviel/VCC) work.
+
+## Decision
+
+1. Vendor [sting8k/pi-vcc](https://github.com/sting8k/pi-vcc) under `vendor/pi-vcc/` (refresh via `npm run vendor:sync-vcc`), following the same pattern as `vendor/pi-model-router`.
+2. Load compaction through [`.pi/extensions/ultimate-pi-vcc.ts`](../../../extensions/ultimate-pi-vcc.ts).
+3. Remove `@sting8k/pi-vcc` from `package.json` dependencies and from `.pi/settings*.json` `packages` arrays.
+4. **Configuration is env-only** — no JSON config files (`PI_VCC_CONFIG_PATH` and `.pi/pi-vcc-config.json` are not used).
+5. **Default:** `HARNESS_VCC_COMPACTION` unset → VCC overrides Pi built-in LLM compaction for `/compact`, auto-threshold, and overflow.
+6. **Opt-out:** `HARNESS_VCC_COMPACTION=false` (also `0` / `off`) uses Pi’s LLM compaction for those paths; explicit `/pi-vcc` still uses VCC.
+7. **Debug:** `HARNESS_VCC_DEBUG=true` writes `/tmp/pi-vcc-debug.json` on compaction (default off).
+8. Settings implementation: [`.pi/extensions/lib/harness-vcc-settings.ts`](../../../extensions/lib/harness-vcc-settings.ts).
+9. Compaction telemetry `details.compactor` is `ultimate-pi-vcc`.
+
+## Consequences
+
+### Positive
+
+- No runtime dependency on `@sting8k/pi-vcc` npm; vendored tree is pinned and patchable.
+- Harness-default compaction matches ADR intent (deterministic, recall-friendly summaries).
+- Operators can revert to LLM compaction per project via one env var.
+
+### Negative / trade-offs
+
+- Maintainer must run `vendor:sync-vcc` to pick up upstream pi-vcc fixes.
+- Vendored `loadSettings` re-exports harness env settings from `.pi/extensions/lib/` (couples vendor tree to ultimate-pi layout).
+
+## References
+
+- [THIRD_PARTY_NOTICES.md](../../../../THIRD_PARTY_NOTICES.md)
+- [vendor/pi-vcc/UPSTREAM_PIN.md](../../../../vendor/pi-vcc/UPSTREAM_PIN.md)
+- [`.env.example`](../../../../.env.example) — `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG`

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

@@ -15,6 +15,7 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0007](0007-interactive-drift-monitor.md) | Interactive drift monitor | Accepted |
 | [0008](0008-harness-posthog-telemetry.md) | Harness PostHog telemetry | Accepted |
 | [0009](0009-sentrux-rules-lifecycle.md) | Sentrux rules.toml lifecycle | Accepted |
+| [0030](0030-inhouse-vcc-compaction.md) | In-house VCC compaction (vendored pi-vcc) | Accepted |
 
 ## Template
 

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.