@smartergpt/lexrunner 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,345 @@
+# Contributing to lexrunner
+
+Thanks for your interest in contributing! This project builds a deterministic CLI that fans out work across many PRs, computes a merge pyramid, runs gates uniformly, and merges cleanly.
+
+This guide keeps contributions small, deterministic, and easy to review.
+
+## Quick start
+
+- Node.js: 20.x (see `.nvmrc` and `package.json` engines)
+- npm: 10.x (see `package.json` packageManager)
+
+Setup:
+
+- npm ci
+- npm run build
+- npm test
+
+Useful scripts:
+
+- Dev CLI (ts): `npm run cli -- <command>`
+- Build artifacts: `npm run build`
+- Types: `npm run typecheck`
+- Tests: `npm test`
+
+## Project layout
+
+- `src/**`: TypeScript source for the Runner CLI and MCP adapter
+- `docs/**`: Documentation
+- `.smartergpt/**`: Portable example workspace profile (not read at runtime)
+- `tests/**`: Vitest unit/integration tests
+
+Two-track separation (firm): The core runner never stores user/work artifacts. Portable example profiles live under `.smartergpt/**` only.
+
+## Commit style
+
+Use imperative, descriptive commit messages. Optional prefixes:
+
+- `runner:` core CLI changes under `src/**`
+- `mcp:` adapter changes
+- `schema:` schema updates and regeneration
+- `tests:` test-only changes
+- `docs:` documentation
+- `ci:` CI/workflow changes
+- `workspace:` portable profile assets under `.smartergpt/**`
+
+Examples:
+
+- `runner: Add retry/backoff to gate executor`
+- `docs: Document plan schema validation CLI`
+
+## ⚠️ Formatting Drift Prevention
+
+**Common issue:** VS Code auto-formats files on save, creating unstaged changes that get added in a separate commit after push.
+
+**Pre-commit hook** warns you if formatting changes exist but aren't staged:
+
+```
+⚠️  WARNING: Unstaged formatting changes detected
+...
+Options:
+  1. Stage these changes:    git add <files>
+  2. Discard them:           git checkout -- <files>
+  3. Continue anyway:        git commit --no-verify
+```
+
+**To avoid this:**
+
+- Either include formatting in your commit, or
+- Run `git checkout -- <files>` to discard them before committing
+
+This keeps your commits clean and prevents "formatting commit" noise in history.
+
+## PR guidelines
+
+Keep PRs small and focused. One PR = one chat/task. Include a "How to verify" section with exact commands and expected outcomes.
+
+Acceptance checklist per PR:
+
+- [ ] Clear scope and acceptance criteria
+- [ ] Deterministic outputs (stable order, sorted keys)
+- [ ] Scripts/types/tests green (`build`, `typecheck`, `test`)
+- [ ] Docs updated (README/docs) when public behavior changes
+
+## Running the CLI locally
+
+Examples:
+
+- `npm run cli -- plan --from-github --json` → prints plan JSON to stdout
+- `npm run cli -- execute plan.json --json` → runs gates with policy
+- `npm run cli -- report ./gate-results --out md` → aggregates gate results
+
+See `docs/cli.md` for the full command reference.
+
+## Tests
+
+- Run all tests: `npm test`
+- Run a specific file: `npm test -- tests/<file>.spec.ts`
+
+If adding public behavior or fixing a bug, prefer tests first (happy path + 1-2 edge cases). Ensure outputs are deterministic.
+
+### Slow CLI Tests
+
+Some CLI tests are excluded from the default `npm test` run because they involve long-running operations (e.g., sleep commands, extensive git operations). These tests run on a scheduled CI workflow instead.
+
+**To run slow CLI tests locally:**
+
+```bash
+LEX_ENABLE_SLOW_CLI_TESTS=true npm run test:cli:slow
+```
+
+**Test categorization:**
+
+| Category            | Command                 | CI Lane          |
+| ------------------- | ----------------------- | ---------------- |
+| Default tests       | `npm test`              | Every PR, fast   |
+| Slow CLI tests      | `npm run test:cli:slow` | Scheduled/manual |
+| Git-dependent tests | `npm run test:git`      | Manual           |
+
+**Adding new slow tests:**
+
+1. Add the test file to `vitest.slow-cli.config.ts` `include` array
+2. Add exclusion to `vitest.config.ts` `exclude` array
+3. Document why the test is slow in the test file
+
+### Testing Planner Features
+
+When working on diffgraph planner features (`src/planner/`), follow these guidelines:
+
+**Test Coverage Requirements:**
+
+- Dependency parser: Test all supported syntax variations
+- File analysis: Test intersection detection, confidence scoring
+- Dependency scoring: Test weight combinations, threshold filtering
+- Validation: Test cycle detection, orphan warnings, invalid refs
+
+**E2E Test Fixtures:**
+Located in `tests/fixtures/` - use realistic PR structures:
+
+- Simple stacks (linear dependencies)
+- Diamond patterns (fan-out/fan-in)
+- Complex graphs (10+ PRs with mixed dependencies)
+- Edge cases (cycles, orphans, self-dependencies)
+
+**Example test structure:**
+
+```typescript
+import { parsePRDescription } from "../src/planner/dependencyParser.js";
+
+describe("Dependency Parser", () => {
+  it("should parse single dependency", () => {
+    const result = parsePRDescription(101, "Depends-on: #100");
+    expect(result.dependencies).toEqual(["#100"]);
+  });
+
+  it("should parse multiple dependencies", () => {
+    const result = parsePRDescription(101, "Depends-on: #100, #102");
+    expect(result.dependencies).toEqual(["#100", "#102"]);
+  });
+
+  // Test determinism
+  it("should produce stable sorted output", () => {
+    const result1 = parsePRDescription(101, "Depends-on: #103, #100, #102");
+    const result2 = parsePRDescription(101, "Depends-on: #102, #103, #100");
+    expect(result1.dependencies).toEqual(result2.dependencies);
+  });
+});
+```
+
+**Run planner-specific tests:**
+
+```bash
+# All planner tests
+npm test -- tests/batch-planner.spec.ts
+
+# Dependency parser tests
+npm test -- tests/dependencyParser.spec.ts
+
+# File analysis tests
+npm test -- tests/fileAnalysis.spec.ts
+```
+
+**Documentation Tests:**
+Ensure examples in documentation work:
+
+```bash
+# Test examples from tutorials
+cd docs/tutorials/diffgraph-planner/
+# Run commands from 01-simple-stack.md, etc.
+```
+
+See [Diffgraph Planner Guide](./docs/diffgraph-planner.md) for feature documentation.
+
+## Code style & types
+
+- TypeScript-first; strict types preferred
+- Keep modules small and pure where possible; isolate side-effects
+- Use Zod for schemas and validation in `src/schema.ts`
+
+### CLI Development Conventions
+
+When adding or modifying CLI commands, follow these critical patterns:
+
+- **Exit handling**: Use `throwExit()` or throw `CLIExitSignal` - never call `process.exit()` directly
+- **JSON purity**: Keep stdout clean - all diagnostics to stderr, use `canonicalJSONStringify()` for JSON output
+- **Stream configuration**: Use Commander's `configureOutput()` to separate data from diagnostics
+- **Exit codes**: 0 = success, 1 = system error, 2 = user/validation error
+
+See [CLI Conventions](./docs/cli.md#cli-conventions) for detailed patterns and examples.
+
+## Adding New Commands
+
+The lexrunner CLI uses a **modular command architecture** where each command lives in its own module. This makes the codebase maintainable and testable.
+
+### Quick Start
+
+1. **Create command module** in `src/commands/myCommand.ts`
+2. **Export registration function**: `registerMyCommandCommand(program: Command)`
+3. **Register in `src/cli.ts`**: Add import and call registration function
+4. **Add tests** in `tests/commands/myCommand.spec.ts`
+5. **Update documentation** in `docs/cli.md`
+
+### Command Module Pattern
+
+```typescript
+// src/commands/myCommand.ts
+import { Command } from "commander";
+import { writeJsonOutput } from "../cli/output.js";
+import { throwExit } from "../cli/exitHandler.js";
+
+export function registerMyCommandCommand(program: Command): void {
+  program
+    .command("my-command")
+    .description("Brief description")
+    .argument("<arg>", "Argument description")
+    .option("--json", "Output as JSON")
+    .action(async (arg, options) => {
+      try {
+        const result = await executeMyCommand(arg, options);
+
+        if (options.json) {
+          writeJsonOutput(result);
+        } else {
+          console.log(formatOutput(result));
+        }
+      } catch (error) {
+        throwExit(error, 1);
+      }
+    });
+}
+
+// Pure, testable business logic
+async function executeMyCommand(arg: string, options: any) {
+  // Implementation here
+  return { success: true };
+}
+
+function formatOutput(result: any): string {
+  return `✅ ${result.success ? "Success" : "Failed"}`;
+}
+```
+
+### Best Practices
+
+✅ **DO:**
+
+- Separate business logic from CLI handling (pure functions)
+- Support both `--json` and human-readable output
+- Use `throwExit()` for error handling
+- Write unit tests for business logic
+- Add JSDoc comments to exported functions
+- Keep commands focused and single-purpose
+
+❌ **DON'T:**
+
+- Mix business logic into `.action()` handlers
+- Call `process.exit()` directly
+- Output to stdout when `--json` is used (except JSON itself)
+- Create commands with implicit dependencies
+
+### Examples
+
+- **Simple command**: `src/commands/completion.ts` (~50 lines)
+- **Medium command**: `src/commands/discover.ts` (~150 lines)
+- **Complex command**: `src/commands/execute.ts` (~300+ lines)
+
+### Full Guide
+
+For comprehensive documentation including:
+
+- Command templates
+- Testing patterns
+- Common utilities
+- Documentation requirements
+- Complete checklist
+
+See **[Command Creation Guide](./docs/command-creation-guide.md)**
+
+## Opening an issue
+
+Use the issue templates (Bug report / Feature request). Include acceptance criteria and reproduce steps. Link related docs/PRs.
+
+## Security
+
+Never commit secrets. See `docs/SECURITY_IMPLEMENTATION.md`. Use the `lex-pr security` subcommands for scanning and validation.
+
+## Release determinism
+
+After `npm run build && npm run format`, the tree should be clean (`git diff --exit-code`). If generation changes are intentional, include them in the PR.
+
+## Releasing
+
+LexRunner follows the same release discipline as Lex. See [Lex RELEASE.md](https://github.com/Guffawaffle/lex/blob/main/RELEASE.md) for the full process.
+
+### Version Alignment Check
+
+Before releasing, verify package.json and Git tags are aligned:
+
+```bash
+npm run check:release-drift
+```
+
+### Quick Release Checklist
+
+1. **Bump version** in `package.json`
+2. **Update CHANGELOG.md** with changes
+3. **Run gates**: `npm run build && npm run typecheck && npm test`
+4. **Commit**: `git commit -am "chore: bump version to X.Y.Z"`
+5. **Tag**: `git tag -s "vX.Y.Z" -m "Release vX.Y.Z"`
+6. **Push**: `git push origin main "vX.Y.Z"`
+7. **Create GitHub release**: `gh release create vX.Y.Z --verify-tag --notes "See CHANGELOG.md"`
+
+### Catch-Up Release (One-Time)
+
+If `npm run check:release-drift` reports that tag v0.5.0 exists but no GitHub release, create it:
+
+```bash
+gh release create v0.5.0 \
+  --title "v0.5.0: Initial Release" \
+  --notes "Initial public release. See CHANGELOG.md for details." \
+  --verify-tag
+```
+
+---
+
+Thank you for helping improve lexrunner! 💙

package/EAGER_PM_FANOUT_ANALYSIS.md

@@ -0,0 +1,283 @@
+# Eager PM Fanout Analysis - LexRunner
+
+**Date:** December 16, 2025
+**Status:** Ready for Coding Agent Assignment
+
+---
+
+## Executive Summary
+
+**Current state:** 6 open draft PRs, 34 open issues, clean CI baseline (4028 tests passing)
+
+**Recommendation:** Prioritize **Issue #589** (Ship one complete workflow) before fanning out additional work. This is the value proposition.
+
+---
+
+## 🎯 Priority 1: Critical Path to 1.0.0
+
+### #589 - Ship one complete workflow: merge-weave-main end-to-end
+
+**Status:** Just created (Dec 16, 2025)
+**Priority:** CRITICAL
+**Labels:** `1.0.0`, `priority:critical`
+
+**Why this matters:**
+
+> "A working merge-weave is the **value proposition** of LexRunner. Everything else is infrastructure. If merge-weave doesn't work end-to-end, nothing else matters."
+
+**Definition of Done:**
+
+- [ ] `lex-pr weave discover` works on any GitHub repo
+- [ ] `lex-pr weave plan` generates valid plan.json
+- [ ] `lex-pr weave apply --dry-run` shows correct execution order
+- [ ] MCP tools work equivalently
+- [ ] Documentation covers the happy path
+- [ ] At least one integration test proves the flow
+
+**Out of Scope (for now):**
+
+- Executor canonicalization (#404 tree)
+- Fan-out orchestration
+- Policy enforcement hooks
+
+**Recommendation:** ✅ **ASSIGN TO COPILOT FIRST**
+
+This unblocks everything else. Once merge-weave works, the PRs become more valuable.
+
+---
+
+## 📊 Open PRs Analysis (6 total, all draft)
+
+### Immediately Ready (No Blockers)
+
+**PR #586 - Universal --json Flag Support** (ALN-004)
+
+- **Ready:** ✅ No dependencies
+- **Value:** Enables AI agent parsing of all CLI outputs
+- **Effort:** Medium (13 tests, JSON envelope + schema docs)
+- **Assign:** ✅ Yes, but AFTER #589
+
+**PR #588 - Tool Budget Enforcement** (LPR-043)
+
+- **Ready:** ✅ Foundation schemas exist in main
+- **Value:** Runtime tool budget enforcement (24 unit tests)
+- **Effort:** Medium
+- **Assign:** ✅ Yes, but AFTER #589
+
+### Has Dependencies
+
+**PR #585 - Frame Emission Enforcement** (LPR-044)
+
+- **Dependencies:** #405 (schema) - **MERGED** ✅
+- **Ready:** ✅ Can proceed
+- **Assign:** ✅ Yes, but AFTER #589
+
+**PR #587 - Guardrail Runtime Enforcement** (LPR-047)
+
+- **Dependencies:** #406 (types) - **MERGED** ✅, #407 (tool budget) - **PR #588**
+- **Ready:** ⚠️ Needs #588 merged first
+- **Assign:** After #588 merges
+
+**PR #583 - Manifest Validation CI** (LPR-049)
+
+- **Dependencies:** #405 (schema) - **MERGED** ✅, #412 (registry) - **NOT FOUND**
+- **Ready:** ⚠️ Need to check if #412 is actually needed
+- **Recommendation:** Review dependencies, may be ready
+
+**PR #584 - CLI Category-Action Pattern** (ALN-003)
+
+- **Status:** 🚫 **BLOCKED** - Firewall blocked GitHub API during Copilot execution
+- **Dependencies:** #574 (naming conventions) - status unknown
+- **Ready:** ❌ Needs firewall allowlist fix
+- **Recommendation:** Create infrastructure ticket for firewall configuration
+
+---
+
+## 🎫 Fanout Ticket Recommendations
+
+### Infrastructure Tickets (Create Now)
+
+**CFG-001: Configure GITHUB_TOKEN for CLI discover command**
+
+- **Priority:** High
+- **Blocker for:** Merge-weave dogfooding
+- **Description:** CLI `discover` command fails without GITHUB_TOKEN
+- **Acceptance Criteria:**
+  - [ ] GITHUB_TOKEN available in environment
+  - [ ] `lex-pr weave discover` works without authentication errors
+  - [ ] Document token setup in README
+
+**CFG-002: Add GitHub API to Copilot firewall allowlist**
+
+- **Priority:** High
+- **Blocker for:** PR #584
+- **Description:** Copilot coding agent cannot access GitHub API
+- **Error:** `Firewall rules blocked me from connecting to https://api.github.com/`
+- **Acceptance Criteria:**
+  - [ ] GitHub API domains added to Copilot allowlist
+  - [ ] PR #584 can be re-run or fixed
+  - [ ] Document allowlist configuration
+
+**EXE-012: Investigate #412 Executor Registry status**
+
+- **Priority:** Medium
+- **Blocks:** PR #583
+- **Description:** PR #583 depends on #412 (Executor Registry & Loader) but registry code not found
+- **Acceptance Criteria:**
+  - [ ] Determine if #412 was merged under different name
+  - [ ] Or: Create executor registry if missing
+  - [ ] Update PR #583 dependencies
+
+### Enhancement Tickets (After #589)
+
+**ALN-005: Break CLI refactoring into smaller PRs**
+
+- **Parent:** PR #584
+- **Priority:** Low
+- **Description:** PR #584 is large (weave + gate + workspace + fanout categories)
+- **Recommendation:** Could be 4 separate PRs for easier review
+- **Benefit:** Smaller blast radius, easier to merge incrementally
+
+---
+
+## 🏗️ Issue Priority Matrix
+
+### Layer 0: Must Ship (1.0.0 Blockers)
+
+| Issue | Title                          | Effort | Assigned | Status           |
+| ----- | ------------------------------ | ------ | -------- | ---------------- |
+| #589  | Ship one complete workflow     | L      | ❌       | **ASSIGN FIRST** |
+| #578  | ALN-004: Universal --json flag | M      | PR #586  | Draft            |
+| #576  | ALN-003: CLI category-action   | M      | PR #584  | Blocked          |
+
+### Layer 1: Executor Canonicalization (Post-0.5.0)
+
+| Issue | Title                           | Dependencies     | Status             |
+| ----- | ------------------------------- | ---------------- | ------------------ |
+| #407  | LPR-043: Tool budget            | #405 ✅          | PR #588 (draft)    |
+| #408  | LPR-044: Frame emission         | #405 ✅          | PR #585 (draft)    |
+| #411  | LPR-047: Guardrail enforcement  | #406 ✅, #407    | PR #587 (draft)    |
+| #413  | LPR-049: Manifest validation CI | #405 ✅, #412 ⚠️ | PR #583 (draft)    |
+| #415  | EXE-010: Senior Dev migration   | #412, #413       | Partially complete |
+| #409  | LPR-045: Jordan-mode protocol   | #405 ✅, #406 ✅ | Not started        |
+
+### Layer 2: Strategic/Future
+
+| Issue | Title                           | Type        | Priority |
+| ----- | ------------------------------- | ----------- | -------- |
+| #486  | Epic: LexRunner 1.0.0 AX-Native | Epic        | Tracking |
+| #389  | LPR-037: Guided workflow tracks | Enhancement | Medium   |
+| #390  | LPR-038: Single issue runner    | Epic        | Vision   |
+| #367  | Epic: Orchestrated fanout runs  | Epic        | Vision   |
+
+---
+
+## 🚦 Suggested Assignment Order
+
+### Phase 1: Foundation (Week 1)
+
+1. ✅ **#589** - Ship merge-weave end-to-end (CRITICAL)
+2. Create **CFG-001** - GitHub token configuration
+3. Create **CFG-002** - Firewall allowlist
+4. Create **EXE-012** - Investigate #412 registry
+
+### Phase 2: PR Cleanup (Week 2)
+
+5. **PR #586** - Universal --json (after #589)
+6. **PR #588** - Tool budget (after #589)
+7. **PR #585** - Frame emission (after #589)
+8. **PR #583** - Manifest validation (after EXE-012 resolves)
+
+### Phase 3: Blockers (Week 2-3)
+
+9. Fix **PR #584** (after CFG-002 resolves)
+10. **PR #587** - Guardrails (after #588 merges)
+
+### Phase 4: Polish (Week 3-4)
+
+11. **#415** - Senior Dev migration
+12. **#409** - Jordan-mode protocol
+
+---
+
+## 🎨 Epic Landscape
+
+### Active Epics
+
+- **#486** - LexRunner 1.0.0 (release tracking)
+- **#335** - Merge-Weave Execute v1 (substantially complete)
+- **#311** - Hook fanout/merge-weave events (substantially complete)
+
+### Vision Epics (Don't Assign Yet)
+
+- **#390** - Single issue runner mode
+- **#389** - Guided workflow tracks
+- **#367** - Orchestrated fanout runs
+- **#376** - Token optimization suite
+
+---
+
+## 💡 Key Insights
+
+### What's Working
+
+- ✅ Copilot coding agent created well-structured PRs
+- ✅ Comprehensive test coverage (24-59 tests per PR)
+- ✅ Clear dependency declarations in issue bodies
+- ✅ Foundation schemas (#405, #406) already merged
+
+### What Needs Attention
+
+- ⚠️ Missing GitHub token for CLI tooling
+- ⚠️ Firewall configuration blocking Copilot agent
+- ⚠️ #412 (Executor Registry) status unclear
+- ⚠️ Large PRs (#584) could be broken down
+
+### Strategic Recommendation
+
+**Focus on value delivery:** Ship merge-weave end-to-end (#589) before expanding the executor framework. The executor work is infrastructure; merge-weave is the product.
+
+---
+
+## 📝 Next Actions for Eager PM
+
+### Create These Tickets Now
+
+1. **CFG-001** - Configure GITHUB_TOKEN
+2. **CFG-002** - Add GitHub API to firewall allowlist
+3. **EXE-012** - Investigate #412 Executor Registry
+
+### Assign to Copilot (In Order)
+
+1. **#589** - Ship one complete workflow (CRITICAL)
+2. Wait for #589 to complete
+3. Then assign PRs #586, #588, #585
+
+### Review and Triage
+
+1. Check if #574 (naming conventions) is merged
+2. Verify #412 (Executor Registry) status
+3. Consider breaking #584 into smaller PRs
+
+---
+
+## 🔄 Feedback Loop
+
+### Dogfooding Observations
+
+- ✅ MCP tools exist but need GitHub auth
+- ✅ PR discovery works via GitHub API search
+- ⚠️ CLI `discover` command needs token
+- ⚠️ Plan creation tool needs better error messaging
+- ⚠️ Should detect when foundation schemas are merged
+
+### Tooling Improvements Needed
+
+- Better error messages when GitHub auth fails
+- Automatic dependency status detection
+- Visualization of which PRs are ready vs blocked
+- Integration with existing merge-weave plans
+
+---
+
+**End of Analysis**