@smartergpt/lexrunner 1.0.0 → 1.3.0

package/docs/autopilot-levels.md

@@ -1,368 +0,0 @@
-# Autopilot Levels
-
-The lexrunner supports graduated automation levels (0-4) for merge-weave execution, allowing teams to incrementally adopt automation while maintaining safety and control.
-
-## Overview
-
-Autopilot levels define the degree of automation in merge-weave operations:
-
-| Level | Name                 | Description                           | GitHub Operations    |
-| ----- | -------------------- | ------------------------------------- | -------------------- |
-| 0     | Report Only          | Generate plans and artifacts only     | None                 |
-| 1     | Artifact Generation  | Create integration plans and previews | None                 |
-| 2     | PR Annotations       | Post comments and update status       | Read + Comment       |
-| 3     | Integration Branches | Create branches and open PRs          | Read + Write         |
-| 4     | Full Automation      | Complete end-to-end merge-weave       | Read + Write + Merge |
-
-## Level 0: Report Only
-
-**Purpose**: Safe plan generation and validation without side effects.
-
-**Capabilities**:
-
-- Generate `plan.json` from configuration
-- Validate dependency graphs
-- Compute merge order (topological sort)
-- Create `snapshot.md` with plan summary
-- Run gates and collect results
-- Generate execution reports
-
-**Use Cases**:
-
-- CI/CD validation
-- Development environment testing
-- Plan review before execution
-- Dry-run mode for all operations
-
-**CLI Flags**:
-
-```bash
-lex-pr execute --max-level 0 --dry-run
-lex-pr merge --max-level 0
-```
-
-**Safety**: No GitHub API calls, no git operations, no side effects.
-
-## Level 1: Artifact Generation
-
-**Purpose**: Create detailed execution plans and merge previews.
-
-**Capabilities** (all Level 0 plus):
-
-- Generate integration branch plans
-- Create merge preview artifacts
-- Write detailed execution logs
-- Generate conflict analysis reports
-- Produce gate result summaries
-
-**Use Cases**:
-
-- Pre-merge analysis
-- Integration planning
-- Conflict prediction
-- Artifact archiving for audit
-
-**CLI Flags**:
-
-```bash
-lex-pr execute --max-level 1
-lex-pr merge --max-level 1 --branch-prefix "integration/"
-```
-
-**Safety**: Still no GitHub interactions, only local artifact generation.
-
-## Level 2: PR Annotations
-
-**Purpose**: Provide automated status updates and feedback on PRs.
-
-**Capabilities** (all Level 1 plus):
-
-- Post status comments on PRs
-- Update PR status checks
-- Add labels based on gate results
-- Generate formatted status tables
-- Update PR descriptions with execution status
-
-**Use Cases**:
-
-- Automated PR feedback
-- Status tracking in GitHub
-- Team visibility into gate results
-- Integration with PR workflows
-
-**CLI Flags**:
-
-```bash
-lex-pr execute --max-level 2 --comment-template /path/to/template.md
-lex-pr merge --max-level 2
-```
-
-**GitHub Permissions Required**:
-
-- `pull_requests: read`
-- `pull_requests: write` (for comments)
-- `statuses: write` (for status checks)
-
-**Safety**: Read-only git operations, no merges performed.
-
-## Level 3: Integration Branches
-
-**Purpose**: Automated creation of integration branches and PRs.
-
-**Capabilities** (all Level 2 plus):
-
-- Create integration branches
-- Perform merge operations
-- Open integration PRs with `--open-pr`
-- Run gates on integration branches
-- Update integration PR status
-
-**Use Cases**:
-
-- Automated integration testing
-- Merge preview in real branches
-- Pre-merge validation with full CI
-- Parallel integration attempts
-
-**CLI Flags**:
-
-```bash
-lex-pr merge --max-level 3 --open-pr --branch-prefix "integration/"
-lex-pr execute --max-level 3 --open-pr
-```
-
-**GitHub Permissions Required**:
-
-- All Level 2 permissions
-- `contents: write` (for branch creation)
-- `pull_requests: write` (for PR creation)
-
-**Safety**: Creates branches and PRs but does not finalize merges to target branch.
-
-## Level 4: Full Automation
-
-**Purpose**: Complete end-to-end merge-weave with finalization.
-
-**Capabilities** (all Level 3 plus):
-
-- Finalize successful integrations
-- Merge integration PRs to target branch
-- Close superseded PRs with `--close-superseded`
-- Cleanup integration branches
-- Complete automation pipeline
-
-**Use Cases**:
-
-- Fully automated merge pyramids
-- Continuous integration workflows
-- Scheduled batch processing
-- Production merge automation
-
-**CLI Flags**:
-
-```bash
-lex-pr merge --max-level 4 --open-pr --close-superseded --execute
-lex-pr execute --max-level 4 --close-superseded
-```
-
-**GitHub Permissions Required**:
-
-- All Level 3 permissions
-- `contents: write` (for merging)
-- `pull_requests: write` (for closing PRs)
-
-**Safety**: Full automation. Use with caution and ensure proper testing at lower levels first.
-
-## CLI Flags Reference
-
-### Core Flags
-
-- `--max-level <0-4>`: Maximum autopilot level (default: 0)
-- `--dry-run`: Preview operations without execution (default: true)
-- `--execute`: Actually perform operations (disables dry-run)
-
-### Level 2+ Flags
-
-- `--comment-template <path>`: Path to custom PR comment template
-  - Requires: `--max-level 2` or higher
-  - Default: Uses built-in template
-
-### Level 3+ Flags
-
-- `--open-pr`: Open pull requests for integration branches
-  - Requires: `--max-level 3` or higher
-- `--branch-prefix <prefix>`: Prefix for integration branch names
-  - Default: `integration/`
-  - Example: `weave/`, `merge-pyramid/`
-
-### Level 4 Flags
-
-- `--close-superseded`: Close superseded PRs after successful integration
-  - Requires: `--max-level 4`
-
-## Validation Rules
-
-The CLI enforces the following validation rules to ensure safe operation:
-
-1. **Level Range**: `--max-level` must be 0-4
-2. **Integer Values**: Level must be an integer (no fractions)
-3. **Flag Dependencies**:
-   - `--open-pr` requires `--max-level 3` or higher
-   - `--close-superseded` requires `--max-level 4`
-   - `--comment-template` requires `--max-level 2` or higher
-
-### Example Validation Errors
-
-```bash
-# Error: Invalid level
-$ lex-pr merge --max-level 5
-Configuration Error: Invalid autopilot configuration: must be at most 4
-
-# Error: Flag requires higher level
-$ lex-pr merge --max-level 2 --open-pr
-Configuration Error: --open-pr requires --max-level 3 or higher
-
-# Error: Flag requires highest level
-$ lex-pr merge --max-level 3 --close-superseded
-Configuration Error: --close-superseded requires --max-level 4
-```
-
-## Examples
-
-### Development Workflow (Level 0-1)
-
-```bash
-# 1. Generate and validate plan
-lex-pr plan --dry-run
-
-# 2. Review plan
-cat .smartergpt/runner/plan.json
-
-# 3. Execute gates in dry-run mode
-lex-pr execute --max-level 0 --dry-run
-
-# 4. Generate detailed artifacts
-lex-pr execute --max-level 1 --artifact-dir ./artifacts
-```
-
-### CI/CD Integration (Level 2)
-
-```bash
-# Post status to PRs from CI
-lex-pr execute \
-  --max-level 2 \
-  --comment-template .github/pr-status-template.md \
-  --artifact-dir ./gate-results
-
-# Use custom branch for status updates
-lex-pr merge \
-  --max-level 2 \
-  --plan ./plan.json \
-  --json > results.json
-```
-
-### Integration Testing (Level 3)
-
-```bash
-# Create integration branches and PRs
-lex-pr merge \
-  --max-level 3 \
-  --open-pr \
-  --branch-prefix "integration/test-" \
-  --execute
-
-# Review integration PRs before finalizing
-gh pr list --label "integration"
-```
-
-### Production Automation (Level 4)
-
-```bash
-# Full automation with all features
-lex-pr merge \
-  --max-level 4 \
-  --open-pr \
-  --close-superseded \
-  --branch-prefix "weave/" \
-  --execute
-
-# Monitor progress
-lex-pr status --json
-```
-
-## Safety Recommendations
-
-1. **Start Low**: Begin with Level 0-1 to understand behavior
-2. **Test Incrementally**: Validate each level in a test environment
-3. **Use Dry-Run**: Always test with `--dry-run` first
-4. **Review Artifacts**: Check generated files before proceeding
-5. **Monitor Closely**: Watch Level 3-4 operations carefully
-6. **Have Rollback Plans**: Be prepared to revert if issues occur
-
-## Integration with GitHub Actions
-
-Example workflow using autopilot levels:
-
-```yaml
-name: Merge Pyramid
-
-on:
-  schedule:
-    - cron: "0 */6 * * *" # Every 6 hours
-  workflow_dispatch:
-    inputs:
-      level:
-        description: "Autopilot level (0-4)"
-        required: true
-        default: "2"
-
-jobs:
-  merge-weave:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Generate plan
-        run: npx lex-pr plan --from-github
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Execute with autopilot
-        run: |
-          npx lex-pr execute \
-            --max-level ${{ github.event.inputs.level || '2' }} \
-            --open-pr \
-            --artifact-dir ./gate-results
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: gate-results
-          path: ./gate-results
-```
-
-## Future Enhancements
-
-Potential future capabilities under consideration:
-
-- **Level 5**: AI-assisted semantic conflict resolution
-- **Adaptive Levels**: Automatically adjust based on success rate
-- **Rollback Automation**: Automatic revert on gate failures
-- **Parallel Execution**: Run multiple integration branches simultaneously
-- **Conflict Resolution**: Interactive prompts for semantic patches
-
-## See Also
-
-- [CLI Reference](./cli.md) - Complete CLI documentation
-- [Merge Weave Analysis](./merge-weave-analysis.md) - Design and architecture
-- [Examples](../examples/) - Example configurations and workflows

