@smartergpt/lexrunner 1.0.0

package/docs/commands/idea.md

@@ -0,0 +1,253 @@
+# lex-pr idea - Feature Idea Capture
+
+The `lex-pr idea` command provides an interactive workflow for capturing feature ideas, generating Feature Spec v0 documents, and creating/updating GitHub Idea Issues with idempotent fingerprinting.
+
+## Overview
+
+This command is part of the front-end capture pipeline that helps teams:
+
+1. Quickly capture feature ideas with structured metadata
+2. Generate machine-readable Feature Spec v0 JSON documents
+3. Create GitHub Issues with the `[IDEA]` prefix and `idea`, `needs-triage` labels
+4. Update existing Issues idempotently using content fingerprinting
+
+## Usage
+
+### Interactive Mode (Default)
+
+```bash
+lex-pr idea
+```
+
+Prompts for:
+
+- Feature title (required)
+- Brief description (required)
+- Acceptance criteria (one per line, optional)
+- Technical context (optional)
+- Constraints (optional)
+
+### Non-Interactive Mode
+
+```bash
+lex-pr idea \
+  --title "Add dark mode support" \
+  --description "Implement dark mode theme switcher" \
+  --repo "owner/repo"
+```
+
+### Dry Run (Generate Spec Without Creating Issue)
+
+```bash
+lex-pr idea \
+  --title "Feature title" \
+  --description "Feature description" \
+  --repo "owner/repo" \
+  --dry-run
+```
+
+### Update Existing Issue
+
+```bash
+# Updates Issue #123 only if content fingerprint changed
+lex-pr idea \
+  --title "Updated feature title" \
+  --description "Updated description" \
+  --repo "owner/repo" \
+  --update-issue 123
+```
+
+## Options
+
+| Option                   | Description                               | Default                                                         |
+| ------------------------ | ----------------------------------------- | --------------------------------------------------------------- |
+| `--title <string>`       | Idea title                                | Interactive prompt                                              |
+| `--description <string>` | Brief description                         | Interactive prompt                                              |
+| `--interactive`          | Force interactive mode                    | `true` if no title/description                                  |
+| `--dry-run`              | Generate spec without creating Issue      | `false`                                                         |
+| `--template <path>`      | Custom prompt template path               | (future enhancement)                                            |
+| `--output <path>`        | Output path for Feature Spec v0           | `.smartergpt.local/deliverables/_session/idea-{timestamp}.json` |
+| `--repo <owner/repo>`    | Target repository                         | Auto-detected from git remote                                   |
+| `--label <label>`        | Additional labels (repeatable)            | `[]`                                                            |
+| `--update-issue <num>`   | Update existing Issue instead of creating | (none)                                                          |
+
+## Feature Spec v0 Schema
+
+Generated JSON documents conform to the Feature Spec v0 schema:
+
+```json
+{
+  "schemaVersion": "0.1.0",
+  "title": "Add dark mode support",
+  "description": "Implement dark mode theme switcher",
+  "acceptanceCriteria": [
+    "User can toggle between light and dark themes",
+    "Theme preference persists across sessions",
+    "All UI components respect theme setting"
+  ],
+  "technicalContext": "Uses CSS variables for theming",
+  "constraints": "Must work in all supported browsers",
+  "repo": "Guffawaffle/LexRunner",
+  "createdAt": "2025-11-09T21:26:56.362Z"
+}
+```
+
+## Fingerprinting for Idempotency
+
+The command generates a deterministic SHA-256 fingerprint from:
+
+- Title
+- Description
+- Acceptance criteria
+
+The fingerprint is injected as a hidden HTML comment in the Issue body:
+
+```markdown
+<!-- fingerprint:d158c1280857f3a5 -->
+```
+
+When updating an Issue with `--update-issue`, the command:
+
+1. Fetches the existing Issue
+2. Extracts its fingerprint
+3. Compares with the new fingerprint
+4. Updates only if fingerprints differ
+
+This prevents unnecessary API calls and Issue edit history noise.
+
+## Issue Format
+
+Created Issues have:
+
+- Title: `[IDEA] {feature title}`
+- Labels: `idea`, `needs-triage`, plus any from `--label`
+- Body sections:
+  - Description
+  - Acceptance Criteria (if provided)
+  - Technical Context (if provided)
+  - Constraints (if provided)
+  - Metadata (repo, created date, schema version)
+  - Hidden fingerprint comment
+
+## Environment Variables
+
+- `GITHUB_TOKEN` - Required for Issue creation/updates (not needed for `--dry-run`)
+
+## Examples
+
+### Basic Interactive Usage
+
+```bash
+$ lex-pr idea
+🎯 Feature Idea Capture
+
+Feature title: Add dark mode support
+Brief description: Implement theme switcher
+Acceptance criteria (enter one per line, empty line to finish):
+  1. User can toggle themes
+  2. Theme persists
+  3.
+Technical context (optional, press Enter to skip): CSS variables
+Constraints (optional, press Enter to skip):
+
+Fingerprint: d158c1280857f3a5
+✓ Feature Spec v0 written to: .smartergpt.local/deliverables/_session/idea-2025-11-09T21-26-56-365Z.json
+✓ Idea Issue created: https://github.com/owner/repo/issues/42
+  Issue #42
+```
+
+### Generate Spec Without Creating Issue
+
+```bash
+$ lex-pr idea \
+  --title "Add API rate limiting" \
+  --description "Implement rate limiting middleware" \
+  --repo "owner/api-server" \
+  --dry-run
+
+Fingerprint: abc123def4567890
+✓ Feature Spec v0 written to: .smartergpt.local/deliverables/_session/idea-2025-11-09T21-30-00-000Z.json
+
+Dry run: Issue not created/updated
+```
+
+### Update Existing Issue
+
+```bash
+$ lex-pr idea \
+  --title "Add API rate limiting (updated)" \
+  --description "Implement rate limiting with Redis backend" \
+  --update-issue 42
+
+Fingerprint: xyz789abc1234567
+Updating Issue #42 (fingerprint changed)
+✓ Issue #42 updated
+```
+
+## Output Paths
+
+By default, Feature Spec v0 files are written to:
+
+```
+.smartergpt.local/deliverables/_session/idea-{timestamp}.json
+```
+
+You can customize with `--output`:
+
+```bash
+lex-pr idea \
+  --title "..." \
+  --description "..." \
+  --output /tmp/my-idea.json \
+  --dry-run
+```
+
+**Security Note:** The command rejects writes to PR artifact directories (e.g., `.smartergpt/deliverables/pr-*`) to prevent accidental overwrites.
+
+## Error Handling
+
+### Missing GITHUB_TOKEN
+
+```bash
+$ lex-pr idea --title "..." --description "..."
+Error: GITHUB_TOKEN environment variable required
+Set GITHUB_TOKEN or use --dry-run to generate spec only
+```
+
+### Unsafe Output Path
+
+```bash
+$ lex-pr idea --title "..." --description "..." --output .smartergpt/deliverables/pr-123/idea.json
+Error: Cannot write to PR artifact directories
+```
+
+### Not a Git Repository
+
+```bash
+$ lex-pr idea --title "..." --description "..."
+Error: Not a git repository or no origin remote configured. Use --repo flag to specify repository.
+```
+
+## Integration with Workflow
+
+The idea command fits into the broader lexrunner workflow:
+
+1. **Ideate**: `lex-pr idea` - Capture feature ideas as GitHub Issues
+2. **Discover**: `lex-pr discover` - Find open PRs matching scope
+3. **Plan**: `lex-pr plan --from-github` - Generate merge plan
+4. **Review**: `lex-pr plan-review plan.json` - Review and edit
+5. **Execute**: `lex-pr execute plan.json` - Run quality gates
+6. **Report**: `lex-pr report artifacts` - Generate reports
+
+## Future Enhancements
+
+- Custom prompt templates (via `--template` flag)
+- AI-powered acceptance criteria generation
+- Integration with `lex-pr create-project` for converting ideas to projects
+- Batch idea import from various sources
+
+## See Also
+
+- [Feature Spec v0 Schema](../../src/schemas/feature-spec-v0.ts)
+- [Fingerprint Utilities](../../src/utils/fingerprint.ts)
+- [GitHub Integration](../../src/github/client.ts)

