ultimate-pi 0.5.0 → 0.6.1

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

@@ -40,7 +40,7 @@ Custom TOML **outside** `# --- harness:managed:start/end ---` is preserved on ev
    node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"
    ```
 3. Optional: `sentrux plugin add-standard` (language plugins; harness-setup Step 2.8).
-4. Merge sentrux MCP into `.pi/mcp.json` if missing (harness-setup Step 4.2).
+4. Symlink **sentrux** skill into `.pi/skills/` if missing (see harness-setup Step 4.2).
 5. `sentrux check .` — fix violations or tune manifest `max_cc` / layers.
 6. Commit `.sentrux/rules.toml` and project-specific `architecture.manifest.json`.
 

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

@@ -0,0 +1,99 @@
+---
+name: sentrux
+description: |
+  Architectural quality sensor for AI-assisted code — rules, modularity, session baselines,
+  and degradation detection via the Sentrux CLI (not MCP in Pi sessions).
+  Use when the user mentions sentrux, quality signal, architectural health, gate, check rules,
+  modularity, session baseline, degradation, structural drift, or before/after agent work on
+  a harness project. Triggers on: sentrux check, sentrux gate, rules.toml, quality gate.
+---
+
+# sentrux (CLI + harness)
+
+[Sentrux](https://github.com/sentrux/sentrux) scans project structure, enforces `.sentrux/rules.toml`, and compares sessions with **gate** baselines. In **Pi**, use the **`sentrux` binary and bash** — Pi does **not** load `.pi/mcp.json`, so Sentrux MCP tools are unavailable in Pi agent sessions.
+
+## Install (once per machine)
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install sentrux/tap/sentrux` |
+| Linux | `curl -fsSL https://raw.githubusercontent.com/sentrux/sentrux/main/install.sh \| sh` |
+
+Verify:
+
+```bash
+command -v sentrux && sentrux --version
+```
+
+Harness setup also checks via `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"` (resolve `UP_PKG` in `.pi/scripts/README.md`).
+
+Optional language plugins (52 tree-sitter parsers):
+
+```bash
+sentrux plugin add-standard
+```
+
+## Core workflows (project root)
+
+Run from the **target repo root** (where `.sentrux/rules.toml` lives).
+
+| When | Command | Notes |
+|------|---------|-------|
+| CI / pre-commit | `sentrux check .` | Exit 0 = pass, 1 = violations |
+| Before agent work | `sentrux gate --save .` | Save session baseline |
+| After agent work | `sentrux gate .` | Detect degradation vs baseline |
+| Explore structure | `sentrux` or `sentrux .` | GUI treemap (optional) |
+
+Typical agent loop:
+
+```bash
+sentrux gate --save .
+# … agent edits …
+sentrux check .          # rules still pass?
+sentrux gate .           # structural regression?
+```
+
+If `check` fails, fix violations or tune manifest constraints (see **Rules** below). If `gate` reports degradation, inspect changed modules before merging.
+
+## Rules (`.sentrux/rules.toml`)
+
+Committed rules file at repo root. Harness projects sync it from `.pi/harness/sentrux/architecture.manifest.json`.
+
+| Task | Skill / command |
+|------|-----------------|
+| First bootstrap, manifest → rules | **harness-sentrux-setup** — `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"` |
+| Manifest edited | bootstrap `--force` or `/harness-sentrux-sync` |
+| CI drift only | `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --check` |
+
+Custom TOML outside `# --- harness:managed:start/end ---` is preserved on sync. Do **not** hand-edit managed blocks without updating the manifest.
+
+## Harness integration
+
+| Piece | Role |
+|-------|------|
+| `sentrux-rules-sync` extension | Session start: warns if `rules.toml` drifts; auto-sync after plan/merge phases |
+| `/harness-sentrux-sync` | Force-regenerate rules from manifest (pi command) |
+| `harness-verify.mjs` | Runs `sentrux check .` when rules 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 |
+
+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.
+
+## Related skills
+
+- **harness-sentrux-setup** — manifest seeding, rules bootstrap, sync semantics (do not duplicate here)
+- **harness-eval** — verdict + Sentrux signal requirements
+- **harness-governor** — when to re-sync after architecture changes
+
+## Do not
+
+- Assume Sentrux **MCP** tools (`scan`, `session_start`, `health`, etc.) exist in **Pi** — they do not; use CLI only
+- Edit or rely on `.pi/mcp.json` for Pi sessions
+- Duplicate bootstrap/sync steps from **harness-sentrux-setup**
+- Skip `sentrux check .` after large refactors when `.sentrux/rules.toml` exists
+
+## References
+
+- ADR 0006 — `.pi/harness/docs/adrs/0006-sentrux-dual-layer.md`
+- ADR 0009 — `.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md`
+- `CONTRIBUTING.md` — Sentrux quick start

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

