@smartergpt/lexrunner 1.0.0 → 1.3.0

package/.smartergpt/fanout-templates.yml

@@ -1,263 +0,0 @@
-# Fanout Templates for LexRunner
-#
-# These templates define patterns to detect in merged PRs and
-# automatically create follow-up issues.
-#
-# Schema: version 1
-# Documentation: .smartergpt/docs/fanout-templates.md
-
-version: 1
-
-templates:
-  # ==========================================================================
-  # NEW MCP TOOL DETECTION
-  # ==========================================================================
-  - id: new-mcp-tool-test
-    description: "Create integration tests for new MCP tools"
-    trigger:
-      pattern: 'tools\.push\(\{\s*name:\s*[''"]([^''"]+)[''"]'
-      files:
-        - "**/tools.ts"
-        - "**/mcp/tools.ts"
-        - "**/server.ts"
-      captures:
-        tool_name: "$1"
-      requires_judgment: false
-    issue:
-      title: "test: Add integration tests for {tool_name} MCP tool"
-      labels:
-        - testing
-        - mcp
-      body: |
-        ## Summary
-
-        Add integration tests for the new `{tool_name}` MCP tool.
-
-        ## Context
-
-        Added in PR #{pr_number} ({pr_title}).
-
-        ## Acceptance Criteria
-
-        - [ ] Happy path test
-        - [ ] Error handling test
-        - [ ] Edge case coverage
-
-        ## Files to Create
-
-        - `tests/integration/mcp/{tool_name}.spec.ts`
-
-        ## Related
-
-        - PR: {pr_url}
-      repo: same
-    priority: 100
-
-  # ==========================================================================
-  # NEW ERROR CODE DOCUMENTATION
-  # ==========================================================================
-  - id: new-error-code-docs
-    description: "Document new error codes"
-    trigger:
-      pattern: 'ErrorCode\.(\w+)\s*='
-      files:
-        - "**/errors.ts"
-        - "**/error-codes.ts"
-      captures:
-        error_code: "$1"
-      requires_judgment: false
-    issue:
-      title: "docs: Document {error_code} error code"
-      labels:
-        - documentation
-      body: |
-        ## Summary
-
-        Document the new `{error_code}` error code.
-
-        ## Context
-
-        Added in PR #{pr_number}.
-
-        ## Acceptance Criteria
-
-        - [ ] Add to docs/error-codes.md
-        - [ ] Include suggested resolution steps
-        - [ ] Update TROUBLESHOOTING.md if user-facing
-
-        ## Related
-
-        - PR: {pr_url}
-      repo: same
-    priority: 80
-
-  # ==========================================================================
-  # NEW CLI COMMAND DOCUMENTATION
-  # ==========================================================================
-  - id: new-cli-command
-    description: "Document new CLI commands in QUICK_START"
-    trigger:
-      pattern: '\.command\([''"]([^''"]+)[''"]'
-      files:
-        - "**/cli/**/*.ts"
-        - "**/commands/**/*.ts"
-      captures:
-        command_name: "$1"
-      requires_judgment: false
-    issue:
-      title: "docs: Add {command_name} to QUICK_START.md"
-      labels:
-        - documentation
-      body: |
-        ## Summary
-
-        Document the new `{command_name}` CLI command.
-
-        ## Context
-
-        Added in PR #{pr_number}.
-
-        ## Acceptance Criteria
-
-        - [ ] Add usage example to QUICK_START.md
-        - [ ] Add to CLI reference in README.md
-        - [ ] Include common use cases
-
-        ## Related
-
-        - PR: {pr_url}
-      repo: same
-    priority: 70
-
-  # ==========================================================================
-  # CROSS-REPO API CHANGES (REQUIRES JUDGMENT)
-  # ==========================================================================
-  - id: cross-repo-api-change
-    description: "Coordinate API changes across consumer repos"
-    trigger:
-      pattern: 'export\s+(interface|type|function)\s+(\w+)'
-      files:
-        - "**/index.ts"
-      captures:
-        export_type: "$1"
-        export_name: "$2"
-      requires_judgment: true
-    issue:
-      title: "chore: Update {export_name} consumers"
-      labels:
-        - cross-repo
-        - api
-      body: |
-        ## Summary
-
-        Review and update consumers of `{export_name}` after API change.
-
-        ## Context
-
-        `{export_type} {export_name}` was modified in PR #{pr_number}.
-
-        **⚠️ This issue requires Senior Dev review** - assess whether
-        the change is breaking and identify affected consumers.
-
-        ## Consumer Repos
-
-        - [ ] Check lexsona
-        - [ ] Check lexrunner
-        - [ ] Check lex
-
-        ## Breaking Change Assessment
-
-        _Fill in after review:_
-        - [ ] Breaking change: Yes / No
-        - [ ] Consumers affected: (list)
-        - [ ] Migration needed: Yes / No
-
-        ## Related
-
-        - PR: {pr_url}
-      repo: Guffawaffle/lexrunner
-    priority: 50
-    enabled: true
-
-  # ==========================================================================
-  # NEW ZSCHEMA EXPORTS
-  # ==========================================================================
-  - id: new-zod-schema
-    description: "Create validation tests for new Zod schemas"
-    trigger:
-      pattern: 'export\s+const\s+(\w+Schema)\s*=\s*z\.'
-      files:
-        - "**/schema*.ts"
-        - "**/schemas/**/*.ts"
-      captures:
-        schema_name: "$1"
-      requires_judgment: false
-    issue:
-      title: "test: Add validation tests for {schema_name}"
-      labels:
-        - testing
-        - schema
-      body: |
-        ## Summary
-
-        Add validation tests for the new `{schema_name}` Zod schema.
-
-        ## Context
-
-        Added in PR #{pr_number}.
-
-        ## Acceptance Criteria
-
-        - [ ] Valid input test
-        - [ ] Invalid input rejection test
-        - [ ] Edge case coverage (nulls, empties, boundaries)
-        - [ ] Error message quality test
-
-        ## Related
-
-        - PR: {pr_url}
-      repo: same
-    priority: 90
-
-  # ==========================================================================
-  # NEW INTERVENTION TYPE
-  # ==========================================================================
-  - id: new-intervention-type
-    description: "Document new intervention types"
-    trigger:
-      pattern: '\|\s*[''"](\w+)[''"]'
-      files:
-        - "**/planner/types.ts"
-        - "**/intervention*.ts"
-      captures:
-        intervention_type: "$1"
-      requires_judgment: true
-    issue:
-      title: "docs: Document {intervention_type} intervention"
-      labels:
-        - documentation
-        - merge-weave
-      body: |
-        ## Summary
-
-        Document the new `{intervention_type}` intervention type.
-
-        ## Context
-
-        Added in PR #{pr_number}.
-
-        **⚠️ This requires review** - confirm this is a new intervention
-        type and not just a string match.
-
-        ## Acceptance Criteria
-
-        - [ ] Add to merge-weave-interventions.md
-        - [ ] Specify determinism level (D1/D2/D3)
-        - [ ] Document inputs/outputs
-        - [ ] Add usage examples
-
-        ## Related
-
-        - PR: {pr_url}
-      repo: same
-    priority: 60