package/docs/config.md

@@ -0,0 +1,245 @@
+# Configuration Management
+
+Complete guide to lexrunner configuration layering, inspection, and precedence rules.
+
+> **📖 See Also**:
+>
+> - [Profile Resolution](./profile-resolution.md) - Profile directory resolution and management
+> - [CLI Reference](./cli.md) - Complete CLI command reference
+
+## Overview
+
+The lexrunner uses a layered configuration system that allows you to:
+
+- Define configuration in multiple files with clear precedence rules
+- Inspect merged configuration with provenance tracking
+- Understand which file sets each configuration value
+
+## Configuration Files
+
+Configuration is loaded from the `.smartergpt/` directory in the following precedence order (highest to lowest):
+
+1. **`stack.yml`** - Highest precedence, defines complete stack configuration
+2. **`scope.yml`** - Fallback for discovery and target settings
+3. **`deps.yml`** - Future support for dependency-only definitions
+
+### File Precedence Rules
+
+- If `stack.yml` exists, it takes precedence for all settings
+- If `stack.yml` doesn't exist, the system falls back to `scope.yml` + `deps.yml`
+- Missing files are tracked but don't cause errors
+
+## Configuration Inspection
+
+### `config:inspect` Command
+
+Display the merged configuration with provenance map showing which file provides each value.
+
+```bash
+lex-pr config:inspect [options]
+
+Options:
+  --json     Output canonical JSON format (deterministic, sorted keys)
+  -h, --help Display help for command
+```
+
+### Human-Readable Output
+
+```bash
+$ lex-pr config:inspect
+
+📋 Configuration Inspection
+
+Configuration:
+  Version: 1
+  Target: main
+  Items: 3
+
+Provenance Map:
+  target: stack.yml
+  version: stack.yml
+
+Configuration Sources:
+  ✓ stack.yml
+  ✗ scope.yml
+  ✗ deps.yml
+```
+
+### JSON Output
+
+The `--json` flag outputs deterministic JSON with sorted keys:
+
+```bash
+$ lex-pr config:inspect --json
+```
+
+```json
+{
+  "config": {
+    "items": [...],
+    "target": "main",
+    "version": 1
+  },
+  "provenance": {
+    "target": "stack.yml",
+    "version": "stack.yml"
+  },
+  "sources": [
+    {
+      "exists": true,
+      "file": "stack.yml"
+    }
+  ]
+}
+```
+
+## Layering Examples
+
+### Example 1: Stack-Only Configuration
+
+When only `stack.yml` exists:
+
+```yaml
+# .smartergpt/stack.yml
+version: 1
+target: main
+items:
+  - id: 1
+    branch: feature/auth
+    deps: []
+    strategy: merge-weave
+```
+
+**Provenance:**
+
+- `version`: stack.yml
+- `target`: stack.yml
+- All item settings from stack.yml
+
+### Example 2: Scope Fallback
+
+When `stack.yml` doesn't exist but `scope.yml` does:
+
+```yaml
+# .smartergpt/scope.yml
+version: 1
+target: staging
+sources:
+  - query: "is:open label:stack:*"
+```
+
+**Provenance:**
+
+- `version`: scope.yml
+- `target`: scope.yml
+
+### Example 3: Stack Overrides Scope
+
+When both files exist, `stack.yml` takes precedence:
+
+```yaml
+# .smartergpt/scope.yml
+version: 2
+target: staging
+```
+
+```yaml
+# .smartergpt/stack.yml
+version: 1
+target: main
+items: []
+```
+
+**Result:**
+
+- `version`: 1 (from stack.yml)
+- `target`: main (from stack.yml)
+- Stack completely overrides scope settings
+
+## Use Cases
+
+### Debugging Configuration
+
+Understand where each configuration value comes from:
+
+```bash
+lex-pr config:inspect
+```
+
+### CI/CD Validation
+
+Verify configuration in automated pipelines with deterministic output:
+
+```bash
+lex-pr config:inspect --json | jq '.config.target'
+# Output: "main"
+```
+
+### Configuration Auditing
+
+Track which files are being used:
+
+```bash
+lex-pr config:inspect --json | jq '.sources'
+```
+
+## Deterministic Output
+
+The `config:inspect --json` command ensures:
+
+- **Stable key ordering** - All object keys are sorted alphabetically
+- **Consistent formatting** - 2-space indentation, trailing newline
+- **Byte-for-byte identical output** - Same input always produces identical output
+
+This makes it ideal for:
+
+- CI/CD pipelines that check configuration changes
+- Git diffs that track configuration evolution
+- Automated testing and validation
+
+## Best Practices
+
+1. **Use stack.yml for complete definitions** - When you have a fully-defined stack
+2. **Use scope.yml for discovery** - When auto-discovering PRs from GitHub
+3. **Inspect before executing** - Always verify merged configuration before running gates
+4. **Track provenance in issues** - Include provenance output when reporting configuration bugs
+
+## Troubleshooting
+
+### "No configuration found"
+
+All configuration files are missing. Solution:
+
+```bash
+# Create a minimal stack.yml
+cat > .smartergpt/stack.yml << EOF
+version: 1
+target: main
+items: []
+EOF
+```
+
+### Unexpected configuration values
+
+Use `config:inspect` to understand precedence:
+
+```bash
+lex-pr config:inspect --json | jq '.provenance'
+```
+
+### Configuration not updating
+
+Check which file has precedence:
+
+```bash
+lex-pr config:inspect
+# Look for ✓ marks to see which files exist
+```
+
+---
+
+**Next Steps:**
+
+- Read [CLI Reference](./cli.md) for all command details
+- See [Profile Resolution](./profile-resolution.md) for directory management
+- Check [Troubleshooting](./troubleshooting.md) for common issues

