@smartergpt/lexrunner 1.0.0

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

@@ -0,0 +1,376 @@
+# 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

@@ -0,0 +1,116 @@
+# 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

@@ -0,0 +1,153 @@
+# 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._