package/.smartergpt/gates.yml

@@ -1,9 +0,0 @@
-version: 1
-levels:
-  default:
-    - name: lint
-      run: "npm run lint"
-    - name: typecheck
-      run: "npm run typecheck"
-    - name: unit
-      run: "npm test"

package/.smartergpt/intent.md

@@ -1 +0,0 @@
-Ship initial Lex-PR Runner scaffold: plan skeleton, CLI, MCP stub, canonical files, and weave philosophy.

package/.smartergpt/issues/QOL-001-analysis-script-filtering.md

@@ -1,36 +0,0 @@
-# QOL-001: Add Filtering & Formatting to Governance Log Analysis
-
-**Status**: Open
-**Priority**: Medium
-**Effort**: 2-3 hours
-**Category**: DX (Developer Experience)
-
-## Context
-
-The `analyze-governance-logs.mjs` script currently processes ALL logs and outputs plain text. For real usage, we need filtering and multiple output formats.
-
-## Acceptance Criteria
-
-- [ ] Add CLI flags: `--since <date>`, `--until <date>`, `--persona <id>`, `--workflow <id>`
-- [ ] Add `--format` flag supporting: `json`, `table`, `markdown`
-- [ ] Add `--disagreements-only` flag to show only logs where runner/LexSona disagree
-- [ ] Update script help text with examples
-- [ ] Add 2-3 tests for filtering logic
-
-## Example Usage
-
-```bash
-# Show only quality-first_engineering logs from last 7 days
-node scripts/analyze-governance-logs.mjs \
-  --since 2025-12-01 \
-  --persona quality-first_engineering \
-  --format markdown
-
-# Show disagreements only (where LexSona would block but runner allowed)
-node scripts/analyze-governance-logs.mjs --disagreements-only
-```
-
-## Non-Goals
-
-- Interactive TUI (keep it simple CLI for now)
-- Statistical modeling (just aggregation)