@@ -1,30 +1,44 @@
 # ultimate-pi harness — local secrets and paths (gitignored .env)
-# Fill in values below; re-run /harness-setup to add newly introduced keys only.
+# Created by /harness-setup (harness-sync-env.mjs). Re-run setup to append newly introduced keys only.
 
-# Telemetry (set false to disable harness PostHog events)
+# --- Telemetry ---
+# Harness domain events (harness-telemetry.ts); set false to disable harness_* only
 HARNESS_TELEMETRY_ENABLED=true
 
-# harness-web (Scrapling scrape + pluggable search)
+# --- harness-web (Scrapling scrape + pluggable search) ---
 HARNESS_WEB_FETCH_MODE=stealth
 HARNESS_WEB_SEARCH_ENGINE=ddg_html
-# SearXNG (when HARNESS_WEB_SEARCH_ENGINE=searxng):
+# When HARNESS_WEB_SEARCH_ENGINE=searxng (bootstrap via harness-searxng-bootstrap.mjs):
 # HARNESS_WEB_SEARXNG_URL=http://127.0.0.1:8080
 # HARNESS_WEB_PROXY=
 # HARNESS_WEB_RATE_LIMIT_MS=2000
 # HARNESS_WEB_TIMEOUT_MS=30000
 
-# PostHog (optional)
+# --- VCC compaction (env-only; no JSON config files) ---
+# Default: VCC handles /compact and auto-compaction. Set false for Pi LLM compaction:
+# HARNESS_VCC_COMPACTION=false
+# HARNESS_VCC_DEBUG=true
+
+# --- PostHog (optional) ---
+# Project key — required for harness_* telemetry when HARNESS_TELEMETRY_ENABLED=true
 # POSTHOG_API_KEY=
+# POSTHOG_HOST=https://us.i.posthog.com
+# POSTHOG_ENABLED=true
 # POSTHOG_PROJECT_NAME=ultimate-pi
 # POSTHOG_PRIVACY_MODE=false
+# Personal API key — PostHog MCP / posthog-analyst skill only
+# POSTHOG_PERSONAL_API_KEY=
+# POSTHOG_MCP_FEATURES=llm_analytics
 
-# Graphify semantic extract (optional; `graphify update .` needs no key)
+# --- Graphify semantic extract (optional; `graphify update .` needs no key) ---
 # GEMINI_API_KEY=
 # GOOGLE_API_KEY=
 # OPENAI_API_KEY=
+# OPENAI_API_BASE=
 
-# Pi VCC compaction config path (project-relative)
-PI_VCC_CONFIG_PATH=.pi/pi-vcc-config.json
+# --- Wiki / Obsidian vault (optional) ---
+VAULT_WIKI_PATH=vault/wiki
 
-# Wiki / vault (optional — Obsidian layer)
-# VAULT_WIKI_PATH=vault/wiki
+# --- Sentrux gate (optional) ---
+# Require Sentrux stub for harness-verify (see .pi/scripts/harness-verify.mjs)
+# HARNESS_SENTRUX_REQUIRED=true

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

@@ -306,7 +306,7 @@ if gh auth status &>/dev/null; then
 fi
 ```
 
-### 2.8 — sentrux (Architectural Quality Gate + MCP Sensor)
+### 2.8 — sentrux (Architectural Quality Gate)
 
 ```bash
 if ! command -v sentrux &>/dev/null || [ "$FORCE" = "true" ]; then
@@ -319,7 +319,7 @@ Install all 52 language plugins:
 sentrux plugin add-standard 2>/dev/null || echo "Plugins already installed or failed"
 ```
 
-Configure MCP server in `.pi/mcp.json` (see Step 4.2). **Rules.toml bootstrap runs in Step 4.3** (idempotent, merge-safe).
+Ensure the **sentrux** Pi skill is linked (see Step 4.2). **Rules.toml bootstrap runs in Step 4.3** (idempotent, merge-safe).
 
 ## Step 3 — Pi Extension Packages
 
@@ -496,28 +496,27 @@ Ensure `.gitignore` contains:
 !.sentrux/rules.toml
 ```
 