package/docs/conflict-clustering.md

@@ -0,0 +1,225 @@
+# Conflict Clustering
+
+**Parser-lite conflict clustering with rename and whitespace awareness**
+
+## Overview
+
+The conflict clustering feature groups merge conflicts by file and affected symbols (functions, classes, interfaces, etc.), helping to understand the scope and nature of conflicts before resolving them.
+
+## Features
+
+- **Parser-lite symbol extraction**: Extracts symbols from TypeScript/JavaScript code using regex patterns
+- **Rename detection**: Identifies potential renames by comparing normalized function signatures
+- **Whitespace normalization**: Compares code without whitespace differences
+- **File + symbol grouping**: Clusters conflicts by affected files and symbols
+- **Deterministic output**: Stable JSON ordering for reproducibility
+
+## Usage
+
+### CLI
+
+```bash
+# Enable conflict clustering
+lex-pr orchestrate:predict-conflicts --prs 166,167,168 --enable-clustering
+
+# Write clustered conflicts to .weave/conflicts.json
+lex-pr orchestrate:predict-conflicts --prs 166,167,168 \
+  --enable-clustering --write-weave-conflicts
+
+# JSON output with clustering details
+lex-pr --json orchestrate:predict-conflicts --prs 166,167,168 \
+  --enable-clustering > report.json
+```
+
+### Programmatic API
+
+```typescript
+import {
+  clusterConflicts,
+  generateClusteredReport,
+  writeConflictsJson,
+} from "./orchestration/conflictClustering.js";
+
+// Example: Cluster conflicts from merge-tree simulation
+const conflicts = [
+  { file: "src/example.ts", lines: "10-20", type: "both-modified" },
+  { file: "src/utils.ts", lines: "5-15", type: "both-modified" },
+];
+
+// Generate clustered report
+const report = await generateClusteredReport(conflicts, "main", "/path/to/repo");
+
+// Write to .weave/conflicts.json
+await writeConflictsJson(report, ".weave");
+```
+
+## Output Format
+
+### `.weave/conflicts.json`
+
+```json
+{
+  "analyzedAt": "2025-11-10T08:00:00.000Z",
+  "baseBranch": "main",
+  "clusters": [
+    {
+      "file": "src/example.ts",
+      "symbols": ["calculateTotal", "ShoppingCart"],
+      "conflictType": "both-modified",
+      "details": {
+        "lineRange": "10-20",
+        "affectedSymbols": [
+          {
+            "name": "calculateTotal",
+            "type": "function",
+            "line": 12,
+            "signature": "export function calculatetotal(items:item[]):number"
+          }
+        ]
+      }
+    }
+  ],
+  "summary": {
+    "totalClusters": 1,
+    "fileCount": 1,
+    "symbolCount": 2,
+    "conflictTypes": {
+      "both-modified": 1
+    }
+  }
+}
+```
+
+### Human-Readable Output
+
+```
+🔬 Conflict Clustering Analysis:
+  Analyzed 2 conflict cluster(s) across 2 file(s)
+  Affected 3 symbol(s)
+
+  Top Conflict Clusters:
+  ⚠️ src/example.ts (both-modified)
+    Lines: 10-20
+    Symbols: calculateTotal, ShoppingCart
+
+  🔄 src/utils.ts (rename)
+    Lines: 5-15
+    Symbols: oldHelper, newHelper
+
+  Conflict Type Breakdown:
+    - both-modified: 1
+    - rename: 1
+```
+
+## Conflict Types
+
+- **both-modified**: Standard merge conflict (both sides modified)
+- **rename**: Detected potential rename (same signature, different name)
+- **whitespace**: Primarily whitespace differences
+- **mixed**: Combination of multiple conflict types
+
+## Symbol Extraction
+
+Supports TypeScript/JavaScript symbols:
+
+- Function declarations: `function name() {}`
+- Arrow functions: `const name = () => {}`
+- Classes: `class Name {}`
+- Interfaces: `interface Name {}`
+- Types: `type Name = ...`
+- Imports: `import { x } from "..."`
+- Exports: `export { x }`
+
+## Rename Detection
+
+Two symbols are considered potential renames if:
+
+1. Same symbol type (e.g., both functions)
+2. Different names
+3. Identical signatures after removing the name
+
+Example:
+
+```typescript
+// Likely a rename
+function oldCalculate(x: number): number {
+  return x * 2;
+}
+function newCalculate(x: number): number {
+  return x * 2;
+}
+```
+
+## Whitespace Normalization
+
+Normalization rules:
+
+- Line endings: `\r\n` → `\n`
+- Tabs: `\t` → `  ` (2 spaces)
+- Trailing whitespace: removed
+- Multiple spaces: collapsed to single space in signatures
+- Case-insensitive for signature comparison
+
+## Integration with Conflict Predictor
+
+The conflict clustering integrates with the existing conflict prediction system:
+
+```typescript
+import { predictConflicts } from "./orchestration/conflictPredictor.js";
+
+const report = await predictConflicts({
+  prs: [
+    { number: 166, files: ["src/cli.ts"], head: "abc123" },
+    { number: 167, files: ["src/cli.ts"], head: "def456" },
+  ],
+  baseBranch: "main",
+  prHeads: new Map([
+    ["166", "abc123"],
+    ["167", "def456"],
+  ]),
+  enableClustering: true,
+  writeWeaveConflicts: true,
+});
+
+// Access clustered report
+console.log(report.clusteredReport);
+```
+
+## Testing
+
+Run conflict clustering tests:
+
+```bash
+# Unit tests
+npm test -- tests/conflictClustering.spec.ts
+
+# Integration tests
+npm test -- tests/conflictPredictor.spec.ts
+
+# E2E tests
+npm test -- tests/conflictClustering-e2e.spec.ts
+
+# All conflict-related tests
+npm test -- tests/conflict*.spec.ts
+```
+
+## Limitations
+
+1. **Language support**: Currently optimized for TypeScript/JavaScript
+2. **Parser-lite approach**: Uses regex, not a full AST parser
+3. **Symbol proximity**: Uses line-based proximity (5-line buffer)
+4. **Rename heuristics**: May produce false positives for similar signatures
+
+## Future Enhancements
+
+- Support for additional languages (Python, Go, Rust, etc.)
+- AST-based parsing for higher accuracy
+- Symbol dependency analysis
+- Conflict resolution suggestions
+- ML-based rename detection
+
+## Related Documentation
+
+- [Conflict Predictor](./conflict-predictor.md)
+- [Merge-Tree Simulator](./MERGE_WEAVE_SUMMARY.md)
+- [CLI Reference](./cli.md)