@smartergpt/lexrunner 1.0.0

package/.smartergpt/issues/QOL-COMPLETION-REPORT.md

@@ -0,0 +1,359 @@
+# QoL Enhancement Suite - Completion Report
+
+**Date**: 2025-12-07
+**Version**: LexRunner 0.5.0
+**Scope**: Shadow Governance Quality of Life Improvements
+
+## Executive Summary
+
+Successfully implemented all 6 QoL enhancements for LexSona shadow governance integration, completing the full foundation roadmap across 3 waves. Total effort: ~18 hours (within estimated 19-21h range).
+
+## Completion Status: ✅ 6/6 (100%)
+
+### Wave 1: Immediate Usability (Completed)
+
+- ✅ **QOL-003**: Real-time Console Feedback (1-2h actual)
+- ✅ **QOL-001**: Analysis Script Filtering (2-3h actual)
+
+### Wave 2: Developer Experience (Completed)
+
+- ✅ **QOL-004**: CLI Governance Report Command (3-4h actual)
+- ✅ **QOL-005**: Schema Versioning (1-2h actual)
+
+### Wave 3: Operational Maturity (Completed)
+
+- ✅ **QOL-006**: Debug Verbose Mode (2-3h actual)
+- ✅ **QOL-002**: Log Retention & Cleanup (2h actual)
+
+## Test Coverage
+
+**Total Tests**: 21 (all passing)
+
+- LexSona Integration: 13 tests
+- Governance Retention: 8 tests
+
+**Test Files**:
+
+- `tests/lexsona-integration.spec.ts`
+- `tests/governance-retention.spec.ts`
+
+## Implementation Highlights
+
+### QOL-003: Real-time Console Feedback
+
+**Impact**: Immediate visibility into shadow governance results
+
+**Features**:
+
+- Colored console output (green = agree, yellow = disagree)
+- Offline mode warnings
+- Error state formatting
+- Log file path display
+- Global `--quiet` flag support (suppresses all console output)
+
+**Files**:
+
+- `src/lexsona/client.ts`: `formatShadowGovernanceSummary()`
+- `src/commands/merge.ts`: Integration with merge command
+- Tests: 4 new formatting tests
+
+**Example Output**:
+
+```
+✅ Shadow Governance: AGREEMENT
+   Both systems arrived at the same decision
+   Logged to: .smartergpt/runner/governance-logs/01JE...json
+```
+
+**Note**: Dedicated `--quiet-shadow` flag is deferred. Use global `--quiet` to suppress all output including shadow summaries.
+
+### QOL-001: Analysis Script Filtering
+
+**Impact**: Flexible log analysis for debugging and insights
+
+**Features**:
+
+- Time range filtering: `--since`, `--until`
+- Persona filtering: `--persona quality-first_engineering`
+- Workflow filtering: `--workflow merge-weave`
+- Disagreements only: `--disagreements-only`
+- Output formats: text (default), json, table, markdown
+- Top N results: `--top 10`
+
+**Files**:
+
+- `scripts/analyze-governance-logs.mjs`: **Thin wrapper (deprecated)** - delegates to CLI
+- Examples and help text included
+
+**Example Usage**:
+
+```bash
+# Markdown report of last week's disagreements
+node scripts/analyze-governance-logs.mjs \
+  --since 2025-12-01 \
+  --disagreements-only \
+  --format markdown \
+  --output report.md
+```
+
+**Note**: The script is a backwards-compatibility wrapper that delegates to `lex-pr governance:report`.
+Deprecation notice is sent to stderr to avoid breaking tooling that expects clean stdout.
+
+### QOL-004: CLI Governance Report Command
+
+**Impact**: Integrated analysis without standalone scripts
+
+**Features**:
+
+- Same filtering as standalone script
+- Same output formats
+- Built into `lex-pr` CLI
+- Consistent with other commands
+
+**Files**:
+
+- `src/commands/governanceReport.ts`: NEW command
+- `src/cli.ts`: Command registration
+
+**Example Usage**:
+
+```bash
+# Quick table view
+lex-pr governance:report --format table --top 5
+
+# JSON export
+lex-pr governance:report --format json --output data.json
+```
+
+### QOL-005: Schema Versioning
+
+**Impact**: Forward compatibility and validation
+
+**Features**:
+
+- SemVer schema versioning (v1.0.0)
+- Major version validation (rejects v2+)
+- Legacy log normalization with `--accept-legacy` flag
+- Best-effort backwards compatibility for pre-versioned logs (normalized as `0.0.0`)
+- Future-proof for schema evolution
+
+**Files**:
+
+- `src/lexsona/types.ts`: Added `schemaVersion` field
+- `src/lexsona/logger.ts`: `readGovernanceLogsWithLegacy()` with fail-forward normalization
+- `src/commands/governanceReport.ts`: `--accept-legacy` flag support
+- Tests: Updated to expect schema version
+
+**Validation Rules**:
+
+- Patch (1.0.x): Optional fields, docs changes
+- Minor (1.x.0): Required fields with defaults
+- Major (x.0.0): Breaking changes (rejected by v1 runner)
+
+**Legacy Handling**:
+
+- Logs without `schemaVersion` are normalized to `0.0.0` when using `--accept-legacy`
+- Missing fields reconstructed with reasonable defaults (offline mode, empty constraints)
+- Normalization warnings surfaced in verbose mode
+- Ensures analysis works with historical data while acknowledging uncertainty
+
+### QOL-006: Debug Verbose Mode
+
+**Impact**: Deep troubleshooting for constraint derivation
+
+**Features**:
+
+- Environment flag: `LEXSONA_DEBUG=1`
+- 15+ debug log points throughout derivation
+- stderr output (doesn't pollute stdout)
+- Covers: config, context, connection, derivation, constraints, errors
+
+**Files**:
+
+- `src/lexsona/client.ts`: `debugLog()` helper and 15+ call sites
+
+**Example Output**:
+
+```
+[lexsona:debug] deriveShadowConstraints() called
+[lexsona:debug]   Context: {"workflow":"merge-weave","item":"PR-123"}
+[lexsona:debug] Connecting to LexSona with persona: quality-first_engineering
+[lexsona:debug]   Lex DB: (none - offline mode)
+[lexsona:debug] Constraints derived successfully
+[lexsona:debug]   Total constraints: 0
+[lexsona:debug]   Offline mode: true
+```
+
+### QOL-002: Log Retention & Cleanup
+
+**Impact**: Prevent unbounded disk usage from accumulating logs
+
+**Features**:
+
+- Age-based cleanup (default: 30 days)
+- Size-based cleanup (default: 100 MB)
+- Automatic cleanup before log writes
+- Manual cleanup CLI command
+- Dry-run mode
+- Statistics view
+
+**Files**:
+
+- `src/lexsona/logger.ts`: Retention functions
+  - `cleanupOldLogs(maxAgeDays)`
+  - `enforceRetentionPolicy(maxSizeMB)`
+  - `applyRetentionPolicy(config)`
+  - `RetentionConfig` interface
+- `src/commands/governanceCleanup.ts`: NEW command
+- `src/cli.ts`: Command registration
+- Tests: 8 comprehensive retention tests
+
+**Example Usage**:
+
+```bash
+# Show current statistics
+lex-pr governance:cleanup --stats
+
+# Preview cleanup (dry-run)
+lex-pr governance:cleanup --dry-run --max-age 7
+
+# Execute cleanup with custom thresholds
+lex-pr governance:cleanup --max-age 60 --max-size 200
+```
+
+## Technical Debt Addressed
+
+1. **No real-time feedback** → Colored console summaries (QOL-003)
+2. **Manual JSON analysis** → Filtered scripts + CLI (QOL-001, QOL-004)
+3. **No schema versioning** → v1.0.0 with validation (QOL-005)
+4. **Hard to debug** → Debug mode with 15+ log points (QOL-006)
+5. **Log accumulation** → Automatic retention policy (QOL-002)
+
+## Build & Test Results
+
+**Build**: ✅ Clean (ESM + CJS + DTS)
+
+- ESM: ~475 KB
+- CJS: ~1.1 MB
+- DTS: ~62 KB
+
+**Tests**: ✅ 21/21 passing
+
+- Integration: 13/13
+- Retention: 8/8
+
+**CLI Commands**: ✅ All working
+
+- `governance:report --help`
+- `governance:cleanup --help`
+- `governance:cleanup --stats`
+
+## Documentation Updated
+
+- ✅ QOL-001 ticket: Marked complete with implementation details
+- ✅ QOL-002 ticket: Marked complete with implementation details
+- ✅ QOL-003 ticket: Marked complete with implementation details
+- ✅ QOL-004 ticket: Marked complete with implementation details
+- ✅ QOL-005 ticket: Marked complete with implementation details
+- ✅ QOL-006 ticket: Marked complete with implementation details
+
+## Next Steps (Recommendations)
+
+### Post-Consolidation Reality Check (2025-12-07)
+
+**Consolidated in This Wave**:
+
+- ✅ `governance:report` is now the canonical CLI command for analysis
+- ✅ `scripts/analyze-governance-logs.mjs` is a thin backwards-compatibility wrapper
+  - Delegates to `governance:report`
+  - Resolves CLI path relative to script location (works from any directory)
+  - Deprecation notice sent to stderr (doesn't pollute stdout)
+  - Exit codes and args properly passed through
+- ✅ Schema versioning is semver-based with legacy normalization via `--accept-legacy`
+- ✅ Global `--quiet` flag suppresses shadow governance console summaries
+
+**Deferred (Not Implemented)**:
+
+- ⏸️ Dedicated `--quiet-shadow` flag (use global `--quiet` for now)
+- ⏸️ Compression support for governance logs
+- ⏸️ Log rotation alongside retention
+- ⏸️ Cloud storage for historical logs
+
+**Test Coverage**:
+
+- ✅ 21 existing tests for governance features
+- ✅ 5 new tests for wrapper delegation behavior (surgical follow-up)
+
+### Immediate (No blockers)
+
+1. Monitor log retention behavior in real usage
+2. Collect feedback on console formatting colors/layout
+3. Validate schema version handling with future changes
+
+### Short-term (1-2 weeks)
+
+1. Add compression support if disk usage becomes issue
+2. Consider adding log rotation alongside retention
+3. Explore cloud storage for historical logs (if needed)
+
+### Long-term (1-2 months)
+
+1. Build dashboard for governance trends over time
+2. Add alerting for high disagreement rates
+3. Create governance reports for team retrospectives
+
+## Risk Assessment
+
+**Low Risk Items**:
+
+- All changes are additive (no breaking changes)
+- Tests provide good coverage (21 tests)
+- CLI follows existing patterns (modular commands)
+- Schema versioning prevents future breakage
+
+**Medium Risk Items**:
+
+- Retention policy could delete logs user wanted to keep
+  - Mitigation: Defaults are conservative (30 days, 100 MB)
+  - Mitigation: Dry-run mode for testing
+  - Mitigation: Manual CLI command for explicit control
+
+**No High Risk Items Identified**
+
+## Metrics
+
+**Code Quality**:
+
+- TypeScript strict mode: ✅
+- ESLint passing: ✅
+- Zero compiler errors: ✅
+- Test coverage: Comprehensive (21 tests)
+
+**Effort Accuracy**:
+
+- Estimated: 19-21h
+- Actual: ~18h
+- Variance: -5% (under estimate, good)
+
+**Value Delivered**:
+
+- 6 distinct features
+- 21 automated tests
+- 2 new CLI commands
+- 4 output formats
+- Full retention system
+- Debug instrumentation
+
+## Conclusion
+
+All 6 QoL enhancements completed successfully. Shadow governance is now production-ready with:
+
+- Real-time visibility (QOL-003)
+- Flexible analysis (QOL-001, QOL-004)
+- Schema stability (QOL-005)
+- Deep debugging (QOL-006)
+- Operational hygiene (QOL-002)
+
+LexRunner 0.5.0 shadow governance integration is feature-complete for the v0.1 Version Contract.
+
+**Recommendation**: Proceed with dogfooding and collect user feedback for v0.2 iteration.

package/.smartergpt/issues/QOL-REVIEW-SUMMARY.md

@@ -0,0 +1,111 @@
+# QoL Review Summary — LexSona Shadow Governance
+
+**Date**: 2025-12-07
+**Reviewers**: Senior Dev (analysis) + Eager PM (tickets)
+**Context**: Post-dogfooding of Version Contract v0.1 shadow mode integration
+
+---
+
+## What We Did
+
+1. **Senior Dev reviewed** the dogfooding results from smoke tests
+2. **Identified 6 QoL improvements** across 3 categories:
+   - Developer Experience (DX)
+   - Operational Hygiene
+   - Future-proofing
+3. **Created tickets** with clear acceptance criteria and effort estimates
+4. **Built roadmap** with prioritization strategy
+
+---
+
+## Key Findings from Dogfooding
+
+### ✅ What Works Well
+
+- Shadow mode executes without errors (100% success rate)
+- Logs persist correctly to `.smartergpt/runner/governance-logs/`
+- Offline mode degrades gracefully (no Lex DB crashes)
+- Zero impact on existing workflows (truly shadow)
+
+### 🔧 What Needs Improvement
+
+- **Visibility**: No console feedback during runs (logs are post-hoc only)
+- **Discoverability**: Analysis script hidden outside main CLI
+- **Usability**: Can't filter logs by date/persona/workflow
+- **Maintenance**: No log cleanup (will grow unbounded)
+- **Debugging**: No way to see why LexSona made a decision
+- **Evolution**: No schema versioning for safe format changes
+
+---
+
+## Created Tickets
+
+| ID      | Title                                  | Priority | Effort | Category     |
+| ------- | -------------------------------------- | -------- | ------ | ------------ |
+| QOL-003 | Real-time Console Feedback             | **High** | 1-2h   | DX           |
+| QOL-001 | Analysis Script Filtering & Formatting | Medium   | 2-3h   | DX           |
+| QOL-004 | `lex-pr governance:report` CLI         | Medium   | 3-4h   | Integration  |
+| QOL-005 | Schema Versioning                      | Low      | 1-2h   | Future-proof |
+| QOL-006 | Debug Verbose Mode                     | Low      | 2-3h   | Debugging    |
+| QOL-002 | Log Retention & Cleanup                | Low      | 2-4h   | Ops Hygiene  |
+
+**Total effort**: 13-20 hours depending on scope
+
+---
+
+## Recommended Next Action
+
+### 🎯 Quick Win: Implement QOL-003 First
+
+**Why QOL-003 (Real-time Console Feedback)?**
+
+1. **Immediate value**: Makes shadow mode visible during actual runs
+2. **Low effort**: 1-2 hours to implement
+3. **Validates need**: Will show if other tickets are worth doing
+4. **User-facing**: Most impactful for actual usage
+
+**After QOL-003:**
+
+- Run a real merge-weave workflow (5-10 PRs)
+- Observe console feedback in practice
+- Decide if remaining tickets are needed based on real pain points
+
+### Alternative: Full Foundation (Wave 1 → Wave 2 → Wave 3)
+
+Execute all 6 tickets sequentially (~20h total) if you want a complete, production-ready system immediately.
+
+---
+
+## Files Created
+
+```
+.smartergpt/issues/
+├── QOL-001-analysis-script-filtering.md
+├── QOL-002-log-retention-policy.md
+├── QOL-003-realtime-console-feedback.md (⭐ START HERE)
+├── QOL-004-governance-report-cli.md
+├── QOL-005-schema-versioning.md
+├── QOL-006-debug-verbose-mode.md
+└── QOL-ROADMAP.md
+```
+
+---
+
+## Senior Dev Notes
+
+> These aren't critical bugs—the shadow mode works. But without QOL-003 (console feedback), users won't notice LexSona running at all. That defeats the purpose of shadow mode: **learning from disagreements**.
+>
+> Start with console feedback. If you see interesting disagreements, the other tickets (filtering, CLI integration, debug mode) become much more valuable. If you see 100% agreement, maybe you don't need them yet.
+
+---
+
+## Eager PM Notes
+
+> Tickets are sized for independent implementation. QOL-003 is the forcing function—it'll tell us if LexSona is actually providing useful signals. The rest are polish that makes the tooling feel professional.
+>
+> If you want to ship this to other teams, do Wave 1 + Wave 2 (QOL-003, QOL-001, QOL-004) for a complete CLI experience. If it's just for internal dogfooding, QOL-003 alone is probably enough for the next phase.
+
+---
+
+**Status**: Ready for decision on implementation order
+**Commit**: 81a91ac (all tickets + roadmap)

package/.smartergpt/issues/QOL-ROADMAP.md

@@ -0,0 +1,71 @@
+# LexSona Shadow Governance: QoL Roadmap
+
+**Generated**: 2025-12-07
+**Context**: Post-dogfooding feedback from initial shadow mode integration (Version Contract v0.1)
+
+## Summary
+
+After smoke-testing the LexSona shadow governance integration, we identified 6 quality-of-life improvements to make the tooling production-ready.
+
+## Priority Tiers
+
+### 🔥 High Priority (Do First)
+
+- **QOL-003**: Real-time Console Feedback — Users need immediate visibility into LexSona opinions
+  - Effort: 1-2h
+  - Impact: Makes shadow mode discoverable during actual runs
+
+### 🟡 Medium Priority (Do Soon)
+
+- **QOL-001**: Analysis Script Filtering & Formatting — Essential for analyzing real logs
+  - Effort: 2-3h
+  - Impact: Enables useful log exploration
+
+- **QOL-004**: `lex-pr governance:report` CLI — Integrate analysis into main CLI
+  - Effort: 3-4h
+  - Impact: Makes reports discoverable and professional
+
+### 🟢 Low Priority (Polish)
+
+- **QOL-002**: Log Retention & Cleanup — Prevents unbounded disk growth
+  - Effort: 2-4h
+  - Impact: Operational hygiene
+
+- **QOL-005**: Schema Versioning — Future-proofs log format
+  - Effort: 1-2h
+  - Impact: Safe evolution path
+
+- **QOL-006**: Debug Verbose Mode — Troubleshooting support
+  - Effort: 2-3h
+  - Impact: Easier debugging when things go wrong
+
+## Suggested Execution Order
+
+**Wave 1: Make it visible** (4-5h total)
+
+1. QOL-003: Real-time feedback
+2. QOL-001: Filtering & formatting
+
+**Wave 2: Make it professional** (5-6h total) 3. QOL-004: CLI integration 4. QOL-005: Schema versioning
+
+**Wave 3: Make it maintainable** (4-7h total) 5. QOL-006: Debug mode 6. QOL-002: Retention policy
+
+## Total Effort
+
+- **Minimum**: 13 hours (just High + Medium priorities)
+- **Complete**: 20 hours (all 6 tickets)
+
+## Next Steps
+
+**Option A: Quick value**
+
+- Implement QOL-003 (console feedback) first
+- Run real workflow tests with visible feedback
+- Decide on remaining tickets based on actual pain points
+
+**Option B: Complete the foundation**
+
+- Execute Wave 1 → Wave 2 → Wave 3 sequentially
+- Results in fully-featured shadow governance system
+
+**Recommendation**: Start with QOL-003 (1-2h) and dogfood it on a real merge-weave run. The immediate feedback will inform whether the other tickets are actually needed.

package/.smartergpt/merge-policy.yml

@@ -0,0 +1,41 @@
+# Deterministic file-level merge preferences (first match wins).
+rules:
+  # Package locks / compiled manifests: prefer *theirs* (incoming PR).
+  - globs:
+      [
+        "**/package-lock.json",
+        "**/yarn.lock",
+        "**/pnpm-lock.yaml",
+        "**/poetry.lock",
+        "**/Cargo.lock",
+        "**/Pipfile.lock",
+      ]
+    resolution: theirs
+
+  # Dependency manifests: prefer *theirs*, then format.
+  - globs:
+      [
+        "**/package.json",
+        "**/pyproject.toml",
+        "**/requirements*.txt",
+        "**/Pipfile",
+        "**/Cargo.toml",
+      ]
+    resolution: theirs
+    format: true
+
+  # CI / workflow files: prefer *ours* (protect runner invariants).
+  - globs: [".github/**", ".smartergpt/**", ".devcontainer/**", ".pre-commit-config.yaml"]
+    resolution: ours
+
+  # Nginx / infra base configs: prefer *ours* by default.
+  - globs: ["**/nginx/**", "**/*.nginx", "**/*.conf"]
+    resolution: ours
+
+  # Docs: keep both (append PR content below ours) and strip markers.
+  - globs: ["**/*.md", "**/*.rst", "docs/**"]
+    resolution: keep-both
+
+  # Everything else (code): attempt auto 3-way merge; if still conflicted, emit AI ticket.
+  - globs: ["**/*"]
+    resolution: auto