-### 4.2 — MCP Server Configuration
+### 4.2 — Sentrux Pi skill
 
-Add sentrux MCP server to `.pi/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "context-mode": {
-      "command": "context-mode"
-    },
-    "sentrux": {
-      "command": "sentrux",
-      "args": ["--mcp"]
-    }
-  }
-}
+Pi does **not** load `.pi/mcp.json`. Agents use Sentrux via the **CLI** and the **`sentrux`** skill.
+
+From **project root**, ensure the skill is discoverable (idempotent):
+
+```bash
+UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
+SKILL_SRC="$UP_PKG/.agents/skills/sentrux"
+SKILL_DST=".pi/skills/sentrux"
+if [ -d "$SKILL_SRC" ] && [ ! -e "$SKILL_DST" ]; then
+  ln -s "../../.agents/skills/sentrux" "$SKILL_DST"
+  echo "✓ linked $SKILL_DST → sentrux skill"
+elif [ -e "$SKILL_DST" ]; then
+  echo "✓ sentrux skill already present at $SKILL_DST"
+else
+  echo "✗ missing $SKILL_SRC — reinstall ultimate-pi"
+fi
 ```
 
-This gives agents real-time access to structural health metrics:
-- `scan` — quality signal, file count, bottleneck detection
-- `session_start` / `session_end` — baseline comparison, degradation detection
-- `check_rules` — architectural constraint enforcement
-- `health`, `rescan`, `evolution`, `dsm`, `test_gaps`
+After `/reload`, agents can invoke **`/skill:sentrux`** for install paths, `sentrux check`, `sentrux gate --save` / `sentrux gate`, and harness integration. **context-mode** remains a separate `npm:context-mode` package in `.pi/settings.json` (its own MCP bridge inside that extension).
 
 ### 4.3 — Sentrux rules bootstrap (required)
 

package/.pi/scripts/harness-searxng-bootstrap.mjs

@@ -21,6 +21,7 @@ import {
 	readFile,
 	writeFile,
 } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -50,7 +51,10 @@ const SETTINGS_PATH = join(CORE_CONFIG, "settings.yml");
 const COMPOSE_PATH = join(SEARXNG_DIR, "docker-compose.yml");
 const ENV_COMPOSE = join(SEARXNG_DIR, ".env");
 
-const HARNESS_SETTINGS = `use_default_settings: true
+const DEFAULT_SECRET = "ultrasecretkey";
+
+function buildHarnessSettings(secret) {
+	return `use_default_settings: true
 
 search:
   formats:
@@ -58,9 +62,11 @@ search:
     - json
 
 server:
+  secret_key: "${secret}"
   limiter: false
   public_instance: false
 `;
+}
 
 async function exists(path) {
 	try {
@@ -138,6 +144,69 @@ async function readComposePort() {
 	return DEFAULT_PORT;
 }
 
+function parseEnvValue(raw) {
+	return raw.trim().replace(/^["']|["']$/g, "");
+}
+
+async function readComposeSecret() {
+	if (!(await exists(ENV_COMPOSE))) return null;
+	const text = await readFile(ENV_COMPOSE, "utf8");
+	for (const line of text.split("\n")) {
+		const m = line.match(/^SEARXNG_SECRET=(.+)$/);
+		if (m) {
+			const val = parseEnvValue(m[1]);
+			if (val && val !== DEFAULT_SECRET) return val;
+		}
+	}
+	return null;
+}
+
+async function readSettingsSecret() {
+	if (!(await exists(SETTINGS_PATH))) return null;
+	const text = await readFile(SETTINGS_PATH, "utf8");
+	const m = text.match(/^\s*secret_key:\s*["']?([^"'\n#]+)["']?\s*$/m);
+	if (!m) return null;
+	const val = m[1].trim();
+	return val && val !== DEFAULT_SECRET ? val : null;
+}
+
+function generateSecret() {
+	return randomBytes(32).toString("hex");
+}
+
+async function getOrCreateSecret() {
+	return (
+		(await readComposeSecret()) ||
+		(await readSettingsSecret()) ||
+		generateSecret()
+	);
+}
+
+async function upsertComposeSecret(secret) {
+	let content = "";
+	if (await exists(ENV_COMPOSE)) {
+		content = await readFile(ENV_COMPOSE, "utf8");
+	}
+	const line = `SEARXNG_SECRET=${secret}`;
+	const re = /^SEARXNG_SECRET=.*$/m;
+	if (re.test(content)) {
+		content = content.replace(re, line);
+	} else {
+		const sep = content.endsWith("\n") || content.length === 0 ? "" : "\n";
+		content = `${content}${sep}${line}\n`;
+	}
+	await writeFile(ENV_COMPOSE, content, "utf8");
+}
+
+async function settingsNeedUpdate() {
+	if (!(await exists(SETTINGS_PATH))) return true;
+	const text = await readFile(SETTINGS_PATH, "utf8");
+	if (!text.includes("json")) return true;
+	if (text.includes(DEFAULT_SECRET)) return true;
+	if (!/^\s*secret_key:/m.test(text)) return true;
+	return false;
+}
+
 async function ensureSearxngLayout() {
 	await mkdir(CORE_CONFIG, { recursive: true });
 	if (!(await exists(COMPOSE_PATH))) {
@@ -152,12 +221,28 @@ async function ensureSearxngLayout() {
 		}
 		await copyFile(example, ENV_COMPOSE);
 	}
-	const needsSettings =
-		!(await exists(SETTINGS_PATH)) ||
-		!(await readFile(SETTINGS_PATH, "utf8")).includes("json");
-	if (needsSettings) {
-		await writeFile(SETTINGS_PATH, HARNESS_SETTINGS, "utf8");
-		console.log(`✓ Wrote ${SETTINGS_PATH} (json format, limiter off)`);
+	const secret = await getOrCreateSecret();
+	await upsertComposeSecret(secret);
+	console.log(`✓ Set SEARXNG_SECRET in ${ENV_COMPOSE}`);
+	if (await settingsNeedUpdate()) {
+		try {
+			await writeFile(SETTINGS_PATH, buildHarnessSettings(secret), "utf8");
+			console.log(
+				`✓ Wrote ${SETTINGS_PATH} (json format, limiter off, secret_key set)`,
+			);
+		} catch (err) {
+			if (err && typeof err === "object" && "code" in err && err.code === "EACCES") {
+				console.warn(
+					`⚠ Could not write ${SETTINGS_PATH} (permission denied). ` +
+						"SEARXNG_SECRET in .env is set — restart containers. " +
+						`Fix ownership: chown -R $USER:$USER ${SEARXNG_DIR}`,
+				);
+			} else {
+				throw err;
+			}
+		}
+	} else {
+		console.log(`✓ ${SETTINGS_PATH} already configured`);
 	}
 }
 

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [v0.6.1] — 2026-05-17
+
+### 🐛 Fixes
+
+- **SearXNG bootstrap:** generate `SEARXNG_SECRET` and set `server.secret_key` so containers no longer crash on the default `ultrasecretkey` (SearXNG 2026.4+).
+- **Harness env template:** remove obsolete `PI_VCC_CONFIG_PATH`; add env-only VCC, PostHog MCP, Sentrux, and default `VAULT_WIKI_PATH` keys aligned with `/harness-setup`.
+
+## [v0.6.0] — 2026-05-17
+
+### ✨ Features
+
+- **sentrux Pi skill:** CLI-first architectural quality workflows (`check`, `gate`, GUI) via `/skill:sentrux`; symlinked in `.pi/skills`. Pi does not load `.pi/mcp.json`.
+
+### 📖 Documentation
+
+- **harness-setup / CONTRIBUTING:** document Sentrux skill instead of MCP config; update `harness-sentrux-setup` workflow.
+
+### 🔧 Chores
+
+- Remove shipped `.pi/mcp.json` from package `files` list; refresh `graphify-out`.
+
 ## [v0.5.0] — 2026-05-17
 
 ### ✨ Features

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.5.0",
+	"version": "0.6.1",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -59,7 +59,6 @@
 		".pi/model-router.example.json",
 		".pi/settings.example.json",
 		".pi/auto-commit.json",
-		".pi/mcp.json",
 		".pi/SYSTEM.md",
 		".pi/PACKAGING.md",
 		"AGENTS.md",

package/.pi/mcp.json

@@ -1,11 +0,0 @@
-{
-	"mcpServers": {
-		"context-mode": {
-			"command": "context-mode"
-		},
-		"sentrux": {
-			"command": "sentrux",
-			"args": ["--mcp"]
-		}
-	}
-}