package/.smartergpt/issues/QOL-002-log-retention-policy.md

@@ -1,92 +0,0 @@
-# QOL-002: Implement Log Retention & Cleanup
-
-**Status**: ✅ Completed (2025-12-07)
-**Priority**: Low
-**Effort**: 2-4 hours (actual: 2h)
-**Category**: Operational Hygiene
-
-## Context
-
-Governance logs will accumulate over time. Need automatic cleanup to prevent unbounded disk usage.
-
-## Acceptance Criteria
-
-- [x] Add `maxLogAgeDays` config (default: 30 days)
-- [x] Add `maxLogSizeMB` config (default: 100 MB)
-- [x] Implement cleanup function in `src/lexsona/logger.ts`
-- [x] ~~Optionally compress old logs (`.json` → `.json.gz`)~~ (deferred - not needed yet)
-- [x] Run cleanup automatically before writing new logs
-- [x] Add `lex-pr governance:cleanup` CLI command for manual cleanup
-- [x] Add tests for retention logic
-
-## Implementation Details
-
-**Files Modified:**
-
-- `src/lexsona/logger.ts`: Added retention functions, async writeGovernanceLog
-  - `cleanupOldLogs(maxAgeDays)`: Deletes logs older than threshold
-  - `enforceRetentionPolicy(maxSizeMB)`: Deletes oldest logs if size exceeded
-  - `applyRetentionPolicy(config)`: Unified cleanup (called before writes)
-  - `getGovernanceLogsDir()`: Now exported for CLI usage
-  - `RetentionConfig` interface with optional maxAgeDays, maxSizeMB
-
-- `src/commands/governanceCleanup.ts`: NEW - Full CLI implementation
-  - `lex-pr governance:cleanup --stats`: Show log statistics
-  - `lex-pr governance:cleanup --dry-run`: Preview deletions
-  - `lex-pr governance:cleanup --max-age <days>`: Custom age threshold
-  - `lex-pr governance:cleanup --max-size <mb>`: Custom size threshold
-
-- `src/commands/merge.ts`: Updated to await writeGovernanceLog (now async)
-
-- `src/cli.ts`: Registered governanceCleanup command
-
-**Tests Added:**
-
-- `tests/governance-retention.spec.ts`: 8 comprehensive tests
-  - Age-based cleanup
-  - Size-based cleanup
-  - Edge cases (no logs, non-existent directory)
-  - Config resolution
-
-**Defaults:**
-
-- Max age: 30 days
-- Max size: 100 MB
-- Compression: Deferred (not implemented - add when disk usage becomes issue)
-- Cleanup: Automatic before every log write
-
-**CLI Examples:**
-
-```bash
-# Show current stats
-lex-pr governance:cleanup --stats
-
-# Preview cleanup
-lex-pr governance:cleanup --dry-run --max-age 7
-
-# Execute cleanup with custom thresholds
-lex-pr governance:cleanup --max-age 60 --max-size 200
-```
-
-## Example Config
-
-```yaml
-# .smartergpt/governance.yml
-retention:
-  maxAgeDays: 30
-  maxSizeMB: 100
-  compressionEnabled: true
-```
-
-## Non-Goals
-
-- Cloud storage integration (local disk only for now)
-- Complex archival strategies
-- Compression (deferred until needed)
-
-## Test Results
-
-✅ All 8 retention tests passing
-✅ All 13 integration tests passing (21 total)
-✅ CLI help and --stats working
-✅ Dry-run mode verified

