ultimate-pi 0.11.0 → 0.13.0

package/.pi/scripts/validate-plan-dag.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * validate-plan-dag — deterministic ExecutionPlan DAG checks (YAML packet in).
+ */
+
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readYamlFile, writeYamlFile } from "../lib/harness-yaml.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const MINIMUMS = {
+	low: { phases: 2, work_items: 5, acceptance_checks: 3, risks: 0 },
+	med: { phases: 3, work_items: 8, acceptance_checks: 5, risks: 3 },
+	high: { phases: 4, work_items: 12, acceptance_checks: 8, risks: 3 },
+};
+
+function fail(msg) {
+	console.error(`validate-plan-dag: FAIL: ${msg}`);
+	process.exit(1);
+}
+
+function ok(msg) {
+	console.log(`  ✓ ${msg}`);
+}
+
+function topoSort(workItems) {
+	const ids = new Set(workItems.map((w) => w.work_item_id));
+	const adj = new Map();
+	for (const w of workItems) {
+		adj.set(w.work_item_id, (w.depends_on ?? []).filter((d) => ids.has(d)));
+	}
+	const visited = new Set();
+	const stack = new Set();
+	const order = [];
+	const cycles = [];
+
+	function dfs(n, path) {
+		if (stack.has(n)) {
+			cycles.push([...path, n]);
+			return;
+		}
+		if (visited.has(n)) return;
+		visited.add(n);
+		stack.add(n);
+		for (const d of adj.get(n) ?? []) dfs(d, [...path, n]);
+		stack.delete(n);
+		order.push(n);
+	}
+
+	for (const id of ids) dfs(id, []);
+	order.reverse();
+	return { order, cycles };
+}
+
+function computeCriticalPath(workItems) {
+	const ids = new Set(workItems.map((w) => w.work_item_id));
+	const len = new Map();
+	for (const w of workItems) len.set(w.work_item_id, 0);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const w of workItems) {
+			const deps = (w.depends_on ?? []).filter((d) => ids.has(d));
+			const base = deps.length === 0 ? 0 : Math.max(...deps.map((d) => len.get(d) ?? 0)) + 1;
+			if (base > (len.get(w.work_item_id) ?? 0)) {
+				len.set(w.work_item_id, base);
+				changed = true;
+			}
+		}
+	}
+	const maxLen = Math.max(0, ...len.values());
+	const end = workItems.filter((w) => len.get(w.work_item_id) === maxLen).map((w) => w.work_item_id);
+	// Backtrack one longest path
+	const path = [];
+	let cur = end[0];
+	if (!cur) return [];
+	const byId = new Map(workItems.map((w) => [w.work_item_id, w]));
+	while (cur) {
+		path.unshift(cur);
+		const w = byId.get(cur);
+		const deps = (w?.depends_on ?? []).filter((d) => ids.has(d));
+		if (deps.length === 0) break;
+		cur = deps.reduce((a, b) => ((len.get(a) ?? 0) >= (len.get(b) ?? 0) ? a : b));
+	}
+	return path;
+}
+
+export function validateExecutionPlan(packet, projectRoot = ROOT) {
+	const errors = [];
+	const ep = packet.execution_plan;
+	if (!ep) {
+		errors.push("execution_plan required");
+		return { status: "fail", errors, report: null };
+	}
+
+	const risk = packet.risk_level ?? "med";
+	const min = MINIMUMS[risk] ?? MINIMUMS.med;
+	const phases = ep.phases ?? [];
+	const workItems = ep.work_items ?? [];
+	const conflicts = [];
+
+	if (phases.length < min.phases) {
+		errors.push(`need >= ${min.phases} phases for risk ${risk}`);
+	}
+	if (workItems.length < min.work_items) {
+		errors.push(`need >= ${min.work_items} work_items for risk ${risk}`);
+	}
+	const ac = packet.acceptance_checks ?? [];
+	if (ac.length < min.acceptance_checks) {
+		errors.push(`need >= ${min.acceptance_checks} acceptance_checks`);
+	}
+	if ((ep.risk_register ?? []).length < min.risks) {
+		errors.push(`need >= ${min.risks} risks for risk ${risk}`);
+	}
+
+	const phaseIds = new Set(phases.map((p) => p.phase_id));
+	const phaseIndex = new Map(phases.map((p, i) => [p.phase_id, i]));
+	const wiIds = new Set(workItems.map((w) => w.work_item_id));
+
+	for (const p of phases) {
+		if (!p.exit_criteria?.length) errors.push(`phase ${p.phase_id} missing exit_criteria`);
+		if (!p.work_item_ids?.length) errors.push(`phase ${p.phase_id} has no work items`);
+	}
+
+	const wiInPhase = new Set();
+	for (const w of workItems) {
+		if (!phaseIds.has(w.phase_id)) {
+			errors.push(`work_item ${w.work_item_id} unknown phase_id`);
+		}
+		wiInPhase.add(w.work_item_id);
+		for (const d of w.depends_on ?? []) {
+			if (!wiIds.has(d)) errors.push(`work_item ${w.work_item_id} depends_on missing ${d}`);
+		}
+		if (!w.non_code && (!w.files || w.files.length === 0)) {
+			errors.push(`work_item ${w.work_item_id} needs files[] or non_code: true`);
+		}
+	}
+
+	for (const p of phases) {
+		for (const wid of p.work_item_ids ?? []) {
+			if (!wiIds.has(wid)) errors.push(`phase ${p.phase_id} references missing ${wid}`);
+		}
+	}
+
+	const { order, cycles } = topoSort(workItems);
+	if (cycles.length) errors.push(`cycle detected: ${JSON.stringify(cycles[0])}`);
+
+	// File conflicts
+	for (let i = 0; i < workItems.length; i++) {
+		for (let j = i + 1; j < workItems.length; j++) {
+			const a = workItems[i];
+			const b = workItems[j];
+			const filesA = new Set(a.files ?? []);
+			const overlap = (b.files ?? []).filter((f) => filesA.has(f));
+			if (overlap.length === 0) continue;
+			const reachable = (from, to, seen = new Set()) => {
+				if (from === to) return true;
+				if (seen.has(from)) return false;
+				seen.add(from);
+				const w = workItems.find((x) => x.work_item_id === from);
+				for (const d of w?.depends_on ?? []) {
+					if (reachable(d, to, seen)) return true;
+				}
+				return false;
+			};
+			if (!reachable(a.work_item_id, b.work_item_id) && !reachable(b.work_item_id, a.work_item_id)) {
+				if ((phaseIndex.get(a.phase_id) ?? 0) === (phaseIndex.get(b.phase_id) ?? 0)) {
+					conflicts.push(
+						`file overlap ${overlap.join(",")} between ${a.work_item_id} and ${b.work_item_id} without dependency`,
+					);
+				}
+			}
+		}
+	}
+
+	const computedCp = computeCriticalPath(workItems);
+	const authorCp = ep.schedule_metadata?.critical_path_work_item_ids ?? [];
+	if (computedCp.length >= 3 && authorCp.length) {
+		const same =
+			authorCp.length === computedCp.length &&
+			authorCp.every((id, i) => id === computedCp[i]);
+		if (!same) {
+			errors.push(
+				`critical_path mismatch author=${authorCp.join("→")} computed=${computedCp.join("→")}`,
+			);
+		}
+	}
+
+	const acIds = new Set(
+		ac.map((c) => (typeof c === "string" ? c : c.id)).filter(Boolean),
+	);
+	for (const w of workItems) {
+		for (const acid of w.acceptance_check_ids ?? []) {
+			if (!acIds.has(acid)) errors.push(`${w.work_item_id} references orphan ${acid}`);
+		}
+	}
+	for (const acid of acIds) {
+		const used = workItems.some((w) => (w.acceptance_check_ids ?? []).includes(acid));
+		if (!used) errors.push(`orphan acceptance check ${acid}`);
+	}
+
+	const status = errors.length === 0 && conflicts.length === 0 ? "pass" : "fail";
+	const report = {
+		status,
+		topological_order: order,
+		cycles,
+		conflicts: [...conflicts, ...errors],
+	};
+	return { status, errors: [...errors, ...conflicts], report };
+}
+
+async function main() {
+	const args = process.argv.slice(2);
+	let packetPath = null;
+	let writeBack = false;
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--packet" && args[i + 1]) packetPath = args[++i];
+		else if (args[i] === "--write") writeBack = true;
+	}
+
+	if (!packetPath) {
+		console.error("Usage: validate-plan-dag.mjs --packet <plan-packet.yaml> [--write]");
+		process.exit(2);
+	}
+
+	const abs = resolve(packetPath);
+	try {
+		await access(abs, constants.R_OK);
+	} catch {
+		fail(`cannot read ${abs}`);
+	}
+
+	const packet = await readYamlFile(abs);
+	const { status, errors, report } = validateExecutionPlan(packet, dirname(abs));
+
+	if (writeBack && report && packet.execution_plan) {
+		packet.execution_plan.dag_validation = {
+			status: report.status,
+			topological_order: report.topological_order,
+			cycles: report.cycles,
+			conflicts: report.conflicts,
+		};
+		await writeYamlFile(abs, packet);
+	}
+
+	if (status !== "pass") {
+		for (const e of errors) console.error(`  - ${e}`);
+		fail("validation failed");
+	}
+	ok(`DAG validation pass (${report.topological_order.length} work items)`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+	main();
+}

