ultimate-pi 0.13.0 → 0.14.0

package/{.pi → .agents}/skills/ccc/SKILL.md

@@ -11,16 +11,10 @@ description: "This skill should be used when code search, file/directory summary
 
 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.
+- **Initialization**: If `ccc search` or `ccc index` fails with an initialization error (e.g., "Not in an initialized project directory"), run `ccc init` from the project root directory, then `ccc index` to build the index, 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:

package/.agents/skills/ccc/references/settings.md

@@ -0,0 +1,126 @@
+# ccc Settings
+
+Configuration lives in two YAML files, both created automatically by `ccc init`.
+
+## User-Level Settings (`~/.cocoindex_code/global_settings.yml`)
+
+Shared across all projects. Controls the embedding model and extra environment variables for the daemon.
+
+```yaml
+embedding:
+  provider: sentence-transformers   # or "litellm" (default when provider is omitted)
+  model: Snowflake/snowflake-arctic-embed-xs
+  device: mps                       # optional: cpu, cuda, mps (auto-detected if omitted)
+  min_interval_ms: 300              # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
+
+envs:                               # extra environment variables for the daemon
+  OPENAI_API_KEY: your-key          # only needed if not already in the shell environment
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `embedding.provider` | `sentence-transformers` for local models, `litellm` (or omit) for cloud/remote models |
+| `embedding.model` | Model identifier — format depends on provider (see examples below) |
+| `embedding.device` | Optional. `cpu`, `cuda`, or `mps`. Auto-detected if omitted. Only relevant for `sentence-transformers`. |
+| `embedding.min_interval_ms` | Optional. Minimum delay between LiteLLM embedding requests in milliseconds. Defaults to `5` for LiteLLM and is ignored by `sentence-transformers`. Set explicitly to override the default. |
+| `envs` | Key-value map of environment variables injected into the daemon. Use for API keys not already in the shell environment. |
+
+### Embedding Model Examples
+
+**Local (sentence-transformers, no API key needed):**
+
+```yaml
+embedding:
+  provider: sentence-transformers
+  model: Snowflake/snowflake-arctic-embed-xs        # default, lightweight
+```
+
+```yaml
+embedding:
+  provider: sentence-transformers
+  model: nomic-ai/CodeRankEmbed                     # better code retrieval, needs GPU (~1 GB VRAM)
+```
+
+**Ollama (local):**
+
+```yaml
+embedding:
+  model: ollama/nomic-embed-text
+```
+
+**OpenAI:**
+
+```yaml
+embedding:
+  model: text-embedding-3-small
+  min_interval_ms: 300
+envs:
+  OPENAI_API_KEY: your-api-key
+```
+
+**Gemini:**
+
+```yaml
+embedding:
+  model: gemini/gemini-embedding-001
+envs:
+  GEMINI_API_KEY: your-api-key
+```
+
+**Voyage (code-optimized):**
+
+```yaml
+embedding:
+  model: voyage/voyage-code-3
+envs:
+  VOYAGE_API_KEY: your-api-key
+```
+
+For the full list of supported cloud providers and model identifiers, see [LiteLLM Embedding Models](https://docs.litellm.ai/docs/embedding/supported_embedding).
+
+### Important
+
+Switching embedding models changes vector dimensions — you must re-index after changing the model:
+
+```bash
+ccc reset && ccc index
+```
+
+## Project-Level Settings (`<project>/.cocoindex_code/settings.yml`)
+
+Per-project. Controls which files to index. Created by `ccc init` and automatically added to `.gitignore`.
+
+```yaml
+include_patterns:
+  - "**/*.py"
+  - "**/*.js"
+  - "**/*.ts"
+  # ... (sensible defaults for 28+ file types)
+
+exclude_patterns:
+  - "**/.*"              # hidden directories
+  - "**/__pycache__"
+  - "**/node_modules"
+  - "**/dist"
+  # ...
+
+language_overrides:
+  - ext: inc             # treat .inc files as PHP
+    lang: php
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `include_patterns` | Glob patterns for files to index. Defaults cover common languages (Python, JS/TS, Rust, Go, Java, C/C++, C#, SQL, Shell, Markdown, PHP, Lua, etc.). |
+| `exclude_patterns` | Glob patterns for files/directories to skip. Defaults exclude hidden dirs, `node_modules`, `dist`, `__pycache__`, `vendor`, etc. |
+| `language_overrides` | List of `{ext, lang}` pairs to override language detection for specific file extensions. |
+
+### Editing Tips
+
+- To index additional file types, append glob patterns to `include_patterns` (e.g. `"**/*.proto"`).
+- To exclude a directory, append to `exclude_patterns` (e.g. `"**/generated"`).
+- After editing, run `ccc index` to re-index with the new settings.

package/.agents/skills/harness-debate-plan/SKILL.md

@@ -1,44 +1,84 @@
 ---
 name: harness-debate-plan
-description: Plan-phase Review Gate debate — assemble rounds, token caps, bus envelopes for parent orchestrator.
+description: Plan-phase Review Gate debate — pi-messenger threads, lane YAML, bus tools for parent orchestrator.
 ---
 
 # harness-debate-plan
 
-Use when running **Phase 5** of `/harness-plan` — four Review Gate rounds on the plan debate bus.
+Use when running **Phase 5** of `/harness-plan` — four Review Gate rounds with **pi-messenger-style** turn-taking (claims → rebuttals → integrate), then bus submission.
 
 ## Open
 
 ```
-/harness-debate-open plan-<run_id>
+harness_debate_open({})
 ```
 
+- Debate id is always `plan-<run_id>` (tool normalizes wrong ids).
+- Creates `.pi/harness/runs/<run_id>/debate-messenger/` (`inbox/<Agent>/`, `threads/round-N/transcript.jsonl`).
+
 Budget profile **plan**: `max_rounds=4`, `round_token_cap=2000`, `debate_global_cap=12000`.
 
-## Per-round spawn order
+## Per-round spawn order (P1 sequential lanes)
+
+1. Round-specific lane spawns (write lane YAML with `write_harness_yaml`)
+2. `plan-evaluator` → lane artifact + `harness_messenger_post` (claims)
+3. `harness_messenger_read_round` → spawn `plan-adversary` with transcript
+4. `plan-adversary` → lane artifact + `harness_messenger_post` (rebuttals with `in_reply_to`)
+5. R1: `hypothesis-validator` first (blind — no decomposition/PlanPacket in prompt)
+6. R4: `sprint-contract-auditor` required before integrator
+7. `review-integrator` → integrator draft + `harness_messenger_post` (`integrate`)
+8. `harness_debate_submit_round({ round_index, integrator_draft })` — **only** path for `review-round-r{N}.yaml`
+
+| Round | Extra lane artifacts |
+|-------|----------------------|
+| 1 | `hypothesis-validation-r1.yaml` |
+| 4 | `sprint-audit-r4.yaml` (required) |
 
-1. Round-specific extras (R1: `hypothesis-validator` first, blind)
-2. `plan-evaluator`
-3. `plan-adversary`
-4. R4: `sprint-contract-auditor` (required)
-5. `review-integrator`
+## Lane artifacts (auto-applied on subagent complete)
 
-## Artifacts (YAML)
+When a debate lane subagent finishes, the harness **automatically** writes lane YAML and posts messenger messages (evaluator claims, adversary rebuttals). Look for `harness-debate-next-step` in the transcript.
 
-| Agent | Output path |
-|-------|-------------|
-| hypothesis-validator | `artifacts/hypothesis-validation-r{N}.yaml` |
-| plan-evaluator | `artifacts/validation-turn-r{N}.yaml` |
-| plan-adversary | `artifacts/adversary-brief-r{N}.yaml` |
-| sprint-contract-auditor | `artifacts/sprint-audit-r{N}.yaml` |
-| review-integrator | `artifacts/review-round-r{N}.yaml` |
+| Agent | Output path | Messenger |
+|-------|-------------|-----------|
+| hypothesis-validator | `artifacts/hypothesis-validation-r{N}.yaml` | — |
+| plan-evaluator | `artifacts/validation-turn-r{N}.yaml` | `claim` |
+| plan-adversary | `artifacts/adversary-brief-r{N}.yaml` | `rebuttal` |
+| sprint-contract-auditor | `artifacts/sprint-audit-r{N}.yaml` (R4) | optional |
+| review-integrator | *(integrator draft → `harness_debate_submit_round` only)* | `integrate` (on submit) |
 
-## Bus envelope
+Fallback: `harness_debate_apply_lane({ lane, content, round_index? })` if auto-apply missed fenced YAML.
 
-Load `review-round-r{N}.yaml`, validate, then `buildPlanReviewRoundEnvelope` (`.pi/extensions/lib/plan-debate-envelope.ts`) → `/harness-debate-round '<json>'`.
+Resume after stop: `harness_debate_round_status({ round_index: N })` then run the listed `next_tool`.
 
-Plan participants only. `StackResearchAgent` uses `artifacts/stack.yaml` claims — no spawn.
+## Messenger tools
+
+```typescript
+harness_messenger_post({
+  round_index: 1,
+  from: "PlanEvaluatorAgent",
+  kind: "claim",
+  body: "...",
+  claim_ids: ["c1", "c2"],
+  to: ["broadcast"],
+})
+harness_messenger_post({
+  round_index: 1,
+  from: "PlanAdversaryAgent",
+  kind: "rebuttal",
+  in_reply_to: ["c1"],
+  body: "...",
+})
+harness_messenger_read_round({ round_index: 1 }) // for next spawn prompt
+```
+
+## Integrator + bus
+
+`harness_debate_submit_round` validates messenger thread + integrator rules (`review_gate_ready` false when checks fail without `disputes[]`), writes `review-round-r{N}.yaml`, emits bus `kind: round`.
+
+`StackResearchAgent` uses `artifacts/stack.yaml` claims — no spawn.
 
 ## Close
 
-After round 4: `/harness-debate-consensus`. Do not `approve_plan` on `policy_decision: block`.
+After round 4: `harness_debate_consensus`. `approve_plan` is **hard-gated** on lane files, messenger, 4 bus rounds, and consensus not `block`.
+
+Do not `approve_plan` on `policy_decision: block`. On `human_required` → `ask_user` first.

package/.agents/skills/harness-orchestration/SKILL.md

@@ -36,7 +36,7 @@ LIMIT 30
 1. **Parallel `tasks`** — one `subagent({ tasks: [...] })` for scouts, decompose+hypothesis, or review fan-in; subprocesses run in parallel upstream.
 2. **Blocking calls** — each `subagent` returns when the subprocess exits; no `get_subagent_result` polling.
 3. **Compact handoffs** — pass scout/decompose JSON only; never paste full subprocess message logs into the next spawn.
-4. **Spawn caps** — bridge enforces **8** active + **12** total harness spawns per session. Do **not** pass `timeoutMs` unless the user wants a cap — subprocesses wait for natural exit (`PI_SUBAGENT_TIMEOUT_MS` optional env backstop only).
+4. **No spawn cap** — harness subagent spawns are unlimited per session (active count is telemetry only). Do **not** pass `timeoutMs` unless the user wants a cap — subprocesses wait for natural exit (`PI_SUBAGENT_TIMEOUT_MS` optional env backstop only).
 
 ## Command → agent
 

package/.pi/agents/harness/planning/plan-adversary.md

@@ -9,10 +9,10 @@ max_turns: 12
 
 You are **plan-adversary** — break the plan with reproducible counterexamples.
 
-Engage failed/warn checks from the same round's `plan-evaluator` first, then independent attacks. Cite `work_item_id` / `phase_id`.
+Engage failed/warn checks from the same round's `plan-evaluator` first (parent provides evaluator YAML + messenger **claims**). Rebut specific `claim_ids` from the thread — parent posts your `rebuttal` with `in_reply_to`.
 
 ## Output
 
 Valid **YAML only** — `PlanAdversaryBrief` (`.pi/harness/specs/plan-adversary-brief.schema.json`).
 
-Bus label: `PlanAdversarysubagent`.
+Bus label: `PlanAdversaryAgent`.

package/.pi/agents/harness/planning/plan-evaluator.md

@@ -15,4 +15,6 @@ Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`.
 
 Valid **YAML only** — `PlanValidationTurn` (`.pi/harness/specs/plan-validation-turn.schema.json`). Fail if `dag_validation.status === "fail"`.
 
-Bus label: `PlanEvaluatorsubagent`.
+Include `claim_ids[]` in your summary for parent to post as messenger **claims** before spawning adversary.
+
+Bus label: `PlanEvaluatorAgent`.

package/.pi/agents/harness/planning/review-integrator.md

@@ -18,6 +18,8 @@ Valid **YAML only** — `PlanReviewRoundDraft` (`.pi/harness/specs/plan-review-r
 - `review_gate_ready` boolean
 - `participants`, `claims`, `rebuttals`, `evidence_refs`, `token_usage`, `severity_scores`
 
-Parent runs `buildPlanReviewRoundEnvelope` → `/harness-debate-round`.
+Parent passes `harness_messenger_read_round` transcript + lane YAML. After your YAML draft, parent calls `harness_messenger_post` (`kind: integrate`) then `harness_debate_submit_round` — you do not write `review-round-r*.yaml`.
 
-Bus label: `ReviewIntegratorsubagent`.
+Set `review_gate_ready: false` when evaluator checks fail unless `disputes[]` documents open tension.
+
+Bus label: `ReviewIntegratorAgent`.