@smartergpt/lexrunner 1.0.0 → 1.2.1

package/docs/tutorials/video-scripts/02-understanding-dependencies.md

@@ -1,376 +0,0 @@
-# Video Script: Understanding Dependencies
-
-**Duration:** 8 minutes  
-**Target Audience:** Developers working with PR stacks  
-**Prerequisites:** Basic lexrunner knowledge (Getting Started video)
-
-## Setup
-
-**Demo Repository:** `lex-pr-demo`  
-**Sample PRs:** 4 dependent PRs forming a stack
-
----
-
-## Script
-
-### Introduction (0:00 - 0:30)
-
-**[Screen: Title slide with dependency graph visualization]**
-
-> "Welcome back! In this video, you'll learn how to manage PR dependencies with lexrunner. We'll cover dependency syntax, merge order computation, and how to handle complex PR stacks."
-
-**[Screen: Show outline]**
-
-- Dependency syntax
-- Merge order
-- PR stacks
-- Troubleshooting
-
----
-
-### Why Dependencies Matter (0:30 - 1:30)
-
-**[Screen: Split screen - manual vs automated]**
-
-> "Let's say you're building a new feature across 4 PRs. Without dependency management, you'd merge them manually, one by one, waiting for CI each time. This takes 30+ minutes."
-
-**[Animation: Show PRs being merged sequentially with waiting time]**
-
-> "With lexrunner, you declare dependencies once, and the tool handles the merge order automatically. Same 4 PRs, merged in 5 minutes."
-
-**[Animation: Show automatic dependency resolution and parallel execution]**
-
----
-
-### Dependency Syntax (1:30 - 3:00)
-
-**[Screen: Terminal with PR body editor]**
-
-> "Declaring dependencies is simple. In your PR description, add a 'Depends-On' line with the PR number."
-
-```markdown
-## Description
-
-This PR adds user authentication.
-
-## Dependencies
-
-Depends-On: #101
-```
-
-**[Annotation: Highlight the syntax]**
-
-> "The syntax is strict: 'Depends-On' followed by colon, space, hash, and the PR number. Let me show you common mistakes."
-
-**[Screen: Show incorrect examples with X marks]**
-
-```markdown
-# ❌ Wrong
-
-Requires: #101
-Needs: #101
-depends on #101
-Depends-On #101
-
-# ✅ Correct
-
-Depends-On: #101
-```
-
-> "Case-sensitive, exact match. Save yourself debugging time - use the correct syntax."
-
----
-
-### Creating a PR Stack (3:00 - 4:30)
-
-**[Screen: Terminal]**
-
-> "Let's create a real PR stack. Imagine refactoring the database layer in 4 steps."
-
-```bash
-# Create base PR
-$ gh pr create \
-  --title "Part 1: Database schema" \
-  --body "Foundation for refactoring"
-
-Created pull request #101
-
-# Create dependent PR
-$ gh pr create \
-  --title "Part 2: Repository layer" \
-  --body "Depends-On: #101"
-
-Created pull request #102
-```
-
-**[Annotation: Show dependency arrow from #102 to #101]**
-
-> "Now PR #102 depends on #101. Let's continue the stack."
-
-```bash
-# Add more dependencies
-$ gh pr create \
-  --title "Part 3: Service layer" \
-  --body "Depends-On: #102"
-
-$ gh pr create \
-  --title "Part 4: API endpoints" \
-  --body "Depends-On: #103"
-```
-
-**[Animation: Show complete dependency chain]**
-
-> "We have a 4-PR stack: 101 → 102 → 103 → 104"
-
----
-
-### Computing Merge Order (4:30 - 5:30)
-
-**[Screen: Terminal]**
-
-> "Now let's see how lexrunner computes the merge order."
-
-```bash
-$ lex-pr plan --from-github
-```
-
-**[Annotation: Highlight plan generation output]**
-
-```
-✓ Generated merge plan
-  - Detected 4 PRs
-  - Computed dependency graph
-  - Calculated merge order
-```
-
-> "The plan.json file now contains the dependency graph. Let's visualize it."
-
-```bash
-$ lex-pr merge-order plan.json
-```
-
-**[Annotation: Show merge order output]**
-
-```
-Merge order for 4 items:
-Level 0: database-schema
-Level 1: repository-layer
-Level 2: service-layer
-Level 3: api-endpoints
-```
-
-> "Perfect! The tool computed the correct order. Level 0 first, then level 1, and so on."
-
----
-
-### Multiple Dependencies (5:30 - 6:30)
-
-**[Screen: Diagram showing diamond dependency]**
-
-> "What about complex dependencies? Let's say PR #105 depends on both #102 and #103."
-
-```markdown
-<!-- In PR #105 -->
-
-Depends-On: #102
-Depends-On: #103
-```
-
-**[Animation: Show dependency graph with diamond shape]**
-
-> "lexrunner handles this automatically. It waits for both #102 and #103 to merge before merging #105."
-
-```bash
-$ lex-pr merge-order plan.json
-```
-
-**[Annotation: Show computed order]**
-
-```
-Level 0: database-schema
-Level 1: repository-layer
-Level 2: service-layer
-Level 3: api-endpoints, complex-feature
-```
-
-> "Notice #105 is at the same level as #104. They can merge in parallel since they have no dependencies between them."
-
----
-
-### Common Issues (6:30 - 7:30)
-
-**[Screen: Terminal with error message]**
-
-> "Let's troubleshoot common dependency issues."
-
-**Issue 1: Circular Dependencies**
-
-```bash
-$ lex-pr plan --from-github
-
-❌ Error: Cycle detected in dependency graph
-   PR #201 → #202 → #203 → #201
-```
-
-**[Animation: Show cycle highlighted]**
-
-> "Circular dependencies are impossible to resolve. Break the cycle by removing one dependency."
-
-**Issue 2: Unknown Dependency**
-
-```bash
-❌ Error: Unknown dependency: #999
-   PR #204 depends on non-existent PR #999
-```
-
-> "Check for typos in PR numbers. The PR must exist and be open."
-
-**Issue 3: Case Sensitivity**
-
-```markdown
-# In PR body
-
-depends-on: #101 ❌
-Depends-On: #101 ✅
-```
-
-> "Remember: exact case matters. 'Depends-On' with capital D and O."
-
----
-
-### Best Practices (7:30 - 8:00)
-
-**[Screen: Checklist]**
-
-> "Here are best practices for managing dependencies:"
-
-1. **Keep stacks short** - 3-5 PRs maximum
-2. **Document why** - Explain dependency in PR body
-3. **Test locally** - Verify each PR builds independently
-4. **Merge frequently** - Don't let stacks grow stale
-
-**[Screen: Summary]**
-
-> "You now know how to:"
-
-- ✓ Declare dependencies with correct syntax
-- ✓ Create PR stacks
-- ✓ Understand merge order
-- ✓ Troubleshoot common issues
-
-> "Next video: Quality Gates. See you there!"
-
-**[End screen with links]**
-
----
-
-## B-Roll Suggestions
-
-- Animated dependency graphs
-- Time-lapse of CI pipeline
-- Visual diff of merge order
-- Real codebase example
-
-## Code Examples to Prepare
-
-### Simple Linear Stack
-
-```bash
-# 3 PRs in sequence
-gh pr create --title "PR1" --body "Base"
-gh pr create --title "PR2" --body "Depends-On: #PR1"
-gh pr create --title "PR3" --body "Depends-On: #PR2"
-```
-
-### Diamond Dependency
-
-```bash
-# PR4 depends on both PR2 and PR3
-gh pr create --title "PR4" --body "Depends-On: #PR2\nDepends-On: #PR3"
-```
-
-### Complex Graph
-
-```bash
-# Multiple independent and dependent branches
-# (Prepare diagram)
-```
-
-## Interactive Elements
-
-### Pause Points
-
-1. After syntax explanation (1:30)
-   - "Pause here and try creating your first dependent PR"
-
-2. After merge order computation (5:30)
-   - "Pause and run merge-order on your own plan"
-
-3. After troubleshooting (7:30)
-   - "Pause and check your PR bodies for correct syntax"
-
-### On-Screen Annotations
-
-- Highlight dependency syntax in green ✅
-- Show errors in red with explanations ❌
-- Use arrows to show dependencies →
-- Box important commands
-
-## Accessibility
-
-### Captions
-
-```
-[Terminal shows: lex-pr plan --from-github]
-[Narrator: The plan.json file now contains the dependency graph]
-[Diagram appears showing PR #101 pointing to PR #102]
-```
-
-### Screen Reader Support
-
-- Describe all visual graphs verbally
-- Read command outputs aloud
-- Explain diagram relationships
-
-## Post-Production
-
-### Editing Checklist
-
-- [ ] Remove long pauses (>2 seconds)
-- [ ] Add smooth transitions between sections
-- [ ] Color-code syntax highlighting
-- [ ] Sync audio with visual cues
-- [ ] Add chapter markers at each section
-
-### Export Settings
-
-- Format: MP4 (H.264)
-- Resolution: 1080p
-- Bitrate: 8 Mbps
-- Audio: AAC, 192 kbps
-
-## Companion Resources
-
-### GitHub Gist
-
-Create gist with:
-
-- Full command reference
-- Syntax cheat sheet
-- Troubleshooting flowchart
-- Example PR bodies
-
-### Interactive Quiz
-
-1. What's the correct dependency syntax?
-2. How do you handle circular dependencies?
-3. Can a PR depend on multiple other PRs?
-
-### Sample Repository
-
-Provide fork-able repo with:
-
-- Example PR stack
-- Configured lexrunner
-- Sample gates
-- README with exercises

package/docs/weave-contract.md

@@ -1,116 +0,0 @@
-# Weave Contract (v0.2)
-
-**Goal:** integrate as many PRs as possible into the integration branch in one pass, resolving conflicts proactively. Only skip when a clean, test-passing reconciliation can't be produced.
-
-## Attempt order
-
-1. Trivial merges (no overlap).
-2. Mechanical weaves (safe, rule-based transforms).
-3. Semantic weaves (small, explicit reconciliation commits).
-4. If 1–3 fail → mark **Skipped: conflict**.
-
-## Hard gates (non-negotiable)
-
-- Existing tests must pass (hard fail).
-- No disabling tests, no relaxing lints/types to "make it green."
-- Determinism check at the end: build + format → zero diff.
-- **Rollback guard**: If determinism check fails after merges, revert the last weave commit(s) and mark PRs as `needs-manual-weave`.
-
-## Mechanical weave rules (safe auto-fixes)
-
-- **Formatting-only conflicts** → reformat repository and re-stage.
-- **Configuration files** (package.json, pyproject.toml, Cargo.toml, pom.xml, etc.):
-  - **Deterministic unions**: Sort all keys alphabetically; maintain stable trailing newline.
-  - **Key collisions**: When both change the same key, prefer the stricter/safer setting; if incomparable, keep superset + document in integration PR.
-  - **Dependency versions**: prefer highest compatible in-range; regenerate dependency lockfiles with **pinned toolchain**.
-  - **Build/task scripts**: Union all scripts with alphabetical sorting. If same key differs:
-    - Try safe composition as `<existing> && <new>` (alphabetical by script name); if order matters, keep both with `:pr-<number>` suffixes.
-    - If truly divergent: keep both with suffixed names (`taskName:pr-<number>`) and comment noting source PRs.
-- **Generated artifacts** (schemas, API docs, type definitions, compiled assets) → re-generate from source, not hand-merged.
-- **Documentation merges**:
-  - Unify headings where possible; keep both bodies under single heading with sub-sections.
-  - Preserve author attributions; ensure navigation/TOC renders cleanly.
-- **Interface/API additions**:
-  - **Back-compat first**: accept both if no naming collision.
-  - **Name collisions with different meanings** → add alias/adapter, mark one as "compat" in documentation.
-  - Must update documentation when adding compatibility layers + include integration tests for all entry points.
-
-If mechanical rules resolve the conflict and gates pass → **Merged (mechanical)**.
-
-## Semantic weave (narrow, auditable)
-
-- **Allowed**: ≤30 LOC across ≤3 files, no behavior changes outside conflict scope.
-  - Examples: reconcile renamed functions/methods, add overloads, widen types, adapt parameters, update imports.
-- **Not allowed**: behavior changes outside conflict scope, feature toggles, or removing someone's change.
-- **Required commit format**: `Weave: reconcile #X + #Y — <short reason>`
-  - **Body**: List of files touched + rationale.
-  - **Trailers**: `Co-authored-by` for both PR authors.
-  - **Example**:
-
-    ```
-    Weave: reconcile #123 + #456 — function rename + caller update
-
-    Files: src/module.{ext}, tests/module_test.{ext}
-    Reason: PR #123 renamed processData → handleData; PR #456 added new caller
-
-    Co-authored-by: Alice <alice@example.com>
-    Co-authored-by: Bob <bob@example.com>
-    ```
-
-- **Exception handling**: Any semantic weave exceeding bounds must be labeled `weave:exception` and approved by a maintainer before merge.
-
-If gates pass → **Merged (semantic)**.
-
-## Skip criteria
-
-Skip only when both of these are true:
-
-- Mechanical rules can't produce a clean index **and** a minimal semantic patch would exceed the "tiny glue" boundary.
-- Or, gates remain red after a semantic attempt (tests fail).
-
-Mark **Skipped: conflict** or **Skipped: tests**, label the source PRs, and post a concise comment: what we tried, why it failed, and what's needed (e.g., "rebase onto integration branch" or "resolve semantic conflict in core module").
-
-## Reporting (integration PR body)
-
-**Integration PR Matrix** (required):
-
-```
-| PR | Status | Details | Weave Commit |
-|----|--------|---------|-------------|
-| #123 | Merged | Clean merge | - |
-| #124 | Merged (mechanical) | package.json union, lockfile regen | - |
-| #125 | Merged (semantic) | Import reconciliation | abc1234 |
-| #126 | Skipped (conflict) | Manual rebase needed | - |
-| #127 | Skipped (tests) | Tests failed after weave | def5678 |
-```
-
-Integration PR **must** include this matrix and attach plan/order/gate logs. For Skipped (tests), the weave commit is optional.
-
-**PR Labeling** (automated):
-
-- `weave:mechanical` - Applied mechanical rules
-- `weave:semantic` - Required semantic patch
-- `weave:exception` - Bounds exceeded, maintainer approved
-- `needs-manual-weave` - Conflicts exceed weave bounds
-- `needs-rebase` - Clean rebase will resolve
-
-**Bot Comments** on affected PRs:
-
-- What rule applied ("mechanical: config file key union" or "semantic: function signature reconciliation")
-- What's needed ("rebase onto integration branch" or "resolve semantic conflict in core module")
-
-**Attachments**: plan + order + gate logs + weave commit SHAs for audit trail.## Toolchain alignment (determinism prerequisite)
-
-- **Lockfile stability**: Requires pinned toolchain versions between local and CI environments.
-- **Required specification**: Version pinning appropriate to ecosystem (package.json engines, .python-version, .ruby-version, .go-version, etc.).
-- **Verification**: Validation tooling must ensure local toolchain matches CI specification.
-- **Pre-regeneration check**: Verify tool versions match CI (doctor step) or abort; do not regenerate lockfiles under mismatched toolchains.
-- **Regeneration**: Only regenerate dependency lockfiles with verified matching toolchain.
-
-## Risk guardrails
-
-- Never delete user code to resolve conflicts.
-- Never change repository policy files (linters, type checkers, security configs) to loosen checks.
-- Limit semantic weaves to localized, reversible patches; anything broader should bounce back to the source PR.
-- **Semantic bounds**: Enforce ≤30 LOC, ≤3 files limit strictly; exceeding bounds → skip with `needs-manual-weave` label.
-- **Ecosystem respect**: Follow language-specific best practices for conflict resolution (e.g., import organization, dependency ranges, build tool conventions).

package/docs/weave-execution-log.md

@@ -1,153 +0,0 @@
-# Merge-Weave Execution Log: PR-70 + PR-71
-
-**Date**: 2025-10-01
-**Branch**: `merge-weave`
-**PRs**: #70 (Enforce write discipline) + #71 (Local overlay setup)
-**Target**: main
-
----
-
-## Pre-Execution Summary
-
-### Plan Generation ✅
-
-- **Command**: `npm run cli -- plan --from-github --query "is:open is:pr" --out .smartergpt/runner`
-- **Result**: Successfully generated plan.json with 2 items
-- **Schema**: v1.0.0
-- **Target**: main
-- **Policy**: requiredGates: [lint, typecheck, test], maxWorkers: 2
-
-### Merge Order Computation ✅
-
-- **Command**: `npm run cli -- merge-order --plan .smartergpt/runner/plan.json --json`
-- **Result**: Single level `[["PR-70", "PR-71"]]`
-- **Analysis**: PRs are independent (no dependencies)
-
-### Conflict Analysis ✅
-
-**File Overlap**:
-
-- `src/cli.ts`: Import conflicts (mechanical weave)
-- `src/mcp/server.ts`: Import conflicts + additive changes (mechanical weave)
-- 9 other files: No overlap (trivial merge)
-
-**Predicted Weave Distribution**:
-
-- Trivial: 9 files
-- Mechanical: 2 files
-- Semantic: 0 files
-
-**Risk Level**: LOW
-
----
-
-## Issues Found & Fixed During Weave
-
-### Issue #1: ESM Module Import Resolution
-
-**Problem**: `PRQueryOptions` import failing in `src/github/client.ts`
-**Root Cause**: Mixed type and value imports causing ESM resolution issues in Node.js v22
-**Fix**: Separated `import type` for interfaces from value imports for classes
-**Commit**: `86d7653` - "Fix: separate type and value imports in GitHub client"
-**Status**: ✅ RESOLVED
-
-### Issue #2: Basic Merge Command Implementation
-
-**Problem**: Current `merge` command is a placeholder (dry-run only shows plan)
-**Analysis**: Doesn't actually execute git operations or detect real conflicts
-**Impact**: Cannot test actual weave execution yet
-**Status**: 🔄 IDENTIFIED (needs implementation)
-
-### Issue #3: Runtime Artifacts in .gitignore
-
-**Problem**: `.smartergpt/runner/` is git-ignored (by design)
-**Analysis**: Follows two-track separation principle - runtime artifacts shouldn't be committed
-**Resolution**: Create weave documentation in `docs/` instead
-**Status**: ✅ WORKING AS DESIGNED
-
----
-
-## Next Steps
-
-1. ⏳ Implement or enhance merge command to:
-   - Actually checkout PR branches
-   - Attempt git merge operations
-   - Detect and classify conflicts
-   - Apply weave contract rules
-
-2. ⏳ Execute actual weave (not just dry-run)
-
-3. ⏳ Run gates on woven result
-
-4. ⏳ Create integration PR with proper reporting
-
----
-
-## Findings & Improvement Opportunities
-
-### Tool Gaps Identified
-
-1. **Merge Execution Engine**: Need full implementation of weave contract
-   - Trivial merge detection
-   - Mechanical rule application (import unions, config merges)
-   - Semantic patch generation
-   - Conflict classification
-
-2. **Conflict Resolution Tooling**: Automate mechanical rules
-   - Import statement merging with deterministic sorting
-   - Config file union operations
-   - Dependency lockfile regeneration
-
-3. **Gate Integration**: Run gates automatically during weave
-   - After each merge attempt
-   - Rollback on failure
-   - Artifact collection
-
-4. **Reporting**: Generate weave matrix automatically
-   - Track which strategy was used per file
-   - Record weave commit SHAs
-   - Link to gate results
-
-### Documentation Needs
-
-1. ✅ Add conflict analysis template
-2. ✅ Document ESM import patterns for future reference
-3. ⏳ Create weave execution playbook
-4. ⏳ Add troubleshooting guide for common weave failures
-
----
-
-## Execution Complete ✅
-
-### Integration PR Created
-
-- **URL**: https://github.com/Guffawaffle/LexRunner/pull/72
-- **Title**: Integration PR: Merge-Weave PR-70 + PR-71
-- **Status**: Ready for review and merge
-
-### Final Results
-
-- **PRs Integrated**: 2/2 (100% success rate)
-- **Weave Distribution**: 1 trivial + 1 mechanical (0 semantic needed)
-- **Gate Results**: ALL PASS ✅ (262/262 tests)
-- **Determinism**: CLEAN ✅
-- **Risk Assessment**: Confirmed LOW (as predicted)
-
----
-
-## Meta-Recursive Success 🎯
-
-**We successfully dogfooded lexrunner's own weave process!**
-
-This execution demonstrates that:
-
-1. The GitHub plan generation works correctly
-2. Merge order computation handles independent PRs properly
-3. Conflict analysis predictions were accurate (mechanical weave needed)
-4. Manual weave execution follows the contract successfully
-5. All gates integrate properly with woven results
-6. Integration PR reporting meets the weave contract requirements
-
----
-
-_Execution complete. Process documented for future iterations and tooling improvements._