@smartergpt/lexrunner 1.0.0

package/docs/dogfood/README.md

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

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

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