package/.pi/scripts/vendor-sync-pi-subagents.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Re-fetch upstream pi-subagents from narumiruna/pi-extensions.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+VEND="$ROOT/vendor/pi-subagents"
+BASE="https://raw.githubusercontent.com/narumiruna/pi-extensions/main/extensions/pi-subagents"
+
+mkdir -p "$VEND/src"
+curl -fsSL "$BASE/LICENSE" -o "$VEND/LICENSE"
+curl -fsSL "$BASE/src/subagents.ts" -o "$VEND/src/subagents.upstream.ts"
+
+# Preserve ultimate-pi harness extensions (agents.ts, harness patches applied to subagents.ts manually or via merge).
+if [[ ! -f "$VEND/src/agents.ts" ]]; then
+	curl -fsSL "$BASE/src/agents.ts" -o "$VEND/src/agents.ts"
+fi
+
+sed -i 's/from "typebox"/from "@sinclair\/typebox"/g' "$VEND/src/subagents.upstream.ts" 2>/dev/null || true
+
+echo "Fetched upstream into $VEND/src/subagents.upstream.ts — merge harness changes into subagents.ts before commit."

package/.pi/skills/ast-grep/SKILL.md

@@ -23,7 +23,7 @@ Verifies with `sg --version`.
 | Task | Tool | Why |
 |------|------|-----|
 | Find code by structure/pattern | **ast-grep** (`sg`) | AST-aware — knows what is a function call vs a string |
