@smartergpt/lexrunner 1.0.0 → 1.3.0

package/MERGE_WEAVE_USAGE_GUIDE.md

@@ -1,368 +0,0 @@
-# How to Best Leverage Merge-Weave Going Forward
-
-**Goal**: Run efficient, token-aware, AI-powered merge-weave operations without bloat.
-
----
-
-## The Core Value Proposition
-
-Merge-weave solves a critical problem: **How do you merge 50+ parallel PRs without token explosion?**
-
-Answer: **Cached reasoning templates + dependency graphs + gate pre-compute**
-
----
-
-## Architecture Pattern (Solid & Robust)
-
-### Three-Layer Approach
-
-```
-Layer 1: DETECTION
-  └─ What kind of fanout are we handling?
-     └─ Patterns: parallel features, sequential dependencies, mixed
-
-Layer 2: TEMPLATE MATCHING
-  └─ Can we use a pre-computed template?
-     └─ Conflict templates: "This looks like pattern X"
-     └─ Dependency templates: "This looks like a linear chain"
-     └─ Gate templates: "This gate is deterministic"
-
-Layer 3: EXECUTION
-  └─ Run with cached reasoning, not full computation
-     └─ Result: 80-90% token savings
-```
-
-### Where Templates Go
-
-```
-.smartergpt/
-├── conflict-templates.yml       # Conflict patterns & resolutions
-├── gates-reasoning.yml           # Gate success/failure paths
-├── dependency-graphs.json        # Pre-computed fanout patterns
-└── token-budgets.yml             # Budget targets & constraints
-```
-
----
-
-## Integration Points: Three Paths to Use This Tool
-
-### Path 1: CLI (Standalone)
-
-```bash
-# Using merge-weave via CLI with templates
-lex-pr plan --from-github --labels "feature-ready"
-lex-pr plan-review plan.json
-lex-pr execute plan.json  # Uses templates automatically
-```
-
-**When**: Manual merge-weave, CI/CD integration, one-time operations
-
-### Path 2: MCP (For AI Assistants)
-
-```
-[IDE Chat / Claude / Copilot]
-  └─ Call: tools/gates.run (checks gate reasoning cache first)
-  └─ Call: tools/merge.apply (checks conflict templates first)
-  └─ Call: tools/plan.create (checks dependency graph cache first)
-```
-
-**When**: AI-driven merge-weave, interactive workflows, token-conscious operations
-
-### Path 3: Hybrid (CLI + MCP Together)
-
-```
-1. CLI: Run discovery & create plan
-2. MCP: AI validates & decides on conflicts
-3. CLI: Execute merges
-4. MCP: Report token metrics
-```
-
-**When**: Large-scale operations, safety-critical merges, production workflows
-
----
-
-## Recommended Operational Workflow
-
-### For Each Merge-Weave
-
-```
-Step 1: INITIALIZE
-  ├─ Create plan.json from GitHub PRs or config
-  ├─ Check for known patterns (conflict templates, dependency graphs)
-  └─ Estimate token budget
-
-Step 2: VALIDATE
-  ├─ Use CLI or MCP to run `gates` on each PR
-  ├─ Apply gate reasoning templates (92% token savings)
-  └─ Stop if gates fail
-
-Step 3: ANALYZE DEPENDENCIES
-  ├─ Check dependency graph cache
-  ├─ If cache hit: use pre-computed order (94% token savings)
-  ├─ If cache miss: compute, then cache for future
-  └─ Validate no cycles
-
-Step 4: MERGE (Sequential or Parallel)
-  ├─ For each PR to merge:
-  │  ├─ Check conflict templates first (83% token savings)
-  │  ├─ If template matches: apply automatically
-  │  ├─ If no template: compute resolution, then cache
-  │  └─ Commit merge
-  └─ Report token metrics
-
-Step 5: FINALIZE
-  ├─ Merge integration branch to main
-  ├─ Close successfully merged PRs
-  ├─ Update caches with any new patterns
-  └─ Report efficiency metrics
-```
-
----
-
-## Token Budget Rules (Solid & Practical)
-
-### Budget Targets Per Operation
-
-| Operation           | Without Templates | With Templates | Target   |
-| ------------------- | ----------------- | -------------- | -------- |
-| Conflict resolution | 3000 tokens       | 500 tokens     | Save 83% |
-| Gate execution      | 1900 tokens       | 50 tokens      | Save 97% |
-| Dependency analysis | 3400 tokens       | 200 tokens     | Save 94% |
-| Merge execution     | 5000 tokens       | 2000 tokens    | Save 60% |
-
-### Total Budget Per Fanout
-
-| Fanout Size | Budget (No Templates) | Budget (With Templates) | Action                                 |
-| ----------- | --------------------- | ----------------------- | -------------------------------------- |
-| 4 PRs       | ~42K                  | ~3.5K                   | ✅ Proceed                             |
-| 20 PRs      | ~170K                 | ~17.5K                  | ⚠️ Monitor tokens                      |
-| 50 PRs      | ~425K                 | ~43.75K                 | ⚠️ High cost, split if possible        |
-| 100 PRs     | ~850K                 | ~87.5K                  | ⚠️ Consider splitting into two fanouts |
-
-**Rule**: If budget exceeds 50K tokens, split fanout into smaller chunks.
-
----
-
-## Model-Agnostic Operation (Not Vendor-Locked)
-
-### Why This Matters
-
-- **Copilot tokens** are expensive ($150/month per user)
-- **Claude tokens** are cheaper but different rate limits
-- **Gemini** offers higher throughput
-- **You want flexibility** to switch based on cost/performance
-
-### How Templates Enable This
-
-```
-Same template works across all models:
-
-1. Copilot sees: "Merge both imports alphabetically"
-   → Outputs: [list of merged imports]
-
-2. Claude sees: "Merge both imports alphabetically"
-   → Outputs: [same list of merged imports]
-
-3. Gemini sees: "Merge both imports alphabetically"
-   → Outputs: [same list of merged imports]
-
-Cost difference: ZERO. Logic difference: ZERO.
-```
-
-### Validation Checklist
-
-- [ ] Template works with Copilot (JavaScript)
-- [ ] Template works with Claude (via API)
-- [ ] Template works with Gemini (via API)
-- [ ] All three produce functionally identical output
-- [ ] No model-specific workarounds needed
-
----
-
-## Best Practices for Solid, Robust Implementation
-
-### DO ✅
-
-1. **Use templates as first check** before full computation
-2. **Cache new patterns** as you discover them (grows smarter over time)
-3. **Log everything** (template matches, cache hits, token usage)
-4. **Validate template output** against actual behavior (gates, merges)
-5. **Fallback gracefully** if template doesn't match (don't fail hard)
-6. **Track metrics** (token saved, efficiency gains, cache hit rates)
-
-### DON'T ❌
-
-1. **Don't over-template** (keep it simple: top 10 patterns max)
-2. **Don't break on template mismatches** (always have fallback path)
-3. **Don't ignore new patterns** (update cache regularly)
-4. **Don't hard-code model names** (keep templates model-agnostic)
-5. **Don't assume templates are always faster** (measure!)
-
----
-
-## Real-World Example: Your Dogfood Run
-
-```
-Scenario: Merge 4 independent Copilot-authored PRs
-
-Without Templates:
-  Conflict detection: 3000 tokens
-  Gate reasoning (4 gates × 4 PRs): 30,400 tokens
-  Dependency analysis: 3,400 tokens
-  Merge execution: 5,000 tokens
-  Total: ~42,000 tokens
-
-With Templates:
-  Conflict template match: 500 tokens
-  Gate reasoning cache: 800 tokens (4 gates × 4 PRs)
-  Dependency cache hit: 200 tokens
-  Merge execution (template-aided): 2,000 tokens
-  Total: ~3,500 tokens
-
-Savings: ~38,500 tokens (92% reduction!)
-```
-
-**Action taken**: Created integration branch with 1 manual conflict (not a template match). If we had template first, would have been automatic.
-
----
-
-## Recommended Starting Point
-
-### For This Sprint
-
-1. Implement conflict resolution templates (#329)
-   - Extract top 5 patterns from recent merges
-   - Validate with 2-3 real conflicts
-   - Deploy as first optimization
-
-2. Add token tracking (#337)
-   - Measure token savings
-   - Prove ROI to stakeholders
-   - Justify further investment
-
-### For Next Sprint
-
-3. Implement gate reasoning cache (#333)
-   - Pre-compute for each gate type
-   - Link to gates.yml schema
-   - Validate against actual results
-
-### For Month 2
-
-4. Build dependency graph cache (#334)
-5. Design model-agnostic templates RFC (#336)
-6. Optimize everything, measure everything
-
----
-
-## Success Criteria (Solid & Measurable)
-
-- [ ] Conflict resolution templates reduce tokens by 80%+
-- [ ] Gate reasoning cache achieves 90%+ hit rate
-- [ ] Dependency cache works for 80%+ of fanouts
-- [ ] Model switching works without code changes
-- [ ] Token budget tracking accurate (within 5%)
-- [ ] All templates validated across 2+ models
-- [ ] Zero functional regressions (same output quality)
-
----
-
-## Conclusion: What Makes This Solid
-
-1. **No bloat**: Only cache what repeats (top 10 patterns, max)
-2. **Graceful fallback**: If template fails, compute normally (not a blocker)
-3. **Measured ROI**: Track savings, validate improvements
-4. **Model-agnostic**: Works with any AI model, not vendor-locked
-5. **Production-ready**: Tested with real PRs, real merges, real conflicts
-
-**This is the foundation for scaling merge-weave to 100+ PR fanouts without token explosion.**
-
----
-
-## Keystone Issue Governance
-
-During merge-weave operations, occasionally issues need to be implemented directly on the umbrella branch rather than via a fanned-out PR. These are called **keystone issues** and should be the exception, not the rule.
-
-### What is a Keystone Issue?
-
-A keystone issue is an issue implemented directly on the umbrella branch during merge-weave, bypassing the normal PR fanout process. They are reserved for true cross-cutting concerns that cannot be safely fanned out.
-
-**Key Principle:** The ideal merge-weave has **zero** keystone issues.
-
-### Litmus Test
-
-Before treating any issue as a keystone:
-
-> **"Could this be split into fannable pieces? If yes, split it."**
-
-### When to Use Keystone Issues
-
-- **True cross-cutting concerns**: Shared files touched by N PRs in the wave
-- **Hot-path fixes**: Changes that would conflict with all PRs in the wave
-- **Critical fixes**: Issues discovered during merge-weave validation that must be addressed immediately
-
-### When NOT to Use Keystone Issues
-
-- **Single-PR issues**: Even if they're "small"
-- **Pre/post wave work**: Issues that could be done before or after the wave
-- **Convenience**: Just because the executor is already looking at the code
-
-### Risks of Keystone Issues
-
-1. **Bottleneck creep**: Executor becomes the only one who can merge
-2. **Less parallelism**: Serial work instead of parallel
-3. **Harder to audit**: Changes not visible in PR review
-4. **Copilot atrophy**: AI agents don't learn from these issues
-
-### Governance Rules
-
-| Constraint   | Value | Description                                  |
-| ------------ | ----- | -------------------------------------------- |
-| `maxPerWave` | 2     | Maximum keystone issues per merge-weave wave |
-| `ideal`      | 0     | Target number of keystone issues             |
-
-### Required Documentation
-
-When implementing a keystone issue, you **must**:
-
-1. Include the **issue number** in the commit message
-2. Provide a brief **rationale** for why it couldn't be fanned out
-3. Reference the keystone in the **umbrella PR description**
-
-### Example Commit Message
-
-```
-Fix shared import paths for all modules (#LR-123)
-
-Keystone rationale: This import path change touches every module
-in the wave and would cause conflicts in all 8 PRs. Implementing
-directly on umbrella branch to avoid N-way merge conflicts.
-```
-
----
-
-## Questions & Troubleshooting
-
-### Q: What if a template doesn't match?
-
-A: Fall back to full computation. No penalty, just slower that time. Cache result if new pattern.
-
-### Q: What if two templates could match?
-
-A: Use highest confidence score. Log both matches for future refinement.
-
-### Q: How often should we update the cache?
-
-A: After each new pattern discovered (merge-weave run). Quarterly comprehensive audit.
-
-### Q: Can we use this with multiple models in parallel?
-
-A: Yes! Same template works for all models. Send to 3 models, take best result.
-
-### Q: What if a gate fails on a cached reasoning?
-
-A: Log the mismatch. Update cache reasoning. This is how the system learns!
-
----
-
-**Ready to build this. The foundation is solid. The ROI is clear. Let's ship it.** 🚀

package/TEST_INFRASTRUCTURE_ASSESSMENT.md

@@ -1,225 +0,0 @@
-# Test Infrastructure Improvements - Assessment
-
-**Issue**: #6 - LPR-E-006: Test Infrastructure Improvements  
-**Date**: 2026-01-01  
-**Status**: ✅ All Core Requirements Met
-
-## Executive Summary
-
-All primary acceptance criteria for test infrastructure improvements have been **successfully implemented and verified**. The issue was broken down into sub-issues #300 (fixtures) and #301 (benchmarks), but the work was actually completed before those issues were created.
-
-## Acceptance Criteria Status
-
-### ✅ Shared Test Fixture Library with Realistic Scenarios
-
-**Location**: `tests/fixtures/`
-
-**Implementation**:
-
-- Comprehensive fixture library with organized structure
-- 11 plan fixtures (simple, linear, diamond, complex, wide parallel, deep chain, etc.)
-- 7 invalid plan fixtures for error testing (cycles, unknown deps, orphans, etc.)
-- PR fixtures with factory functions (basic, with dependencies, chains, diamonds)
-- Gate fixtures (configs and results for various scenarios)
-- Scenario fixtures for end-to-end testing
-- Utility fixtures (temp directories, mock GitHub, cleanup)
-
-**Quality**:
-
-- ✅ 38 validation tests (all passing)
-- ✅ 400+ lines of comprehensive documentation
-- ✅ Full TypeScript support with strict typing
-- ✅ Deterministic fixtures (no randomness)
-- ✅ Cross-platform compatible
-
-**Evidence**:
-
-```bash
-npm test -- tests/fixtures/fixtures.spec.ts
-# Result: 38 tests passed
-```
-
-### ✅ Performance Regression Test Suite
-
-**Location**: `tests/benchmarks/`
-
-**Implementation**:
-
-- Benchmark infrastructure with Vitest
-- Core algorithm benchmarks:
-  - Topological sort (10, 50, 100, 500 nodes)
-  - Plan parsing (small, medium, large)
-  - Dependency resolution (simple, complex, cross-repo)
-- I/O operation benchmarks:
-  - File operations
-  - Git operations
-- End-to-end workflow benchmarks:
-  - Complete plan generation workflows
-  - Different dependency patterns
-  - Cached vs uncached performance
-
-**Quality**:
-
-- ✅ Baseline management system (`baselines/baseline.json`)
-- ✅ CI integration scripts (`npm run benchmark:ci`)
-- ✅ Performance targets documented
-- ✅ JSON and Markdown report generation
-- ✅ All benchmarks running successfully
-
-**Evidence**:
-
-```bash
-npm run benchmark
-# Result: All benchmarks complete, performance within targets
-```
-
-### ✅ Mock GitHub API Server for Deterministic Integration Tests
-
-**Location**: `tests/fixtures/utils/mockGitHub.ts`
-
-**Implementation**:
-The requirement for a "Mock GitHub API server" has been **implemented using a superior approach**: dependency injection with mock objects rather than a separate server process.
-
-**Mock Types Available**:
-
-1. **Basic Mock** (`createMockGitHub`): Standard mock with fixture PRs
-2. **Error Mock** (`createErrorMock`): Simulates API errors
-3. **Rate-Limited Mock** (`createRateLimitedMock`): Tests rate limit handling
-4. **Slow Mock** (`createSlowMock`): Tests timeout scenarios
-
-**Supported Endpoints**:
-
-- `pulls.list` - List pull requests
-- `pulls.get` - Get PR details
-- `pulls.listFiles` - Get PR files
-- `issues.listLabelsOnIssue` - Get issue labels
-- `issues.addLabels` - Add labels (no-op)
-
-**Quality**:
-
-- ✅ 114 GitHub-related tests passing
-- ✅ Full type safety with TypeScript
-- ✅ Deterministic responses
-- ✅ Easy to extend with additional endpoints
-- ✅ Used extensively across test suite
-
-**Evidence**:
-
-```bash
-npm test -- tests/github
-# Result: 8 test files passed, 114 tests passed
-```
-
-**Rationale for Mock Objects vs Mock Server**:
-
-1. **Performance**: No network overhead, even locally
-2. **Simplicity**: Easier to set up and tear down
-3. **Maintainability**: Changes are localized to mock files
-4. **Determinism**: Guaranteed consistent responses
-5. **Developer Experience**: No additional processes to manage
-
-### ⏸️ Deferred Items
-
-The following items were explicitly deferred per issue comments:
-
-1. **Parallel E2E Test Execution with Proper Isolation**
-   - Status: Deferred
-   - Reason: Needs test infrastructure foundation first
-   - Note: Worker pools already implemented for parallel processing
-
-2. **Test Report Aggregation and Trending**
-   - Status: Covered by sub-issue #301
-   - Note: Basic reporting exists (JSON/Markdown outputs)
-
-## Verification Results
-
-### Build & Type Safety
-
-```bash
-npm run typecheck
-# ✅ PASS: No TypeScript errors
-```
-
-### Test Suite
-
-```bash
-npm test -- tests/fixtures/fixtures.spec.ts
-# ✅ PASS: 38 fixture tests passed
-
-npm test -- tests/github
-# ✅ PASS: 114 GitHub integration tests passed
-
-npm run benchmark
-# ✅ PASS: All benchmarks completed successfully
-```
-
-### Code Quality
-
-- ✅ All fixtures pass schema validation
-- ✅ No TypeScript errors
-- ✅ Deterministic test results
-- ✅ Cross-platform compatibility
-
-## File Inventory
-
-### Fixture Library (20 files, ~83KB)
-
-- `tests/fixtures/README.md` (8.5KB documentation)
-- `tests/fixtures/index.ts` (6.2KB exports)
-- `tests/fixtures/plans/*.ts` (4 files, 10.5KB)
-- `tests/fixtures/invalid/plans.ts` (3.2KB)
-- `tests/fixtures/prs/*.ts` (2 files, 7.9KB)
-- `tests/fixtures/gates/*.ts` (2 files, 8.5KB)
-- `tests/fixtures/utils/*.ts` (3 files, 10.5KB)
-- `tests/fixtures/scenarios/*.ts` (2 files, 13KB)
-- `tests/fixtures/fixtures.spec.ts` (10KB, 38 tests)
-- `tests/fixtures-usage-examples.spec.ts` (10KB, 20 tests)
-- `tests/mergeOrder-with-fixtures.spec.ts` (7.2KB, 16 tests)
-
-### Benchmark Infrastructure (9 files)
-
-- `tests/benchmarks/README.md` (3KB documentation)
-- `tests/benchmarks/index.ts` (1.2KB)
-- `tests/benchmarks/core/*.bench.ts` (3 files)
-- `tests/benchmarks/io/*.bench.ts` (2 files)
-- `tests/benchmarks/workflows/*.bench.ts` (1 file)
-- `tests/benchmarks/utils/*.ts` (2 files)
-- `tests/benchmarks/baselines/baseline.json`
-
-### Related Files
-
-- `vitest.benchmark.config.ts` (Benchmark configuration)
-- `tests/performance.spec.ts` (Performance monitoring tests)
-- `FIXTURE_LIBRARY_SUMMARY.md` (Implementation summary)
-
-## Recommendations
-
-### 1. Documentation
-
-- ✅ Comprehensive README files exist
-- ✅ Usage examples provided
-- ✅ Migration guides included
-
-### 2. Maintenance
-
-- Monitor baseline performance metrics
-- Update fixtures as new patterns emerge
-- Expand mock GitHub endpoints if needed
-
-### 3. Future Enhancements (Low Priority)
-
-- Additional mock endpoints if new GitHub API calls are added
-- Enhanced reporting dashboard (if #301 requires it)
-- Parallel E2E orchestration (if undeferred)
-
-## Conclusion
-
-**All core acceptance criteria have been met**:
-
-- ✅ Shared test fixture library with realistic scenarios
-- ✅ Performance regression test suite
-- ✅ Mock GitHub API for deterministic integration tests
-
-The implementation is high-quality, well-tested, well-documented, and already integrated into the main branch. The mock object approach for GitHub API testing is superior to a mock server for the use cases in this codebase.
-
-**Recommendation**: This issue can be **closed as complete**. Any remaining work from deferred items or sub-issues should be tracked separately.