package/docs/autopilot.md

@@ -1,288 +0,0 @@
-# Autopilot Levels
-
-Autopilot provides progressive automation for merge-weave execution, from report-only analysis to full integration branch creation.
-
-## Overview
-
-The autopilot system implements a "ladder of automation" with increasing levels of capability:
-
-- **Level 0**: Report-only analysis (no side effects) ✅ **Implemented**
-- **Level 1**: Artifact generation (JSON/MD deliverables) ✅ **Implemented**
-- **Level 2**: PR annotation + status checks ✅ **Implemented**
-- **Level 3**: Integration branch creation + merge ✅ **Implemented**
-- **Level 4**: Finalize + close superseded PRs ✅ **Implemented**
-
-## Level 0: Report-Only Analysis
-
-Analyzes the merge plan and provides recommendations without generating any artifacts or making any changes.
-
-### Usage
-
-```bash
-# Basic usage
-lex-pr autopilot plan.json --level 0
-
-# JSON output mode
-lex-pr autopilot plan.json --level 0 --json
-```
-
-### Output
-
-Prints analysis to stdout including:
-
-- Plan summary (items, levels)
-- Merge order computation
-- Recommendations for execution
-
-### Use Cases
-
-- Quick validation of plan structure
-- CI/CD pipeline checks
-- Development workflow verification
-
-## Level 1: Artifact Generation
-
-Extends Level 0 by generating structured JSON and Markdown deliverables to support both manual and automated workflows.
-
-### Usage
-
-```bash
-# Generate artifacts (requires writable profile)
-lex-pr autopilot plan.json --level 1 --profile-dir .smartergpt.local/
-
-# Use custom profile directory
-lex-pr autopilot plan.json --level 1 --profile-dir /path/to/profile
-
-# JSON output mode
-lex-pr autopilot plan.json --level 1 --json
-```
-
-### Write Protection
-
-Level 1 respects the write protection discipline:
-
-- **role=example**: Read-only, writes are rejected
-- **role=local**: Writable, artifacts can be generated
-
-To use Level 1, ensure you have a writable profile:
-
-```bash
-# Option 1: Use local profile override
-mkdir -p .smartergpt.local
-echo "role: local" > .smartergpt.local/profile.yml
-lex-pr autopilot plan.json --level 1
-
-# Option 2: Set environment variable
-export LEX_PR_PROFILE_DIR=/path/to/writable/profile
-lex-pr autopilot plan.json --level 1
-
-# Option 3: Use --profile-dir flag
-lex-pr autopilot plan.json --level 1 --profile-dir /path/to/writable/profile
-```
-
-### Generated Artifacts
-
-All artifacts are generated in `.smartergpt/deliverables/weave-{timestamp}/`:
-
-#### 1. `analysis.json`
-
-Structured analysis data with schema versioning:
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "timestamp": "2025-10-02T15:30:00Z",
-  "plan": {
-    "nodes": [...],
-    "policy": {...}
-  },
-  "mergeOrder": [["PR-123"], ["PR-456", "PR-789"]],
-  "conflicts": [],
-  "recommendations": [...]
-}
-```
-
-#### 2. `weave-report.md`
-
-Human-readable execution recommendations:
-
-- Plan summary
-- Merge order breakdown
-- Item details with dependencies and gates
-- Execution recommendations
-
-#### 3. `gate-predictions.json`
-
-Expected gate outcomes for verification:
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "timestamp": "2025-10-02T15:30:00Z",
-  "predictions": [
-    {
-      "item": "feature-a",
-      "gate": "lint",
-      "expectedStatus": "pass",
-      "reason": "Gate defined in plan"
-    }
-  ]
-}
-```
-
-#### 4. `execution-log.md`
-
-Template for manual execution tracking:
-
-- Pre-execution checklist
-- Level-by-level execution steps
-- Post-execution verification
-
-#### 5. `metadata.json`
-
-Runtime metadata:
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "timestamp": "2025-10-02T15:30:00Z",
-  "runnerVersion": "0.1.0",
-  "levelExecuted": 1,
-  "profilePath": "/path/to/profile"
-}
-```
-
-### Use Cases
-
-- **Manual workflows**: Use generated reports and templates for guided execution
-- **CI/CD integration**: Parse JSON artifacts for automated decision-making
-- **Documentation**: Archive execution plans and recommendations
-- **Debugging**: Compare planned vs. actual execution outcomes
-
-## Artifact Versioning
-
-All JSON artifacts include `schemaVersion` fields following semantic versioning:
-
-- **Patch** (1.0.x): Additive optional fields or documentation changes
-- **Minor** (1.x.0): Additive required fields with safe defaults
-- **Major** (x.0.0): Breaking changes to structure or semantics
-
-Consumers should validate schema versions before parsing artifacts.
-
-## Timestamps
-
-All artifacts use ISO 8601 timestamps (UTC) for consistency:
-
-```
-2025-10-02T15:30:00.123Z
-```
-
-Directory names use filesystem-safe format:
-
-```
-weave-2025-10-02T15-30-00-123
-```
-
-## Error Handling
-
-### Write Protection Errors
-
-```bash
-$ lex-pr autopilot plan.json --level 1
-Error: Cannot write autopilot artifacts: profile at "/path/to/profile" has role="example" (read-only).
-Use a local profile (.smartergpt.local/) or set LEX_PR_PROFILE_DIR to a writable location.
-```
-
-### Invalid Level
-
-```bash
-$ lex-pr autopilot plan.json --level 99
-Error: unsupported autopilot level 99 (supported: 0, 1)
-```
-
-### Missing Plan File
-
-```bash
-$ lex-pr autopilot --level 0
-Error: plan file is required (use --plan <file> or provide as argument)
-```
-
-## Integration with Existing Workflows
-
-### With plan Command
-
-```bash
-# Generate plan
-lex-pr plan --from-github --query "is:open is:pr" --out .smartergpt.local/runner
-
-# Run autopilot on generated plan
-lex-pr autopilot .smartergpt.local/runner/plan.json --level 1
-```
-
-### With execute Command
-
-```bash
-# Generate autopilot artifacts first
-lex-pr autopilot plan.json --level 1 --profile-dir .smartergpt.local/
-
-# Review artifacts
-cat .smartergpt.local/deliverables/weave-*/weave-report.md
-
-# Execute plan with gate validation
-lex-pr execute plan.json --artifact-dir ./gate-results
-```
-
-### CI/CD Pipeline
-
-```yaml
-# Example GitHub Actions workflow
-- name: Generate autopilot artifacts
-  run: |
-    npm run cli -- autopilot plan.json --level 1 --profile-dir ./workspace --json > autopilot-result.json
-
-- name: Upload artifacts
-  uses: actions/upload-artifact@v3
-  with:
-    name: autopilot-deliverables
-    path: ./workspace/deliverables/
-
-- name: Check success
-  run: |
-    if ! jq -e '.success' autopilot-result.json > /dev/null; then
-      echo "Autopilot failed"
-      exit 1
-    fi
-```
-
-## All Levels Implemented ✅
-
-All autopilot levels (0-4) have been successfully implemented:
-
-### Level 2: PR Annotation + Status Checks ✅
-
-- Comment on PRs with gate results
-- Update PR status checks
-- Label PRs based on merge readiness
-
-### Level 3: Integration Branch Creation + Merge ✅
-
-- Create integration branch
-- Perform actual merges following computed order
-- Handle conflicts with mechanical rules
-
-### Level 4: Finalize + Close Superseded PRs ✅
-
-- Merge integration branch to target
-- Close superseded PRs (with `--close-superseded` flag)
-- Cleanup integration branches after successful merge
-- Post-merge validation and verification
-- Rollback capabilities for failed operations
-
-For detailed usage, see [Autopilot Levels Documentation](./autopilot-levels.md).
-
-## Related Documentation
-
-- [Autopilot Levels](./autopilot-levels.md) - Complete autopilot documentation
-- [Merge-Weave Analysis](./merge-weave-analysis.md) - Strategic planning and epic breakdown
-- [Profile Resolver](../src/config/profileResolver.ts) - Write protection and profile precedence
-- [Plan Schema](../src/schema.ts) - Plan structure and validation