@smartergpt/lexrunner 1.0.0 → 1.2.1

package/docs/dogfood/README.md

@@ -1,33 +0,0 @@
-# Dogfood Results
-
-This directory contains results and observations from dogfooding the merge-weave workflow.
-
-## Waves
-
-- **[Wave 3](./wave-3-results.md)** (January 2, 2026) - 4 PRs, 100% success rate, identified auto-undraft and auto-update opportunities
-
-## Purpose
-
-These documents serve to:
-
-1. Track merge-weave workflow improvements over time
-2. Document automation opportunities discovered during execution
-3. Validate Copilot agent quality
-4. Guide future enhancements to the workflow
-
-## Metrics Tracked
-
-Each wave documents:
-
-- Number of PRs
-- Build/test success rates
-- Manual interventions required
-- Code quality metrics
-- Time savings from automation
-- Lessons learned
-
-## Related Docs
-
-- [Merge-Weave Quickstart](../merge-weave-quickstart.md)
-- [Merge-Weave Setup](../MERGE_WEAVE_SETUP.md)
-- [Policy Schema](../../.smartergpt/merge-weave-policy.yml)

package/docs/dogfood/wave-3-results.md

@@ -1,303 +0,0 @@
-# Wave 3 Merge-Weave Dogfood Results
-
-**Date:** January 2, 2026  
-**Executor:** Senior Dev (Copilot)  
-**Scope:** 4 issues → 4 PRs across lexrunner and lex repos
-
----
-
-## Executive Summary
-
-Wave 3 demonstrated **excellent Copilot agent quality** with **100% success rate**:
-
-- ✅ All 4 PRs built successfully on first try
-- ✅ All tests passed (4558-4559 tests in lexrunner, 123 in lex)
-- ✅ Zero manual fixes required
-- ✅ Comprehensive test coverage and documentation included
-
-**Key Insight:** The Wave 3 workflow revealed two opportunities for automation that were already partially implemented but not fully activated.
-
----
-
-## Wave 3 PRs
-
-| PR                                                        | Repo      | Lines Added | Lines Deleted | Files Changed | New Tests    | Status    |
-| --------------------------------------------------------- | --------- | ----------- | ------------- | ------------- | ------------ | --------- |
-| [#680](https://github.com/Guffawaffle/lexrunner/pull/680) | lexrunner | 1170        | 3             | 10            | 3 test files | ✅ Merged |
-| [#681](https://github.com/Guffawaffle/lexrunner/pull/681) | lexrunner | 1005        | 1             | 8             | 2 test files | ✅ Merged |
-| [#657](https://github.com/Guffawaffle/lex/pull/657)       | lex       | 127         | 97            | 1             | 0 (script)   | ✅ Merged |
-| [#656](https://github.com/Guffawaffle/lex/pull/656)       | lex       | 206         | 28            | 11            | 2 test files | ✅ Merged |
-
----
-
-## Observations & Improvements
-
-### Observation 1: Copilot Agent PRs Stay Draft ✅ RESOLVED
-
-**What happened:**
-
-- Assigned 4 issues to Copilot coding agents
-- All 4 agents completed their work successfully
-- PRs remained in "draft" state, requiring manual undraft
-
-**Root cause:**
-
-- Copilot agents leave PRs as draft after completion
-- D2 executor has `undraft_copilot` handler but wasn't invoked automatically
-
-**Solution implemented:**
-The merge-weave policy already supports auto-undraft via:
-
-\`\`\`yaml
-discovery:
-draft_policy:
-undraft_copilot_prs: true # Auto-undraft Copilot PRs during discovery
-\`\`\`
-
-This setting automatically undrafts Copilot PRs that are in draft state when discovered. The workflow is:
-
-1. Discovery phase finds PRs (including drafts if `include_drafts: true`)
-2. `filter_drafts` intervention filters based on policy
-3. `undraft_copilot` intervention runs for draft Copilot PRs if `undraft_copilot_prs: true`
-4. PRs are automatically promoted to ready for review
-
-**Configuration:**
-
-- Default: `undraft_copilot_prs: true` (enabled)
-- Can be disabled by setting to `false` in merge-weave-policy.yml
-- Copilot PRs are identified by author metadata
-
----
-
-### Observation 2: Branch Update After First Merge ✅ RESOLVED
-
-**What happened:**
-
-- Merged lexrunner#680 (gate attestation)
-- Had to call \`update_pull_request_branch\` for lexrunner#681 before merging
-- Same pattern for lex PRs
-
-**Root cause:**
-
-- After merging first PR, base branch moves forward
-- Subsequent PRs may need branch update before merge
-- No automatic branch update intervention before merge
-
-**Solution implemented:**
-Added `update_pr_branch` intervention (D1 - deterministic) that:
-
-1. Runs before each `execute_merge` intervention
-2. Updates PR branch with latest from base
-3. Prevents merge conflicts from stale branches
-
-**Configuration:**
-
-\`\`\`yaml
-merge:
-auto_update_branch: true # Default: true
-\`\`\`
-
-The planner now creates this intervention sequence for each PR:
-\`\`\`
-check_admin_authority → update_pr_branch → execute_merge
-\`\`\`
-
-**Implementation details:**
-
-- New intervention type: `update_pr_branch` (D1)
-- Handler in `d1-executor.ts`
-- GitHub API method: `updatePullRequestBranch(owner, repo, prNumber)`
-- Skipped if `auto_update_branch: false` in policy
-
----
-
-### Observation 3: Excellent Agent Quality ✅ DOCUMENTED
-
-**Positive findings:**
-All 4 Copilot agent PRs demonstrated:
-
-1. **Build quality**: All built successfully on first try
-   - No syntax errors
-   - No import errors
-   - No configuration issues
-
-2. **Test coverage**: Comprehensive test files included
-   - lexrunner#680: 3 new test files
-   - lexrunner#681: 2 new test files
-   - lex#656: 2 new test files
-   - lex#657: Script-based (no unit tests needed)
-
-3. **Test pass rate**: 100%
-   - lexrunner: 4558-4559 tests passing
-   - lex: 123 tests passing
-   - Zero flaky tests
-   - Zero manual fixes needed
-
-4. **Documentation**: All PRs included
-   - Updated README files where relevant
-   - Inline code comments
-   - Type definitions
-   - Usage examples
-
-**Quality metrics:**
-
-| Metric                | Value      |
-| --------------------- | ---------- |
-| Build success rate    | 100% (4/4) |
-| Test pass rate        | 100% (4/4) |
-| Manual fixes required | 0          |
-| Files changed (total) | 30         |
-| Lines added (total)   | 2,508      |
-| Lines deleted (total) | 129        |
-| Net addition          | +2,379 LOC |
-
----
-
-## Workflow Improvements Applied
-
-### 1. Auto-undraft Copilot PRs
-
-**Before:** Manual API call required to undraft each PR
-\`\`\`bash
-
-# Manual undraft (before)
-
-gh pr ready 680
-gh pr ready 681
-gh pr ready 657
-gh pr ready 656
-\`\`\`
-
-**After:** Automatic undraft during discovery phase
-\`\`\`yaml
-
-# merge-weave-policy.yml
-
-discovery:
-draft_policy:
-undraft_copilot_prs: true
-\`\`\`
-
-### 2. Auto-update PR branches
-
-**Before:** Manual branch update after each merge
-\`\`\`bash
-
-# Manual update (before)
-
-gh pr update-branch 681 # After merging 680
-gh pr update-branch 657 # After merging 656
-\`\`\`
-
-**After:** Automatic update before merge
-\`\`\`yaml
-
-# merge-weave-policy.yml
-
-merge:
-auto_update_branch: true
-\`\`\`
-
----
-
-## Impact Analysis
-
-### Time Saved
-
-**Manual operations eliminated:**
-
-- 4 × manual undraft = ~2 minutes saved
-- 3 × manual branch update = ~3 minutes saved
-- Total: ~5 minutes per wave
-
-**Automation benefits:**
-
-- Reduced manual API calls
-- Fewer context switches
-- Lower error rate
-- More deterministic workflow
-
-### Code Quality
-
-**Agent performance:**
-
-- Zero build failures
-- Zero test failures
-- Zero manual corrections
-- Comprehensive test coverage
-
-**Maintainability:**
-
-- Tests verify behavior
-- Documentation up to date
-- Type safety preserved
-- Patterns consistent with codebase
-
----
-
-## Related Work
-
-- **D2 executor**: Implemented in lexrunner#679 (already merged before Wave 3)
-- **Agent stall detection**: Tracked in lexrunner#685
-- **Policy schema**: Updated to support auto-undraft and auto-update
-
----
-
-## Lessons Learned
-
-1. **Copilot agent quality is production-ready**
-   - No quality gate failures
-   - Comprehensive test coverage
-   - Documentation included
-   - Build-test-merge ready
-
-2. **Automation opportunities exist in workflow**
-   - Draft PR handling
-   - Branch updates
-   - Both already partially implemented
-
-3. **Policy-driven behavior is effective**
-   - Single source of truth (merge-weave-policy.yml)
-   - Deterministic execution
-   - Easy to configure
-
-4. **Intervention model scales well**
-   - D1 (deterministic): update_pr_branch
-   - D2 (bounded judgment): undraft_copilot
-   - Clear separation of concerns
-
----
-
-## Future Work
-
-### Potential Enhancements
-
-1. **Smart branch update detection**
-   - Only update if base has moved forward
-   - Skip if branch is already up-to-date
-   - Report update status in audit log
-
-2. **Draft PR detection improvements**
-   - Detect when agent completes work (all tasks checked)
-   - Auto-undraft when local gates pass
-   - Report readiness criteria in intervention output
-
-3. **Quality gate optimization**
-   - Cache gate results across PRs
-   - Parallel gate execution
-   - Progressive gate failure handling
-
----
-
-## Conclusion
-
-Wave 3 validated the **merge-weave workflow** with **100% success rate** and identified two automation opportunities that were quickly resolved through policy configuration and minimal code changes.
-
-The results demonstrate that:
-
-- Copilot agents produce production-quality PRs
-- The intervention model is effective
-- Policy-driven automation reduces manual work
-- D1/D2/D3 determinism levels guide handoff readiness
-
-**Next wave**: Continue dogfooding with larger PR sets to validate scalability.

package/docs/dogfood-merge-weave-script.md

@@ -1,224 +0,0 @@
-# Dogfood Merge-Weave Script
-
-## Overview
-
-The `scripts/dogfood-merge-weave.sh` script provides a parameterized, repo-agnostic wrapper around `lexrunner` commands for executing merge-weave workflows. It automates the complete workflow from plan generation to merge execution and reporting.
-
-## Features
-
-- **Flexible Plan Sources**: Load from a plan file or discover PRs from GitHub
-- **Parameterized Configuration**: Customize repository path, artifacts location, and execution mode
-- **Automated Workflow**: Runs validation gates, analyzes merge order, and executes merges
-- **Rich Output**: Generates JSON artifacts, markdown reports, and user-friendly console output
-- **Error Handling**: Gracefully handles validation failures and provides clear error messages
-
-## Installation
-
-The script is located at `scripts/dogfood-merge-weave.sh` and requires:
-
-- Bash shell
-- `lexrunner` CLI (installed globally or via npm)
-- `jq` (optional, for enhanced plan summaries)
-
-## Usage
-
-```bash
-./scripts/dogfood-merge-weave.sh [options]
-```
-
-### Options
-
-#### Repository Options
-
-- `--repo <path>` - Path to repository (default: current directory)
-
-#### Plan Source Options (choose one)
-
-- `--plan <path>` - Path to plan.json file
-- `--from-github` - Discover PRs from GitHub using filters
-
-#### GitHub Discovery Options (used with --from-github)
-
-- `--owner <name>` - GitHub repository owner
-- `--repo-name <name>` - GitHub repository name
-- `--base <branch>` - Base branch (default: main)
-- `--labels <labels>` - Comma-separated list of labels to filter PRs
-- `--query <query>` - Custom GitHub search query
-
-#### Output Options
-
-- `--artifacts <dir>` - Artifacts output directory (default: ./artifacts/dogfood-<timestamp>)
-- `--integration-branch <name>` - Custom integration branch name (default: auto-generated)
-
-#### Execution Options
-
-- `--dry-run` - Preview operations without executing (default)
-- `--execute` - Actually perform merge operations
-- `--cleanup` - Clean up integration branches after execution
-- `--verbose` - Enable verbose output
-
-#### Other Options
-
-- `-h, --help` - Show help message
-
-## Examples
-
-### Dry Run with Existing Plan File
-
-Preview merge operations without executing:
-
-```bash
-./scripts/dogfood-merge-weave.sh --plan merge-weave-dogfood.json --dry-run
-```
-
-### Execute from GitHub Discovery
-
-Discover PRs from GitHub and execute merge:
-
-```bash
-./scripts/dogfood-merge-weave.sh \
-  --from-github \
-  --owner myorg \
-  --repo-name myrepo \
-  --labels "ready-to-merge" \
-  --execute
-```
-
-### Execute with Custom Configuration
-
-Use a custom repository and artifacts directory:
-
-```bash
-./scripts/dogfood-merge-weave.sh \
-  --repo /srv/my-project \
-  --plan plan.json \
-  --artifacts ./output/dogfood-run \
-  --execute \
-  --cleanup
-```
-
-### Discover and Preview PRs
-
-Preview PRs from GitHub without merging:
-
-```bash
-./scripts/dogfood-merge-weave.sh \
-  --from-github \
-  --owner octocat \
-  --repo-name hello-world \
-  --base main \
-  --dry-run \
-  --verbose
-```
-
-### Execute with Verbose Output
-
-Get detailed output during execution:
-
-```bash
-./scripts/dogfood-merge-weave.sh \
-  --plan merge-weave-dogfood.json \
-  --execute \
-  --verbose
-```
-
-## Workflow Steps
-
-The script executes the following workflow:
-
-1. **Plan Generation/Validation**
-   - If `--from-github`: Discovers PRs from GitHub and generates plan.json
-   - If `--plan`: Validates existing plan file (continues even if validation fails for older formats)
-
-2. **Gate Validation**
-   - Runs local gates: lint, typecheck
-   - Optionally runs tests (only in execute mode)
-
-3. **Merge Analysis**
-   - Computes merge order and dependencies
-   - Generates merge-order.json artifact
-
-4. **Merge Execution**
-   - Dry-run: Previews merge operations without executing
-   - Execute: Performs actual merge operations
-
-5. **Report Generation**
-   - Generates markdown report with full details
-   - Saves all artifacts to timestamped directory
-
-## Output Artifacts
-
-All artifacts are saved to the artifacts directory (default: `./artifacts/dogfood-<timestamp>/`):
-
-- `plan.json` - Generated plan (if using --from-github)
-- `merge-order.json` - Computed merge order and dependencies
-- `dry-run.json` - Dry-run preview (if in dry-run mode)
-- `merge-results.json` - Merge execution results (if in execute mode)
-- `dogfood-report.md` - Comprehensive markdown report
-
-## Exit Codes
-
-- `0` - Success
-- `1` - Error (missing arguments, invalid configuration, merge failure, etc.)
-
-## Error Handling
-
-The script handles errors gracefully:
-
-- **Schema Validation Failures**: Continues with a warning (useful for older plan formats)
-- **Merge Preview Warnings**: In dry-run mode, continues even if merge preview has warnings
-- **Missing Dependencies**: Checks for required tools and provides clear error messages
-
-## Integration with CI/CD
-
-The script can be used in CI/CD pipelines:
-
-```yaml
-# Example GitHub Actions workflow
-- name: Run dogfood merge-weave
-  run: |
-    ./scripts/dogfood-merge-weave.sh \
-      --from-github \
-      --owner ${{ github.repository_owner }} \
-      --repo-name ${{ github.event.repository.name }} \
-      --labels "auto-merge" \
-      --execute \
-      --cleanup
-```
-
-## Troubleshooting
-
-### Script fails with "lex-pr command not found"
-
-The script automatically falls back to `npm run cli` if `lex-pr` is not in PATH. Ensure you're running from the repository root or install `lexrunner` globally.
-
-### Schema validation failures
-
-The script continues execution even if plan validation fails. This is normal for older plan formats. Check the artifacts directory for detailed error messages.
-
-### Merge conflicts
-
-In execute mode, the script will stop if merge conflicts occur. Resolve conflicts manually and re-run with `--resume` (if supported by the lex-pr merge command).
-
-### Permission denied errors
-
-Ensure the script is executable:
-
-```bash
-chmod +x scripts/dogfood-merge-weave.sh
-```
-
-## Related Documentation
-
-- [Merge Weave Usage Guide](../MERGE_WEAVE_USAGE_GUIDE.md)
-- [lexrunner README](../README.md)
-- [Plan Schema Documentation](../schemas/)
-
-## Contributing
-
-When modifying the script:
-
-1. Update the help text and this documentation
-2. Add test cases in `tests/dogfood-merge-weave-script.spec.ts`
-3. Test with both plan file and GitHub discovery modes
-4. Ensure backward compatibility with existing plan formats