@smartergpt/lexrunner 1.0.0 → 1.3.0

package/docs/diffgraph-planner.md

@@ -1,1211 +0,0 @@
-# Diffgraph Planner Guide
-
-The diffgraph planner enables automatic dependency discovery and intelligent merge ordering for multiple PRs. This guide covers everything from basic usage to advanced workflows.
-
-## Table of Contents
-
-- [Introduction](#introduction)
-- [Quick Start](#quick-start)
-- [Dependency Syntax Reference](#dependency-syntax-reference)
-- [File-Change Heuristics](#file-change-heuristics)
-- [Validation & Troubleshooting](#validation--troubleshooting)
-- [Workflows & Best Practices](#workflows--best-practices)
-- [Advanced Topics](#advanced-topics)
-- [API Reference](#api-reference)
-- [Examples Gallery](#examples-gallery)
-
----
-
-## Introduction
-
-### What is Diffgraph Planning?
-
-Diffgraph planning automatically discovers dependencies between pull requests and computes an optimal merge order. Instead of manually tracking which PRs depend on which, the planner:
-
-1. **Parses explicit dependencies** from PR descriptions (e.g., `Depends-on: #123`)
-2. **Analyzes file changes** to suggest implicit dependencies
-3. **Validates the dependency graph** for cycles and orphans
-4. **Computes merge layers** using topological sort
-5. **Generates a deterministic plan** for execution
-
-**Result:** A validated, executable plan that merges PRs in the correct order, respecting dependencies.
-
-### When to Use Auto-Discovery vs Manual Planning
-
-| Scenario                   | Recommended Approach        | Why                               |
-| -------------------------- | --------------------------- | --------------------------------- |
-| **Small team (2-5 devs)**  | Auto-discovery with review  | Fast, catches missed dependencies |
-| **Large team (10+ devs)**  | Explicit deps + suggestions | Better control, human oversight   |
-| **Complex feature stacks** | Hybrid (both)               | Combines precision with discovery |
-| **Independent hotfixes**   | Manual planning             | No dependencies to discover       |
-| **Batch refactors**        | Auto-discovery              | File overlap is reliable signal   |
-
-### High-Level Workflow
-
-```
-┌─────────────────┐
-│  Open PRs (GitHub)│
-│  with descriptions│
-└────────┬─────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ 1. Parse Dependencies   │ ← Explicit footers (Depends-on:)
-│    (dependencyParser)   │
-└────────┬────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ 2. Analyze File Changes │ ← Implicit suggestions (shared files)
-│    (fileAnalysis)       │
-└────────┬────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ 3. Score Dependencies   │ ← Combine explicit + implicit
-│    (dependencyScoring)  │
-└────────┬────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ 4. Validate Plan        │ ← Check cycles, orphans, refs
-│    (validation)         │
-└────────┬────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ 5. Generate plan.json   │ ← Deterministic, executable
-└─────────────────────────┘
-```
-
----
-
-## Quick Start
-
-This minimal example shows how to generate and execute a plan for 3 PRs with dependencies.
-
-### Setup: PRs with Dependencies
-
-You have 3 open PRs:
-
-- **PR-100:** `feature/auth-api` - Add authentication API endpoints
-- **PR-101:** `feature/auth-ui` - Add authentication UI (depends on API)
-- **PR-102:** `feature/auth-tests` - Add E2E tests (depends on UI)
-
-### Step 1: Add Dependency Footers
-
-Update PR descriptions with explicit dependencies:
-
-**PR-101 description:**
-
-```markdown
-Add authentication UI components.
-
-Depends-on: #100
-```
-
-**PR-102 description:**
-
-```markdown
-Add E2E tests for authentication flow.
-
-Depends-on: #101
-```
-
-### Step 2: Generate Plan
-
-```bash
-# Set GitHub token (if not already in environment)
-export GITHUB_TOKEN=your_token_here
-
-# Generate plan from GitHub PRs
-lex-pr plan --from-github --output plan.json
-```
-
-**Expected output:**
-
-```
-✓ Fetched 3 open PRs
-✓ Parsed dependencies: 2 explicit, 0 implicit
-✓ Validated: no cycles, no orphans
-✓ Generated plan: 3 nodes, 2 edges, 3 layers
-
-Plan written to: plan.json
-```
-
-### Step 3: Review Plan
-
-```bash
-# Show merge order
-lex-pr merge-order plan.json
-```
-
-**Expected output:**
-
-```
-📊 Merge order for 3 items:
-
-Layer 0 (ready):
-  → PR-100 (auth-api)
-
-Layer 1 (after PR-100):
-  → PR-101 (auth-ui)
-
-Layer 2 (after PR-101):
-  → PR-102 (auth-tests)
-```
-
-### Step 4: Execute
-
-```bash
-# Run gates and merge (dry-run first)
-lex-pr merge --plan plan.json
-
-# Execute for real
-lex-pr merge --plan plan.json --execute
-```
-
-**What happens:**
-
-1. PR-100 gates run → merge
-2. PR-101 gates run → merge (after PR-100)
-3. PR-102 gates run → merge (after PR-101)
-
----
-
-## Dependency Syntax Reference
-
-The planner recognizes multiple dependency formats in PR descriptions.
-
-### Supported Keywords
-
-| Keyword       | Example               | Notes                                 |
-| ------------- | --------------------- | ------------------------------------- |
-| `Depends-on:` | `Depends-on: #123`    | **Recommended** - explicit dependency |
-| `Depends:`    | `Depends: #123, #456` | Alias for `Depends-on:`               |
-| `Requires:`   | `Requires: #123`      | Alias for `Depends-on:`               |
-| `Closes:`     | `Closes: #100`        | GitHub keyword (not a dependency)     |
-| `Fixes:`      | `Fixes: #200`         | GitHub keyword (not a dependency)     |
-| `Resolves:`   | `Resolves: #300`      | GitHub keyword (not a dependency)     |
-
-**Note:** `Closes`, `Fixes`, and `Resolves` are GitHub issue-closing keywords and are **not treated as dependencies** by the planner.
-
-### Single Dependency
-
-```markdown
-Depends-on: #123
-```
-
-### Multiple Dependencies
-
-```markdown
-Depends-on: #123, #456, #789
-```
-
-or split across lines:
-
-```markdown
-Depends-on: #123
-Depends-on: #456
-Depends-on: #789
-```
-
-### Cross-Repo References
-
-```markdown
-Depends-on: owner/repo#123
-Depends-on: other-repo#456
-```
-
-**Normalization:** All references are normalized to `owner/repo#number` format internally.
-
-### Invalid Syntax Examples
-
-❌ **Don't do this:**
-
-```markdown
-# Missing PR number
-
-Depends-on: feature-branch
-
-# Using PR- prefix (not needed)
-
-Depends-on: PR-123
-
-# Using URLs (not supported)
-
-Depends-on: https://github.com/owner/repo/pull/123
-```
-
-✅ **Do this instead:**
-
-```markdown
-Depends-on: #123
-```
-
-### Placement in PR Description
-
-Dependencies can appear **anywhere** in the PR description:
-
-```markdown
-## Summary
-
-Add new feature X.
-
-## Dependencies
-
-Depends-on: #100, #101
-
-## Changes
-
-- Feature implementation
-- Tests added
-```
-
-The parser extracts all `Depends-on:` lines regardless of position.
-
----
-
-## File-Change Heuristics
-
-When explicit dependencies are missing, the planner uses file-change analysis to suggest implicit dependencies.
-
-### How It Works
-
-1. **Fetch file changes** for each PR (via GitHub API)
-2. **Build intersection matrix** - which PRs touch the same files
-3. **Calculate confidence scores** based on overlap patterns
-4. **Generate suggestions** sorted by confidence (high to low)
-
-### Confidence Scoring Explained
-
-#### Shared File Modifications (0.6 - 1.0)
-
-**Highest confidence** - both PRs modify the same file.
-
-| Pattern                   | Confidence | Example                                                      |
-| ------------------------- | ---------- | ------------------------------------------------------------ |
-| Both modify same file     | 1.0        | PR-101 modifies `core.ts`, PR-102 modifies `core.ts`         |
-| One modifies, one renames | 0.8        | PR-101 modifies `old.ts`, PR-102 renames `old.ts` → `new.ts` |
-| Mixed (modify + delete)   | 0.6        | PR-101 modifies `utils.ts`, PR-102 deletes `utils.ts`        |
-
-**Heuristic:** If two PRs modify overlapping files, they likely have a dependency relationship.
-
-#### Directory Proximity (0.3 - 0.8)
-
-**Medium confidence** - PRs work in the same area of the codebase.
-
-```
-Formula: min(commonDirs / totalDirs, 0.8)
-```
-
-| Scenario                    | Confidence | Example                                  |
-| --------------------------- | ---------- | ---------------------------------------- |
-| All files in same directory | 0.8        | Both modify files only in `src/planner/` |
-| Majority overlap            | 0.6        | 3/5 directories in common                |
-| Partial overlap             | 0.4        | 1/3 directories in common                |
-| Minimal overlap             | 0.3        | Different directories, same parent       |
-
-**Heuristic:** PRs working in the same module/directory often have dependencies.
-
-#### Test Overlap (0.5 - 0.85)
-
-**Medium-high confidence** - PRs test the same modules.
-
-| Pattern            | Confidence | Example                                                    |
-| ------------------ | ---------- | ---------------------------------------------------------- |
-| Shared test file   | 0.85       | Both modify `tests/core.spec.ts`                           |
-| Same module tested | 0.65       | PR-101: `tests/core.spec.ts`, PR-102: `tests/core.test.ts` |
-| Related test files | 0.5        | Both modify tests in `tests/api/`                          |
-
-**Heuristic:** If PRs test the same module, their implementations may be related.
-
-### When to Trust Implicit Dependencies
-
-✅ **High confidence (≥0.7)** - likely a real dependency:
-
-- Both PRs modify the same critical file (`core.ts`, `schema.ts`)
-- Extensive file overlap (5+ files)
-- Test files overlap suggests implementation dependency
-
-⚠️ **Medium confidence (0.4-0.7)** - requires human review:
-
-- Partial file overlap (1-3 files)
-- Directory proximity but different concerns
-- Test overlap but different features
-
-❌ **Low confidence (<0.4)** - probably coincidence:
-
-- Minimal file overlap
-- Common utility files (`utils.ts`, `types.ts`)
-- Documentation changes
-
-### When to Add Explicit Dependencies
-
-Even with high-confidence suggestions, **always prefer explicit dependencies**:
-
-1. **Clarity:** Human-readable intent in PR descriptions
-2. **Determinism:** Explicit deps never change (file-based suggestions can)
-3. **Debugging:** Easier to understand why PRs are ordered a certain way
-4. **Trust:** Team members understand the relationship
-
-**Best practice:** Use suggestions to **discover** missing dependencies, then **add explicit footers** to PR descriptions.
-
-### Suggestion Output Formats
-
-#### Table Format (Human-Readable)
-
-```bash
-lex-pr plan --suggest-deps
-```
-
-```
-📊 Dependency Suggestions (3 found):
-
-| From   | To     | Confidence | Heuristic          | Reason                              |
-|--------|--------|------------|--------------------|-------------------------------------|
-| PR-101 | PR-102 | 95%        | shared-files       | shared file modifications           |
-| PR-201 | PR-202 | 65%        | test-overlap       | tests for same module               |
-| PR-301 | PR-302 | 50%        | directory-proximity| both modify files in 1 common dir   |
-```
-
-#### JSON Format (Machine-Readable)
-
-```bash
-lex-pr plan --suggest-deps --json
-```
-
-```json
-{
-  "suggestions": [
-    {
-      "from": "PR-101",
-      "to": "PR-102",
-      "reason": "shared file modifications",
-      "confidence": 0.95,
-      "sharedFiles": ["src/core.ts", "src/utils.ts"],
-      "heuristic": "shared-files"
-    }
-  ]
-}
-```
-
-#### Markdown Format (Review-Friendly)
-
-```bash
-lex-pr plan --suggest-deps --format=markdown
-```
-
-```markdown
-## Dependency Suggestions
-
-### High Confidence (≥0.7)
-
-- **PR-101 → PR-102** (95% confidence)
-  - Heuristic: shared-files
-  - Reason: shared file modifications
-  - Files: `src/core.ts`, `src/utils.ts`
-
-### Medium Confidence (0.4-0.7)
-
-- **PR-201 → PR-202** (65% confidence)
-  - Heuristic: test-overlap
-  - Reason: tests for same module
-```
-
----
-
-## Validation & Troubleshooting
-
-The planner validates plans before execution to catch errors early.
-
-### Validation Checks
-
-1. **Cycle detection** - no circular dependencies
-2. **Reference validation** - all deps point to valid PRs
-3. **Self-dependency check** - no PR depends on itself
-4. **Orphan detection** - warn about isolated PRs
-
-### Error: Dependency Cycle Detected
-
-**Symptom:**
-
-```
-❌ Validation failed: Dependency cycle detected
-Cycle path: PR-100 → PR-101 → PR-102 → PR-100
-```
-
-**Cause:** Circular dependency in the graph.
-
-**Diagnosis:**
-
-1. Review the cycle path from the error message
-2. Check PR descriptions for circular `Depends-on:` footers
-3. Check file overlap (might be false positive from heuristics)
-
-**Solution:**
-
-```bash
-# Step 1: Identify the weakest link in the cycle
-lex-pr plan --suggest-deps --json | jq '.suggestions[] | select(.from == "PR-100" and .to == "PR-101")'
-
-# Step 2: If the dependency is weak (low confidence), remove it
-# Edit PR description, remove "Depends-on: #100"
-
-# Step 3: Regenerate plan
-lex-pr plan --from-github --output plan.json
-```
-
-**Example fix:**
-
-Before (cycle):
-
-```
-PR-100: Depends-on: #102
-PR-101: Depends-on: #100
-PR-102: Depends-on: #101
-```
-
-After (broken cycle):
-
-```
-PR-100: (no dependencies)
-PR-101: Depends-on: #100
-PR-102: Depends-on: #101
-```
-
-### Warning: Unreachable/Orphan PRs
-
-**Symptom:**
-
-```
-⚠️  Warning: Orphan PRs detected (no dependencies, no dependents)
-  - PR-999 (hotfix/security-patch)
-```
-
-**Cause:** PR has no dependencies and no other PRs depend on it.
-
-**Is this a problem?**
-
-Sometimes **NO** (valid scenarios):
-
-- Independent hotfixes
-- Parallel feature work
-- Refactors with no dependencies
-
-Sometimes **YES** (missing dependencies):
-
-- PR should depend on foundation work
-- PR is part of a stack but missing `Depends-on:` footer
-
-**Diagnosis:**
-
-```bash
-# Check if suggestions exist for the orphan PR
-lex-pr plan --suggest-deps | grep "PR-999"
-```
-
-**Solution:**
-
-If suggestions exist:
-
-```bash
-# Add explicit dependency to PR description
-# Edit PR-999, add "Depends-on: #100"
-```
-
-If truly independent:
-
-```bash
-# Ignore the warning - this is expected
-```
-
-### Low-Confidence Implicit Dependencies
-
-**Symptom:**
-
-```
-📊 Dependency Suggestions (1 found):
-| From   | To     | Confidence | Heuristic          |
-|--------|--------|------------|-------------------|
-| PR-101 | PR-102 | 35%        | directory-proximity|
-```
-
-**Cause:** File overlap is weak, heuristics are uncertain.
-
-**Options:**
-
-1. **Add explicit dependency** (if relationship exists):
-
-   ```markdown
-   # In PR-102 description
-
-   Depends-on: #101
-   ```
-
-2. **Ignore suggestion** (if PRs are truly independent):
-
-   ```bash
-   # Use higher threshold to filter out low-confidence suggestions
-   lex-pr plan --suggest-deps --threshold=0.5
-   ```
-
-3. **Investigate further**:
-   ```bash
-   # Get detailed file overlap info
-   lex-pr plan --suggest-deps --json | jq '.suggestions[] | select(.confidence < 0.5)'
-   ```
-
-### Plan Differs Between Runs
-
-**Symptom:** Running the same command twice produces different output.
-
-**Cause:** This should **never happen** - it's a determinism bug.
-
-**Diagnosis:**
-
-```bash
-# Generate plan twice, compare
-lex-pr plan --from-github --output plan1.json
-lex-pr plan --from-github --output plan2.json
-diff plan1.json plan2.json
-```
-
-**If different:**
-
-1. Check for timestamp fields (file them as a bug)
-2. Check for random ordering (file them as a bug)
-3. Check for network timing issues (file them as a bug)
-
-**Workaround:**
-
-```bash
-# Pin specific commit SHAs in plan (not yet supported - file a feature request)
-```
-
-**Report:** This is a critical bug - please [file an issue](https://github.com/Guffawaffle/LexRunner/issues/new/choose) with:
-
-- Commands run
-- Diff of the two plans
-- Environment details (OS, Node version, lex-pr version)
-
----
-
-## Workflows & Best Practices
-
-Choose the workflow that matches your team's size and trust level.
-
-### Workflow 1: Full Auto (Trust the Planner)
-
-**Best for:** Small teams (2-5 devs), high trust in tooling
-
-```bash
-# One-shot: generate and execute
-lex-pr plan --from-github --output plan.json
-lex-pr execute --plan plan.json
-```
-
-**Pros:**
-
-- ✅ **Fast** - minimal overhead
-- ✅ **No manual review** - trust heuristics
-- ✅ **Catch implicit deps** - discovers missed relationships
-
-**Cons:**
-
-- ❌ **Potential errors** - heuristics can be wrong
-- ❌ **Less control** - no human verification
-- ❌ **Trust required** - team must trust the planner
-
-**When to use:**
-
-- Small codebase with clear module boundaries
-- High test coverage (gates catch integration issues)
-- Team is comfortable with automation
-
-### Workflow 2: Review Before Execute
-
-**Best for:** Medium teams (5-10 devs), safety-first culture
-
-```bash
-# Step 1: Generate suggestions for review
-lex-pr plan --suggest-deps --format=markdown > review.md
-
-# Step 2: Human reviews review.md
-#   - Approve high-confidence suggestions
-#   - Reject false positives
-#   - Add missing explicit dependencies
-
-# Step 3: Update PR descriptions with approved dependencies
-# (Manual step: edit PR descriptions in GitHub)
-
-# Step 4: Generate final plan (with updated explicit deps)
-lex-pr plan --from-github --output plan.json
-
-# Step 5: Execute
-lex-pr execute --plan plan.json
-```
-
-**Pros:**
-
-- ✅ **Human oversight** - catches errors early
-- ✅ **Learning opportunity** - team understands dependencies
-- ✅ **Trust building** - verify heuristics are working
-
-**Cons:**
-
-- ❌ **Slower** - requires review step
-- ❌ **Manual updates** - editing PR descriptions
-- ❌ **Cognitive load** - reviewing suggestions
-
-**When to use:**
-
-- Medium-sized team with complex dependencies
-- High-stakes releases (production deployments)
-- Building trust in the planner (early adoption)
-
-### Workflow 3: Hybrid (Explicit + Suggestions)
-
-**Best for:** Large teams (10+ devs), complex repos
-
-```bash
-# Step 1: PRs already have some explicit dependencies
-# (Team discipline: always add Depends-on: for known deps)
-
-# Step 2: Generate suggestions for missing dependencies
-lex-pr plan --suggest-deps --threshold=0.7 > suggestions.md
-
-# Step 3: Review high-confidence suggestions only (≥0.7)
-# Add them to PR descriptions
-
-# Step 4: Generate plan (combines explicit + reviewed implicit)
-lex-pr plan --from-github --output plan.json
-
-# Step 5: Execute
-lex-pr execute --plan plan.json
-```
-
-**Pros:**
-
-- ✅ **Best of both worlds** - explicit control + discovery
-- ✅ **Scales well** - clear rules for large teams
-- ✅ **High confidence** - only trust strong signals
-
-**Cons:**
-
-- ❌ **Requires discipline** - team must add explicit deps
-- ❌ **Configuration needed** - threshold tuning
-- ❌ **More steps** - review + update cycle
-
-**When to use:**
-
-- Large codebase with many concurrent PRs
-- Established team with good practices
-- Complex dependency patterns (stacks, diamonds, etc.)
-
-### Best Practices Summary
-
-| Practice                 | Why                     | How                                    |
-| ------------------------ | ----------------------- | -------------------------------------- |
-| **Prefer explicit deps** | Clarity and determinism | Always add `Depends-on:` when known    |
-| **Use high thresholds**  | Filter noise            | `--threshold=0.7` for hybrid workflow  |
-| **Review suggestions**   | Catch errors            | Generate `review.md` before execution  |
-| **Test heuristics**      | Build trust             | Compare suggestions to ground truth    |
-| **Document decisions**   | Team alignment          | Add comments in PR descriptions        |
-| **Validate early**       | Catch cycles            | Run `plan --validate` before execution |
-| **Commit plans**         | Reproducibility         | Store `plan.json` in version control   |
-
----
-
-## Advanced Topics
-
-### Custom Scoring Weights
-
-Adjust the weights for different heuristics:
-
-```typescript
-import { scoreDependencies } from "./planner/dependencyScoring.js";
-
-const scores = await scoreDependencies(prs, fileAnalyzer, {
-  weights: {
-    explicit: 1.0, // Explicit deps always win
-    sharedFiles: 0.8, // Lower weight for file overlap
-    directoryProximity: 0.5, // Lower weight for directory proximity
-    testOverlap: 0.6, // Medium weight for test overlap
-  },
-  threshold: 0.5, // Filter out scores below 0.5
-});
-```
-
-**Use case:** Tune weights based on your codebase characteristics.
-
-### Filtering PRs by Label
-
-```bash
-# Only include PRs with specific labels
-lex-pr plan --from-github --labels "ready-to-merge,stack:*"
-
-# Exclude PRs with specific labels
-lex-pr plan --from-github --exclude-labels "do-not-merge,wip"
-```
-
-**Use case:** Focus on a subset of PRs (e.g., only "ready" PRs).
-
-### Excluding Stale PRs
-
-```bash
-# Only include PRs updated in the last 7 days
-lex-pr plan --from-github --since 7d
-
-# Only include PRs created after a specific date
-lex-pr plan --from-github --created-after 2024-01-01
-```
-
-**Use case:** Ignore old PRs that are no longer relevant.
-
-### Plan Diffing
-
-Compare two plans to see what changed:
-
-```bash
-# Generate plan at two different times
-lex-pr plan --from-github --output plan-old.json
-# (PRs are updated)
-lex-pr plan --from-github --output plan-new.json
-
-# Diff the plans
-lex-pr plan-diff plan-old.json plan-new.json
-```
-
-**Output:**
-
-```
-📊 Plan Diff:
-
-Added PRs:
-  + PR-105 (new-feature)
-
-Removed PRs:
-  - PR-99 (merged)
-
-Changed dependencies:
-  ~ PR-101: added dep on PR-104
-```
-
-**Use case:** Understand how plan evolved as PRs are added/merged.
-
-### Incremental Planning
-
-Add new PRs to an existing plan without regenerating:
-
-```bash
-# Start with existing plan
-lex-pr plan --from-github --output plan.json
-
-# Add a new PR manually
-# (Edit plan.json, add new item)
-
-# Validate the updated plan
-lex-pr plan --validate plan.json
-```
-
-**Use case:** Quick updates without full regeneration.
-
----
-
-## API Reference
-
-This section documents the public APIs in the planner modules. Each function includes TypeScript signatures, examples, and links to source code.
-
-### `parsePRDescription()`
-
-Parse dependencies and metadata from a PR description.
-
-**Module:** `src/planner/dependencyParser.ts`
-
-**Signature:**
-
-```typescript
-function parsePRDescription(
-  prNumber: number,
-  description: string | null,
-  options?: ParserOptions
-): ParsedDependency;
-```
-
-**Parameters:**
-
-- `prNumber` - PR number (e.g., `123`)
-- `description` - PR body text (can be `null`)
-- `options` - Parsing options
-  - `repository?: string` - Owner/repo for normalization (e.g., `"owner/repo"`)
-  - `partialExtraction?: boolean` - Continue on errors (default: `false`)
-
-**Returns:** `ParsedDependency` object with:
-
-- `prId: string` - Normalized PR ID (e.g., `"PR-123"`)
-- `dependencies: string[]` - Array of dependency references
-- `gates?: { skip?: string[], required?: string[] }` - Gate overrides
-- `metadata?: { priority?: string, labels?: string[], ... }` - Extracted metadata
-
-**Example:**
-
-```typescript
-import { parsePRDescription } from "./planner/dependencyParser.js";
-
-const description = `
-Add authentication API.
-
-Depends-on: #100, #101
-Required: security-scan
-`;
-
-const result = parsePRDescription(123, description, {
-  repository: "owner/repo",
-});
-
-console.log(result);
-// {
-//   prId: "PR-123",
-//   dependencies: ["#100", "#101"],
-//   gates: { required: ["security-scan"] }
-// }
-```
-
-**See also:** [Dependency Syntax Reference](#dependency-syntax-reference)
-
-### `scoreDependencies()`
-
-Score and rank dependencies by combining explicit and implicit signals.
-
-**Module:** `src/planner/dependencyScoring.ts`
-
-**Signature:**
-
-```typescript
-async function scoreDependencies(
-  prs: Array<{ number: number; name: string; body: string; sha: string }>,
-  fileAnalyzer: FileAnalyzer,
-  options?: ScoringOptions
-): Promise<DependencyScore[]>;
-```
-
-**Parameters:**
-
-- `prs` - Array of PRs with number, name, body, sha
-- `fileAnalyzer` - File analyzer instance (from `createFileAnalyzer()`)
-- `options` - Scoring options
-  - `weights?: { explicit?, sharedFiles?, directoryProximity?, testOverlap? }` - Custom weights
-  - `threshold?: number` - Filter out scores below this value (default: `0.3`)
-
-**Returns:** Array of `DependencyScore` objects, sorted by confidence (descending), then from/to (ascending).
-
-**Example:**
-
-```typescript
-import { scoreDependencies } from "./planner/dependencyScoring.js";
-import { createFileAnalyzer } from "./planner/fileAnalysis.js";
-import { Octokit } from "@octokit/rest";
-
-const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
-const fileAnalyzer = createFileAnalyzer(octokit, "owner", "repo");
-
-const scores = await scoreDependencies(
-  [
-    { number: 101, name: "PR-101", body: "Depends-on: #100", sha: "abc123" },
-    { number: 102, name: "PR-102", body: "", sha: "def456" },
-  ],
-  fileAnalyzer,
-  {
-    weights: { explicit: 1.0, sharedFiles: 0.8 },
-    threshold: 0.5,
-  }
-);
-
-console.log(scores);
-// [
-//   {
-//     from: "PR-101",
-//     to: "PR-100",
-//     score: 1.0,
-//     reason: "explicit-footer",
-//     evidence: { explicit: ["Depends-on: #100"] }
-//   }
-// ]
-```
-
-**See also:** [File-Change Heuristics](#file-change-heuristics)
-
-### `validatePlan()`
-
-Validate a plan for cycles, invalid references, and orphans.
-
-**Module:** `src/planner/validation.ts`
-
-**Signature:**
-
-```typescript
-function validatePlan(plan: Plan): {
-  valid: boolean;
-  errors: ValidationError[];
-  warnings: ValidationWarning[];
-  diagnostics: ValidationDiagnostics;
-};
-```
-
-**Parameters:**
-
-- `plan` - Plan object (from `generatePlan()` or loaded from JSON)
-
-**Returns:** Validation result with:
-
-- `valid: boolean` - `true` if no errors
-- `errors: ValidationError[]` - Array of validation errors (cycles, invalid refs, etc.)
-- `warnings: ValidationWarning[]` - Array of warnings (orphans, low confidence, etc.)
-- `diagnostics: ValidationDiagnostics` - Plan statistics (nodes, edges, layers)
-
-**Example:**
-
-```typescript
-import { validatePlan } from "./planner/validation.js";
-import { loadPlan } from "./core/plan.js";
-
-const plan = await loadPlan("plan.json");
-const result = validatePlan(plan);
-
-if (!result.valid) {
-  console.error("Validation errors:");
-  result.errors.forEach((err) => {
-    console.error(`  - ${err.message}`);
-    console.error(`    Suggestion: ${err.suggestion}`);
-  });
-  process.exit(1);
-}
-
-if (result.warnings.length > 0) {
-  console.warn("Validation warnings:");
-  result.warnings.forEach((warn) => {
-    console.warn(`  - ${warn.message}`);
-    console.warn(`    Affected PRs: ${warn.affectedPRs.join(", ")}`);
-  });
-}
-
-console.log(
-  `✓ Plan is valid: ${result.diagnostics.nodes} nodes, ${result.diagnostics.edges} edges`
-);
-```
-
-**See also:** [Validation & Troubleshooting](#validation--troubleshooting)
-
-### `createFileAnalyzer()`
-
-Create a file analyzer for detecting implicit dependencies.
-
-**Module:** `src/planner/fileAnalysis.ts`
-
-**Signature:**
-
-```typescript
-function createFileAnalyzer(octokit: Octokit, owner: string, repo: string): FileAnalyzer;
-```
-
-**Parameters:**
-
-- `octokit` - Authenticated Octokit instance
-- `owner` - Repository owner
-- `repo` - Repository name
-
-**Returns:** `FileAnalyzer` instance with methods:
-
-- `getPRFileChanges(prNumber, sha?)` - Fetch file changes for a PR
-- `analyzeFiles(prs)` - Perform complete file analysis
-- `clearCache()` - Clear the internal cache
-- `getCacheStats()` - Get cache statistics
-
-**Example:**
-
-```typescript
-import { createFileAnalyzer } from "./planner/fileAnalysis.js";
-import { Octokit } from "@octokit/rest";
-
-const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
-const analyzer = createFileAnalyzer(octokit, "owner", "repo");
-
-const analysis = await analyzer.analyzeFiles([
-  { number: 101, name: "PR-101", sha: "abc123" },
-  { number: 102, name: "PR-102", sha: "def456" },
-]);
-
-console.log("File intersections:", analysis.fileIntersections);
-console.log("Suggestions:", analysis.suggestions);
-console.log("Conflicts:", analysis.conflicts);
-```
-
-**See also:** [File-Change Heuristics](#file-change-heuristics), [`src/planner/README.md`](../src/planner/README.md)
-
----
-
-## Examples Gallery
-
-Real-world examples demonstrating different dependency patterns.
-
-### Example 1: Simple Stack (Linear)
-
-**Scenario:** 3 PRs building on each other sequentially.
-
-**PRs:**
-
-- PR-100: Add auth API (foundation)
-- PR-101: Add auth UI (depends on API)
-- PR-102: Add auth tests (depends on UI)
-
-**Dependencies:**
-
-```
-PR-100 → PR-101 → PR-102
-```
-
-**Plan:**
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "target": "main",
-  "items": [
-    { "id": "pr-100", "name": "auth-api", "deps": [] },
-    { "id": "pr-101", "name": "auth-ui", "deps": ["auth-api"] },
-    { "id": "pr-102", "name": "auth-tests", "deps": ["auth-ui"] }
-  ]
-}
-```
-
-**Merge order:**
-
-```
-Layer 0: PR-100
-Layer 1: PR-101
-Layer 2: PR-102
-```
-
-**Tutorial:** [01-simple-stack.md](./tutorials/diffgraph-planner/01-simple-stack.md)
-
-### Example 2: Diamond Pattern (Fan-out/Fan-in)
-
-**Scenario:** UI depends on both auth and API (which are independent).
-
-**PRs:**
-
-- PR-100: Add auth system
-- PR-101: Add API endpoints
-- PR-102: Add UI (depends on both PR-100 and PR-101)
-
-**Dependencies:**
-
-```
-    PR-102 (UI)
-    /        \
-PR-100    PR-101
-(auth)    (API)
-```
-
-**Plan:**
-
-```json
-{
-  "items": [
-    { "id": "pr-100", "name": "auth", "deps": [] },
-    { "id": "pr-101", "name": "api", "deps": [] },
-    { "id": "pr-102", "name": "ui", "deps": ["auth", "api"] }
-  ]
-}
-```
-
-**Merge order:**
-
-```
-Layer 0: PR-100, PR-101 (parallel)
-Layer 1: PR-102
-```
-
-**Tutorial:** [02-diamond-pattern.md](./tutorials/diffgraph-planner/02-diamond-pattern.md)
-
-### Example 3: Large Batch (20+ PRs)
-
-**Scenario:** Major refactor with 20 PRs, mixed explicit and implicit dependencies.
-
-**Approach:**
-
-1. Generate suggestions: `lex-pr plan --suggest-deps --threshold=0.7`
-2. Review high-confidence suggestions
-3. Add explicit deps to PR descriptions
-4. Generate final plan: `lex-pr plan --from-github`
-
-**Result:** Complex graph with 5-7 layers, parallel execution within each layer.
-
-**Tutorial:** [03-large-batch.md](./tutorials/diffgraph-planner/03-large-batch.md)
-
-### Example 4: Cycle Error (Before/After Fix)
-
-**Before (error):**
-
-```
-PR-100: Depends-on: #102
-PR-101: Depends-on: #100
-PR-102: Depends-on: #101
-
-❌ Cycle detected: PR-100 → PR-102 → PR-101 → PR-100
-```
-
-**Fix:** Remove weakest dependency (PR-100 → PR-102).
-
-**After (valid):**
-
-```
-PR-100: (no dependencies)
-PR-101: Depends-on: #100
-PR-102: Depends-on: #101
-
-✓ Valid: 3 nodes, 2 edges, 3 layers
-```
-
-**Tutorial:** [04-fixing-cycles.md](./tutorials/diffgraph-planner/04-fixing-cycles.md)
-
-### Example 5: Mixed Explicit + Implicit
-
-**Scenario:** Some PRs have explicit deps, others rely on file-based suggestions.
-
-**PRs:**
-
-- PR-100: Explicit: `Depends-on: #99`
-- PR-101: No explicit deps, but modifies same files as PR-100
-- PR-102: Explicit: `Depends-on: #101`
-
-**Suggestions:**
-
-```
-PR-101 → PR-100 (0.95 confidence, shared files)
-```
-
-**Workflow:**
-
-1. Review suggestion
-2. Add to PR-101: `Depends-on: #100`
-3. Regenerate plan
-
-**Tutorial:** [05-hybrid-workflow.md](./tutorials/diffgraph-planner/05-hybrid-workflow.md)
-
----
-
-## Related Documentation
-
-- **[Dependency Parser](./dependency-parser.md)** - Detailed parser documentation
-- **[Troubleshooting Planner](./troubleshooting-planner.md)** - Common errors and solutions
-- **[CLI Reference](./cli.md)** - Complete CLI documentation
-- **[Quickstart Guide](./quickstart.md)** - Initial setup and configuration
-- **[Tutorials](./tutorials/diffgraph-planner/)** - Step-by-step tutorials
-
-## Feedback and Support
-
-- **Issues:** [GitHub Issues](https://github.com/Guffawaffle/LexRunner/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/Guffawaffle/LexRunner/discussions)
-- **Epic:** [#75 - Diffgraph Planner & Dependency Auto-Discovery](https://github.com/Guffawaffle/LexRunner/issues/75)