ultimate-pi 0.1.7 → 0.2.2

package/vault/wiki/concepts/vcc-conversation-compaction-for-pi.md

@@ -1,53 +0,0 @@
----
-type: concept
-status: active
-created: 2026-05-05
-updated: 2026-05-07
-tags:
-  - pi-agent
-  - vcc
-  - compaction
-  - memory
-related:
-  - "[[pi-vcc-github-repo]]"
-  - "[[context-continuity]]"
-  - "[[structured-compaction]]"
-  - "[[adr-027]]"
----
-
-# VCC Conversation Compaction for Pi
-
-## Definition
-
-VCC in Pi context refers to transcript-preserving, deterministic compaction approach adopted by `pi-vcc`, inspired by View-oriented Conversation Compiler. It compresses sessions without calling an LLM, then adds recall over raw lineage history.
-
-## Core Mechanics
-
-- Algorithmic extraction, not model summarization
-- Stable sectioned output: goal, files, commits, outstanding context, preferences
-- Explicit recall API (`vcc_recall`) with regex and lineage scope
-- High token reduction on long sessions (often 90%+)
-
-## Practical Impact
-
-For long-running coding sessions, VCC-style compaction reduces cost and hallucination risk during summarization while preserving retrievability of older context.
-
-## Competitive Position in Pi Ecosystem
-
-pi-vcc is the only fully deterministic (no-LLM) compaction extension. Three other Pi compaction extensions exist but all use LLM calls:
-- **pi-model-aware-compaction**: Per-model threshold triggers (timing control, not algorithm change)
-- **pi-custom-compaction**: Swap compaction model/template (still LLM-based)
-- **pi-agentic-compaction**: Virtual filesystem + sandboxed tools (still LLM-based)
-
-See [[pi-compaction-extensions-ecosystem]] for full comparison and [[deterministic-session-compaction]] for the broader pattern.
-
-## Broader Pattern Validation
-
-The deterministic compaction pattern is independently validated by:
-- **Codex DSC RFC** (openai/codex#8573): Proposed identical approach for Codex, closed as not_planned (Source: [[codex-dsc-rfc-8573]])
-- **Distill** (143 stars): Deterministic context preprocessing, different layer but same no-LLM principle (Source: [[distill-deterministic-context-compression]])
-- **MemoSift**: 6-layer deterministic compression engine with framework adapters
-
-## Clarification
-
-VCC here is **not** VS Code extension acronym. It is compaction method and Pi package category.

package/vault/wiki/concepts/verification-drift-detection.md

@@ -1,19 +0,0 @@
----
-type: concept
-title: "verification-drift-detection"
-created: 2026-04-30
-updated: 2026-04-30
-status: seed
-tags: [#concept, #harness, #testing]
-related:
-  - "[[execution-feedback-loop]]"
-  - "[[grounding-checkpoints]]"
----
-
-# Verification Drift Detection
-
-> [!stub] See [[grounding-checkpoints]] for the harness implementation.
-
-Detects when an agent's implementation drifts away from the spec or when verification results become stale. Part of the execution feedback loop: after each change, verify that the output still matches expected behavior. Drift detection triggers re-grounding — forcing the agent to re-read the spec before continuing.
-
-In the ultimate-pi harness, this is implemented by Layer 3 ([[grounding-checkpoints]]), which enforces smallest-verifiable-change + drift detection on every checkpoint.

package/vault/wiki/consensus/consensus-records.md

@@ -1,58 +0,0 @@
----
-type: index
-title: Consensus Records
-created: 2026-04-30
-updated: 2026-04-30
-status: active
-tags: [consensus, debate, alignment, index]
-related:
-  - "[[consensus-debate]]"
-  - "[[adr-011]]"
-  - "[[harness-implementation-plan]]"
----
-
-# Consensus Records
-
-Permanent alignment records for all agent debates. **Every debate verdict — win, lose, or deadlock — is filed here.**
-
-Future agents query this directory before forming positions. Contradicting a filed consensus triggers a harness block (L7 enforcement).
-
-## Directory Convention
-
-- Filename: `[layer]-[topic-slug].md`
-- Layers: `spec` (L1), `plan` (L2), `verify` (L4)
-- Example: `spec-idempotency-key-design.md`
-
-## Consensus Page Template
-
-```markdown
----
-type: consensus
-layer: spec | plan | verify
-verdict: CONSENSUS_REACHED | DEADLOCK | BUDGET_EXHAUSTED | TIMEOUT
-date: YYYY-MM-DD
-participants: [agent-a, agent-b]
-topic: "Brief description"
-related: page-refs (wikilinks to related pages)
----
-
-# [Topic]
-
-## Final Position
-[The winning / final agreed position]
-
-## Key Rounds Summary
-| Round | Attacker | Defender | Outcome |
-|-------|----------|----------|---------|
-| 1 | ... | ... | ... |
-
-## Evidence References
-- (wikilinks to evidence sources)
-
-## Rationale
-Why this consensus was reached. What was settled.
-```
-
-## No records yet
-
-Consensus filing begins with Phase P19b of the [[harness-implementation-plan]].

package/vault/wiki/decisions/2026-04-30-pi-lean-ctx-native.md

@@ -1,122 +0,0 @@
----
-type: decision
-status: accepted
-created: 2026-04-30
-tags:
-  - lean-ctx
-  - pi
-  - extensions
-  - token-optimization
-  - mcp
-related:
-  - "[[lean-ctx]]"
-  - "[[leanctx-website]]"
-  - "[[Research: context-mode vs lean-ctx]]"
-updated: 2026-04-30
-title: "ADR: Adopt pi-lean-ctx Native Package, Drop Custom Extension"
-
----# ADR: Adopt pi-lean-ctx Native Package, Drop Custom Extension
-
-## Context
-
-The ultimate-pi harness had a custom extension (`extensions/lean-ctx-enforce.ts`) that:
-
-- Detected lean-ctx binary availability
-- Wrapped `bash` commands with `lean-ctx -c` prefix
-- Overrode `read` to call `lean-ctx read` with simple mode selection
-- Registered `/lean-ctx-status` diagnostic command
-
-This custom extension was a stopgap — basic, manual wrapping, no MCP bridge, no auto mode selection, no compression stats.
-
-Meanwhile, the pi-lean-ctx npm package (v3.4.5, published by yvgude) provides a native Pi extension with full lean-ctx integration.
-
-## Alternatives Considered
-
-1. **Keep custom extension** — Simple, self-contained, no external npm dependency. But misses MCP bridge (48 tools), auto read-mode selection, ls/find/grep tools, compression stats, and reconnection logic.
-
-2. **Adopt pi-lean-ctx** — npm package maintained by lean-ctx author. Full MCP integration, all 48 lean-ctx MCP tools as native Pi tools, rich read mode selection, spawnHook bash wrapping, compression stats footer, reconnect/timeout-handling.
-
-3. **Hybrid: keep custom + add MCP manually** — Would duplicate effort. pi-lean-ctx already does everything better.
-
-## Decision
-
-**Replace the custom `lean-ctx-enforce.ts` extension with the `pi-lean-ctx` npm package.**
-
-## Changes Made
-
-| File | Action | Detail |
-|------|--------|--------|
-| `extensions/lean-ctx-enforce.ts` | Deleted | Replaced by pi-lean-ctx |
-| `.pi/settings.json` | Edited | Added `"npm:pi-lean-ctx"` to packages array |
-| `.pi/SYSTEM.md` | Edited | Updated skill routing line |
-| `package.json` | Edited | Updated `check:ts` script to dotenv-loader |
-| `.pi/skills/lean-ctx/SKILL.md` | Edited | Added integration note at top |
-| `.pi/npm/node_modules/pi-lean-ctx` | Installed | v3.4.5 + all deps |
-
-## What pi-lean-ctx Provides
-
-### Tool Overrides
-
-| Tool | Custom Ext | pi-lean-ctx |
-|------|-----------|-------------|
-| `bash` | Prepends `lean-ctx -c` | SpawnHook wraps `lean-ctx -c sh -lc` (preserves env, aliases). `raw=true` bypass option. |
-| `read` | Basic `lean-ctx read -m lines/…` | Auto mode selection: full (<8KB code), map (8KB–96KB), signatures (>96KB). Syntax highlighting. Compression stats footer. Truncation handling. |
-| `ls` | Not handled | Routes through `lean-ctx ls` with limit support |
-| `find` | Not handled | Routes through `lean-ctx find` with glob + limit |
-| `grep` | Not handled | Routes through `lean-ctx -c rg` with full ripgrep flags |
-| `cat` blocking | Not enforced | Read tool description warns: "Do NOT use bash to read files (cat/head/tail)" |
-
-### MCP Bridge
-
-- Auto-connects to lean-ctx MCP server (stdio transport)
-- Registers all 48 lean-ctx MCP tools as native Pi tools
-- Auto-reconnect (3 attempts, exponential backoff 2s/4s/8s)
-- 120s tool timeout with retry for idempotent tools
-- Tools excluded from bridge: `ctx_read`, `ctx_multi_read`, `ctx_shell`, `ctx_search`, `ctx_tree` (already handled via Pi-native tools)
-
-### Diagnostic Command
-
-`/lean-ctx` — Shows binary path, MCP bridge status, registered tool count, reconnect attempts, last hung/errored tool.
-
-## Dependencies
-
-- **Runtime**: `lean-ctx` binary (v3.4.2 installed via npm/cargo)
-- **npm**: `pi-lean-ctx@3.4.5` with `@modelcontextprotocol/sdk@^1.29.0`
-- **Peer**: `@mariozechner/pi-coding-agent@>=0.50.0` (we have 0.70.x)
-- **Peer**: `@mariozechner/pi-tui@*` (available via pi-coding-agent)
-- **TypeBox alias**: pi-agent's jiti loader aliases `@sinclair/typebox` → `typebox`
-
-## Consequences
-
-### Positive
-
-- 48 lean-ctx MCP tools available to agent: `ctx_session`, `ctx_knowledge`, `ctx_semantic_search`, `ctx_impact`, `ctx_architecture`, `ctx_workflow`, `ctx_gain`, etc.
-- Richer read modes: auto mode selection based on file size + extension
-- Proper compression stats on every tool output
-- Graceful reconnection if MCP server dies
-- Upstream-maintained (by lean-ctx author yvgude)
-
-### Negative
-
-- External npm dependency (mitigated: published by same author as lean-ctx, Apache 2.0)
-- MCP bridge adds startup latency (~200ms for tool discovery)
-- One more package to keep updated
-
-### Neutral
-
-- `/lean-ctx-status` command removed; replaced by `/lean-ctx`
-- Skill routing in SYSTEM.md changed from "default layer" to "native Pi package" description
-
-## Verification
-
-- `lean-ctx` binary v3.4.2 installed ✓
-- `pi-lean-ctx` v3.4.5 installed in `.pi/npm/node_modules` ✓
-- All peer dependencies satisfied ✓
-- `tsc` check on remaining extensions passes ✓
-- @sinclair/typebox aliased by jiti loader ✓
-
-## Next
-
-- Restart pi agent; pi-lean-ctx loads at session start
-- Run `/lean-ctx` to verify MCP bridge connected
-- Monitor `lean-ctx gain` after a few sessions for token savings data

package/vault/wiki/decisions/2026-05-07-replace-lean-ctx-with-context-mode.md

@@ -1,59 +0,0 @@
----
-type: decision
-title: "Replace pi-lean-ctx with context-mode"
-created: 2026-05-07
-updated: 2026-05-07
-tags:
-  - decision
-  - context-optimization
-  - migration
-status: accepted
-related:
-  - "[[context-mode]]"
-  - "[[lean-ctx]]"
-  - "[[agentic-harness-context-enforcement]]"
-
----
-# Replace pi-lean-ctx with context-mode
-
-## Context
-
-ultimate-pi uses `pi-lean-ctx@3.5.1` for context compression via AST parsing, shell pattern compression, and smart read modes. User requested migration to `context-mode` (11K+ GitHub stars, 48K npm downloads/month) as the primary context optimization layer.
-
-context-mode uses intercept-and-sandbox architecture: raw tool output never enters the agent's context window. Instead, output is indexed into SQLite FTS5 with BM25 ranking, and the agent queries on demand. Claims 98-99.5% token reduction. Has native Pi Coding Agent extension support with session_start, tool_call, tool_result, and session_before_compact hooks.
-
-## Alternatives Considered
-
-1. **Keep pi-lean-ctx** — mature, 48 MCP tools, agent governance (profiles, budgets, SLOs), Apache 2.0. Less community adoption (924 stars vs 11K).
-2. **Run both simultaneously** — wiki research notes they solve complementary halves (lean-ctx: compress input, context-mode: sandbox output). However, potential tool conflicts, complexity, and user explicitly requested removal.
-3. **Replace with context-mode** — stronger community validation, native Pi extension, FTS5 sandbox, "Think in Code" paradigm, session continuity.
-
-## Chosen
-
-Replace pi-lean-ctx with context-mode (`npm:context-mode@^1.0.111`).
-
-## Changes Made
-
-- `.pi/settings.json`: replaced `"npm:pi-lean-ctx"` with `"npm:context-mode"`
-- `.pi/npm/package.json`: replaced `"pi-lean-ctx": "^3.5.1"` with `"context-mode": "^1.0.111"`
-- `package.json`: replaced `"lean-ctx"` keyword with `"context-mode"`
-- `.pi/extensions/ck-enforce.ts`: **deleted** (lean-ctx-specific grep override, no longer needed)
-- `CONTRIBUTING.md`: updated lean-ctx reference to context-mode
-
-## Tradeoffs
-
-| Gained | Lost |
-|--------|------|
-| 11K+ GitHub stars, larger community | 48 MCP tools reduced to 11 |
-| FTS5 sandbox (output never enters context) | AST-based compression (tree-sitter, 18 languages) |
-| Native Pi extension with full hook lifecycle | 90+ shell pattern compression |
-| "Think in Code" paradigm enforcement | Smart read modes (full/map/signatures) |
-| Session continuity (26 events) | Agent governance (profiles, budgets, SLOs) |
-
-## Consequences
-
-- Need to ensure context-mode's `ctx_search` and `ctx_execute` tools are integrated into the search policy
-- ck-enforce.ts was blocking conceptual grep searches and steering to `ck --hybrid` — this enforcement is lost; SYSTEM.md grep policy still applies but relies on agent compliance
-- context-mode uses ELv2 license (vs Apache 2.0) — acceptable for internal use
-- `npm install` in `.pi/npm/` installed 42 new packages, removed pi-lean-ctx
-- Wiki pages referencing `[[lean-ctx]]` should be updated to reference `[[context-mode]]` where appropriate

package/vault/wiki/decisions/adr-008.md

@@ -1,40 +0,0 @@
----
-type: decision
-title: "ADR-008: Spec-Only Black-Box QA"
-status: active
-priority: 1
-date: "2026-04-28"
-tags: [adr, qa, testing, harness, layer-4]
-sources:
-  - "[[harness-implementation-plan]]"
-related:
-  - "[[adversarial-verification]]"
-  - "[[agentic-harness]]"
-created: 2026-04-30
-updated: 2026-04-30
----
-
-# ADR-008: Spec-Only Black-Box QA
-
-## Context
-
-Layer 4 (Adversarial Verification) needs to generate tests. Where should the test specifications come from — the implementation code or the specification?
-
-## Decision
-
-Tests are generated from the **specification only** — never from implementation code. This is black-box testing enforced at the architectural level.
-
-The prompt for the QA test writer **never includes implementation code**. The `spec_only` flag is immutable.
-
-## Rationale
-
-- Implementation-aware tests can be gamed by the implementation itself
-- Spec-only tests verify behavior, not implementation details
-- Prevents the common failure mode where agents write tests that pass by construction
-
-## Consequences
-
-- **Positive**: Tests are honest arbiters of correctness
-- **Positive**: No temptation to "test the implementation" rather than the behavior
-- **Negative**: May miss implementation-specific edge cases (mitigated by critic review in Layer 5)
-- **Negative**: Requires well-specified success criteria (enforced by Layer 1 Spec Hardening)

package/vault/wiki/decisions/adr-009.md

@@ -1,46 +0,0 @@
----
-type: decision
-title: "ADR-009: claude-obsidian Mode B for Persistent Memory"
-status: active
-priority: 1
-date: "2026-04-28"
-tags: [adr, memory, wiki, harness, layer-6, claude-obsidian]
-sources:
-  - "[[harness-implementation-plan]]"
-related:
-  - "[[persistent-memory]]"
-  - "[[wiki-query-interface]]"
-  - "[[agentic-harness]]"
-created: 2026-04-30
-updated: 2026-04-30
----
-
-# ADR-009: claude-obsidian Mode B for Persistent Memory
-
-## Context
-
-Layer 6 (Persistent Memory) needs a knowledge base that persists across sessions, supports cross-referencing, and enables retrieval. Previous approach used a custom `WikiKnowledgeBase` class with Vectra BM25+vector search (~87MB deps).
-
-## Decision
-
-Replace custom WikiKnowledgeBase + Vectra with **claude-obsidian skills in GitHub Mode B**. Search is LLM-native: `hot.md` → `index.md` → pages. No custom code, no embedding model.
-
-## Comparison
-
-| Aspect | Before (ADR-007) | After (ADR-009) |
-|--------|-------------------|------------------|
-| Cross-session memory | None | hot.md ~500-word cache |
-| Source provenance | No tracking | .raw/ immutable sources + manifest delta |
-| Repository structure | Flat patterns/ dirs | Mode B: modules, components, decisions, dependencies, flows |
-| Search | Vectra BM25+vector (~80MB model) | LLM-native: hot.md → index.md → pages |
-| Lint / health | None | 8+ category checks |
-| Contradiction flagging | None | `> [!contradiction]` callouts |
-| Dependencies | ~87MB | ~50KB skills + optional ollama |
-
-## Consequences
-
-- **Positive**: Eliminates ~87MB dependency footprint
-- **Positive**: LLM-native search leverages existing Claude capabilities
-- **Positive**: Obsidian wiki is human-readable and browseable
-- **Negative**: Search quality depends on LLM context management (mitigated by 3-mode depth system)
-- **Negative**: No semantic similarity search without optional ollama setup

package/vault/wiki/decisions/adr-010.md

@@ -1,55 +0,0 @@
----
-type: decision
-title: "ADR-010: Agentic Harness ↔ Wiki Tight-Coupling Contract"
-status: active
-priority: 1
-created: "2026-04-28"
-updated: "2026-04-28"
-tags: [decision, harness, wiki, integration, pipeline, adr]
-sources:
-  - "[[harness]]"
-  - "[[harness-implementation-plan]]"
-  - "[[adr-009]]"
-  - "[[adr-008]]"
-  - "[[persistent-memory]]"
-  - "[[wiki-query-interface]]"
-related:
-  - "[[colocate-wiki]]"
-  - "[[harness-wiki-skill-mapping]]"
-  - "[[harness-wiki-pipeline]]"
----
-
-# ADR-010: Agentic Harness ↔ Wiki Tight-Coupling Contract
-
-## Context
-
-The harness has 8 layers. Layers 6 (Persistent Memory) and 8 (Wiki Query Interface) already reference the wiki. But the other 6 layers have **no explicit read/write contract** with the wiki. This creates two failure modes:
-
-1. **Design drift**: An agent makes a decision that contradicts an existing ADR or module spec because it never read the wiki first.
-2. **Wiki staleness**: After a pipeline event changes the codebase, the wiki is not updated — decisions, patterns, and statuses go stale.
-
-[[adr-009]] replaced Vectra with LLM-native wiki search. [[colocate-wiki]] put the wiki in-repo. Now we need the **contract** that makes the harness and wiki a single synchronized system.
-
-## Decision
-
-**Every harness layer reads relevant wiki docs before acting, and writes back to the wiki after every state transition.** The contract is enforced at the extension layer (L7 schema orchestration), not by convention.
-
-Two axioms:
-1. **Read-first**: No layer acts without querying the wiki for relevant ADRs, module specs, and patterns.
-2. **Write-after**: No state transition completes without a wiki write that keeps docs current.
-
-## Rationale
-
-- **Consistency**: If ADR-008 says "black-box QA", no layer should generate implementation-coupled tests. Reading the wiki first prevents this.
-- **Traceability**: Every state transition produces a wiki artifact. Future sessions can reconstruct the full decision chain.
-- **Staleness elimination**: The wiki is the single source of truth for design decisions. If code changes, the wiki reflects it. If the wiki says something, the code respects it.
-- **Self-healing**: wiki-lint after every 10-15 writes catches contradictions, orphans, and stale claims before they compound.
-
-## Consequences
-
-- **Positive**: Harness decisions are always grounded in documented architecture.
-- **Positive**: Wiki stays current automatically — no manual doc updates needed.
-- **Positive**: New sessions can pick up exactly where the last left off via hot.md.
-- **Negative**: Extra token cost per subtask (~500-1500 for reads, ~500-1500 for writes).
-- **Negative**: Requires discipline at the extension-layer hooks — must not skip wiki reads.
-- **Negative**: Lint runs add latency but prevent long-term decay.

package/vault/wiki/decisions/adr-011.md

@@ -1,165 +0,0 @@
----
-type: decision
-title: "ADR-011: Multi-Agent Consensus Debate in the Harness Pipeline"
-status: accepted
-priority: 1
-date: "2026-04-30"
-tags: [adr, harness, consensus, debate, multi-agent, pi-messenger, selective-routing, imad]
-sources:
-  - "[[harness-implementation-plan]]"
-  - "[[pi-messenger-analysis]]"
-  - "[[fan2025-imad]]"
-related:
-  - "[[agentic-harness]]"
-  - "[[adversarial-verification]]"
-  - "[[spec-hardening]]"
-  - "[[structured-planning]]"
-  - "[[consensus-debate]]"
-  - "[[selective-debate-routing]]"
-  - "[[drift-detection-unified]]"
-supersedes:
-created: 2026-04-30
-updated: 2026-04-30
----
-
-# ADR-011: Multi-Agent Consensus Debate with Selective Routing
-
-## Context
-
-The current harness pipeline is single-agent sequential: one agent hardens the spec (L1), one agent plans (L2), one agent executes (L3), one critic attacks once (L4). L4 has `max_attack_rounds: 2` — a retry loop, not a debate.
-
-The best human software decisions come from back-and-forth argument: thesis → antithesis → synthesis. Single-pass review is weak because the reviewer's first objection is often shallow, and the proposer's rebuttal frequently reveals a deeper truth neither saw alone.
-
-Agents lack intuition. Multi-round argument is a substitute for intuition — each round forces the opponent to find a new attack surface, and each rebuttal forces the defender to articulate deeper justification.
-
-pi-messenger (nicobailon/pi-messenger, 532 ⭐) demonstrates that agents CAN communicate peer-to-peer via the file system — registry, inboxes, `fs.watch` for real-time delivery. No server, no daemon, just files. This is the right transport primitive for consensus debates.
-
-**UPDATE (2026-04-30)**: iMAD (Fan et al., AAAI 2026) demonstrates that debate is NOT always beneficial. Multi-agent debate can overturn correct single-agent answers. Always-on debate wastes tokens AND can reduce accuracy. Selective routing via a pre-debate gating classifier saves 92% tokens AND improves accuracy by 13.5%.
-
-## Decision
-
-**Add a consensus debate capability to the harness pipeline. Use pi-messenger's file-based message passing as the transport layer. Strip all UI overlays. Build a consensus protocol on top. Gate debate with iMAD-style selective routing — trigger debate only when a pre-debate classifier detects hesitation/uncertainty cues in single-agent self-critique.**
-
-### iMAD Integration: Pre-Debate Gate
-
-Before spawning a debate, the system:
-
-1. Single agent produces structured self-critique response
-2. Extract hesitation cues: uncertainty markers ("might", "could be", "I think"), contradictory statements, missing evidence references, low confidence indicators
-3. Lightweight classifier → debate or skip
-4. If confidence high + no hesitation → skip debate, save tokens
-5. If uncertainty detected → trigger full consensus debate
-
-Expected reduction: ~92% token savings on high-confidence tasks (~80% of tasks in early estimate).
-
-### What we adopt from pi-messenger:
-
-| Component | Purpose |
-|-----------|---------|
-| Agent registry (`.pi/messenger/registry/`) | Agent discovery, presence |
-| Per-agent inbox directories | Message delivery |
-| `fs.watch`-based message detection | Real-time delivery without polling |
-| JSON message format | Structured inter-agent communication |
-| Atomic file write patterns | Race-free message delivery |
-| Stale registration cleanup | Dead agent garbage collection |
-| Memorable name generation | Debug-friendly agent identification |
-
-### What we strip (the "overlays"):
-
-- Chat overlay UI (`/messenger`)
-- Status bar indicators (●3, on fire, debugging...)
-- Activity feed timeline
-- Emoji-based status messages
-- Human-as-participant features
-- Crew orchestration (planner→worker→reviewer DAG) — L7 handles this
-- Swarm claim/complete — L7 handles task tracking
-- Message budgets (per-coordination-level) — consensus budget replaces this
-
-### Consensus Protocol:
-
-A structured debate protocol with:
-
-1. **DebateSession**: N agents, M rounds, defined topic/scope
-2. **ConsensusBudget**: Max rounds, max tokens per round, max wall-clock time
-3. **Turn protocol**: Structured messages with `{ role, round, claim, counter_to, evidence_refs }`
-4. **Convergence detection**: When positions stabilize for K consecutive rounds
-5. **Verdict**: `CONSENSUS_REACHED`, `DEADLOCK` (positions unchanged after N rounds), `BUDGET_EXHAUSTED`
-
-### Integration points (selective — triggered only when pre-debate gate signals uncertainty):
-
-| Layer | Debate purpose | Agents | Budget |
-|-------|---------------|--------|--------|
-| L1 (Spec Hardening) | Argue about ambiguity resolution | Spec proposer + Spec critic | 3 rounds, ~6K tokens |
-| L2 (Structured Planning) | Argue about plan structure, dependencies | Planner + Plan critic | 3 rounds, ~10K tokens |
-| L4 (Adversarial Verification) | Multi-round attack on implementation | Defender + Attacker | 4 rounds, ~8K tokens |
-
-## Rationale
-
-### Why file-based messaging (not MCP, not HTTP, not in-process)?
-
-1. **Zero infrastructure**: No server, no daemon, no port management. pi.dev extensions already have filesystem access.
-2. **Process isolation**: Each debate participant is a separate LLM session. Filesystem is the natural IPC boundary.
-3. **Crash safety**: Messages are files. If an agent crashes, its messages persist. Debate can resume.
-4. **Observability**: Debate transcripts are files on disk. Debuggable without tooling.
-5. **pi-messenger already solved this**: Registry format, inbox pattern, watcher debouncing, stale cleanup — all battle-tested.
-
-### Why selective routing (not always-on debate)?
-
-iMAD shows that always-on debate:
-- Costs 92% more tokens than selective routing
-- Can overturn correct single-agent answers (accuracy regression)
-- Is only beneficial when the single agent shows hesitation/uncertainty
-
-Single agent self-critique is cheaper than full debate. Route to debate only when needed.
-
-### Why not use pi-messenger's Crew orchestration?
-
-The harness has L7 (Schema Orchestration via Archon) for DAG execution, loop nodes, approval gates, and worktree isolation. pi-messenger's Crew (planner→worker→reviewer waves) is a competing orchestration model. Using both would create conflicting DAG executors.
-
-### Why consensus budgets?
-
-Without budgets, debates consume unlimited tokens. A budget forces convergence — agents must prioritize their strongest arguments. This mirrors real human meetings with time limits.
-
-## Consequences
-
-### Positive
-- **Better decisions when needed**: Multi-round argument surfaces deeper issues than single-pass review
-- **Token-efficient**: Selective routing avoids debating settled questions
-- **Defense in depth**: Adversarial verification becomes genuine debate when warranted
-- **Spec quality**: L1 debates catch ambiguous specs before implementation
-- **Permanent agent alignment**: Winning consensus filed to `wiki/consensus/` — future agents query and align to resolved debates, preventing re-litigation
-- **Observable reasoning**: Debate transcripts are file artifacts that can be audited
-
-### Negative
-- **Complexity**: New consensus protocol layer, pre-debate classifier, message schema, convergence detection
-- **Classifier accuracy risk**: Pre-debate gate may miss cases where debate would help (false negatives)
-- **Latency**: When debate IS triggered, multi-round adds wall-clock time
-- **Agent quality variance**: Cheap models may produce shallow arguments
-
-### Mitigations
-- Debate is opt-in per layer (configurable `consensus: { enabled: true/false }`)
-- Pre-debate classifier is conservative: when uncertain, trigger debate
-- Budgets prevent runaway token consumption
-- **Winning consensus MUST be filed in wiki (`wiki/consensus/`)** as a permanent alignment record — NOT optional. Future agents query consensus before making decisions. Contradicting a filed consensus triggers harness block.
-- Hard-threshold pass/fail criteria (not narrative self-assessment) as primary L4 mechanism; debate is supplementary
-
-## Token Budget Impact (with Selective Routing)
-
-| Activity | Always-Debate | With Selective (80% skip rate) |
-|----------|--------------|-------------------------------|
-| L1 Spec Debate | +4,000 | +800 avg |
-| L2 Plan Debate | +5,000 | +1,000 avg |
-| L4 Adversarial Debate | +4,000 | +1,200 avg |
-| **Total added per subtask** | **~13,000** | **~3,000 avg** |
-
-## Implementation
-
-See [[harness-implementation-plan]] Phases P17-P19 and P2b.
-
-## Related
-
-- [[consensus-debate]] — concept page for the consensus protocol
-- [[selective-debate-routing]] — iMAD concept and mechanism
-- [[pi-messenger-analysis]] — full analysis of pi-messenger and what we adopt/strip
-- [[harness-implementation-plan]] — master plan with build phases
-- [[drift-detection-unified]] — how consensus debate complements drift detection