package/.smartergpt/issues/QOL-003-realtime-console-feedback.md

@@ -1,44 +0,0 @@
-# QOL-003: Add Real-time Console Feedback for Shadow Mode
-
-**Status**: Open
-**Priority**: High
-**Effort**: 1-2 hours
-**Category**: DX (Developer Experience)
-
-## Context
-
-Currently, shadow mode silently logs to disk. Users have no immediate feedback about LexSona's opinion during execution. This makes it hard to notice disagreements.
-
-## Acceptance Criteria
-
-- [ ] After shadow derivation, print 1-line summary to console:
-  ```
-  [LexSona shadow] quality-first_engineering: 3 constraints, WOULD BLOCK (runner: allow)
-  [LexSona shadow] quality-first_engineering: 0 constraints, AGREES (runner: allow)
-  ```
-- [ ] Use colored output (yellow for disagreements, green for agreement)
-- [ ] Add `--quiet-shadow` flag to suppress console output
-- [ ] Update `src/lexsona/client.ts` to return summary string
-- [ ] Add unit test for summary formatting
-
-## Example Output
-
-```bash
-$ lex-pr merge-weave --plan test-plan.json
-
-Running gates...
-✓ lint passed
-✓ typecheck passed
-✓ test passed
-
-[LexSona shadow] quality-first_engineering: 2 constraints, AGREES (runner: allow)
-  - "Run full test suite before merge" (confidence: 0.85)
-  - "Verify no TODOs in diff" (confidence: 0.72)
-
-Merging PR-123...
-```
-
-## Non-Goals
-
-- Detailed constraint explanations in console (keep logs for that)
-- Interactive mode (shadow is observation-only)

package/.smartergpt/issues/QOL-004-governance-report-cli.md

@@ -1,44 +0,0 @@
-# QOL-004: Add `lex-pr governance:report` CLI Command
-
-**Status**: Open
-**Priority**: Medium
-**Effort**: 3-4 hours
-**Category**: Integration
-
-## Context
-
-The `analyze-governance-logs.mjs` script is a good start, but it's not discoverable and lives outside the main CLI. Users expect `lex-pr <command>` for all operations.
-
-## Acceptance Criteria
-
-- [ ] Create `src/commands/governanceReport.ts`
-- [ ] Wire into main CLI as `lex-pr governance:report`
-- [ ] Support same filtering flags as QOL-001
-- [ ] Add `--output <file>` flag to save report
-- [ ] Add `--top N` to show top N constraints/personas
-- [ ] Print to stdout by default (no file arg needed)
-- [ ] Add integration test for command
-
-## Example Usage
-
-```bash
-# Quick summary of all logs
-lex-pr governance:report
-
-# Detailed markdown report for last 7 days
-lex-pr governance:report --since 2025-12-01 --format markdown --output governance-report.md
-
-# Show top 5 most frequent constraints
-lex-pr governance:report --top 5
-```
-
-## Implementation Notes
-
-- Move logic from `scripts/analyze-governance-logs.mjs` into `src/lexsona/logger.ts`
-- Keep script as thin wrapper for backwards compat
-- Use Commander for CLI parsing
-
-## Non-Goals
-
-- Web UI or dashboard (CLI only)
-- Real-time streaming (batch processing is fine)

