@smartergpt/lexrunner 1.0.0

package/docs/cli.md

@@ -0,0 +1,2262 @@
+# CLI Reference
+
+Complete reference for the lexrunner command-line interface, including all subcommands, options, and JSON output schemas.
+
+> **📖 See Also**:
+>
+> - [Merge-Weave Quickstart](./merge-weave-quickstart.md) - End-to-end guide for merge-weave operations
+> - [Autopilot Levels](./autopilot-levels.md) - Comprehensive guide to automation levels 0-4
+> - [Advanced CLI Features](./advanced-cli.md) - Power user tools and interactive modes
+> - [Command Creation Guide](./command-creation-guide.md) - How to add new commands to the CLI
+
+## Architecture
+
+The lexrunner CLI uses a **modular command architecture** that provides:
+
+- **Maintainability**: Each command lives in its own module under `src/commands/`
+- **Testability**: Business logic separated from CLI registration
+- **Consistency**: Shared utilities for output, flags, and exit handling
+- **Extensibility**: Easy to add new commands following established patterns
+
+### Command Registration Flow
+
+```
+┌─────────────────┐
+│   src/cli.ts    │  Entry point, parses global flags
+└────────┬────────┘
+         │ registerCommands()
+         ↓
+┌─────────────────────────────────────────────┐
+│ src/commands/                               │
+│  ├── init.ts         → registerInitCommand  │
+│  ├── plan.ts         → registerPlanCommand  │
+│  ├── execute.ts      → registerExecuteCmd   │
+│  ├── merge.ts        → registerMergeCmd     │
+│  └── ...                                    │
+└─────────────────────────────────────────────┘
+         │
+         ↓ Each command registers with Commander
+┌─────────────────┐
+│  Commander.js   │  Handles argument parsing & dispatch
+└────────┬────────┘
+         │
+         ↓ .action() handler
+┌─────────────────────────────────────────────┐
+│ Business Logic (pure functions)             │
+│  • Separated from CLI concerns              │
+│  • Unit testable                            │
+│  • Returns typed results                    │
+└─────────────────────────────────────────────┘
+         │
+         ↓
+┌─────────────────────────────────────────────┐
+│ Shared Utilities                            │
+│  • src/cli/output.js    (JSON output)       │
+│  • src/cli/flags.js     (global flags)      │
+│  • src/cli/exitHandler.js (error handling)  │
+└─────────────────────────────────────────────┘
+```
+
+### Command Module Pattern
+
+Each command module exports a single registration function:
+
+```typescript
+// src/commands/myCommand.ts
+import { Command } from "commander";
+
+export function registerMyCommandCommand(program: Command): void {
+  program
+    .command("my-command")
+    .description("Command description")
+    .action(async (args, options) => {
+      // Thin wrapper - delegates to business logic
+      const result = await executeMyCommand(args, options);
+      handleOutput(result, options);
+    });
+}
+
+// Pure, testable business logic
+async function executeMyCommand(args, options) {
+  // All logic here
+}
+```
+
+**Key Principles:**
+
+- **Separation of Concerns**: CLI registration separate from business logic
+- **Pure Functions**: Business logic has no side effects (testable)
+- **Consistent Output**: All commands support `--json` and human-readable formats
+- **Error Handling**: Use `throwExit()` from `src/cli/exitHandler.js`
+
+### Shared Utilities
+
+#### Output (`src/cli/output.js`)
+
+```typescript
+import { writeJsonOutput } from '../cli/output.js';
+
+// Canonical JSON output to stdout
+writeJsonOutput({ success: true, items: [...] });
+```
+
+#### Exit Handling (`src/cli/exitHandler.js`)
+
+```typescript
+import { throwExit, CLIExitSignal } from "../cli/exitHandler.js";
+
+// Graceful exit with error message
+throwExit(new Error("Operation failed"), 1);
+
+// Exit with success
+throw new CLIExitSignal(0, "Operation complete");
+```
+
+#### Global Flags (`src/cli/flags.js`)
+
+```typescript
+import { parseGlobalFlags } from "../cli/flags.js";
+
+// Access global flags (--json, --no-color, etc.)
+const globalOpts = parseGlobalFlags(process.argv);
+```
+
+### Adding New Commands
+
+See the **[Command Creation Guide](./command-creation-guide.md)** for:
+
+- Step-by-step command creation
+- Templates and examples
+- Testing patterns
+- Documentation requirements
+- Complete checklist
+
+Quick reference:
+
+1. Create `src/commands/myCommand.ts`
+2. Export `registerMyCommandCommand(program: Command)`
+3. Register in `src/cli.ts`
+4. Add tests in `tests/commands/myCommand.spec.ts`
+5. Update this file (`docs/cli.md`) with command reference
+
+---
+
+## Global Options
+
+```bash
+lex-pr [options] [command]
+
+Options:
+  -V, --version        Output the version number
+  --no-color           Disable ANSI color codes in output
+  --json               Enable JSON output mode (implies --no-color)
+  --log-format <fmt>   Log output format: 'json' or 'human' (default: 'human')
+  -h, --help           Display help for command
+```
+
+### Output Control Flags
+
+#### `--no-color`
+
+Unconditionally disables ANSI escape codes in output, regardless of TTY detection.
+
+**Use cases:**
+
+- Force plain text output when piping to tools that don't handle ANSI codes
+- Debugging in environments where color codes interfere with output
+- CI/CD pipelines where color codes are not needed
+
+**Example:**
+
+```bash
+lex-pr --no-color config:inspect
+```
+
+#### `--json`
+
+Enables JSON output mode and automatically disables colors. This flag:
+
+- Forces JSON output to stdout for supported commands
+- Disables ANSI color codes (implies `--no-color`)
+- Suppresses human-friendly decorations (emojis, tips, progress indicators)
+- Uses plain text prefixes in error messages (e.g., `[lex-pr]` instead of ❌)
+
+**Use cases:**
+
+- Machine-readable output for automation and scripting
+- Clean JSON output for piping to `jq` or other JSON processors
+- CI/CD pipelines and automated testing
+
+**Example:**
+
+```bash
+lex-pr --json plan > plan.json
+```
+
+**Note:** The `--json` flag can be used either globally or at the command level:
+
+```bash
+# Global flag (affects all output)
+lex-pr --json plan
+
+# Command-level flag (some commands support this)
+lex-pr plan --json
+```
+
+## Configuration Precedence
+
+Configuration values are resolved in the following order (highest to lowest priority):
+
+1. **Command-line flags** (`--out ./custom-dir`)
+2. **Environment variables** (`LEX_PR_OUT_DIR=./custom-dir`)
+3. **Configuration files** (`.smartergpt/config.json`)
+4. **Built-in defaults**
+
+### Environment Variables
+
+| Variable             | Description                                   | Default              |
+| -------------------- | --------------------------------------------- | -------------------- |
+| `LEX_PR_OUT_DIR`     | Default output directory for artifacts        | `.smartergpt/runner` |
+| `LEX_PR_MAX_WORKERS` | Maximum parallel gate execution               | `1`                  |
+| `LEX_PR_TIMEOUT`     | Default gate timeout in seconds               | `300`                |
+| `NO_COLOR`           | Disable ANSI color codes when set (any value) | unset                |
+| `LOG_FORMAT`         | Log output format: 'json' or 'human'          | `human`              |
+
+## Commands
+
+### `init`
+
+Initialize lexrunner workspace with interactive setup wizard.
+
+```bash
+lex-pr init [options]
+
+Options:
+  --force                 Overwrite existing configuration files
+  --non-interactive       Run without prompts (use environment variables)
+  --github-token <token>  GitHub token for authentication
+  --profile-dir <dir>     Profile directory (default: .smartergpt.local)
+  -h, --help              Display help for command
+```
+
+#### What Gets Created
+
+The init command creates a complete workspace configuration:
+
+```
+.smartergpt.local/
+├── profile.yml              # Profile metadata (role: local)
+├── intent.md                # Project goals and scope
+├── scope.yml                # PR discovery rules
+├── deps.yml                 # Dependency relationships
+├── gates.yml                # Quality gates configuration
+└── pull-request-template.md # PR template with dependency syntax
+```
+
+#### Interactive Setup
+
+When run without `--non-interactive`, the wizard will:
+
+1. Detect project type (Node.js, Python, Rust, Go, etc.)
+2. Prompt for GitHub token (optional)
+3. Validate repository access if token provided
+4. Create workspace configuration files
+5. Display next steps
+
+#### Examples
+
+```bash
+# Interactive setup with prompts
+lex-pr init
+
+# Non-interactive setup (use environment variables)
+export GITHUB_TOKEN=your_token_here
+lex-pr init --non-interactive
+
+# Force overwrite existing configuration
+lex-pr init --force
+
+# Use custom profile directory
+lex-pr init --profile-dir .smartergpt.custom
+
+# Provide GitHub token via CLI
+lex-pr init --github-token ghp_your_token_here
+```
+
+#### Environment Variables
+
+| Variable       | Description                  | Used When            |
+| -------------- | ---------------------------- | -------------------- |
+| `GITHUB_TOKEN` | GitHub personal access token | Token authentication |
+| `GH_TOKEN`     | Alternative GitHub token     | Token authentication |
+
+#### Exit Codes
+
+- `0`: Initialization successful
+- `1`: Initialization failed (general error)
+- `2`: Write protection error (tried to write to read-only profile)
+
+#### Profile Directory Selection
+
+The init command automatically selects the appropriate profile directory:
+
+1. If `--profile-dir` is specified, uses that directory
+2. If `.smartergpt` exists (tracked example), uses `.smartergpt.local`
+3. Otherwise, uses `.smartergpt.local` for new setups
+
+This ensures local development work doesn't overwrite tracked example configurations.
+
+#### See Also
+
+- [Quickstart Guide](./quickstart.md) - Complete onboarding workflow
+- [Profile Resolution](./profile-resolution.md) - Understanding profile directories
+- `lex-pr doctor` - Validate environment after initialization
+
+---
+
+### `schema validate`
+
+Validate plan.json files against the schema with enhanced cycle detection and diagnostics.
+
+```bash
+lex-pr schema validate [options] [file]
+
+Arguments:
+  file              Path to plan.json file
+
+Options:
+  --json            Output machine-readable JSON errors
+  --verbose         Show detailed diagnostics (layers, warnings, full dependency graph)
+  -h, --help        Display help for command
+```
+
+#### Validation Checks
+
+The validator performs comprehensive checks:
+
+1. **Schema validation** - Ensures plan follows correct structure
+2. **Cycle detection** - Identifies circular dependencies with full path details
+3. **Orphan detection** - Warns about items with no dependencies/dependents
+4. **Reference validation** - Ensures all dependencies exist
+5. **Self-dependency detection** - Catches items depending on themselves
+6. **Topology analysis** - Computes merge layers and identifies bottlenecks
+
+#### Examples
+
+```bash
+# Basic validation with human-readable output
+lex-pr schema validate plan.json
+
+# Detailed validation with layer information
+lex-pr schema validate plan.json --verbose
+
+# Validate with JSON output for CI
+lex-pr schema validate --json plan.json
+
+# Example output (human-readable):
+=== Plan Validation Report ===
+
+❌ Errors:
+
+Dependency cycle detected in plan
+
+Cycle path: feat-a → feat-b → feat-c → feat-a
+
+Dependency chain:
+  feat-a               depends on feat-b
+  feat-b               depends on feat-c
+  feat-c               depends on feat-a
+
+Suggestion: Consider removing the dependency from 'feat-c' to 'feat-a' to break the cycle
+
+❌ Plan has 1 error(s) that must be fixed
+
+# Example verbose output:
+=== Plan Validation Report ===
+
+Nodes: 6 items
+Edges: 4 dependencies
+
+Layers (topological sort):
+  Layer 0: feat-a, feat-b, feat-f
+  Layer 1: feat-c, feat-d
+  Layer 2: feat-e
+
+⚠️  Warnings:
+
+Item 'feat-f' has no dependencies and no dependents (orphan)
+Suggestion: Consider if these items should have dependencies or dependents.
+
+✅ Plan is valid and ready for execution
+```
+
+#### JSON Output Schema
+
+**Success Response:**
+
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": [],
+  "diagnostics": {
+    "nodes": 5,
+    "edges": 4,
+    "layers": [
+      { "level": 0, "prs": ["feat-a", "feat-b"] },
+      { "level": 1, "prs": ["feat-c"] }
+    ],
+    "orphans": []
+  }
+}
+```
+
+**Error Response (Cycle):**
+
+```json
+{
+  "valid": false,
+  "errors": [
+    {
+      "type": "cycle",
+      "message": "Dependency cycle detected in plan\n\nCycle path: feat-a → feat-b → feat-a\n\nDependency chain:\n  feat-a depends on feat-b\n  feat-b depends on feat-a",
+      "details": {
+        "cyclePath": ["feat-a", "feat-b", "feat-a"]
+      },
+      "suggestion": "Consider removing the dependency from 'feat-b' to 'feat-a' to break the cycle"
+    }
+  ],
+  "warnings": [],
+  "diagnostics": {
+    "nodes": 2,
+    "edges": 2,
+    "layers": [],
+    "orphans": []
+  }
+}
+```
+
+**Warning Response (Orphans):**
+
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": [
+    {
+      "type": "orphan",
+      "message": "2 items have no dependencies and no dependents (orphans): orphan-1, orphan-2",
+      "affectedPRs": ["orphan-1", "orphan-2"],
+      "suggestion": "Consider if these items should have dependencies or dependents. Use labels to mark intentional orphans."
+    }
+  ],
+  "diagnostics": {
+    "nodes": 4,
+    "edges": 1,
+    "layers": [
+      { "level": 0, "prs": ["feat-a", "orphan-1", "orphan-2"] },
+      { "level": 1, "prs": ["feat-b"] }
+    ],
+    "orphans": ["orphan-1", "orphan-2"]
+  }
+}
+```
+
+**Error Types:**
+
+- `cycle` - Circular dependency detected
+- `invalid-ref` - Reference to non-existent item
+- `self-dependency` - Item depends on itself
+
+**Warning Types:**
+
+- `orphan` - Item has no dependencies and no dependents
+- `large-layer` - Layer has too many items (potential merge conflicts)
+
+**Exit Codes:**
+
+- `0`: Validation successful (may have warnings)
+- `1`: Validation failed with errors or system error
+- `2`: Validation failed
+
+---
+
+### `plan`
+
+Generate merge plan from workspace configuration or GitHub PRs with automatic dependency discovery.
+
+```bash
+lex-pr plan [options]
+
+Options:
+  --out <dir>               Output directory for artifacts (default: ".smartergpt/runner")
+  --json                    Output canonical plan JSON to stdout only
+  --dry-run                 Validate inputs and show what would be written
+  --from-github             Auto-discover PRs from GitHub API with dependency detection
+  --suggest-deps            Generate dependency suggestions from file analysis
+  --threshold <float>       Confidence threshold for suggestions (0.0-1.0, default: 0.3)
+  --no-suggestions          Disable file-based dependency suggestions
+  --query <query>           GitHub search query (e.g., 'is:open label:stack:*')
+  --labels <labels>         Filter PRs by comma-separated labels
+  --exclude-labels <l>      Exclude PRs with labels (comma-separated)
+  --include-drafts          Include draft PRs in the plan
+  --exclude-prs <numbers>   Exclude specific PRs by comma-separated PR numbers
+  --github-token <token>    GitHub API token (or use GITHUB_TOKEN env var)
+  --owner <owner>           GitHub repository owner (auto-detected from git remote)
+  --repo <repo>             GitHub repository name (auto-detected from git remote)
+  --required-gates <gates>  Comma-separated list of required gates (default: lint,typecheck,test)
+  --max-workers <n>         Maximum parallel workers for execution (default: 2)
+  --target <branch>         Target branch for merging PRs (default: repo default branch)
+  --validate                Validate plan after generation (cycles, orphans, refs)
+  --validate-cycles         Enable dependency cycle detection (default: true)
+  --optimize                Optimize plan for parallel execution
+  --format <type>           Output format: json|markdown|dot (default: json)
+  --output <file>           Output file path (alternative to --out, for single file)
+  -h, --help                Display help for command
+```
+
+#### Plan Generation Modes
+
+**1. GitHub Auto-Discovery Mode (Recommended)**
+
+Generate plan from GitHub PRs with automatic dependency detection:
+
+```bash
+# Basic auto-discovery with dependency parsing
+lex-pr plan --from-github
+
+# With file-based dependency suggestions
+lex-pr plan --from-github --suggest-deps --threshold=0.7
+
+# Filter by labels
+lex-pr plan --from-github --labels "ready-to-merge,stack:feature"
+
+# Exclude certain labels
+lex-pr plan --from-github --exclude-labels "wip,draft"
+```
+
+**What auto-discovery does:**
+
+1. Fetches open PRs from GitHub
+2. Parses `Depends-on:` footers from PR descriptions
+3. Analyzes file changes to suggest implicit dependencies (if `--suggest-deps`)
+4. Validates dependency graph (detects cycles, orphans)
+5. Computes merge layers using topological sort
+6. Generates deterministic `plan.json`
+
+**2. Dependency Suggestions Only**
+
+Generate file-based dependency suggestions without creating a plan:
+
+```bash
+# High-confidence suggestions (≥0.7)
+lex-pr plan --suggest-deps --threshold=0.7
+
+# Output as markdown for review
+lex-pr plan --suggest-deps --format=markdown > suggestions.md
+
+# JSON format for automation
+lex-pr plan --suggest-deps --format=json | jq '.suggestions'
+```
+
+**3. Configuration Files Mode (Default)**
+
+```bash
+# Generate from .smartergpt/ configuration files
+lex-pr plan
+```
+
+#### Dependency Syntax
+
+The planner recognizes these dependency formats in PR descriptions:
+
+```markdown
+# Single dependency
+
+Depends-on: #123
+
+# Multiple dependencies
+
+Depends-on: #123, #456, #789
+
+# Cross-repo references
+
+Depends-on: owner/repo#123
+
+# Alternative keywords (aliases)
+
+Depends: #123
+Requires: #456
+```
+
+**Note:** `Closes`, `Fixes`, and `Resolves` are GitHub keywords for closing issues and are **not** treated as dependencies.
+
+#### File-Based Heuristics
+
+When `--suggest-deps` is used, the planner analyzes file changes to suggest dependencies:
+
+| Heuristic               | Confidence Range | Description                      |
+| ----------------------- | ---------------- | -------------------------------- |
+| **Shared files**        | 0.6 - 1.0        | Both PRs modify the same files   |
+| **Directory proximity** | 0.3 - 0.8        | PRs work in the same directories |
+| **Test overlap**        | 0.5 - 0.85       | PRs test the same modules        |
+
+**Threshold guidelines:**
+
+- `≥0.8`: Very high confidence, almost always valid
+- `≥0.7`: High confidence, recommended for hybrid workflow
+- `≥0.5`: Medium confidence, requires manual review
+- `<0.5`: Low confidence, likely false positive
+
+#### Examples
+
+```bash
+# Generate plan with default output directory
+lex-pr plan
+
+# Generate plan to custom directory
+lex-pr plan --out ./my-artifacts
+
+# JSON-only output for piping/processing
+lex-pr plan --json
+
+# Validate inputs without writing files
+lex-pr plan --dry-run
+
+# GitHub mode: Auto-discover and generate plan
+lex-pr plan --from-github --github-token $GITHUB_TOKEN
+
+# Custom policy configuration
+lex-pr plan --from-github \
+  --required-gates "lint,test,security-scan" \
+  --max-workers 4 \
+  --target develop
+
+# Optimize and validate plan
+lex-pr plan --from-github --optimize --validate-cycles
+
+# Search for specific PRs
+lex-pr plan --from-github \
+  --query "is:open label:stack:*" \
+  --labels "priority-high"
+```
+
+#### Dependency Validation and Optimization
+
+The plan command automatically validates dependencies when using `--from-github`:
+
+- **Cycle Detection**: Detects circular dependencies between PRs (enabled by default with `--validate-cycles` or `--validate`)
+- **Orphan Detection**: Warns about PRs with no dependencies/dependents
+- **Reference Validation**: Ensures all dependencies exist in the plan
+- **Optimization**: Shows parallelization levels with `--optimize` flag
+
+```bash
+# Full validation (recommended)
+lex-pr plan --from-github --validate
+
+# Show optimization levels and merge layers
+lex-pr plan --from-github --optimize
+
+# Disable cycle detection (not recommended)
+lex-pr plan --from-github --validate-cycles=false
+```
+
+Example output with `--optimize`:
+
+```
+✓ Auto-discovered 5 PRs from GitHub
+✓ Parsed dependencies: 3 explicit, 1 implicit
+✓ Dependency validation passed (no cycles detected)
+✓ Plan optimized for parallel execution: 3 layers
+  Layer 0: PR-100 (ready to merge)
+  Layer 1: PR-101, PR-102 (after PR-100, parallel)
+  Layer 2: PR-103, PR-104 (after Layer 1, parallel)
+```
+
+#### Exit Codes
+
+- `0`: Plan generated successfully
+- `1`: Plan generation failed (general error)
+- `2`: Validation failed (cycles, invalid refs, orphans)
+
+#### See Also
+
+- **[Diffgraph Planner Guide](./diffgraph-planner.md)** - Complete feature documentation
+- **[Troubleshooting](./troubleshooting-planner.md)** - Common errors and solutions
+- **[Dependency Parser](./dependency-parser.md)** - Parser documentation
+- **[Tutorials](./tutorials/diffgraph-planner/)** - Step-by-step guides
+- `lex-pr schema validate` - Validate existing plan
+- `lex-pr merge-order` - Review merge layers
+
+---
+
+#### JSON Output Schema (`--json` flag)
+
+**Success Response:**
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "target": "main",
+  "policy": {
+    "requiredGates": ["string"],
+    "optionalGates": ["string"],
+    "maxWorkers": 1,
+    "retries": {},
+    "overrides": {},
+    "blockOn": ["string"],
+    "mergeRule": {
+      "type": "strict-required"
+    }
+  },
+  "items": [
+    {
+      "name": "string",
+      "deps": ["string"],
+      "gates": [
+        {
+          "name": "string",
+          "run": "string",
+          "cwd": "string",
+          "env": {},
+          "runtime": "local|container|ci-service",
+          "container": {
+            "image": "string",
+            "entrypoint": ["string"],
+            "mounts": [
+              {
+                "source": "string",
+                "target": "string",
+                "type": "bind|volume"
+              }
+            ]
+          },
+          "artifacts": ["string"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Deterministic Guarantees:**
+
+- Keys sorted alphabetically at all levels
+- Arrays maintain stable ordering (deps sorted, items by name)
+- No runtime timestamps or random values
+- Cross-platform identical output
+
+**Exit Codes:**
+
+- `0`: Plan generated successfully
+- `1`: System error (filesystem, permissions)
+- `2`: Configuration validation failed
+
+---
+
+### `merge-order`
+
+Compute dependency levels and merge order using Kahn's algorithm.
+
+```bash
+lex-pr merge-order [options] [file]
+
+Arguments:
+  file              Path to plan.json file (alternative to --plan)
+
+Options:
+  --plan <file>     Path to plan.json file
+  --json            Output JSON format
+  -h, --help        Display help for command
+```
+
+#### Examples
+
+```bash
+# Human-readable merge order
+lex-pr merge-order plan.json
+
+# JSON output for automation
+lex-pr merge-order --json plan.json
+
+# Using --plan flag
+lex-pr merge-order --plan ./configs/plan.json
+```
+
+#### JSON Output Schema (`--json` flag)
+
+**Success Response:**
+
+```json
+{
+  "levels": [
+    ["item-a", "item-c"], // Level 0: No dependencies
+    ["item-b"], // Level 1: Depends on level 0
+    ["item-d"] // Level 2: Depends on level 1
+  ],
+  "totalItems": 4,
+  "maxParallelism": 2
+}
+```
+
+**Human-Readable Output:**
+
+```
+Merge Order (3 levels):
+  Level 0: item-a, item-c
+  Level 1: item-b
+  Level 2: item-d
+
+Total items: 4, Max parallelism: 2
+```
+
+**Exit Codes:**
+
+- `0`: Merge order computed successfully
+- `1`: System error (file not readable)
+- `2`: Dependency cycle or unknown dependency detected
+
+---
+
+### `orchestrate:predict-conflicts`
+
+Predict merge conflicts using conflict graphs, Maximal Independent Set (MIS) computation, and git merge-tree simulation.
+
+```bash
+lex-pr orchestrate:predict-conflicts [options]
+
+Options:
+  --prs <numbers>       Comma-separated list of PR numbers (e.g., 166,167,168) [required]
+  --base <branch>       Base branch for conflict analysis (default: "main")
+  --skip-merge-tree     Skip git merge-tree simulation
+  -h, --help            Display help for command
+```
+
+#### Algorithm Overview
+
+1. **Conflict Graph**: Build undirected graph where nodes are PRs and edges represent shared files
+2. **MIS Computation**: Use greedy algorithm to find Maximal Independent Set (PRs with no conflicts)
+3. **Merge Simulation**: Run `git merge-tree` to validate predicted conflicts
+
+**Greedy MIS Algorithm:**
+
+- Sort nodes by degree (fewest conflicts first), then by PR number
+- Greedily select nodes that don't conflict with already selected nodes
+- Result: Maximum set of PRs that can merge in parallel
+
+#### Examples
+
+```bash
+# Predict conflicts for specific PRs (human-readable)
+lex-pr orchestrate:predict-conflicts --prs 166,167,168
+
+# JSON output for automation
+lex-pr --json orchestrate:predict-conflicts --prs 166,167,168
+
+# Skip merge-tree simulation (faster, file-based analysis only)
+lex-pr orchestrate:predict-conflicts --prs 166,167,168 --skip-merge-tree
+
+# Custom base branch
+lex-pr orchestrate:predict-conflicts --prs 100,101,102 --base develop
+```
+
+#### JSON Output Schema (`--json` flag)
+
+**Success Response:**
+
+```json
+{
+  "analyzedAt": "2025-10-13T02:00:00Z",
+  "baseBranch": "main",
+  "conflictGraph": {
+    "nodes": ["166", "167", "168"],
+    "edges": [
+      {
+        "from": "166",
+        "to": "167",
+        "sharedFiles": ["src/cli.ts"]
+      },
+      {
+        "from": "167",
+        "to": "168",
+        "sharedFiles": ["src/gates.ts"]
+      }
+    ]
+  },
+  "misBatches": [
+    {
+      "id": "mis-1",
+      "prs": ["166", "168"],
+      "reason": "No shared files"
+    },
+    {
+      "id": "mis-2",
+      "prs": ["167"],
+      "reason": "Conflicts with #166 and #168"
+    }
+  ],
+  "mergeTreeSimulation": {
+    "166-168": {
+      "status": "clean",
+      "conflicts": []
+    },
+    "166-167": {
+      "status": "conflict",
+      "conflicts": [
+        {
+          "file": "src/cli.ts",
+          "lines": "125-140",
+          "type": "both-modified"
+        }
+      ]
+    }
+  },
+  "recommendations": {
+    "safeBatch": ["166", "168"],
+    "sequential": ["167"]
+  }
+}
+```
+
+**Human-Readable Output:**
+
+```
+🔍 Conflict Analysis
+============================================================
+
+📊 Conflict Graph:
+  - #166 ↔ #167: src/cli.ts
+  - #167 ↔ #168: src/gates.ts
+
+🔀 MIS Batches (safe parallel groups):
+  - mis-1: [#166, #168]
+    No shared files
+  - mis-2: [#167]
+    Conflicts with #166 and #168
+
+🧪 git merge-tree Simulation:
+  - #166 + #168: ✅ Clean merge
+  - #166 + #167: ❌ Conflict
+    ↳ src/cli.ts (both-modified)
+
+💡 Recommendations:
+  ✓ Safe parallel batch: #166, #168
+  ⚠ Merge sequentially: #167
+```
+
+**Exit Codes:**
+
+- `0`: Conflict analysis completed successfully
+- `1`: Missing required parameters or system error
+
+#### Use Cases
+
+- **Batch Planning**: Determine which PRs can be merged in parallel
+- **Conflict Avoidance**: Identify potential conflicts before merging
+- **Optimization**: Maximize parallelism in merge pyramid execution
+- **CI/CD Integration**: Automate conflict detection in merge workflows
+
+---
+
+### `plan-review`
+
+Interactively review and edit a plan with human-in-the-loop validation.
+
+```bash
+lex-pr plan-review [options] [file]
+
+Arguments:
+  file                  Path to plan.json file (alternative to --plan)
+
+Options:
+  --plan <file>         Path to plan.json file
+  --non-interactive     Non-interactive mode (auto-approve)
+  --profile-dir <dir>   Profile directory for history tracking
+  --save-history        Save plan versions to history
+  --output <file>       Output file for approved/modified plan
+  -h, --help            Display help for command
+```
+
+#### Features
+
+- **Interactive Review**: View plan summary, dependency graph, and merge order
+- **Plan Editing**: Add/remove items, modify dependencies, change target branch
+- **Validation**: Automatic validation of dependencies and cycles during editing
+- **Approval Workflow**: Approve or reject plans with optional reason
+- **History Tracking**: Save plan versions with metadata for audit trail
+- **Diff View**: See changes made during interactive session
+
+#### Examples
+
+```bash
+# Interactive review with prompts
+lex-pr plan-review plan.json
+
+# Auto-approve in non-interactive mode
+lex-pr plan-review plan.json --non-interactive
+
+# Review and save to new file
+lex-pr plan-review plan.json --output approved-plan.json
+
+# Review with history tracking
+lex-pr plan-review plan.json --save-history --profile-dir .smartergpt.local
+```
+
+#### Interactive Options
+
+When running in interactive mode, you'll see:
+
+1. **Plan Summary**: Items count, target branch, dependencies overview
+2. **Dependency Graph**: ASCII visualization of item dependencies
+3. **Merge Order**: Computed execution levels
+
+Then you can choose:
+
+- `[a]` Approve plan - Accept the plan as-is
+- `[r]` Reject plan - Reject with optional reason
+- `[e]` Edit plan - Interactively modify the plan
+- `[v]` View plan details - See full JSON
+- `[d]` Show diff - Compare original vs modified
+- `[q]` Quit without saving
+
+#### Edit Operations
+
+When editing, you can:
+
+- Add new items with dependencies
+- Remove items (validated against dependents)
+- Modify item dependencies (cycle detection)
+- Change target branch
+- Gates editing (planned for future release)
+
+#### Exit Codes
+
+- `0`: Plan approved
+- `1`: Plan rejected or operation failed
+
+---
+
+### `plan-diff`
+
+Compare two plans and show differences.
+
+```bash
+lex-pr plan-diff [options] <plan1> <plan2>
+
+Arguments:
+  plan1       First plan file
+  plan2       Second plan file
+
+Options:
+  --json      Output JSON format
+  -h, --help  Display help for command
+```
+
+#### Examples
+
+```bash
+# Human-readable diff
+lex-pr plan-diff plan-v1.json plan-v2.json
+
+# JSON output for automation
+lex-pr plan-diff plan-v1.json plan-v2.json --json
+```
+
+#### Human-Readable Output
+
+```
+📊 Plan Comparison
+
+Plan 1: plan-v1.json
+Plan 2: plan-v2.json
+
+Target Branch: main → develop
+
+Added Items:
+  + feature-d
+    deps: feature-b
+    gates: 2
+
+Removed Items:
+  - feature-c
+
+Modified Items:
+  ~ feature-b
+    deps: [feature-a] → [feature-a, feature-x]
+```
+
+#### JSON Output Schema
+
+```json
+{
+  "targetChanged": true,
+  "originalTarget": "main",
+  "modifiedTarget": "develop",
+  "addedItems": [
+    {
+      "name": "feature-d",
+      "deps": ["feature-b"],
+      "gates": []
+    }
+  ],
+  "removedItems": [
+    {
+      "name": "feature-c",
+      "deps": ["feature-a"],
+      "gates": []
+    }
+  ],
+  "modifiedItems": [
+    {
+      "name": "feature-b",
+      "originalDeps": ["feature-a"],
+      "modifiedDeps": ["feature-a", "feature-x"],
+      "originalGatesCount": 1,
+      "modifiedGatesCount": 2
+    }
+  ],
+  "hasChanges": true
+}
+```
+
+#### Exit Codes
+
+- `0`: No changes detected (plans are identical)
+- `1`: Changes detected or comparison successful
+
+---
+
+### `execute`
+
+Execute plan with policy-aware gate running and status tracking.
+
+```bash
+lex-pr execute [options] [file]
+
+Arguments:
+  file                       Path to plan.json file (alternative to --plan)
+
+Options:
+  --plan <file>              Path to plan.json file
+  --artifact-dir <dir>       Output directory for artifacts (default: "./artifacts")
+  --timeout <ms>             Gate timeout in milliseconds (default: "30000")
+  --dry-run                  Validate plan and show execution order without running gates
+  --json                     Output results in JSON format
+  --status-table             Generate status table for PR comments
+  --max-level <level>        Maximum autopilot level (0-4) (default: "0")
+  --open-pr                  Open pull requests for integration branches (Level 3+)
+  --close-superseded         Close superseded PRs after integration (Level 4)
+  --comment-template <path>  Path to PR comment template (Level 2+)
+  --branch-prefix <prefix>   Prefix for integration branch names (default: "integration/")
+  -h, --help                 Display help for command
+```
+
+> **📖 Autopilot Levels**: See [Autopilot Levels](./autopilot-levels.md) for details on automation levels 0-4.
+
+#### Examples
+
+```bash
+# Execute entire plan
+lex-pr execute plan.json
+
+# Execute specific item only
+lex-pr execute --only-item item-a plan.json
+
+# JSON output for monitoring
+lex-pr execute --json plan.json
+
+# Execute plan with vulnerability scanning
+lex-pr execute plan-with-vuln.json
+```
+
+#### Built-in Gates
+
+##### Vulnerability Gate (`vuln`)
+
+The `vuln` gate is a special built-in gate that scans for security vulnerabilities using artifact-based detection:
+
+- **Artifact Detection**: Automatically looks for `scan-results.sarif` (SARIF 2.1.0 format) or `npm-audit.json` in the item's artifact directory
+- **Policy Enforcement**: Applies thresholds from `plan.policy.security`
+- **Deterministic Output**: Provides consistent, structured vulnerability counts
+
+**Policy Configuration:**
+
+```json
+{
+  "policy": {
+    "requiredGates": ["vuln"],
+    "security": {
+      "blockCritical": true,
+      "blockHigh": true,
+      "maxMedium": 5,
+      "maxLow": 10
+    }
+  }
+}
+```
+
+**Example Gate:**
+
+```json
+{
+  "gates": [
+    {
+      "name": "vuln",
+      "run": "trivy fs --format sarif --output scan-results.sarif ."
+    }
+  ]
+}
+```
+
+**Supported Scanners:**
+
+- Trivy: `trivy fs --format sarif`
+- Snyk: `snyk test --sarif`
+- CodeQL: `codeql database analyze --format=sarif-latest`
+- npm audit: `npm audit --json > npm-audit.json`
+
+See [Gate Report Examples](./gate-report-examples.md#vulnerability-gate-vuln) for detailed output examples.
+
+#### JSON Output Schema (`--json` flag)
+
+**Success Response:**
+
+```json
+{
+  "executionId": "string", // Unique execution identifier
+  "startedAt": "2024-01-15T10:30:00Z",
+  "completedAt": "2024-01-15T10:35:00Z",
+  "status": "completed|failed|running",
+  "totalItems": 4,
+  "completedItems": 4,
+  "failedItems": 0,
+  "items": [
+    {
+      "name": "item-a",
+      "status": "pass|fail|blocked|skipped|retrying",
+      "gates": [
+        {
+          "gate": "test",
+          "status": "pass|fail|blocked|skipped|retrying",
+          "exitCode": 0,
+          "duration": 1500, // milliseconds
+          "stdout": "string",
+          "stderr": "string",
+          "artifacts": ["coverage.json"],
+          "attempts": 1,
+          "lastAttempt": "2024-01-15T10:32:00Z"
+        }
+      ],
+      "blockedBy": [], // Items that blocked this one
+      "eligibleForMerge": true
+    }
+  ]
+}
+```
+
+**Exit Codes:**
+
+- `0`: All gates passed successfully
+- `1`: System error during execution
+- `2`: One or more gates failed
+
+---
+
+### `merge`
+
+Execute merge pyramid with git operations. Supports dry-run preview, conflict detection, and resumable execution.
+
+```bash
+lex-pr merge [options]
+
+Options:
+  --plan <file>                      Path to plan.json file (default: "plan.json")
+  --dry-run                          Show what would be merged without executing (default: true)
+  --execute                          Actually perform merge operations
+  --resume [runId]                   Resume execution from weave-lock.json (optional: specific run ID)
+  --cleanup                          Clean up integration branches after execution
+  --force                            Force execution even if same lock hash exists
+  --json                             Output JSON format
+  --batch                            Enable batch mode for multiple items
+  --filter <query>                   Filter items using query language
+  --levels <levels>                  Comma-separated list of levels to merge
+  --items <items>                    Comma-separated list of items to merge
+  --max-level <level>                Maximum autopilot level (0-4) (default: "0")
+  --open-pr                          Open pull requests for integration branches (Level 3+)
+  --close-superseded                 Close superseded PRs after integration (Level 4)
+  --comment-template <path>          Path to PR comment template (Level 2+)
+  --branch-prefix <prefix>           Prefix for integration branch names (default: "integration/")
+  --skip-preflight                   Skip preflight conflict detection in dry-run mode
+  --fail-on-preflight-conflict       Exit with error if preflight conflict detection finds conflicts
+  --track-turncost                   Track Turn Cost metrics during execution (coordination overhead)
+  -h, --help                         Display help for command
+```
+
+> **📖 Quick Start**: See [Merge-Weave Quickstart](./merge-weave-quickstart.md) for an end-to-end walkthrough with examples.
+>
+> **📖 Autopilot Levels**: See [Autopilot Levels](./autopilot-levels.md) for details on automation levels 0-4.
+
+#### Basic Examples
+
+```bash
+# Dry-run: preview merge operations (default)
+lex-pr merge
+
+# Dry-run with explicit flag
+lex-pr merge --plan ./plan.json --dry-run --json
+
+# Execute merge pyramid
+lex-pr merge --execute
+
+# Execute and clean up integration branches
+lex-pr merge --execute --cleanup
+
+# Resume from previous execution
+lex-pr merge --resume
+
+# Force execution even if already executed
+lex-pr merge --execute --force
+```
+
+#### Batch Operations
+
+```bash
+# Merge specific items only
+lex-pr merge --batch --items "pr-123,pr-456" --execute
+
+# Merge specific dependency levels
+lex-pr merge --batch --levels "1,2" --execute
+
+# Merge items matching a query
+lex-pr merge --batch --filter "level eq 1" --execute
+```
+
+#### Conflict Detection
+
+```bash
+# Skip preflight conflict detection
+lex-pr merge --skip-preflight
+
+# Fail if conflicts detected in dry-run
+lex-pr merge --fail-on-preflight-conflict
+
+# Execute even if conflicts detected
+lex-pr merge --execute  # Will pause on conflicts for manual resolution
+```
+
+#### State Management
+
+The merge command uses a lock file (`weave-lock.json`) for idempotency and resumability:
+
+- **Lock Hash**: Computed from `plan.json` + PR head commits
+- **Idempotency**: Duplicate runs with same lock hash are skipped (use `--force` to override)
+- **Resume**: Failed executions can be resumed with `--resume`
+
+**Lock File Example:**
+
+```json
+{
+  "lockHash": "abc123de",
+  "planHash": "def456gh",
+  "prHeads": [
+    { "name": "feature/auth", "sha": "a1b2c3d4" },
+    { "name": "feature/api", "sha": "e5f6g7h8" }
+  ],
+  "timestamp": "2024-12-13T02:00:00Z",
+  "status": "completed"
+}
+```
+
+#### Preflight Conflict Detection
+
+Enabled by default in dry-run mode. Uses `git merge-tree` to simulate merges without modifying the working tree.
+
+**Benefits:**
+
+- Detects conflicts early before actual merge execution
+- No working tree modifications
+- Fast simulation of merge operations
+
+**Example Dry-Run Output with Conflicts:**
+
+```json
+{
+  "mode": "dry-run",
+  "lockHash": "abc123de",
+  "preflight": {
+    "enabled": true,
+    "conflictsDetected": 2,
+    "items": [
+      {
+        "id": "feature-ui",
+        "branch": "feature/ui",
+        "conflicts": ["src/components/Header.tsx", "src/styles/main.css"]
+      }
+    ]
+  },
+  "warnings": ["feature-ui has 2 potential conflicts. Review and resolve before executing."]
+}
+```
+
+#### Turn Cost Tracking
+
+Track coordination overhead during merge-weave operations:
+
+```bash
+lex-pr merge --execute --track-turncost
+```
+
+**Components:**
+
+- **Latency (L)**: Total execution time
+- **Renegotiation (R)**: Conflicts requiring manual resolution
+- **Token Bloat (T)**: Token usage overhead (future)
+- **Attention (A)**: Context switches during execution
+
+**Weighted Score**: `λL + γC + ρR + τT + αA`
+
+See [Governance Metrics](./governance-metrics.md) for details on Turn Cost calculation.
+
+#### Exit Codes
+
+- `0`: Success (merge completed or dry-run successful)
+- `1`: Merge failed or conflicts detected (with `--fail-on-preflight-conflict`)
+- `2`: Configuration or validation error
+
+#### See Also
+
+- [Merge-Weave Quickstart](./merge-weave-quickstart.md) - Complete walkthrough with troubleshooting
+- [Merge-Weave State Machine](./merge-weave-state-machine.md) - Execution state transitions
+- [Advanced CLI Features](./advanced-cli.md) - Advanced merge-weave options
+- [Autopilot Levels](./autopilot-levels.md) - Automated PR creation and management
+
+---
+
+### `status`
+
+Show current execution status and merge eligibility.
+
+```bash
+lex-pr status [options] [file]
+
+Arguments:
+  file              Path to plan.json file (alternative to --plan)
+
+Options:
+  --plan <file>     Path to plan.json file
+  --json            Output JSON format
+  --state-dir <dir> Directory containing execution state (default: ".smartergpt/runner")
+  -h, --help        Display help for command
+```
+
+#### Examples
+
+```bash
+# Show human-readable status
+lex-pr status plan.json
+
+# JSON status for dashboards
+lex-pr status --json plan.json
+```
+
+#### JSON Output Schema (`--json` flag)
+
+**Success Response:**
+
+```json
+{
+  "executionStatus": "not_started|running|completed|failed",
+  "lastUpdated": "2024-01-15T10:35:00Z",
+  "summary": {
+    "totalItems": 4,
+    "passedItems": 2,
+    "failedItems": 1,
+    "blockedItems": 1,
+    "eligibleForMerge": 2
+  },
+  "items": [
+    {
+      "name": "item-a",
+      "status": "pass",
+      "eligibleForMerge": true,
+      "gatesSummary": {
+        "total": 2,
+        "passed": 2,
+        "failed": 0
+      }
+    }
+  ]
+}
+```
+
+**Exit Codes:**
+
+- `0`: Status retrieved successfully
+- `1`: System error (state files not readable)
+- `2`: No execution state found
+
+---
+
+### `report`
+
+Aggregate gate reports from directory of JSON files.
+
+```bash
+lex-pr report [options] <dir>
+
+Arguments:
+  dir               Directory containing gate report JSON files
+
+Options:
+  --out <format>    Output format: json|md (default: "json")
+  --validate        Validate reports against schema before aggregating
+  -h, --help        Display help for command
+```
+
+#### Examples
+
+```bash
+# JSON summary of gate results
+lex-pr report ./gate-results
+
+# Markdown report for humans
+lex-pr report --out md ./gate-results
+
+# Validate reports first
+lex-pr report --validate ./gate-results
+```
+
+#### JSON Output Schema (`--out json`)
+
+**Success Response:**
+
+```json
+{
+  "summary": {
+    "totalReports": 8,
+    "totalItems": 4,
+    "totalGates": 12,
+    "passedGates": 10,
+    "failedGates": 2,
+    "allGreen": false
+  },
+  "items": [
+    {
+      "name": "item-a",
+      "gates": [
+        {
+          "name": "test",
+          "status": "pass",
+          "duration_ms": 1500,
+          "started_at": "2024-01-15T10:30:00Z"
+        }
+      ],
+      "summary": {
+        "totalGates": 3,
+        "passedGates": 3,
+        "failedGates": 0
+      }
+    }
+  ]
+}
+```
+
+**Markdown Output (`--out md`):**
+
+```markdown
+# Gate Execution Report
+
+## Summary
+
+- **Total Items**: 4
+- **Total Gates**: 12
+- **Passed**: 10 ✅
+- **Failed**: 2 ❌
+- **Overall Status**: ❌ FAILED
+
+## Item Results
+
+### item-a ✅
+
+- test: ✅ PASS (1.5s)
+- lint: ✅ PASS (0.8s)
+- build: ✅ PASS (12.3s)
+```
+
+**Exit Codes:**
+
+- `0`: All gates passed (allGreen: true)
+- `1`: System error (directory not readable, invalid reports)
+- `2`: One or more gates failed
+
+---
+
+### `doctor`
+
+Environment and configuration sanity checks.
+
+```bash
+lex-pr doctor [options]
+
+Options:
+  --json            Output JSON format
+  -h, --help        Display help for command
+```
+
+#### Examples
+
+```bash
+# Human-readable environment check
+lex-pr doctor
+
+# JSON output for automation
+lex-pr doctor --json
+```
+
+#### JSON Output Schema (`--json` flag)
+
+**Success Response:**
+
+```json
+{
+  "status": "healthy|warning|error",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "checks": [
+    {
+      "name": "node_version",
+      "status": "pass|warn|fail",
+      "message": "Node.js 20.10.0 (OK)",
+      "expected": ">=18.0.0",
+      "actual": "20.10.0"
+    },
+    {
+      "name": "config_files",
+      "status": "pass",
+      "message": "All configuration files found",
+      "details": [".smartergpt/intent.md: ✓", ".smartergpt/scope.yml: ✓"]
+    }
+  ],
+  "summary": {
+    "totalChecks": 5,
+    "passed": 4,
+    "warnings": 1,
+    "failures": 0
+  }
+}
+```
+
+**Exit Codes:**
+
+- `0`: All checks passed or warnings only
+- `1`: System error during checks
+- `2`: One or more critical checks failed
+
+## Deterministic Output Requirements
+
+All CLI commands with `--json` output must guarantee:
+
+1. **Stable key ordering**: All JSON objects have keys sorted alphabetically
+2. **Consistent formatting**: Use 2-space indentation, no trailing whitespace
+3. **Reproducible timestamps**: Avoid runtime timestamps except where semantically required
+4. **Sorted arrays**: Dependencies, items, errors sorted by name/path
+5. **Cross-platform consistency**: Same inputs produce identical outputs on Windows/macOS/Linux
+
+### Verification
+
+```bash
+# Determinism check - should be byte-identical
+npm run build && npm run format
+git diff --exit-code  # Must be clean
+
+# Cross-platform verification
+lex-pr plan --json > output1.json
+lex-pr plan --json > output2.json
+cmp output1.json output2.json     # Should be identical
+```
+
+---
+
+## CLI Conventions
+
+This section documents internal patterns for CLI development. Follow these conventions to ensure consistent behavior across all commands.
+
+### Exit Handling
+
+**Core Principle**: Never call `process.exit()` directly. Use `throwExit()` or throw `CLIExitSignal` instead.
+
+#### The CLIExitSignal Pattern
+
+The CLI uses a custom error class for all exits:
+
+```typescript
+class CLIExitSignal extends Error {
+  exitCode: number;
+
+  constructor(code: number, message?: string) {
+    super(message ?? `CLI exited with code ${code}`);
+    this.exitCode = code;
+  }
+}
+
+const throwExit = (code: number): never => {
+  throw new CLIExitSignal(code);
+};
+```
+
+**Why**: This approach allows:
+
+- Centralized exit handling in the main error handler
+- Proper cleanup of resources before exit
+- Testability (errors can be caught in tests)
+- Consistent error formatting
+
+#### Commander Exit Override
+
+All Commander exits are intercepted centrally:
+
+```typescript
+program.exitOverride((err: CommanderError) => {
+  // Help/version often exit with code 0; normalize through CLIExitSignal
+  throw new CLIExitSignal(err.exitCode ?? 1, err.message);
+});
+```
+
+**Why**: Commander's default exit behavior calls `process.exit()` directly. Overriding ensures:
+
+- All exits go through the same path
+- Help/version commands work correctly with exit code 0
+- No bypassing of error handlers
+
+#### Exit Code Discipline
+
+Use the standard exit codes consistently:
+
+```typescript
+throwExit(0); // Success
+throwExit(1); // System/infrastructure errors
+throwExit(2); // User/validation errors
+```
+
+**Examples**:
+
+✅ **Correct**:
+
+```typescript
+try {
+  const plan = loadPlan(planPath);
+  // ... process plan
+  throwExit(0);
+} catch (e) {
+  if (e instanceof SchemaValidationError) {
+    console.error(`Validation failed: ${e.message}`);
+    throwExit(2); // User can fix this
+  }
+  console.error(`Unexpected error: ${e.message}`);
+  throwExit(1); // System error
+}
+```
+
+❌ **Incorrect**:
+
+```typescript
+// DON'T: Direct process.exit
+process.exit(1);
+
+// DON'T: Throw generic errors for exit
+throw new Error("exit");
+
+// DON'T: Return exit codes
+return 1;
+```
+
+### JSON Purity
+
+**Core Principle**: Keep stdout clean for JSON output. All diagnostics, progress messages, and errors go to stderr.
+
+#### Output Stream Configuration
+
+Configure Commander to use explicit streams:
+
+```typescript
+program.configureOutput({
+  writeOut: (str) => process.stdout.write(str),
+  writeErr: (str) => process.stderr.write(str),
+});
+```
+
+**Why**: This ensures:
+
+- Help/version output goes to stderr (Commander default)
+- stdout remains pure for JSON or data output
+- Pipeable commands work correctly
+
+#### JSON Mode Discipline
+
+Commands with `--json` flag must follow strict rules:
+
+```typescript
+let jsonModeActive = false;
+
+command.action(async (opts) => {
+  const previousJsonMode = jsonModeActive;
+  jsonModeActive = !!opts.json;
+
+  try {
+    if (opts.json) {
+      // ONLY write JSON to stdout, nothing else
+      process.stdout.write(canonicalJSONStringify(result));
+      return;
+    }
+
+    // Human-readable output
+    console.log("✓ Success!");
+    console.log(summary);
+  } finally {
+    jsonModeActive = previousJsonMode;
+  }
+});
+```
+
+**Rules for JSON mode**:
+
+1. **No console.log** in JSON mode - use `process.stdout.write()` directly
+2. **No progress messages** - suppress all diagnostics in JSON mode
+3. **No emojis or formatting** - JSON only
+4. **Always use canonicalJSONStringify** - ensures deterministic output
+
+**Examples**:
+
+✅ **Correct**:
+
+```typescript
+if (opts.json) {
+  // Pure JSON to stdout
+  process.stdout.write(canonicalJSONStringify({ status: "ok", data }));
+  return;
+}
+
+// Human mode: rich output to stdout/stderr
+console.log("✓ Operation complete");
+console.error("ℹ️ Note: Some items were skipped");
+```
+
+❌ **Incorrect**:
+
+```typescript
+if (opts.json) {
+  console.log("Processing..."); // DON'T: breaks JSON purity
+  console.log(JSON.stringify(data)); // DON'T: use canonicalJSONStringify
+  console.error(JSON.stringify(error)); // DON'T: errors to stderr, not JSON mixed in
+}
+```
+
+#### Diagnostic Output
+
+Even in normal mode, separate data from diagnostics:
+
+```typescript
+// Diagnostics and progress → stderr
+console.error("🔍 Analyzing plan...");
+console.error(`Found ${items.length} items`);
+
+// Final output → stdout
+console.log(canonicalJSONStringify(result));
+```
+
+**Why**: Allows users to pipe output while still seeing progress:
+
+```bash
+lex-pr plan --json > plan.json  # Progress visible, JSON piped
+```
+
+### Output Modes
+
+#### Canonical JSON Output
+
+Always use `canonicalJSONStringify()` for JSON output:
+
+```typescript
+import { canonicalJSONStringify } from "./util/canonicalJson.js";
+
+// Automatically includes trailing newline
+process.stdout.write(canonicalJSONStringify(data));
+```
+
+**Note**: Import path shown is from `src/` directory. Adjust relative path based on your file location. Use `.js` extension in imports even for TypeScript source files (required for ES modules - TypeScript doesn't rewrite extensions).
+
+**Why**: Ensures deterministic output:
+
+- Keys sorted alphabetically at all levels
+- Consistent 2-space indentation
+- Always includes trailing newline
+- Same output every time (no timestamps, no random ordering)
+
+#### Human-Readable Output
+
+For human output, use rich formatting:
+
+```typescript
+console.log("\n✓ Plan generated successfully\n");
+console.log(`📁 Output: ${planPath}`);
+console.log(`📊 Items: ${items.length}`);
+console.log("");
+console.log(generatePlanSummary(plan));
+```
+
+**Guidelines**:
+
+- Use emojis for visual clarity
+- Include spacing for readability
+- Provide actionable next steps
+- Use colors (via chalk) sparingly
+
+### Error Handling Patterns
+
+#### The exitWith() Helper
+
+Use the `exitWith()` helper for consistent error handling:
+
+```typescript
+function exitWith(e: unknown, schemaCode = "ESCHEMA") {
+  // Let CLIExitSignal propagate - don't treat it as an error
+  if (e instanceof CLIExitSignal) {
+    throw e;
+  }
+
+  const err: any = e;
+
+  // Schema-specific error handling
+  if (err?.code === schemaCode && Array.isArray(err.issues)) {
+    console.log(JSON.stringify({ errors: err.issues }, null, 2));
+    console.error(err.message);
+    throwExit(2);
+  }
+
+  // Handle known validation errors (exit 2)
+  if (
+    e instanceof SchemaValidationError ||
+    e instanceof CycleError ||
+    e instanceof UnknownDependencyError ||
+    e instanceof WriteProtectionError ||
+    e instanceof AutopilotConfigError
+  ) {
+    console.error(`\n❌ Error: ${err.message}\n`);
+
+    // Add contextual help based on error type
+    // e.g., for WriteProtectionError: suggest using local profile
+    // e.g., for CycleError: suggest checking dependency declarations
+
+    throwExit(2);
+  }
+
+  // Handle system errors (exit 1)
+  console.error(`\n❌ Unexpected error: ${err.message}\n`);
+  throwExit(1);
+}
+```
+
+**Note**: Simplified example. See `src/cli.ts` for the full implementation with contextual error messages.
+
+**Usage**:
+
+```typescript
+try {
+  const plan = await generatePlan();
+  process.stdout.write(canonicalJSONStringify(plan));
+} catch (error) {
+  exitWith(error);
+}
+```
+
+#### Error Context
+
+Provide helpful context in error messages:
+
+```typescript
+if (e instanceof WriteProtectionError) {
+  console.error(`\n❌ Error: ${e.message}\n`);
+  console.error("💡 Tip: Use a local profile directory for development:");
+  console.error("   lex-pr init --profile-dir .smartergpt.local\n");
+  throwExit(2);
+}
+```
+
+### Testing CLI Commands
+
+Write tests that verify exit behavior:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { CLIExitSignal } from "../src/cli.js";
+
+describe("CLI exit codes", () => {
+  it("should throw CLIExitSignal on validation error", () => {
+    // Test that validation errors throw CLIExitSignal with code 2
+    expect(() => {
+      throw new CLIExitSignal(2, "Validation failed");
+    }).toThrow(CLIExitSignal);
+  });
+
+  it("should have correct exit code in signal", () => {
+    const signal = new CLIExitSignal(2, "Validation error");
+    expect(signal.exitCode).toBe(2);
+  });
+});
+```
+
+**Note**: Testing the full CLI requires mocking process.exit or using child processes. The above shows testing the CLIExitSignal class itself.
+
+### Summary
+
+**Key Takeaways**:
+
+1. **Exit Discipline**: Always use `throwExit()` or throw `CLIExitSignal`, never `process.exit()`
+2. **JSON Purity**: stdout for data, stderr for diagnostics - configure Commander explicitly
+3. **Deterministic Output**: Use `canonicalJSONStringify()` for all JSON output
+4. **Error Codes**: 0 = success, 1 = system error, 2 = user error
+5. **Stream Separation**: Commander's `configureOutput()` ensures help/errors don't pollute stdout
+
+**Related Documentation**:
+
+- [Error Taxonomy](./errors.md) - Complete error code reference
+- [Deterministic Output](#deterministic-output-requirements) - JSON output guarantees
+- Source: `src/cli.ts` - See `CLIExitSignal`, `throwExit()`, `exitWith()`
+
+---
+
+## Advanced Commands
+
+### `view`
+
+Interactive plan viewer with keyboard navigation and filtering.
+
+```bash
+lex-pr view [options] [file]
+
+Arguments:
+  file              Path to plan.json file (alternative to --plan)
+
+Options:
+  --plan <file>     Path to plan.json file
+  --filter <text>   Initial filter text
+  --no-deps         Hide dependencies by default
+  --no-gates        Hide gates by default
+  -h, --help        Display help for command
+```
+
+**Keyboard Navigation:**
+
+- `↑/↓` - Navigate items
+- `/` - Enter filter mode
+- `d` - Toggle dependencies
+- `g` - Toggle gates
+- `q` - Quit
+
+#### Examples
+
+```bash
+# Open interactive viewer
+lex-pr view plan.json
+
+# Start with a filter
+lex-pr view plan.json --filter "feature"
+
+# Hide gates by default
+lex-pr view plan.json --no-gates
+```
+
+---
+
+### `query`
+
+Advanced query and analysis of plan using SQL-like syntax.
+
+```bash
+lex-pr query [file] [query] [options]
+
+Arguments:
+  file              Path to plan.json file (alternative to --plan)
+  query             Query string (e.g., 'level eq 1', 'name contains feature')
+
+Options:
+  --plan <file>     Path to plan.json file
+  --format <fmt>    Output format: json, table, csv (default: "table")
+  --output <file>   Output file (default: stdout)
+  --stats           Show plan statistics
+  --roots           Show root nodes (no dependencies)
+  --leaves          Show leaf nodes (no dependents)
+  --level <level>   Filter by merge level
+  -h, --help        Display help for command
+```
+
+**Query Syntax:**
+
+```
+field operator value [AND field operator value]
+```
+
+**Operators:** `eq`, `ne`, `contains`, `in`, `gt`, `lt`, `gte`, `lte`
+
+**Fields:** `name`, `level`, `depsCount`, `gatesCount`, `dependentsCount`
+
+#### Examples
+
+```bash
+# Find all items at merge level 1
+lex-pr query plan.json "level eq 1"
+
+# Find items with specific name pattern
+lex-pr query plan.json "name contains feature"
+
+# Find items with more than 2 dependencies
+lex-pr query plan.json "depsCount gt 2"
+
+# Complex queries with AND
+lex-pr query plan.json "level eq 1 AND depsCount eq 0"
+
+# Show plan statistics
+lex-pr query plan.json --stats
+
+# Output as JSON
+lex-pr query plan.json "level eq 1" --format json
+
+# Save to file
+lex-pr query plan.json --roots --output roots.json --format json
+```
+
+---
+
+### `retry`
+
+Retry failed gates with selective filtering.
+
+```bash
+lex-pr retry [options]
+
+Options:
+  --state-dir <dir>  State directory (default: ".smartergpt/runner")
+  --filter <text>    Filter items/gates to retry
+  --items <items>    Comma-separated list of items to retry
+  --dry-run          Show what would be retried without executing
+  --json             Output JSON format
+  -h, --help         Display help for command
+```
+
+#### Examples
+
+```bash
+# Show all failed gates
+lex-pr retry --dry-run
+
+# Retry all failed gates
+lex-pr retry
+
+# Retry specific items
+lex-pr retry --items "item1,item2"
+
+# Retry with filter
+lex-pr retry --filter "integration"
+
+# JSON output
+lex-pr retry --json
+```
+
+---
+
+### `completion`
+
+Generate shell completion scripts for bash and zsh.
+
+```bash
+lex-pr completion [shell] [options]
+
+Arguments:
+  shell             Shell type: bash, zsh (default: "bash")
+
+Options:
+  --install         Show installation instructions
+  -h, --help        Display help for command
+```
+
+#### Examples
+
+```bash
+# Generate bash completion
+lex-pr completion bash
+
+# Generate zsh completion
+lex-pr completion zsh
+
+# Show installation instructions
+lex-pr completion bash --install
+```
+
+**Installation:**
+
+For bash:
+
+```bash
+# Add to ~/.bashrc
+eval "$(lex-pr completion bash)"
+```
+
+For zsh:
+
+```bash
+# Add to ~/.zshrc
+eval "$(lex-pr completion zsh)"
+```
+
+---
+
+### Enhanced `merge` Options
+
+The `merge` command now supports batch operations:
+
+```bash
+lex-pr merge [options]
+
+Additional Batch Options:
+  --batch               Enable batch mode for multiple items
+  --filter <query>      Filter items using query language
+  --levels <levels>     Comma-separated list of levels to merge
+  --items <items>       Comma-separated list of items to merge
+```
+
+#### Batch Examples
+
+```bash
+# Merge specific items
+lex-pr merge plan.json --batch --items "item1,item2" --execute
+
+# Merge all items at specific levels
+lex-pr merge plan.json --batch --levels "1,2" --execute
+
+# Merge items matching a query
+lex-pr merge plan.json --batch --filter "level eq 1" --execute
+```
+
+---
+
+## Error Handling
+
+All commands follow consistent error handling:
+
+- **Exit code 0**: Success
+- **Exit code 1**: System/infrastructure errors
+- **Exit code 2**: User/validation errors
+
+JSON error responses use consistent format:
+
+```json
+{
+  "error": true,
+  "code": "ERROR_CODE",
+  "message": "Human-readable error message",
+  "details": {
+    // Command-specific error context
+  }
+}
+```
+
+See [Error Taxonomy](./errors.md) for complete error code reference.