clearctx 3.0.0

package/README.md

@@ -0,0 +1,1006 @@
+# clearctx
+
+[![npm version](https://img.shields.io/npm/v/clearctx.svg)](https://www.npmjs.com/package/clearctx)
+[![license](https://img.shields.io/npm/l/clearctx.svg)](https://github.com/)
+[![node](https://img.shields.io/node/v/clearctx.svg)](https://nodejs.org)
+
+> Multi-session orchestration system for Claude Code CLI. Spawn parallel workers that coordinate via artifacts and phase gates. 68 MCP tools. v2.9.0.
+
+---
+
+**Multi-session orchestrator for Claude Code CLI** — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically.
+
+Built on Claude CLI's `stream-json` protocol for efficient multi-turn conversations using a single long-lived process per session.
+
+## Why?
+
+Claude Code's `-p` (print) mode is one-shot: one prompt, one response. For larger projects you need:
+
+- **Multi-turn conversations** — send follow-ups without restarting
+- **Parallel sessions** — work on multiple tasks simultaneously
+- **Pause & Resume** — stop a session and come back later
+- **Session forking** — branch off to try different approaches
+- **Cost tracking** — know what each session costs
+- **Programmatic control** — use from scripts or other tools
+
+This package solves all of the above with zero dependencies.
+
+## Install
+
+```bash
+npm install -g clearctx
+```
+
+### Quick Setup (MCP Integration)
+
+After installing, run the setup wizard to register the MCP server with Claude Code:
+
+```bash
+clearctx setup
+```
+
+This adds 17 native tools to Claude Code (spawn_session, delegate_task, etc.) so Claude can manage sessions directly — no Bash commands needed.
+
+**Non-interactive options:**
+```bash
+clearctx setup --global          # Register for all projects
+clearctx setup --local           # Register for current project only
+clearctx setup --global --guide  # Also add strategy guide to CLAUDE.md
+clearctx setup --uninstall       # Remove MCP integration
+```
+
+### CLI Usage
+
+Use `cms` (or `clearctx`) from anywhere:
+
+```bash
+clearctx spawn --name my-task --prompt "Fix the auth bug"
+clearctx send --name my-task --message "Also add tests"
+```
+
+**Or use without installing:**
+```bash
+npx clearctx spawn --name my-task --prompt "Fix the auth bug"
+```
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/code) must be installed and authenticated.
+
+## Quick Start
+
+```bash
+# Start a session with a prompt
+clearctx spawn --name fix-auth --prompt "Fix the authentication bug in auth.service.ts" --model sonnet
+
+# Send follow-up messages (same session, full context retained)
+clearctx send --name fix-auth --message "Also add input validation"
+clearctx send --name fix-auth --message "Now write tests for it"
+
+# Stop when done (can resume later)
+clearctx stop --name fix-auth
+
+# Resume days later
+clearctx resume --name fix-auth --message "Actually, handle the edge case too"
+
+# Check what happened
+clearctx output --name fix-auth --full
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `spawn` | Start a new session |
+| `send` | Send follow-up message (auto-resumes if stopped) |
+| `resume` | Restore a stopped/paused session |
+| `pause` | Pause session (process stays alive) |
+| `fork` | Branch off into new session (keeps parent context) |
+| `stop` | Gracefully stop (saves state, can resume later) |
+| `kill` | Force kill a session |
+| `status` | Show detailed session info |
+| `output` | Get last response text |
+| `list` | List all sessions |
+| `history` | Show full interaction history |
+| `delete` | Permanently remove a session |
+| `batch` | Spawn multiple sessions from JSON file |
+| `cleanup` | Remove old sessions |
+| `delegate` | Smart task delegation with safety limits + control loop |
+| `continue` | Send follow-up to a delegated session |
+
+## How It Works
+
+### Streaming Mode (Default)
+
+Uses Claude CLI's `--input-format stream-json` to keep **one process alive** per session:
+
+```
+spawn  → starts ONE claude process (stays alive)
+send   → pipes message into stdin → reads response from stdout
+send   → pipes again → reads again (same process, no reload)
+```
+
+**Benefits over the resume approach:**
+- No process restart overhead (~2-3s saved per message)
+- No conversation history reload (lower token cost)
+- Instant follow-up responses
+
+### Session Persistence
+
+Sessions are saved to `~/.clearctx/sessions.json`. When a session is stopped, its Claude session ID is saved. When you resume it later, the system uses `--resume <session-id>` to restore the full conversation context.
+
+## Parallel Tasks
+
+### Batch Mode
+```bash
+# Create a tasks.json file
+echo '[
+  { "name": "task-1", "prompt": "Build login page", "model": "sonnet" },
+  { "name": "task-2", "prompt": "Build signup page", "model": "sonnet" },
+  { "name": "task-3", "prompt": "Build dashboard", "model": "sonnet" }
+]' > tasks.json
+
+# Spawn all in parallel
+clearctx batch --file tasks.json
+```
+
+### Programmatic API
+```javascript
+const { SessionManager } = require('clearctx');
+const mgr = new SessionManager();
+
+// Spawn multiple sessions in parallel
+const results = await mgr.batch([
+  { name: 'task-1', prompt: 'Build login page', model: 'sonnet' },
+  { name: 'task-2', prompt: 'Build signup page', model: 'sonnet' },
+]);
+
+// Send follow-ups
+const r1 = await mgr.send('task-1', 'Add form validation');
+const r2 = await mgr.send('task-2', 'Add password strength meter');
+
+console.log(r1.text); // The response
+console.log(r1.cost); // Cost in USD
+
+mgr.stopAll();
+```
+
+## Forking Sessions
+
+Fork creates a new session that starts with all the parent's conversation context:
+
+```bash
+# Original session
+clearctx spawn --name approach-a --prompt "Implement auth with sessions"
+clearctx send --name approach-a --message "Add login endpoint"
+
+# Fork to try a different approach (keeps all context from approach-a)
+clearctx fork --name approach-a --new-name approach-b --message "Actually, use JWT instead"
+
+# Now both sessions exist independently
+clearctx send --name approach-a --message "Add session storage"
+clearctx send --name approach-b --message "Add token refresh"
+```
+
+## Delegate (Control Loop + Safety Net)
+
+The `delegate` system gives the parent Claude (or any automation) human-like control over child sessions:
+
+1. **Spawns** a session with the right permissions
+2. **Sends** the task
+3. **Monitors** for issues (permission denials, cost overruns, turn limits)
+4. **Auto-handles** permission retries
+5. **Returns** structured output for the parent to evaluate
+6. **Accepts** follow-up corrections via `continue`
+
+### CLI Usage
+
+```bash
+# Delegate a task with a $1 budget limit
+clearctx delegate --name fix-bug --task "Fix the auth bug in auth.service.ts" --max-cost 1.00
+
+# Delegate with read-only mode (no file edits allowed)
+clearctx delegate --name review --task "Review code quality of src/" --preset read-only
+
+# Get structured JSON output (for programmatic use)
+clearctx delegate --name task-1 --task "Count all TypeScript files" --model haiku --json
+
+# Send follow-up corrections
+clearctx continue --name fix-bug --message "Also add input validation"
+
+# Full control with context and custom limits
+clearctx delegate --name big-refactor --task "Refactor the auth module" \
+  --model opus --preset full --max-cost 5.00 --max-turns 100 \
+  --context "Use JWT tokens, not sessions"
+
+# Disable safety net entirely (no cost/turn/path limits)
+clearctx delegate --name trusted-task --task "Build the feature" --no-safety
+```
+
+### Permission Presets
+
+| Preset | Permission Mode | Description |
+|--------|----------------|-------------|
+| `read-only` | default | Can search and read files only |
+| `review` | default | Same as read-only (code review) |
+| `edit` | acceptEdits | Can read and edit files (default) |
+| `full` | bypassPermissions | Full access (use with caution) |
+| `plan` | plan | Explore only, no execution |
+
+### Safety Net
+
+Every delegated session has automatic safety limits:
+
+- **Cost limit** — Auto-kills if cumulative cost exceeds threshold (default: $2.00)
+- **Turn limit** — Auto-kills if agent turns exceed threshold (default: 50)
+- **Time limit** — Timeout per interaction (default: 5 minutes)
+- **Protected paths** — Warns on modifications to `.env`, `.git/`, `node_modules/`, etc.
+
+### Structured Output (--json)
+
+When using `--json`, delegate returns machine-readable output:
+
+```json
+{
+  "status": "completed",
+  "response": "Fixed the auth bug by...",
+  "cost": 0.0342,
+  "turns": 5,
+  "duration": 12340,
+  "sessionId": "abc123",
+  "name": "fix-bug",
+  "canContinue": true,
+  "toolsUsed": ["Read", "Edit", "Grep"],
+  "safety": {
+    "totalViolations": 0,
+    "violations": [],
+    "limits": { "maxCostUsd": 1.00, "maxTurns": 50 }
+  },
+  "error": null
+}
+```
+
+**Status values:** `completed`, `needs_input`, `failed`, `cost_exceeded`, `turns_exceeded`
+
+### Programmatic Delegate API
+
+```javascript
+const { SessionManager, Delegate } = require('clearctx');
+
+const mgr = new SessionManager();
+const delegate = new Delegate(mgr);
+
+// One-shot delegation
+const result = await delegate.run('fix-bug', {
+  task: 'Fix the authentication bug in auth.service.ts',
+  model: 'sonnet',
+  preset: 'edit',
+  maxCost: 1.00,
+  maxTurns: 30,
+});
+
+console.log(result.status);   // 'completed'
+console.log(result.response);  // What the session did
+console.log(result.cost);      // $0.0342
+
+// Disable safety net entirely
+const noSafety = await delegate.run('trusted', {
+  task: 'Build the whole feature',
+  safety: false,  // No cost/turn/path limits
+});
+
+// Multi-step with evaluation
+const r1 = await delegate.run('feature', { task: 'Build login page' });
+// Parent evaluates r1.response...
+const r2 = await delegate.continue('feature', 'Good, now add form validation');
+// Parent evaluates r2.response...
+const r3 = await delegate.continue('feature', 'Perfect. Now write tests.');
+delegate.finish('feature');
+```
+
+### SafetyNet Standalone
+
+```javascript
+const { SafetyNet, StreamSession } = require('clearctx');
+
+const safety = new SafetyNet({
+  maxCostUsd: 0.50,
+  maxTurns: 20,
+  protectedPaths: ['.env', 'credentials/', '.git/'],
+});
+
+const session = new StreamSession({ name: 'task', model: 'haiku' });
+session.start();
+safety.attach(session);
+
+// Safety net monitors all interactions
+safety.on('violation', (v) => console.log('VIOLATION:', v.message));
+safety.on('kill', (v) => console.log('SESSION KILLED:', v.message));
+
+await session.send('Do something');
+```
+
+## Options
+
+### spawn
+```
+--name <name>              Session name (required)
+--prompt <text>            Initial prompt (required)
+--model <model>            Model: sonnet, opus, haiku (default: sonnet)
+--stop                     Stop after first response (one-shot mode)
+--work-dir <path>          Working directory for claude
+--permission-mode <mode>   Permission mode: default, acceptEdits, bypassPermissions
+--allowed-tools <t1,t2>    Restrict available tools
+--system-prompt <text>     Append to system prompt
+--max-budget <usd>         Max budget in USD
+--agent <name>             Use a specific agent
+```
+
+### send
+```
+--name <name>              Session name (required)
+--message <text>           Message to send (required)
+--stop                     Stop session after response
+```
+
+### delegate
+```
+--name <name>              Session name (required)
+--task <text>              Task description (required)
+--model <model>            Model: sonnet, opus, haiku (default: sonnet)
+--preset <preset>          Permission preset (default: edit)
+--max-cost <usd>           Max cost in USD (default: 2.00)
+--max-turns <n>            Max agent turns (default: 50)
+--no-safety                Disable safety net entirely (no cost/turn/path limits)
+--context <text>           Extra context to prepend to the task
+--work-dir <path>          Working directory
+--system-prompt <text>     Append to system prompt
+--agent <name>             Use a specific agent
+--json                     Output structured JSON
+```
+
+### continue
+```
+--name <name>              Session name (required)
+--message <text>           Follow-up message (required)
+--json                     Output structured JSON
+```
+
+## Programmatic API
+
+```javascript
+const { SessionManager, StreamSession } = require('clearctx');
+
+// High-level API (recommended)
+const mgr = new SessionManager({
+  defaultModel: 'sonnet',
+  defaultPermissionMode: 'default',
+});
+
+const { session, response } = await mgr.spawn('my-task', {
+  prompt: 'Fix the auth bug',
+  model: 'sonnet',
+  workDir: '/path/to/project',
+});
+
+const r2 = await mgr.send('my-task', 'Add tests');
+mgr.stop('my-task');
+
+// Low-level API (single session)
+const session = new StreamSession({
+  name: 'direct',
+  model: 'haiku',
+});
+session.start();
+const r1 = await session.send('Hello');
+const r2 = await session.send('Follow up');
+session.stop();
+```
+
+### Events
+
+```javascript
+session.on('text', (text) => { /* partial text chunks */ });
+session.on('tool-use', ({ name, input }) => { /* tool calls */ });
+session.on('result', (response) => { /* complete response */ });
+session.on('init', (data) => { /* session initialized */ });
+session.on('error', (err) => { /* error occurred */ });
+session.on('close', (code) => { /* process exited */ });
+```
+
+## Cost Tracking
+
+Every interaction tracks cost:
+
+```bash
+clearctx status --name my-task
+# Shows: total cost, turns, interactions
+
+clearctx history --name my-task
+# Shows: cost per interaction
+```
+
+## Data Storage
+
+Session data is stored in `~/.clearctx/`:
+- `sessions.json` — Session metadata, history, and config
+
+Clean up old sessions:
+```bash
+clearctx cleanup --days 7
+```
+
+## MCP Server (Claude Code Native Integration)
+
+The MCP server exposes all multi-session tools as **native Claude Code tools**. Instead of running CLI commands via Bash, Claude calls tools directly — just like Read, Edit, or Grep.
+
+### Setup
+
+**Automatic (recommended):**
+```bash
+clearctx setup
+```
+This interactive wizard registers the MCP server for you. See [Quick Setup](#quick-setup-mcp-integration) above.
+
+**Manual — Option 1: Global install**
+```bash
+npm install -g clearctx
+```
+
+Add to your Claude Code MCP config (`~/.claude/settings.json` or project `.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "multi-session": {
+      "command": "cms-mcp"
+    }
+  }
+}
+```
+
+**Manual — Option 2: Local (no install)**
+```json
+{
+  "mcpServers": {
+    "multi-session": {
+      "command": "node",
+      "args": ["/absolute/path/to/clearctx/bin/mcp.js"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+Once configured, Claude sees these tools:
+
+**Session Management:**
+| Tool | Description |
+|------|-------------|
+| `spawn_session` | Start a new session |
+| `send_message` | Send message (auto-resumes if stopped) |
+| `resume_session` | Resume a stopped session |
+| `pause_session` | Pause a session |
+| `fork_session` | Fork into a new session |
+| `stop_session` | Gracefully stop |
+| `kill_session` | Force kill |
+
+**Information:**
+| Tool | Description |
+|------|-------------|
+| `get_session_status` | Detailed session info |
+| `get_last_output` | Last response text |
+| `list_sessions` | List all sessions |
+| `get_history` | Full interaction history |
+| `delete_session` | Permanently delete |
+
+**Delegate (Control Loop + Safety):**
+| Tool | Description |
+|------|-------------|
+| `delegate_task` | Smart delegation with safety limits |
+| `continue_task` | Send corrections to a delegated task |
+| `finish_task` | Finish a task cleanly |
+| `abort_task` | Emergency abort |
+
+**Batch:**
+| Tool | Description |
+|------|-------------|
+| `batch_spawn` | Spawn multiple sessions in parallel |
+
+### How Claude Uses It
+
+With MCP configured, Claude can autonomously:
+
+```
+User: "Build auth with login, signup, and password reset"
+
+Claude thinks: "This has 3 independent parts. I'll delegate in parallel."
+
+Claude calls:
+  → delegate_task(name="auth-login", task="Build login with JWT", model="sonnet")
+  → delegate_task(name="auth-signup", task="Build signup with validation", model="sonnet")
+  → delegate_task(name="auth-reset", task="Build password reset with email", model="sonnet")
+
+Claude reads results, notices signup is missing email validation...
+
+Claude calls:
+  → continue_task(name="auth-signup", message="Add email format validation")
+
+All good now. Claude calls:
+  → finish_task(name="auth-login")
+  → finish_task(name="auth-signup")
+  → finish_task(name="auth-reset")
+
+Claude: "Done! All 3 auth features implemented."
+```
+
+### Strategy Guide
+
+See `STRATEGY.md` for the complete guide on:
+- When to delegate vs do it yourself
+- How to decompose tasks
+- Model selection (haiku/sonnet/opus)
+- Budget allocation
+- The correction loop pattern
+- Parallel coordination
+
+## Requirements
+
+- **Node.js** >= 18
+- **Claude Code CLI** installed and authenticated
+- Zero npm dependencies
+
+---
+
+## Team Hub v2 — Multi-Session Collaboration
+
+**Team Hub v2** transforms isolated Claude sessions into **self-organizing teams** that exchange structured data, auto-resolve dependencies, and heal themselves when things break. Instead of talking in natural language (which degrades over time), sessions coordinate through **versioned artifacts** and **formal contracts**.
+
+This is the only multi-agent system for Claude Code that uses **transactional coordination** instead of conversational coordination.
+
+### The Three-Layer Architecture
+
+**Layer 1: Chat** — Sessions message each other directly (like Slack)
+- Send DMs, broadcasts, and blocking ask/reply questions
+- Check inbox before starting work, after major steps
+- Rate-limited and loop-protected to prevent message storms
+
+**Layer 2: Artifacts & Contracts** — Sessions exchange structured, versioned data (like Git + Jira)
+- **Artifacts:** Immutable, versioned outputs with JSON schema validation
+- **Contracts:** Formal task assignments with auto-resolving dependencies
+- **Peer-to-peer:** ANY session can create contracts for ANY other session (not just the orchestrator)
+
+**Layer 3: Reactive Intelligence** — The system monitors itself and auto-heals (like a self-driving car)
+- **Lineage Graph:** Track data provenance, detect stale artifacts, analyze impact radius
+- **Reactive Pipelines:** Event-driven trigger→action rules (e.g., "when tests fail, reopen the API contract")
+- **Snapshot & Replay:** Capture full state, rollback, replay workflows with different parameters
+
+### Quick Start
+
+```bash
+# Spawn 3 team members
+clearctx team-spawn --name db-dev --role database --prompt "Create User model"
+clearctx team-spawn --name api-dev --role backend --prompt "Build auth API"
+clearctx team-spawn --name qa-dev --role QA --prompt "Write auth tests"
+
+# Create a contract chain (Layer 2)
+clearctx contract-create setup-user-model --assignee db-dev \
+  --title "Create User schema" \
+  --expected-output schema-change
+
+clearctx contract-create build-auth-api --assignee api-dev \
+  --title "Build auth endpoints" \
+  --depends-on setup-user-model \
+  --expected-output api-contract
+
+clearctx contract-create write-auth-tests --assignee qa-dev \
+  --title "Write integration tests" \
+  --depends-on build-auth-api \
+  --expected-output test-results
+
+# Watch the contracts auto-resolve as artifacts are published
+clearctx contract-list
+
+# DB session publishes schema
+clearctx artifact-publish schema-user-model --type schema-change \
+  --name "User model schema" \
+  --data '{"models":[{"name":"User","fields":["email","phone","password"]}]}'
+# → setup-user-model auto-completes → build-auth-api becomes "ready"
+
+# API session publishes contract (derived from schema)
+clearctx artifact-publish api-contract-user-auth --type api-contract \
+  --name "Auth API contract" \
+  --derived-from schema-user-model@v1 \
+  --data '{"endpoints":[{"method":"POST","path":"/login"}]}'
+# → build-auth-api auto-completes → write-auth-tests becomes "ready"
+
+# QA session publishes test results (derived from API contract)
+clearctx artifact-publish test-results-auth --type test-results \
+  --name "Auth integration tests" \
+  --derived-from api-contract-user-auth@v1 \
+  --data '{"total":12,"passed":12,"failed":0}'
+# → write-auth-tests auto-completes → entire chain done
+
+# Query the lineage graph (Layer 3)
+clearctx artifact-lineage test-results-auth --direction upstream
+# Shows: test-results → api-contract → schema
+
+# Take a snapshot before trying a different approach
+clearctx team-snapshot pre-graphql --label "Auth feature complete with REST"
+
+# Replay with overrides to try GraphQL instead
+clearctx team-replay pre-graphql --overrides '{"build-auth-api":{"inputs":{"context":"Use GraphQL instead of REST"}}}'
+# → Entire workflow re-executes with GraphQL approach
+```
+
+---
+
+## Layer 1: Chat (8 MCP Tools)
+
+Sessions can communicate directly without routing through the orchestrator.
+
+| Tool | Description |
+|------|-------------|
+| `team_spawn` | Spawn a session with team system prompt injected (includes roster, artifact/contract tools) |
+| `team_send_message` | Send a DM to a specific teammate |
+| `team_broadcast` | Send a message to all team members |
+| `team_check_inbox` | Check unread messages (do this before starting work and after major steps) |
+| `team_ask` | Ask a question and WAIT for reply (blocking poll) |
+| `team_reply` | Reply to a question received in inbox |
+| `team_roster` | View all team members with roles, status, and lastSeen times |
+| `team_update_status` | Update your own status, task, or role |
+
+**Safety features:**
+- Rate limit: 10 messages/minute per session
+- Loop detection: >5 exchanges between same pair in 60s = blocked
+- Auto-compaction: Inbox files auto-compact when they exceed 1000 lines
+
+**When to use chat vs artifacts:**
+- Use **chat** for quick questions, coordination, status updates
+- Use **artifacts** for actual work outputs (schemas, API contracts, test results)
+- Use **contracts** to assign work and track progress
+
+---
+
+## Layer 2: Artifacts & Contracts (12 MCP Tools)
+
+### Versioned Artifacts (6 Tools)
+
+Artifacts are **immutable, versioned outputs** with JSON schema validation for well-known types.
+
+| Tool | Description |
+|------|-------------|
+| `artifact_publish` | Publish structured data (creates new version, validates schema, records lineage, triggers resolution + pipelines) |
+| `artifact_get` | Read an artifact (latest or specific version) |
+| `artifact_list` | List all artifacts with optional filters (type, publisher, tag) |
+| `artifact_history` | View all versions of an artifact |
+
+**Well-known artifact types** (validated against JSON schemas):
+
+| Type | Data Shape |
+|------|-----------|
+| `api-contract` | `{ endpoints: [{ method, path, request, response }] }` |
+| `schema-change` | `{ models: [{ name, action, fields }] }` |
+| `component-spec` | `{ componentName, props, states, events }` |
+| `test-results` | `{ total, passed, failed, failures: [...] }` |
+| `file-manifest` | `{ files: [{ path, action, description }] }` |
+| `config-change` | `{ changes: [{ key, oldValue, newValue }] }` |
+| `custom` | Any JSON (no schema validation) |
+
+**Immutability:** Version files are write-once. First writer wins, second gets an error. This prevents version conflicts.
+
+**Schema validation:** When publishing a well-known artifact type, the `data` field is validated against the JSON schema. If validation fails, the publish is rejected with a clear error message.
+
+### Contracts (6 Tools)
+
+Contracts are **formal task assignments** with auto-resolving dependencies. ANY session can create contracts for ANY other session (not just the orchestrator) — this is what makes the system truly **peer-to-peer**.
+
+| Tool | Description |
+|------|-------------|
+| `contract_create` | Create a task contract and assign it to any teammate (peer-to-peer) |
+| `contract_start` | Start working on an assigned contract (returns inputs + resolved artifacts) |
+| `contract_complete` | Mark a contract as done (triggers cascade + pipelines) |
+| `contract_fail` | Mark a contract as failed (notifies assigner) |
+| `contract_reopen` | Reopen a failed/completed contract for retry (increments retryCount) |
+| `contract_get` | Get full contract details |
+| `contract_list` | List all contracts with optional filters (status, assignee, assigner) |
+| `contract_reassign` | Change who's assigned to a contract |
+
+**Contract lifecycle:**
+
+```
+pending → ready → in_progress → completed
+            ↑           ↓
+            └─ (reopen) ─ failed
+```
+
+- **pending:** Waiting for dependencies (other contracts or artifacts)
+- **ready:** All dependencies satisfied, ready to start
+- **in_progress:** Assignee is working on it
+- **completed:** Auto-completed when acceptance criteria are met
+- **failed:** Assignee marked it as failed OR timeout exceeded
+
+**Acceptance criteria types:**
+
+| Type | Met when |
+|------|----------|
+| `artifact_published` | Matching artifact exists at required version |
+| `tests_passing` | test-results artifact meets pass/fail thresholds |
+| `contract_completed` | Referenced contract is completed |
+| `all_outputs_published` | All required expectedOutputs have matching artifacts |
+
+**Safety features:**
+- **Timeout:** Contracts can have `timeoutMs` — auto-failed if not completed in time
+- **Retry limit:** `maxRetries` (default 3) — reopen rejected after too many failures
+- **Circular dependency detection:** DFS cycle detection on contract creation
+- **Cascade depth guard:** Max 10 levels of auto-resolution to prevent infinite loops
+
+---
+
+## Layer 3: Reactive Intelligence (12 MCP Tools)
+
+This is the layer that makes the system **unbeatable**. Each feature depends on Layer 2's versioned artifacts and contract state machine — competitors cannot bolt these on because they lack the foundation.
+
+### 3a. Lineage Graph (4 Tools)
+
+Track **data provenance** and analyze impact.
+
+| Tool | Description |
+|------|-------------|
+| `artifact_lineage` | Query the provenance DAG (upstream: what inputs? downstream: what depends on this?) |
+| `artifact_impact` | "If I change this artifact, what downstream artifacts and contracts break?" |
+| `artifact_stale` | List all artifacts derived from outdated sources (e.g., derived from v1 but v2 now exists) |
+| `team_audit` | Full provenance trail: who created it, from what inputs, under which contract, at what time |
+
+**How lineage is captured:**
+
+Every `artifact_publish` can include a `derivedFrom` array listing input artifacts. Additionally, when a contract completes, the system auto-links published artifacts to the contract's input artifacts. This builds a full DAG (directed acyclic graph) of how data flowed through the system.
+
+**Example:**
+
+```
+schema-user-model@v1 (root)
+    └─► api-contract-user-auth@v2 (derivedFrom schema@v1)
+        └─► test-results-auth@v1 (derivedFrom api-contract@v2)
+
+If schema-user-model gets bumped to v2:
+→ artifact_stale() reports api-contract-user-auth@v2 as stale
+→ artifact_impact("schema-user-model") shows 2 downstream artifacts affected
+```
+
+### 3b. Reactive Pipelines (4 Tools)
+
+Event-driven **trigger→condition→action** rules. "When X happens, automatically do Y."
+
+| Tool | Description |
+|------|-------------|
+| `pipeline_create` | Define trigger→condition→action rules |
+| `pipeline_list` | View active pipelines and execution counts |
+| `pipeline_pause` | Disable a pipeline without deleting |
+| `pipeline_resume` | Re-enable a paused pipeline |
+
+**Trigger types:**
+
+| Trigger | Fires when |
+|---------|-----------|
+| `artifact_published` | Any artifact of matching type/id is published |
+| `artifact_version_bumped` | An existing artifact gets a new version |
+| `contract_completed` | A contract transitions to completed |
+| `contract_failed` | A contract transitions to failed |
+| `artifact_stale` | An artifact is detected as stale |
+
+**Action types:**
+
+| Action | What it does |
+|--------|-------------|
+| `notify_session` | Send an inbox message to a specific session |
+| `broadcast` | Send inbox message to all team members |
+| `reopen_contract` | Call contract_reopen with given reason |
+| `create_contract` | Create a new contract (deduplication: skips if already exists) |
+| `invalidate_downstream` | Mark all downstream artifacts as stale via lineage graph |
+
+**Example pipeline (self-healing CI loop):**
+
+```javascript
+{
+  rules: [
+    {
+      trigger: { type: "artifact_published", artifactType: "api-contract" },
+      action: { type: "notify_session", target: "qa-dev",
+                message: "API contract updated — re-run tests" }
+    },
+    {
+      trigger: { type: "artifact_published", artifactType: "test-results" },
+      condition: "data.failed > 0",
+      action: { type: "reopen_contract", contractId: "build-auth-api",
+                reason: "Tests failing: ${data.failed} failures" }
+    }
+  ]
+}
+```
+
+When tests fail, the API contract is **automatically reopened** without human intervention. When the API is fixed and tests pass, the contract auto-completes. This is a **self-healing CI loop** with zero conversation.
+
+### 3c. Snapshot & Replay (4 Tools)
+
+**Time-travel** for workflows. Capture full state, rollback, replay with different parameters.
+
+| Tool | Description |
+|------|-------------|
+| `team_snapshot` | Capture current state of all contracts + artifacts + pipelines |
+| `team_snapshot_list` | View all snapshots with timestamp and summary |
+| `team_rollback` | Reset contract/pipeline state to a previous snapshot |
+| `team_replay` | Rollback + apply overrides + re-trigger dependency resolution |
+
+**Why this matters:**
+
+Because artifacts are **immutable** (version files never change) and contracts have a well-defined **state machine**, the entire system state can be captured as a snapshot and restored later.
+
+**Rollback:** Undo a bad workflow execution and restore to a known-good state.
+
+**Replay:** Re-execute from a snapshot with different parameters (e.g., "try GraphQL instead of REST"). The entire downstream chain re-executes with the new approach. Original artifacts are preserved as historical versions for comparison.
+
+**Example:**
+
+```bash
+# Take a snapshot before a risky operation
+clearctx team-snapshot pre-refactor --label "Before auth refactor"
+
+# Do the refactor... oops, tests are broken
+clearctx contract-list  # shows multiple failed contracts
+
+# Rollback to the snapshot
+clearctx team-rollback pre-refactor
+# → Contracts reset to their pre-refactor state
+# → Post-snapshot artifacts marked as "rolled-back" (files preserved)
+# → Sessions notified to restart
+
+# Or replay with different parameters
+clearctx team-replay pre-refactor --overrides '{"build-auth-api":{"inputs":{"context":"Use JWT instead of sessions"}}}'
+# → Entire workflow re-executes with JWT approach
+# → Compare test-results artifacts from both runs
+```
+
+---
+
+## CLI Commands (Team Hub v2)
+
+### Chat Commands
+
+```bash
+clearctx team-send --from db-dev --to api-dev --message "Schema is ready"
+clearctx team-broadcast --from orchestrator --message "Deploy in 10 minutes"
+clearctx team-roster  # View all team members
+clearctx team-inbox --name db-dev  # Check unread messages
+```
+
+### Artifact Commands
+
+```bash
+clearctx artifact-publish schema-user-model --type schema-change \
+  --name "User schema" --data '{"models":[...]}'
+
+clearctx artifact-get api-contract-user-auth  # Latest version
+clearctx artifact-get api-contract-user-auth --version 2  # Specific version
+clearctx artifact-list --type api-contract
+clearctx artifact-history api-contract-user-auth
+```
+
+### Contract Commands
+
+```bash
+clearctx contract-create setup-user-model --assignee db-dev \
+  --title "Create User schema" \
+  --expected-output schema-change
+
+clearctx contract-start setup-user-model
+clearctx contract-complete setup-user-model --summary "User model created"
+clearctx contract-fail setup-user-model --reason "Missing field validation"
+clearctx contract-reopen setup-user-model --reason "Add phone field"
+clearctx contract-list --status ready
+```
+
+### Lineage Commands
+
+```bash
+clearctx artifact-lineage test-results-auth --direction upstream
+clearctx artifact-lineage schema-user-model --direction downstream
+clearctx artifact-impact schema-user-model  # What breaks if I change this?
+clearctx artifact-stale  # List all artifacts derived from outdated sources
+clearctx team-audit test-results-auth  # Full provenance trail
+```
+
+### Pipeline Commands
+
+```bash
+clearctx pipeline-create ci-loop --rules ci-rules.json
+clearctx pipeline-list
+clearctx pipeline-pause ci-loop
+clearctx pipeline-resume ci-loop
+```
+
+### Snapshot Commands
+
+```bash
+clearctx team-snapshot pre-work --label "All contracts created"
+clearctx team-snapshot-list
+clearctx team-rollback pre-work
+clearctx team-replay pre-work --overrides overrides.json
+```
+
+---
+
+## Architecture & Directory Structure
+
+```
+~/.clearctx/
+  sessions.json                       # Existing session metadata (unchanged)
+  team/
+    default/                          # Team namespace
+      roster.json                     # Layer 1: who's active, role, status
+      inbox/
+        {session}.jsonl               # Layer 1: chat messages (append-only)
+      asks/
+        ask_{id}.json                 # Layer 1: pending ask-and-wait
+      artifacts/
+        index.json                    # Layer 2: artifact registry
+        schemas/                      # Layer 2: JSON schemas for well-known types
+          api-contract.json
+          schema-change.json
+          test-results.json
+        data/
+          {artifactId}/
+            v1.json                   # Immutable version files
+            v2.json
+      contracts/
+        index.json                    # Layer 2: contract state
+      pipelines/
+        index.json                    # Layer 3: reactive pipeline rules
+        log.jsonl                     # Layer 3: pipeline execution history
+      snapshots/
+        snap_{id}.json                # Layer 3: full state snapshots
+      locks/
+        artifacts-index.lock          # Cross-process lock files
+        contracts-index.lock
+        pipelines-index.lock
+```
+
+**Key design choices:**
+
+- **JSONL for inboxes:** Append-only, safe for concurrent writers
+- **JSON for indexes:** Atomic temp+rename for safe updates
+- **Immutable version files:** Write-once (wx flag), first writer wins
+- **File locks:** PID-aware locking with staleness detection
+- **Team namespaces:** Multiple teams can coexist in separate directories
+
+---
+
+## Comparison: Why This Is Revolutionary
+
+| | Agent Teams | claude-flow | CrewAI | **clearctx v2.0** |
+|---|---|---|---|---|
+| Coordination model | Conversational | Conversational | Conversational | **Transactional** |
+| Structured data exchange | No | No | No | **Versioned artifacts** |
+| Schema validation | No | No | No | **JSON schema on publish** |
+| Auto-resolving dependencies | No | No | No | **Contract system** |
+| Peer-to-peer task assignment | No | No | No | **Any session → any session** |
+| Contract timeout + retry | No | No | No | **Yes** |
+| Direct session messaging | Yes (text only) | No | No | **Yes (text + structured artifacts)** |
+| Data lineage / provenance | No | No | No | **Full DAG** |
+| Impact analysis | No | No | No | **"What breaks if I change X?"** |
+| Reactive pipelines | No | No | No | **Event-driven trigger→action** |
+| Self-healing CI loops | No | No | No | **Auto-reopen + re-test** |
+| Workflow snapshots | No | No | No | **Full state capture** |
+| Rollback + replay | No | No | No | **Time-travel with overrides** |
+| Each session: own context | No (shared) | No | No | **100K each** |
+| Resume team next day | No | No | No | **Yes** |
+| Quality over time | Degrades | Degrades | Degrades | **Stays consistent** |
+| Zero dependencies | N/A | No (46MB) | No | **Yes** |
+
+**The key insight:** Every competitor uses conversational coordination — agents talk in natural language, summaries pile up, quality degrades over time. We use **transactional coordination** — agents exchange structured data, operate on formal contracts, and auto-resolve dependencies. The result is a system that **stays consistent** instead of degrading.
+
+**The moat:** Layer 3 features (lineage, pipelines, snapshots) cannot be bolted onto conversational systems because they require Layer 2 (versioned artifacts + contracts) to exist first. Competitors would need to rebuild their entire coordination layer to replicate this.
+
+---
+
+## License
+
+MIT