-| Find code by concept/meaning | graphify / ck | Semantic search, knowledge graph |
+| Find code by concept/meaning | graphify / `ccc search` | Architecture (graphify) vs implementation chunks (`ccc`) |
 | Find exact literal string | `grep` | Only tool for non-code files or exact byte match |
 | Explore architecture | graphify | Call graph, community detection |
 
@@ -319,7 +319,7 @@ Need to find code
   ├─ Structural pattern (function calls, imports, classes)? → sg -p 'pattern'
   ├─ Rewrite/codemod needed? → sg -p 'old' --rewrite 'new'
   ├─ Project-wide lint rule? → sg scan (with sgconfig.yml)
-  ├─ Conceptual/semantic search? → graphify query or ck --hybrid
+  ├─ Conceptual/semantic search? → graphify query (architecture) or ccc search (implementation)
   ├─ Explore architecture? → graphify
   └─ Exact literal string in non-code? → grep
 ```

package/.pi/skills/ccc/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: ccc
+description: "This skill should be used when code search, file/directory summary lookup, or concept-guide lookup is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'describe this file', 'read the concept guide', 'update the index', 'ccc', 'cocoindex-code'."
+---
+
+# ccc - Semantic Code Search & Indexing
+
+`ccc` is the CLI for CocoIndex Code, providing semantic search over the current codebase and index management.
+
+## Ownership
+
+The agent owns the `ccc` lifecycle for the current project — initialization, indexing, and searching. Do not ask the user to perform these steps; handle them automatically.
+
+- **Initialization**: If `ccc search` or `ccc index` fails with an initialization error (e.g., "Not in an initialized project directory"), run `bash "$UP_PKG/.pi/scripts/harness-cocoindex-bootstrap.sh"` from the project root (or `ccc init` + `ccc index` when not in ultimate-pi harness), then retry the original command.
+- **Index freshness**: Keep the index up to date by running `ccc index` (or `ccc search --refresh`) when the index may be stale — e.g., at the start of a session, or after making significant code changes (new files, refactors, renamed modules). There is no need to re-index between consecutive searches if no code was changed in between.
+- **Installation**: If `ccc` itself is not found (command not found), refer to [management.md](references/management.md) for installation instructions and inform the user.
+
+### ultimate-pi harness
+
+- **Parent / main agents:** follow ownership above (`ccc index` when stale after large edits).
+- **`harness/planning/scout-semantic`:** use **`ccc search` only** — the harness runs incremental `ccc index` before subagent spawns. Never run `ccc index`, `ccc init`, or `ccc search --refresh` in scouts.
+- **Lane contract:** graphify = callers/communities/architecture; `ccc` = implementation-by-meaning (chunks). Do not use `ccc` for “who calls X” — use `graphify explain` / `graphify path`.
+
+## Searching the Codebase
+
+To perform a semantic search:
+
+```bash
+ccc search <query terms>
+```
+
+The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:
+
+```bash
+ccc search database connection pooling
+ccc search user authentication flow
+ccc search error handling retry logic
+```
+
+### Filtering Results
+
+- **By language** (`--lang`, repeatable): restrict results to specific languages.
+
+  ```bash
+  ccc search --lang python --lang markdown database schema
+  ```
+
+- **By path** (`--path`): restrict results to a glob pattern relative to project root. If omitted, defaults to the current working directory (only results under that subdirectory are returned).
+
+  ```bash
+  ccc search --path 'src/api/*' request validation
+  ```
+
+### Pagination
+
+Results default to the first page. To retrieve additional results:
+
+```bash
+ccc search --offset 5 --limit 5 database schema
+```
+
+If all returned results look relevant, use `--offset` to fetch the next page — there are likely more useful matches beyond the first page.
+
+### Working with Search Results
+
+Search results include file paths and line ranges. To explore a result in more detail:
+
+- Use the editor's built-in file reading capabilities (e.g., the `Read` tool) to load the matched file and read lines around the returned range for full context.
+- When working in a terminal without a file-reading tool, use `sed -n '<start>,<end>p' <file>` to extract a specific line range.
+
+### Following Hints in Search Output
+
+Search results are a mixed ranking of code chunks, per-file/dir summaries, and (when configured) curated concept guides — all scored against the same query. Two kinds of hit come with a follow-up command embedded in the output:
+
+- `[summary]` — a file or directory summary. Read with `ccc describe <path>`.
+- `[guide]` — a curated concept guide. Read with `ccc guide <slug>`.
+
+When a hit carries one of these tags, follow the hint: the synthesised text is usually a faster read than chasing through individual files. Conversely, do **not** run `ccc describe .` or `ccc guide` proactively as a triage step — let search rank what's relevant and act on what it returns.
+
+## Describing Files and Directories
+
+Per-file and per-directory summaries (when configured for the project) condense each file's public API, contracts, and role into a short markdown block. They are typically faster to consult than reading the source.
+
+```bash
+ccc describe src/auth/session.py        # one file
+ccc describe src/auth/                  # directory: summary + children tree
+ccc describe .                          # project root overview
+```
+
+Use `describe` when you already know the path you want; let `ccc search` find paths for you when you don't.
+
+## Concept Guides
+
+Some projects configure cross-cutting concept guides in `.cocoindex_code/guides.yml` — synthesised markdown documents for architectural topics that span many files (e.g. memoization, plugin-SDK boundary, channel routing). Each guide names canonical files, end-to-end flow, and contracts/invariants.
+
+```bash
+ccc guide                               # list available guides + descriptions
+ccc guide <slug>                        # print one guide
+```
+
+Discovery is search-driven: a relevant guide will surface in `ccc search` results tagged `[guide]` with a `ccc guide <slug>` hint. Run `ccc guide` (no args) only when first orienting in an unfamiliar codebase or when the user explicitly asks for the guide list — not as a routine first step.
+
+### Authoring `guides.yml` Interactively
+
+When the user wants to add or improve concept guides, collaborate on the slug list rather than dumping a finished YAML. Good guide candidates are **named subsystems the codebase obviously has** — cross-cutting lifecycles, registration/dispatch protocols, end-to-end data paths. Single-file or symbol-specific topics do not warrant a guide; per-file summaries already cover those.
+
+Recommended flow:
+
+1. **Survey the codebase.** Use `ccc describe .` and a few likely subdirectory summaries to enumerate the project's subsystems and inter-edge boundaries.
+2. **Propose candidates.** Suggest 5–10 slugs with one-line descriptions, framed to name the canonical starting file or directory for each topic. Show them to the user as a list.
+3. **Iterate.** Ask which to keep, drop, rename, or merge. Surface non-obvious dependencies (`deps:`) so a higher-level guide can cite a lower-level one rather than restate it. Cycles are rejected at load time.
+4. **Write the YAML.** Add the agreed entries to `.cocoindex_code/guides.yml` (creating the file if absent). Confirm `defaults.enabled: true` and that the project's summary feature is enabled — guides require summaries.
+5. **Generate.** Run `ccc index` to drive the per-guide agent loop and produce `<slug>.md` files under `.cocoindex_code/guides/`. Re-run after editing descriptions to refresh.
+
+Schema:
+
+```yaml
+defaults:
+  enabled: true                     # disables all guides when false
+  model: openai/gpt-5.4-nano        # falls back to summary.model when omitted
+  session_budget: 200
+  max_logical_depth: 3
+  max_turns_per_session: 18
+
+guides:
+  - slug: memoization                          # [a-z0-9][a-z0-9-]*
+    description: |
+      What this guide covers, framed for the reader.
+      Name the canonical starting files (e.g. "start with src/cache.py").
+    deps: [other-slug]                         # optional; must not cycle
+    max_turns_per_session: 28                  # optional per-entry overrides
+```
+
+A multi-line description is fine and often clearer than one terse sentence — the description seeds the guide-generation agent's question, so concrete file/directory anchors pay off.
+
+## Settings
+
+To view or edit embedding model configuration, include/exclude patterns, or language overrides, see [settings.md](references/settings.md).
+
+## Management & Troubleshooting
+
+For installation, initialization, daemon management, troubleshooting, and cleanup commands, see [management.md](references/management.md).

package/.pi/skills/ccc/references/management.md

@@ -0,0 +1,110 @@
+# ccc Management
+
+## Installation
+
+Install CocoIndex Code via pipx. Two install styles:
+
+```bash
+pipx install 'cocoindex-code[full]'      # batteries included (local embeddings via sentence-transformers)
+pipx install cocoindex-code              # slim (LiteLLM-only; requires a cloud embedding provider + API key)
+```
+
+The `[full]` extra pulls in `sentence-transformers` so the first-run default (local embeddings, no API key) works out of the box. The slim install is for environments where you don't want the torch/transformers deps and plan to use a LiteLLM-supported cloud provider instead.
+
+To upgrade to the latest version:
+
+```bash
+pipx upgrade cocoindex-code
+```
+
+After installation, the `ccc` command is available globally.
+
+## Project Initialization
+
+Run from the root directory of the project to index:
+
+```bash
+ccc init
+```
+
+**First run (global settings don't exist yet)** — `ccc init` prompts interactively for the embedding provider (sentence-transformers / litellm) and model, then runs a one-off test embed via the daemon to confirm the model works. Accept the defaults for the sentence-transformers path, or pick litellm and enter a model identifier.
+
+**Subsequent runs** (global settings already exist) — prompts are skipped; only project settings and `.gitignore` are set up.
+
+To skip the interactive prompts on the first run (e.g. in a script or container), pass `--litellm-model MODEL`:
+
+```bash
+ccc init --litellm-model openai/text-embedding-3-small
+```
+
+This is also the only way to pick a LiteLLM model when stdin isn't a TTY and you've done a slim install.
+
+`ccc init` creates:
+- `~/.cocoindex_code/global_settings.yml` (user-level, embedding config + env vars).
+- `.cocoindex_code/settings.yml` (project-level, include/exclude patterns).
+
+If `.git` exists in the directory, `.cocoindex_code/` is automatically added to `.gitignore`.
+
+Use `-f` to skip the confirmation prompt if `ccc init` detects a potential parent project root.
+
+After initialization, edit the settings files if needed (see [settings.md](settings.md) for format details), then run `ccc index` to build the initial index. If the model test printed `[FAIL]` during `init`, edit `global_settings.yml` (and optionally add API keys under the commented `envs:` block) and verify with `ccc doctor` before indexing.
+
+## Troubleshooting
+
+### Diagnostics
+
+Run `ccc doctor` to check system health end-to-end:
+
+```bash
+ccc doctor
+```
+
+This checks global settings, daemon status, embedding model (runs a test embedding), and — if run from within a project — file matching (walks files using the same logic as the indexer) and index status. Results stream incrementally. Always points to `daemon.log` at the end for further investigation.
+
+### Checking Project Status
+
+To view the current project's index status:
+
+```bash
+ccc status
+```
+
+This shows whether indexing is ongoing and index statistics.
+
+### Daemon Management
+
+The daemon starts automatically on first use. To check its status:
+
+```bash
+ccc daemon status
+```
+
+This shows whether the daemon is running, its version, uptime, and loaded projects.
+
+To restart the daemon (useful if it gets into a bad state):
+
+```bash
+ccc daemon restart
+```
+
+To stop the daemon:
+
+```bash
+ccc daemon stop
+```
+
+## Cleanup
+
+To reset a project's index (removes databases, keeps settings):
+
+```bash
+ccc reset
+```
+
+To fully remove all CocoIndex Code data for a project (including settings):
+
+```bash
+ccc reset --all
+```
+
+Both commands prompt for confirmation. Use `-f` to skip.

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [v0.13.0] — 2026-05-18
+
+### ✨ Features
+
+- **CocoIndex Code:** replace `@beaconbay/ck-search` with offline `ccc` semantic search; `harness-cocoindex-bootstrap.sh`, pre-scout incremental index in `harness-subagents-bridge`, vendored `/skill:ccc`, `cocoindex-search` skill, and `ck-search` deprecation stub.
+
+### 🔧 Chores
+
+- Harness excludes for `graphify-out/`, `vendor/`, `raw/`, etc. in `.cocoindex_code/settings.yml`; `.gitignore` tracks `.cocoindex_code/`.
+
+## [v0.12.0] — 2026-05-18
+
+### ✨ Features
+
+- **Harness subagents:** vendor `pi-subagents`; spawn budget, precheck, and policy bridge.
+- **Router spawn auth:** forward concrete provider/model + API key to subprocesses using `--no-extensions` (fixes planning scout 401 with `router/auto`).
+- **Plan review gate:** debate orchestration, execution-plan schemas, `write_harness_yaml`, plan-phase smoke fixture (ADR 0035).
+
+### 🔧 Chores
+
+- Stop tracking harness runtime and local graphify artifacts in git.
+
 ## [v0.11.0] — 2026-05-17
 
 ### ✨ Features

package/THIRD_PARTY_NOTICES.md

@@ -14,3 +14,18 @@
 - **License:** MIT (see upstream repository)  
 - **Pinned revision:** See [vendor/pi-vcc/UPSTREAM_PIN.md](vendor/pi-vcc/UPSTREAM_PIN.md)  
 - ultimate-pi loads it from [`vendor/pi-vcc`](vendor/pi-vcc) via [`.pi/extensions/ultimate-pi-vcc.ts`](.pi/extensions/ultimate-pi-vcc.ts). Harness configuration is env-only: `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG` ([`.pi/extensions/lib/harness-vcc-settings.ts`](.pi/extensions/lib/harness-vcc-settings.ts)). Maintainer refresh: `npm run vendor:sync-vcc`.
+
+## pi-subagents (vendored)
+
+- **Project:** https://github.com/narumiruna/pi-extensions (`extensions/pi-subagents`)  
+- **npm:** `@narumitw/pi-subagents@0.1.26`  
+- **License:** MIT ([vendor/pi-subagents/LICENSE](vendor/pi-subagents/LICENSE))  
+- **Pinned revision:** See [vendor/pi-subagents/UPSTREAM_PIN.md](vendor/pi-subagents/UPSTREAM_PIN.md)  
+- ultimate-pi loads it from [`vendor/pi-subagents`](vendor/pi-subagents) via [`.pi/extensions/harness-subagents.ts`](.pi/extensions/harness-subagents.ts) with harness discovery, spawn gates, and subprocess env. Maintainer refresh: `npm run vendor:sync-subagents`.
+
+## CocoIndex Code (CLI + skill)
+
+- **Project:** https://github.com/cocoindex-io/cocoindex-code  
+- **License:** Apache-2.0  
+- **Install:** `uv tool install 'cocoindex-code[full]'` (see `/harness-setup` §2.4)  
+- ultimate-pi vendors the upstream agent skill at [`.pi/skills/ccc/`](.pi/skills/ccc/) and bootstraps indexes via [`.pi/scripts/harness-cocoindex-bootstrap.sh`](.pi/scripts/harness-cocoindex-bootstrap.sh). Replaces deprecated `@beaconbay/ck-search`.

package/biome.json

@@ -14,8 +14,8 @@
 			"!graphify-books-out/**/*",
 			"!vendor/**/*",
 			"!.pi/harness/active-run.json",
-			"!.pi/harness/runs/**/run-context.json",
-			"!.pi/harness/runs/**/plan-packet.json"
+			"!.pi/harness/runs/**/run-context.yaml",
+			"!.pi/harness/runs/**/plan-packet.yaml"
 		]
 	},
 	"formatter": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -67,22 +67,24 @@
 		"README.md",
 		"THIRD_PARTY_NOTICES.md",
 		"vendor/pi-model-router",
+		"vendor/pi-subagents",
 		"vendor/pi-vcc"
 	],
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*"
 	},
 	"scripts": {
-		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/00-ultimate-pi-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/harness-plan-approval.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/lib/plan-approval/types.ts .pi/extensions/lib/plan-approval/schema.ts .pi/extensions/lib/plan-approval/validate.ts .pi/extensions/lib/plan-approval/format-plan.ts .pi/extensions/lib/plan-approval/dialog.ts .pi/extensions/lib/plan-approval/fallback.ts .pi/extensions/lib/plan-approval/render.ts .pi/extensions/lib/plan-approval/create-plan.ts .pi/extensions/lib/harness-subagents/parent-harness-ui-bridge.ts .pi/extensions/lib/harness-subagents/parent-harness-ui-hooks.ts .pi/extensions/lib/harness-subagents/parent-ask-user-bridge.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
+		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/custom-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/harness-plan-approval.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/lib/plan-approval/types.ts .pi/extensions/lib/plan-approval/schema.ts .pi/extensions/lib/plan-approval/validate.ts .pi/extensions/lib/plan-approval/format-plan.ts .pi/extensions/lib/plan-approval/dialog.ts .pi/extensions/lib/plan-approval/fallback.ts .pi/extensions/lib/plan-approval/render.ts .pi/extensions/lib/plan-approval/create-plan.ts .pi/extensions/harness-subagents.ts .pi/extensions/lib/harness-subagents-bridge.ts .pi/extensions/lib/harness-cocoindex-refresh.ts .pi/extensions/lib/harness-subagent-auth.ts .pi/extensions/lib/harness-subagent-policy.ts .pi/extensions/lib/harness-subagent-precheck.ts .pi/extensions/lib/harness-spawn-budget.ts .pi/extensions/lib/spawn-policy.ts vendor/pi-subagents/src/agents.ts vendor/pi-subagents/src/subagents.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
 		"vendor:sync-router": "bash .pi/scripts/vendor-sync-pi-model-router.sh",
 		"vendor:sync-vcc": "bash .pi/scripts/vendor-sync-pi-vcc.sh",
+		"vendor:sync-subagents": "bash .pi/scripts/vendor-sync-pi-subagents.sh",
 		"release": "bash .pi/scripts/release.sh",
 		"lint": "biome check",
 		"lint:fix": "biome check --fix",
 		"format": "biome format --write",
 		"format:check": "biome format",
 		"prepare": "lefthook install",
-		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagents-import-path.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-turn-routing.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs",
+		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-spawn-budget.test.mjs test/harness-turn-routing.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs",
 		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
@@ -96,7 +98,8 @@
 		"@earendil-works/pi-tui": "0.74.1",
 		"@sinclair/typebox": "^0.34.49",
 		"lefthook": "2.1.6",
-		"typescript": "^6.0.3"
+		"typescript": "^6.0.3",
+		"yaml": "^2.8.0"
 	},
 	"dependencies": {
 		"@posthog/pi": "latest",