@smartergpt/lexrunner 1.0.0 → 1.3.0

package/docs/counter-examples.md

@@ -1,199 +0,0 @@
-# Counter-Example Capture (LR-TSF-003)
-
-Automatic failure capture for learning loop closure. When gates fail, lexrunner can prompt to record the failure as a counter-example, which can later feed into constraint refinement.
-
-## Overview
-
-Counter-examples are structured records of execution failures that include:
-
-- What failed (gate, merge, validation)
-- Execution context (plan, run ID, constraints, scope)
-- User classification (transient, gap, false-positive, unknown)
-- Related constraints for learning
-
-## Usage
-
-### During Execution
-
-When a gate fails during execution, lexrunner can be configured to prompt for counter-example recording:
-
-```bash
-# Interactive mode - prompts after each failure
-lexrunner merge-weave --plan plan.json --record-failures interactive
-
-# Auto mode - automatically records as 'unknown'
-lexrunner merge-weave --plan plan.json --record-failures auto
-
-# Disabled (default)
-lexrunner merge-weave --plan plan.json
-```
-
-### Interactive Prompt
-
-When a gate fails with `--record-failures interactive`, you'll see:
-
-```
-❌ Gate Failure Detected
-
-Gate: test
-Error: Coverage below 80%
-
-Would you like to record this failure as a counter-example?
-This helps improve future constraint derivation.
-
-[1] Yes - Transient failure (don't learn from this)
-[2] Yes - Constraint gap (should have caught this)
-[3] Yes - False positive (constraint too strict)
-[4] No - Skip recording
-
-Choose option [1-4]:
-```
-
-### Listing Counter-Examples
-
-```bash
-# List all recorded counter-examples (table format)
-lexrunner counter-examples list
-
-# List in JSON format
-lexrunner counter-examples list --format json
-```
-
-### Viewing Details
-
-```bash
-# Show details of a specific counter-example
-lexrunner counter-examples show <id>
-```
-
-### Exporting for Analysis
-
-```bash
-# Export as JSON
-lexrunner counter-examples export --format json
-
-# Export as CSV
-lexrunner counter-examples export --format csv
-
-# Export to file
-lexrunner counter-examples export --format json --output counter-examples.json
-```
-
-## Storage
-
-Counter-examples are stored in `.lexrunner/counter-examples/`:
-
-```
-.lexrunner/counter-examples/
-├── 2026-01-02-test-gate-gate.json
-├── 2026-01-02-build-gate.json
-└── index.json
-```
-
-## Counter-Example Schema
-
-Each counter-example includes:
-
-```typescript
-{
-  id: string;              // Unique identifier (ULID)
-  timestamp: string;       // ISO 8601 timestamp
-
-  failure: {
-    type: "gate" | "merge" | "validation";
-    target: string;        // Gate name, PR number, etc.
-    error: string;         // Error message
-    exitCode?: number;     // Process exit code
-  };
-
-  context: {
-    plan: string;          // Plan file path
-    runId: string;         // Execution run ID
-    activeConstraints: string[];
-    scope: string[];
-  };
-
-  classification: {
-    type: "transient" | "gap" | "false-positive" | "unknown";
-    description: string;   // User-provided description
-    suggestedAction?: string;
-  };
-
-  relatedConstraints: string[];  // Inferred related constraints
-  shouldLearn: boolean;          // Whether to use for learning (false for transient)
-}
-```
-
-## Classification Types
-
-- **transient**: Temporary failures (network issues, flaky tests) - not used for learning
-- **gap**: Missing constraints that should have caught this
-- **false-positive**: Constraint is too strict and should be relaxed
-- **unknown**: Auto-recorded without user input
-
-## Integration with LexSona
-
-Counter-examples with `shouldLearn: true` can be fed into LexSona for rule learning:
-
-```typescript
-import { listCounterExamples } from "lexrunner/learning/storage";
-
-const counterExamples = listCounterExamples().filter((ce) => ce.shouldLearn);
-
-// Feed to LexSona for constraint refinement
-```
-
-## CLI Options
-
-| Option                          | Description                                          |
-| ------------------------------- | ---------------------------------------------------- |
-| `--record-failures`             | Enable counter-example recording (default: disabled) |
-| `--record-failures interactive` | Prompt user for classification                       |
-| `--record-failures auto`        | Auto-record as 'unknown'                             |
-| `--no-record-failures`          | Explicitly disable                                   |
-
-## Examples
-
-### Example 1: Record a test coverage gap
-
-```bash
-$ lexrunner merge-weave --plan plan.json --record-failures interactive
-
-ERROR: Gate 'test' failed for PR-123
-
-Would you like to record this failure as a counter-example?
-[2] Yes - Constraint gap (should have caught this)
-
-Describe what constraint gap this reveals: Missing test coverage requirement
-Suggested action: Add test-coverage-required constraint
-
-✓ Recorded counter-example: gap
-  Stored in: .lexrunner/counter-examples/2026-01-02-test-gate.json
-```
-
-### Example 2: Auto-record all failures
-
-```bash
-$ lexrunner merge-weave --plan plan.json --record-failures auto
-
-ERROR: Gate 'lint' failed for PR-456
-✓ Recorded counter-example: unknown
-  Stored in: .lexrunner/counter-examples/2026-01-02-lint-gate.json
-```
-
-### Example 3: Export for analysis
-
-```bash
-$ lexrunner counter-examples export --format csv > analysis.csv
-$ cat analysis.csv
-ID,Timestamp,Failure Type,Target,Classification,Should Learn,File Path
-01HK...,2026-01-02T04:30:00Z,gate,test,gap,true,2026-01-02-test-gate.json
-01HK...,2026-01-02T04:35:00Z,gate,lint,transient,false,2026-01-02-lint-gate.json
-```
-
-## Future Enhancements
-
-- Automatic pattern detection across counter-examples
-- Integration with LexSona for automated rule refinement
-- Counter-example deduplication
-- Trend analysis and reporting