package/.smartergpt/issues/QOL-005-schema-versioning.md

@@ -1,46 +0,0 @@
-# QOL-005: Add Schema Versioning to Governance Logs
-
-**Status**: Open
-**Priority**: Low
-**Effort**: 1-2 hours
-**Category**: Future-proofing
-
-## Context
-
-Following the `plan.json` pattern, governance logs should include explicit schema versions for safe evolution.
-
-## Acceptance Criteria
-
-- [ ] Add `schemaVersion` field to `GovernanceComparisonLog` type
-- [ ] Set initial version to `"1.0.0"`
-- [ ] Update `createGovernanceComparisonLog()` to include version
-- [ ] Add validation in log reader to reject unknown major versions
-- [ ] Update existing test fixtures with schema version
-- [ ] Document versioning policy in `src/lexsona/types.ts`
-
-## Schema Version Policy
-
-Follow SemVer for governance log schema:
-
-- **Patch (1.0.x)**: Additive optional fields, docs only
-- **Minor (1.x.0)**: Additive required fields with safe defaults
-- **Major (x.0.0)**: Breaking changes to structure
-
-## Example Log (Updated)
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "id": "gov-01KBVZN705AQ4PWW024JCDV57C",
-  "timestamp": "2025-12-07T08:43:07.654Z",
-  "context": { ... },
-  "lexsona": { ... },
-  "runner": { ... },
-  "mode": "shadow"
-}
-```
-
-## Non-Goals
-
-- Migration scripts for old logs (acceptable to skip)
-- Multiple schema support in readers (just validate and fail fast)

package/.smartergpt/issues/QOL-006-debug-verbose-mode.md

@@ -1,45 +0,0 @@
-# QOL-006: Add Verbose Debug Mode for LexSona Integration
-
-**Status**: Open
-**Priority**: Low
-**Effort**: 2-3 hours
-**Category**: Debugging
-
-## Context
-
-When LexSona derivations fail or produce unexpected constraints, there's no way to see intermediate steps. Need verbose logging for troubleshooting.
-
-## Acceptance Criteria
-
-- [ ] Honor `LEXSONA_DEBUG=1` env var
-- [ ] Log to stderr (not to governance logs):
-  - Rules loaded count
-  - Filtered rules count (by scope/mode)
-  - Each constraint derivation step
-  - Confidence calculations
-  - Offline mode warnings
-- [ ] Add debug logs to `src/lexsona/client.ts`
-- [ ] Use `debug` npm package or simple `if (process.env.LEXSONA_DEBUG)`
-- [ ] Add example debug session to README or docs
-
-## Example Debug Output
-
-```bash
-$ LEXSONA_DEBUG=1 lex-pr merge-weave --plan test-plan.json
-
-[lexsona:debug] Loading persona: quality-first_engineering
-[lexsona:debug] Rules loaded: 12
-[lexsona:debug] Filtered by scope (merge-weave): 8 rules
-[lexsona:debug] Confidence threshold: 0.30
-[lexsona:debug] Deriving constraints...
-[lexsona:debug]   Rule "require-full-test-suite" -> constraint (confidence: 0.85)
-[lexsona:debug]   Rule "no-todos-in-pr" -> constraint (confidence: 0.72)
-[lexsona:debug]   Rule "verify-changelog" -> SKIPPED (confidence: 0.25 < 0.30)
-[lexsona:debug] Final: 2 constraints derived
-[lexsona:debug] Offline mode: true (no Lex DB connection)
-```
-
-## Non-Goals
-
-- Interactive debugger (just logs)
-- Performance profiling (separate concern)