@smartergpt/lexrunner 1.0.0 → 1.2.1

package/FAQ.md

@@ -1,292 +0,0 @@
-# FAQ — lexrunner
-
-Quick answers to common questions. See `docs/README.md` for the full documentation index.
-
-## What is lexrunner?
-
-A deterministic CLI that fans out tasks as many PRs, computes a merge pyramid (dependency order), runs gates uniformly (lint/type/test/etc.), and merges cleanly.
-
-## Where does the runner read inputs from?
-
-At integration time, only from a single frozen `plan.json` (Schema v1). See `docs/schemas.md` and `src/schema.ts`.
-
-## What's the difference between `src/**` and `.smartergpt/**`?
-
-- `src/**`: Core runner (stateless, packageable). Never stores user/work artifacts.
-- `.smartergpt/**`: Portable example profile for humans/agents. Not read at runtime by the runner.
-
-## What's the difference between `.smartergpt/` and `.smartergpt.local/`?
-
-- **`.smartergpt/`**: Tracked example profile (role: example)
-  - Provides team defaults and documentation
-  - Read-only (runner refuses to write artifacts)
-  - Tracked in git
-  - Contains canonical prompts in `prompts/` subdirectory
-
-- **`.smartergpt.local/`**: Local development profile (role: development)
-  - Personal/project-specific customizations
-  - Read-write (runner can write artifacts)
-  - Gitignored
-  - Overrides tracked profile on file-by-file basis
-  - Can have custom prompts in `prompts/` subdirectory
-
-See [Profile Resolution](./docs/profile-resolution.md) and [SmartGPT Structure v1 Spec](./docs/specs/smartergpt-structure-v1.md) for details.
-
-## Why are config files at the profile root instead of in a `runner/` subdirectory?
-
-**Actual structure:**
-
-```
-.smartergpt/
-├── intent.md              # ✅ Config at root
-├── scope.yml              # ✅ Config at root
-├── gates.yml              # ✅ Config at root
-└── runner/                # ✅ Working artifacts only
-    ├── plan.json
-    └── cache/
-```
-
-**Reason:** The `runner/` directory is for **working artifacts only** (plan.json, cache, logs), not configuration. Config files are at the profile root for simpler access and consistency. The `runner/` directory is gitignored to prevent commits of generated content.
-
-## What's in the `runner/` directory?
-
-The `runner/` directory contains **working artifacts only**:
-
-- `plan.json` - Generated execution plan
-- `snapshot.md` - Current state snapshot
-- `cache/` - Ephemeral cache data
-- `logs/` - Execution logs
-- `bin/` - Temporary binaries
-- `wt/` - Work tree
-
-**Important:** Config files (intent.md, scope.yml, etc.) are NOT in `runner/`. They're at the profile root.
-
-The entire `runner/` directory should be gitignored.
-
-## How do prompts work? What's the precedence?
-
-Prompts are template files used for plan generation with token expansion (`{{today}}`, `{{branch}}`, etc.).
-
-**Precedence chain** (highest to lowest):
-
-1. **`LEX_PROMPTS_DIR`** environment variable - Explicit override for cross-repo usage
-2. **`.smartergpt.local/prompts/`** - Local overlay (not tracked)
-3. **`.smartergpt/prompts/`** - Tracked canonical prompts
-
-**Example:**
-
-```bash
-# Use Lex prompts from another repo
-export LEX_PROMPTS_DIR=/path/to/lex/.smartergpt/prompts
-lex-pr plan --from-github
-```
-
-See [Prompts Configuration](./docs/prompts.md) for complete documentation.
-
-## How do I share prompts across multiple repositories?
-
-Three methods:
-
-**1. Environment Variable (Recommended for CI/CD)**
-
-```bash
-export LEX_PROMPTS_DIR=/path/to/shared/prompts
-```
-
-**2. Symlink (Recommended for Development)**
-
-```bash
-ln -s ../../lex/.smartergpt/prompts .smartergpt.local/prompts
-```
-
-**3. Copy (Recommended for Customization)**
-
-```bash
-cp -r ../lex/.smartergpt/prompts .smartergpt.local/
-```
-
-See [examples/profile-setup/cross-repo-prompts/](./examples/profile-setup/cross-repo-prompts/) for detailed guide.
-
-## What tokens are supported in prompts?
-
-| Token                | Description                  | Example Output            |
-| -------------------- | ---------------------------- | ------------------------- |
-| `{{today}}`          | Current date (YYYY-MM-DD)    | `2025-11-13`              |
-| `{{now}}`            | ISO timestamp without colons | `2025-11-13T14-30-45-123` |
-| `{{repo_root}}`      | Git repository root path     | `/path/to/repo`           |
-| `{{workspace_root}}` | Workspace root path          | `/path/to/workspace`      |
-| `{{branch}}`         | Current git branch           | `main`                    |
-| `{{commit}}`         | Current commit SHA           | `a1b2c3d4...`             |
-
-**Example:**
-
-```markdown
-# Report for {{branch}} - {{today}}
-
-Repository: {{repo_root}}
-```
-
-See [Prompts Configuration](./docs/prompts.md) for details.
-
-## Where do deliverables go?
-
-Deliverables placement depends on the profile:
-
-- **`.smartergpt/deliverables/`**: May be tracked for example outputs (use sparingly)
-- **`.smartergpt.local/deliverables/`**: Always gitignored, contains timestamped deliverable sets
-
-Deliverables include:
-
-- `analysis.json` - Structured merge analysis
-- `weave-report.md` - Human-readable report
-- `execution-log.md` - Tracking template
-
-See [Deliverables Management](./docs/deliverables-management.md) for details.
-
-## How do I migrate from an old structure where config was in `runner/`?
-
-**Old (incorrect):**
-
-```
-.smartergpt/
-└── runner/
-    ├── intent.md          # ❌ Config in subdirectory
-    ├── scope.yml
-    └── gates.yml
-```
-
-**New (correct):**
-
-```
-.smartergpt/
-├── intent.md              # ✅ Config at root
-├── scope.yml
-├── gates.yml
-└── runner/                # ✅ Working artifacts only
-    ├── plan.json
-    └── cache/
-```
-
-**Migration steps:**
-
-```bash
-cd .smartergpt
-mv runner/intent.md .
-mv runner/scope.yml .
-mv runner/gates.yml .
-mv runner/deps.yml .
-# Move other config files as needed
-```
-
-See [SmartGPT Structure v1 Spec - Migration Guide](./docs/specs/smartergpt-structure-v1.md#migration-guide) for complete instructions.
-
-## How do I generate a plan?
-
-Use GitHub discovery and plan commands:
-
-- `npm run cli -- discover --json`
-- `npm run cli -- plan --from-github --json > plan.json`
-
-## How do I run gates locally and in CI?
-
-`npm run cli -- execute plan.json` — the same semantics apply in both places. See `docs/cli.md` and `docs/gate-report-examples.md`.
-
-## Are outputs deterministic?
-
-Yes. We sort items and keys for stable diffs. The determinism check is described in `AGENTS.md`.
-
-## How do I scan for secrets or vulnerabilities?
-
-Security subcommands:
-
-- `lex-pr security scan-plan plan.json`
-- `lex-pr security check-rotation GITHUB_TOKEN --max-age 90`
-- `lex-pr security validate-secrets GITHUB_TOKEN DATABASE_URL`
-
-See `docs/SECURITY_IMPLEMENTATION.md`.
-
-## Do you support SARIF ingestion for a vulnerability gate?
-
-The security scanning service is present (`src/security/scanning.ts`) and a SARIF-backed "vuln" gate is on the roadmap (Issue #129). Until then, you can run npm audit locally and enforce thresholds via policy.
-
-## How do I contribute?
-
-See `CONTRIBUTING.md`. Keep PRs small and deterministic. Include a "How to verify" section.
-
-## Why are config files at profile root instead of in `runner/`?
-
-Config files (`intent.md`, `scope.yml`, `gates.yml`, etc.) define runner behavior and live at the **profile root** for easy access. The `runner/` directory is reserved for **working artifacts** (plan.json, cache, logs) generated during execution.
-
-**Structure:**
-
-```
-.smartergpt.local/
-├── intent.md              # Config at root
-├── scope.yml              # Config at root
-├── gates.yml              # Config at root
-└── runner/                # Working artifacts only
-    ├── plan.json
-    ├── cache/
-    └── logs/
-```
-
-## What's the difference between `.smartergpt/` and `.smartergpt.local/`?
-
-- **`.smartergpt/`**: Tracked example profile (read-only). Contains canonical config and prompts for the repository.
-- **`.smartergpt.local/`**: Local development profile (gitignored). Your working copy where you customize config and the runner writes artifacts.
-
-**Profile precedence:** `.smartergpt.local/` files override `.smartergpt/` files.
-
-## How do prompts work? Can I share prompts across repositories?
-
-Yes! Prompts use a three-level precedence chain:
-
-1. **`LEX_PROMPTS_DIR` env variable** - Cross-repository override
-2. **`.smartergpt.local/prompts/`** - Local prompt overlay
-3. **`.smartergpt/prompts/`** - Tracked canonical prompts
-
-**Cross-repo usage example:**
-
-```bash
-# Point LexRunner to Lex prompts
-export LEX_PROMPTS_DIR=/srv/lex-mcp/lex/.smartergpt/prompts
-lex-pr plan --from-github
-```
-
-**See:** `docs/prompts.md` for comprehensive guide including token expansion (`{{today}}`, `{{branch}}`, etc.) and usage patterns.
-
-## What tokens can I use in prompts?
-
-Prompts support dynamic token expansion:
-
-| Token           | Expands To     | Example               |
-| --------------- | -------------- | --------------------- |
-| `{{today}}`     | YYYY-MM-DD     | `2025-11-13`          |
-| `{{now}}`       | ISO timestamp  | `2025-11-13T14-30-45` |
-| `{{repo_root}}` | Repo path      | `/path/to/repo`       |
-| `{{branch}}`    | Current branch | `main`                |
-| `{{commit}}`    | Commit SHA     | `a1b2c3d4...`         |
-
-**See:** `docs/prompts.md` for complete token reference.
-
-## Why does `.smartergpt/` have a `deliverables/` directory?
-
-This is legacy from early development. In practice:
-
-- **Tracked profiles** (`role: example`) should NOT write deliverables
-- **Local profiles** (`role: development`) write to `.smartergpt.local/deliverables/`
-
-The runner enforces write protection based on profile role.
-
-## How do I migrate from an old structure with config in `runner/`?
-
-1. Run `lex-pr doctor` to check current structure
-2. Move config files from `runner/` to profile root:
-   ```bash
-   mv .smartergpt.local/runner/intent.md .smartergpt.local/
-   mv .smartergpt.local/runner/scope.yml .smartergpt.local/
-   mv .smartergpt.local/runner/gates.yml .smartergpt.local/
-   ```
-3. Verify with `lex-pr doctor` again
-
-**See:** `docs/specs/smartergpt-structure-v1.md` for complete migration guide.

package/FIXTURE_LIBRARY_SUMMARY.md

@@ -1,327 +0,0 @@
-# Shared Test Fixture Library - Implementation Summary
-
-## Overview
-
-Successfully implemented a comprehensive shared test fixture library for lexrunner to eliminate test duplication and accelerate test development.
-
-## What Was Built
-
-### Directory Structure
-
-```
-tests/fixtures/
-├── README.md                          # Comprehensive documentation
-├── index.ts                           # Central export point
-├── fixtures.spec.ts                   # 38 validation tests
-├── plans/                             # Plan fixtures
-│   ├── simple.ts                      # Independent PRs
-│   ├── linear.ts                      # Sequential dependencies
-│   ├── diamond.ts                     # Diamond/pyramid patterns
-│   └── complex.ts                     # Large realistic scenarios
-├── invalid/                           # Error-testing fixtures
-│   └── plans.ts                       # Cycles, unknown deps, etc.
-├── prs/                               # PR fixtures
-│   ├── basic.ts                       # Basic PR factory
-│   └── withDeps.ts                    # Dependency patterns
-├── gates/                             # Gate fixtures
-│   ├── configs.ts                     # Gate configurations
-│   └── results.ts                     # Execution results
-├── utils/                             # Test utilities
-│   ├── tempDir.ts                     # Temp directory helpers
-│   ├── mockGitHub.ts                  # GitHub API mocks
-│   └── cleanup.ts                     # Resource cleanup
-└── scenarios/                         # End-to-end scenarios
-    └── mergeWorkflows.ts              # Complete workflows
-```
-
-### Fixtures Implemented
-
-#### Plan Fixtures (11 total)
-
-- **simple**: 3 independent PRs
-- **simpleWithGates**: 2 PRs with lint/test gates
-- **linear**: 4-step dependency chain
-- **linearWithGates**: 3-step chain with gates
-- **diamond**: A,B → C pattern
-- **diamondExtended**: 4-layer diamond
-- **doubleDiamond**: Pyramid pattern
-- **complex**: 16 PRs, 4 layers, realistic scenario
-- **wideParallel**: 10 independent PRs (stress test)
-- **deepChain**: 15 sequential PRs (stress test)
-
-#### Invalid Plan Fixtures (7 total)
-
-- **cycle**: Simple circular dependency
-- **complexCycle**: Multi-path cycle
-- **unknownDependency**: References non-existent item
-- **orphans**: Disconnected dependency graph
-- **duplicateNames**: Duplicate item names
-- **missingRequiredGates**: Policy violations
-- **empty**: Edge case testing
-
-#### PR Fixtures
-
-- **basic**: Configurable PR factory
-- **batch**: Generate N PRs at once
-- **withFiles**: Specific file patterns
-- **withLabels**: Label configuration
-- **closed**: Merged/closed PRs
-- **largeChangeset**: 50+ file changes
-- **withDeps**: PRs with dependencies
-- **blocking**: PRs that block others
-- **chain**: Sequential dependency chains
-- **diamond**: Diamond PR patterns
-- **complex**: Realistic multi-PR scenarios
-- **mixedDependencyFormats**: Parser testing
-
-#### Gate Fixtures
-
-**Configurations:**
-
-- lint, test, e2e, security, build
-- flaky (retry testing)
-- containerized (Docker gates)
-- withArtifacts (output collection)
-- slow (timeout testing)
-- standard (lint + test)
-- full (all gate types)
-
-**Results:**
-
-- pass, fail, blocked, skipped, retrying
-- allPass, allFail, someFail
-- withRetries (attempt tracking)
-- testSuite (realistic test output)
-- lintResult (realistic lint output)
-
-#### Scenario Fixtures (8 complete workflows)
-
-- **simpleSuccess**: All PRs pass
-- **linearChain**: Sequential execution
-- **diamondMerge**: Parallel dependencies
-- **complexMerge**: Configurable large scenario
-- **withGateFailures**: Failure handling
-- **withRetries**: Retry logic
-- **withBlockedPRs**: Dependency blocking
-- **empty**: Edge case handling
-
-#### Utility Fixtures
-
-**tempDir:**
-
-- create, createWithFiles, cleanup
-- readFile, writeFile, exists, listFiles
-
-**mockGitHub:**
-
-- createMockGitHub (basic mock)
-- createErrorMock (error simulation)
-- createRateLimitedMock (rate limit testing)
-- createSlowMock (timeout testing)
-
-**cleanup:**
-
-- CleanupManager class
-- withCleanup helper
-
-## Key Features
-
-### 1. Type Safety
-
-- All fixtures fully typed with TypeScript
-- Proper interfaces for MockPR, MockOctokit, etc.
-- No `any` types (replaced with proper interfaces)
-
-### 2. Determinism
-
-- Fixed timestamps instead of `new Date()`
-- Seed-based approach instead of random
-- Consistent results across multiple runs
-- All fixtures validated for determinism
-
-### 3. Cross-Platform
-
-- Use `os.tmpdir()` instead of `/tmp`
-- Works on Windows, macOS, Linux
-
-### 4. Documentation
-
-- Comprehensive README.md (400+ lines)
-- Inline documentation for all functions
-- Usage examples for each fixture type
-- Migration guide from old fixtures
-
-### 5. Validation
-
-- 38 validation tests ensure correctness
-- Schema validation for all plan fixtures
-- Type checking for all TypeScript code
-
-## Test Results
-
-### Fixture Tests
-
-✅ **38 validation tests** - All passing
-
-- Plan fixture validation (7 tests)
-- Invalid plan validation (3 tests)
-- PR fixture validation (6 tests)
-- Gate fixture validation (6 tests)
-- Scenario validation (5 tests)
-- Mock GitHub utilities (5 tests)
-- Cleanup utilities (3 tests)
-- Determinism checks (3 tests)
-
-### Usage Examples
-
-✅ **20 example tests** - All passing
-
-- Plan fixture usage (3 tests)
-- PR fixture usage (3 tests)
-- Gate fixture usage (3 tests)
-- Mock GitHub usage (3 tests)
-- Temp directory usage (2 tests)
-- Cleanup manager usage (1 test)
-- Combined fixtures (2 tests)
-
-### Migration Examples
-
-✅ **16 migration tests** - All passing
-
-- Basic ordering (3 tests)
-- Complex scenarios (3 tests)
-- Determinism (1 test)
-- Error detection (3 tests)
-- Edge cases (2 tests)
-- Benefits demonstration (4 tests)
-
-### Overall Test Suite
-
-✅ **All existing tests still pass**
-
-- 144 test files passing (unchanged)
-- 2030 tests passing
-- 10 tests skipped
-- No breaking changes introduced
-
-## Code Quality
-
-### Code Review Improvements
-
-All 9 code review comments addressed:
-
-1. ✅ Cross-platform temp directory (os.tmpdir())
-2. ✅ Deterministic PR timestamps (UTC-based)
-3. ✅ Fixed gate result timestamps (FIXTURE_TIMESTAMP)
-4. ✅ Removed random gate behavior (seed-based)
-5. ✅ Proper error typing (APIError interface)
-
-### TypeScript Compilation
-
-✅ Zero TypeScript errors
-✅ Strict mode enabled
-✅ All types properly defined
-
-## Usage Impact
-
-### Before (Old Approach)
-
-```typescript
-// Load JSON from file
-const planContent = fs.readFileSync("fixtures/plan.tiny.json", "utf-8");
-const plan = loadPlan(planContent);
-
-// Manually create PRs
-const pr = {
-  number: 100,
-  title: "Test",
-  body: "Depends on: #99",
-  files: [
-    /* ... */
-  ],
-  // ... many more fields
-};
-```
-
-### After (New Approach)
-
-```typescript
-import { fixtures } from "./fixtures";
-
-// One line to get a plan
-const plan = fixtures.plans.simple();
-
-// One line to create PRs with dependencies
-const pr = fixtures.prs.withDeps({
-  number: 100,
-  title: "Test",
-  dependsOn: [99],
-});
-```
-
-## Benefits Delivered
-
-1. **Reduced Duplication**: Central fixture library eliminates copy-paste
-2. **Faster Development**: Pre-built scenarios save setup time
-3. **Better Quality**: Validated, realistic fixtures
-4. **Type Safety**: Full TypeScript support catches errors
-5. **Maintainability**: Single source of truth for test data
-6. **Determinism**: Consistent results enable reliable testing
-7. **Composability**: Mix and match fixtures for complex scenarios
-8. **Documentation**: Comprehensive guide for all fixtures
-
-## Files Added
-
-### Core Fixture Files (17 files)
-
-- `tests/fixtures/README.md` (8.5KB)
-- `tests/fixtures/index.ts` (6.2KB)
-- `tests/fixtures/plans/*.ts` (4 files, 10.5KB total)
-- `tests/fixtures/invalid/plans.ts` (3.2KB)
-- `tests/fixtures/prs/*.ts` (2 files, 7.9KB total)
-- `tests/fixtures/gates/*.ts` (2 files, 8.5KB total)
-- `tests/fixtures/utils/*.ts` (3 files, 10.5KB total)
-- `tests/fixtures/scenarios/mergeWorkflows.ts` (7.1KB)
-
-### Test Files (3 files)
-
-- `tests/fixtures/fixtures.spec.ts` (10KB, 38 tests)
-- `tests/fixtures-usage-examples.spec.ts` (10KB, 20 tests)
-- `tests/mergeOrder-with-fixtures.spec.ts` (7.2KB, 16 tests)
-
-### Total
-
-- **20 new files**
-- **~83KB of code**
-- **74 new tests**
-
-## Next Steps (Recommendations)
-
-1. **Migrate existing tests**: Gradually convert tests to use new fixtures
-2. **Expand fixtures**: Add more scenarios as patterns emerge
-3. **Integration**: Use fixtures in CI/CD testing
-4. **Documentation**: Add fixtures to developer onboarding docs
-5. **Performance**: Consider caching for large fixture generation
-
-## Acceptance Criteria Met
-
-✅ New directory: `tests/fixtures/` with organized structure
-✅ Shared fixture factory functions for common scenarios
-✅ Realistic sample plans (simple, complex, with dependencies, cyclic)
-✅ Mock PR data (titles, bodies, labels, dependencies)
-✅ Mock gate results (pass, fail, mixed scenarios)
-✅ Fixture utilities for temporary directories and cleanup
-✅ Documentation for using fixtures in tests
-✅ Examples showing fixture usage in existing tests
-✅ All fixtures pass schema validation
-✅ Cleanup utilities work correctly
-✅ Each fixture's purpose and usage documented
-
-## Success Metrics
-
-- **Test Coverage**: 74 new tests, 100% pass rate
-- **Code Quality**: 0 TypeScript errors, 0 lint issues
-- **Determinism**: 100% of fixtures produce consistent results
-- **Type Safety**: 100% typed, no `any` usage
-- **Documentation**: 400+ lines of comprehensive docs
-- **No Regressions**: All existing tests still pass