package/docs/create-project.md

@@ -1,211 +0,0 @@
-# Create Project Command
-
-The `lex-pr create-project` command generates an Execution Plan v1 from a Feature Spec v0 and optionally creates GitHub Epic and Sub-Issues.
-
-## Synopsis
-
-```bash
-lex-pr create-project --spec <path> [OPTIONS]
-```
-
-## Description
-
-This command implements the front-end capture pipeline for feature planning:
-
-1. **Loads** Feature Spec v0 from a JSON file
-2. **Generates** Execution Plan v1 with Epic and Sub-Issues
-3. **Creates** GitHub Epic and Sub-Issues (unless --dry-run is specified)
-4. **Links** Sub-Issues to the parent Epic
-5. **Outputs** the Execution Plan to a file
-
-## Options
-
-| Option                    | Description                                   | Default                                                         |
-| ------------------------- | --------------------------------------------- | --------------------------------------------------------------- |
-| `--spec <path>`           | Feature Spec v0 file path (required)          | -                                                               |
-| `--dry-run`               | Generate plan without creating Issues         | `false`                                                         |
-| `--output <path>`         | Output path for Execution Plan v1             | `.smartergpt.local/deliverables/_session/plan-{timestamp}.json` |
-| `--repo <owner/repo>`     | Target repository                             | Auto-detect from spec                                           |
-| `--project <name/num>`    | Link Issues to GitHub Project                 | -                                                               |
-| `--epic-labels <labels>`  | Additional Epic labels (comma-separated)      | `[]`                                                            |
-| `--issue-labels <labels>` | Additional sub-issue labels (comma-separated) | `[]`                                                            |
-| `--no-link`               | Skip sub-issue linking to Epic                | `false`                                                         |
-
-## Feature Spec v0 Format
-
-A Feature Spec v0 file is a JSON document with the following structure:
-
-```json
-{
-  "title": "Feature Title",
-  "description": "Detailed feature description",
-  "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
-  "repo": "owner/repo",
-  "labels": ["enhancement", "priority-high"],
-  "priority": "high",
-  "estimatedComplexity": "complex"
-}
-```
-
-### Required Fields
-
-- `title` (string): Feature title
-- `description` (string): Detailed description
-- `acceptanceCriteria` (string[]): Array of acceptance criteria (at least one required)
-- `repo` (string): Target repository in format `owner/repo`
-
-### Optional Fields
-
-- `labels` (string[]): Labels to apply (default: `[]`)
-- `priority` ("low" | "medium" | "high" | "critical"): Priority level (default: `"medium"`)
-- `estimatedComplexity` ("simple" | "moderate" | "complex"): Complexity estimate
-- `schemaVersion` (string): Schema version (default: `"0.1.0"`)
-
-## Execution Plan v1 Format
-
-The generated Execution Plan v1 contains:
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "sourceSpec": {
-    /* Feature Spec v0 */
-  },
-  "epic": {
-    "title": "Epic Title",
-    "description": "Epic description",
-    "acceptanceCriteria": ["..."]
-  },
-  "subIssues": [
-    {
-      "id": "feature-impl",
-      "title": "Implement Feature",
-      "description": "Core implementation",
-      "type": "feature",
-      "acceptanceCriteria": ["..."],
-      "dependsOn": []
-    },
-    {
-      "id": "tests",
-      "title": "Add tests",
-      "type": "testing",
-      "acceptanceCriteria": ["..."],
-      "dependsOn": ["feature-impl"]
-    },
-    {
-      "id": "docs",
-      "title": "Document feature",
-      "type": "docs",
-      "acceptanceCriteria": ["..."],
-      "dependsOn": ["feature-impl"]
-    }
-  ],
-  "createdAt": "2025-11-09T12:00:00.000Z"
-}
-```
-
-## Examples
-
-### Dry Run (Generate Plan Only)
-
-```bash
-lex-pr create-project \
-  --spec ./feature-spec.json \
-  --dry-run
-```
-
-This validates the Feature Spec and generates an Execution Plan without creating GitHub Issues.
-
-### Create Epic and Sub-Issues
-
-```bash
-export GITHUB_TOKEN=ghp_...
-lex-pr create-project \
-  --spec ./feature-spec.json \
-  --repo "owner/repo" \
-  --epic-labels "phase-1,priority-high" \
-  --issue-labels "sprint-3"
-```
-
-### Custom Output Path
-
-```bash
-lex-pr create-project \
-  --spec ./feature-spec.json \
-  --dry-run \
-  --output /tmp/execution-plan.json
-```
-
-### Without Sub-Issue Linking
-
-```bash
-export GITHUB_TOKEN=ghp_...
-lex-pr create-project \
-  --spec ./feature-spec.json \
-  --no-link
-```
-
-## Workflow
-
-1. **Create Feature Spec v0**:
-
-   ```bash
-   cat > feature-spec.json << EOF
-   {
-     "title": "Add User Authentication",
-     "description": "Implement JWT-based authentication",
-     "acceptanceCriteria": [
-       "Users can register",
-       "Users can log in",
-       "Tokens are validated"
-     ],
-     "repo": "owner/repo"
-   }
-   EOF
-   ```
-
-2. **Generate and Review Plan** (dry run):
-
-   ```bash
-   lex-pr create-project --spec feature-spec.json --dry-run
-   ```
-
-3. **Create GitHub Issues**:
-   ```bash
-   export GITHUB_TOKEN=ghp_...
-   lex-pr create-project --spec feature-spec.json
-   ```
-
-## Error Handling
-
-The command performs comprehensive validation:
-
-- **Missing GITHUB_TOKEN**: If not in dry-run mode and `GITHUB_TOKEN` is not set, exits with error
-- **Invalid Feature Spec**: Validates against Feature Spec v0 schema, shows detailed validation errors
-- **Invalid Output Path**: Rejects writes to PR artifact directories (e.g., `/path/pr-123/`)
-- **Invalid Repository Format**: Ensures `repo` field matches `owner/repo` format
-
-## Dependencies
-
-This command depends on:
-
-- Feature Spec v0 schema (from `@guffawaffle/lex` or local definitions)
-- Execution Plan v1 schema (from `@guffawaffle/lex` or local definitions)
-- GitHub API access via `@octokit/rest`
-
-## Security
-
-- Never commits the generated Execution Plan to version control by default (uses `.smartergpt.local/`)
-- Requires `GITHUB_TOKEN` with appropriate permissions to create issues
-- Validates paths to prevent writing to protected directories
-
-## Exit Codes
-
-- `0`: Success
-- `1`: Error (validation failure, missing token, invalid path, etc.)
-
-## See Also
-
-- [CLI Documentation](./cli.md)
-- [Feature Spec v0 Schema](../src/schemas/project.ts)
-- [Execution Plan v1 Schema](../src/schemas/project.ts)

package/docs/deliverables-generator.md

@@ -1,299 +0,0 @@
-# Deliverables Generator
-
-Auto-generates merge-weave deliverables with plan hashing and toolchain manifests for full auditability.
-
-## Overview
-
-The deliverables generator creates structured documentation for merge-weave operations, including:
-
-- **Plan Hash**: SHA256 hash of canonical plan.json for reproducibility verification
-- **Toolchain Manifest**: Captured tool versions and environment for deterministic execution
-- **Gate Deliverables**: Markdown templates for each orchestration gate (GATE0-GATE5)
-- **Summary**: Comprehensive batch summary with metrics and metadata
-
-## Usage
-
-### Basic Command
-
-```bash
-lex-pr orchestrate:generate-deliverables --batch <batchId> --plan <path-to-plan.json>
-```
-
-### Options
-
-- `--batch <batchId>` (required): Batch identifier (e.g., `batch3`, `sprint-2025-Q1`)
-- `--plan <path>`: Path to plan.json file (default: `plan.json`)
-- `--output-dir <path>`: Output directory for deliverables (default: `.smartergpt.local/deliverables/<batch-id>`)
-
-### Examples
-
-#### Generate deliverables for batch3
-
-```bash
-lex-pr orchestrate:generate-deliverables \
-  --batch batch3 \
-  --plan batch3-plan.json \
-  --output-dir .smartergpt.local/deliverables/batch3
-```
-
-#### Use default output directory
-
-```bash
-lex-pr orchestrate:generate-deliverables \
-  --batch batch3 \
-  --plan batch3-plan.json
-# Output: .smartergpt.local/deliverables/batch3/
-```
-
-## Generated Files
-
-### Directory Structure
-
-```
-.smartergpt.local/deliverables/batch3/
-├── plan.json              # Copy of input plan
-├── plan-hash.txt          # SHA256 hash + timestamp
-├── toolchain-manifest.json # Tool versions and environment
-├── GATE0_preflight.md     # Batch overview, issue list, dependencies
-├── GATE1_assignment.md    # Agent assignments, timing
-├── GATE2_conflicts.md     # Conflict analysis
-├── GATE3_merge.md         # Merge execution log
-├── GATE4_gates.md         # Gate results (lint/type/test)
-├── GATE5_cleanup.md       # Branch cleanup, PR closure
-└── SUMMARY.md             # Full batch summary with metrics
-```
-
-### Plan Hash File Format
-
-**plan-hash.txt**:
-
-```
-SHA256: a3f2b9c8d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0
-Algorithm: SHA256
-Canonical JSON: true
-Generated: 2025-10-13T02:00:00Z
-Plan Version: 1.0.0
-```
-
-### Toolchain Manifest
-
-**toolchain-manifest.json**:
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "generated": "2025-10-13T02:00:00Z",
-  "tools": [
-    { "name": "git", "version": "2.45.2", "path": "/usr/bin/git" },
-    { "name": "Node.js", "version": "20.18.0", "path": "/usr/bin/node" },
-    { "name": "npm", "version": "10.8.2", "path": "/usr/bin/npm" },
-    { "name": "TypeScript", "version": "5.6.3" },
-    { "name": "ESLint", "version": "9.14.0" }
-  ],
-  "environment": {
-    "timezone": "UTC",
-    "locale": "en_US.UTF-8",
-    "platform": "linux",
-    "arch": "x64",
-    "nodeVersion": "20.18.0"
-  }
-}
-```
-
-### Summary with Plan Hash and Toolchain
-
-**SUMMARY.md** includes:
-
-```markdown
-## Plan Hash
-
-**SHA256:** `a3f2b9c8...`
-
-This hash uniquely identifies the plan.json used for this merge-weave.
-To verify reproducibility, compare this hash with a re-execution.
-
-## Toolchain
-
-| Tool       | Version |
-| ---------- | ------- |
-| git        | 2.45.2  |
-| Node.js    | 20.18.0 |
-| npm        | 10.8.2  |
-| TypeScript | 5.6.3   |
-| ESLint     | 9.14.0  |
-
-**Environment:** TZ=UTC, LANG=en_US.UTF-8
-
-Full manifest: `toolchain-manifest.json`
-```
-
-## Plan Hash Verification
-
-The plan hash is deterministic and can be used to verify reproducibility:
-
-1. **Generate deliverables twice** with the same plan
-2. **Compare hashes** in `plan-hash.txt`
-3. **Identical hashes** prove deterministic plan processing
-
-### Programmatic Hash Computation
-
-```typescript
-import { computePlanHash } from "./src/orchestration/deliverablesGenerator";
-import { Plan } from "./src/schema";
-
-const plan: Plan = {
-  /* your plan */
-};
-const hash = computePlanHash(plan);
-// Returns: SHA256 hex string (64 characters)
-```
-
-### Canonical JSON
-
-The hash uses canonical JSON serialization:
-
-- **Keys sorted alphabetically** (recursively)
-- **Deterministic serialization** (no whitespace variance)
-- **UTF-8 encoding** for consistent byte representation
-
-## Integration with Merge-Weave Workflow
-
-```bash
-# 1. Execute merge-weave
-lex-pr execute --plan batch3-plan.json
-
-# 2. Generate deliverables
-lex-pr orchestrate:generate-deliverables --batch batch3 --plan batch3-plan.json
-
-# 3. Commit to repository
-git add .smartergpt.local/deliverables/batch3/
-git commit -m "docs: Add batch3 merge-weave deliverables (plan hash: a3f2b9c8...)"
-```
-
-## API Reference
-
-### `generateDeliverables(options: DeliverablesOptions): Promise<void>`
-
-Generates full deliverables for a merge-weave batch.
-
-**Parameters:**
-
-- `options.batchId` (string): Batch identifier
-- `options.planPath` (string): Path to plan.json
-- `options.outputDir` (string): Output directory
-- `options.templateDir?` (string, optional): Custom template directory
-
-**Example:**
-
-```typescript
-import { generateDeliverables } from "./src/orchestration/deliverablesGenerator";
-
-await generateDeliverables({
-  batchId: "batch3",
-  planPath: "batch3-plan.json",
-  outputDir: ".smartergpt.local/deliverables/batch3",
-});
-```
-
-### `computePlanHash(plan: Plan): string`
-
-Computes SHA256 hash of canonical plan.json.
-
-**Returns:** 64-character hex string
-
-**Example:**
-
-```typescript
-import { computePlanHash } from "./src/orchestration/deliverablesGenerator";
-
-const hash = computePlanHash(plan);
-// "a3f2b9c8d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
-```
-
-### `generateToolchainManifest(): ToolchainManifest`
-
-Generates toolchain manifest with current environment and tool versions.
-
-**Returns:** `ToolchainManifest` object
-
-**Example:**
-
-```typescript
-import { generateToolchainManifest } from "./src/orchestration/toolchainManifest";
-
-const manifest = generateToolchainManifest();
-// { schemaVersion: "1.0.0", tools: [...], environment: {...} }
-```
-
-## Testing
-
-### Run Tests
-
-```bash
-# All deliverables tests
-npm test -- deliverables-generator.spec.ts
-
-# Toolchain manifest tests
-npm test -- toolchain-manifest.spec.ts
-
-# CLI integration tests
-npm test -- cli-deliverables-generator.spec.ts
-```
-
-### Test Fixtures
-
-Located in `tests/fixtures/deliverables/`:
-
-- `batch-example-plan.json`: Sample plan with 3 items and dependencies
-
-### Test Coverage
-
-- ✅ Plan hash determinism
-- ✅ Canonical JSON key ordering
-- ✅ All deliverable files generation
-- ✅ Toolchain manifest accuracy
-- ✅ CLI integration
-- ✅ Error handling
-- ✅ Custom batch IDs
-- ✅ Default output directory
-
-## Implementation Details
-
-### Canonical JSON Serialization
-
-Uses `canonicalJSONStringify()` from `src/util/canonicalJson.ts`:
-
-1. Recursively sorts object keys alphabetically
-2. Preserves array order (authored order)
-3. Deterministic output across executions
-
-### Toolchain Detection
-
-Detects tool versions via:
-
-- **Command execution**: `git --version`, `npm --version`
-- **package.json parsing**: TypeScript, ESLint, Prettier versions
-- **Process environment**: Node.js version, platform, arch
-
-### Template Generation
-
-Uses inline template strings (no external dependencies):
-
-- Simple string interpolation
-- Markdown formatting
-- Stable ordering for determinism
-
-## Related
-
-- **Epic #171**: Pyramid Orchestration Tools (Phase 2)
-- **Feature 7**: Determinism Framework (toolchain manifest)
-- **Feature 2**: Batch Planner (plan.json format)
-- **Feature 5**: Conflict Predictor (conflict data for GATE2)
-
-## Future Enhancements
-
-- [ ] Custom template support (Handlebars/Mustache)
-- [ ] Additional gate types (GATE6+)
-- [ ] Conflict data integration from Feature 5
-- [ ] Performance metrics tracking
-- [ ] Diff comparison between batch runs