@smartergpt/lexrunner 1.0.0

package/docs/counter-examples.md

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

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

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