cto-ai-cli 4.0.0 → 5.0.0

package/DOCS.md

@@ -7,6 +7,8 @@
 - [CLI Commands](#cli-commands)
 - [Security Audit](#security-audit---audit)
 - [Context Gateway](#context-gateway)
+- [Learning Mode](#learning-mode)
+- [Code Review](#code-review)
 - [MCP Server](#mcp-server)
 - [API Server](#api-server)
 - [Programmatic API](#programmatic-api)
@@ -100,6 +102,21 @@ npx cto-ai-cli --compare                 # Compare your score vs popular open so
 npx cto-ai-cli --benchmark              # CTO vs naive vs random comparison
 npx cto-ai-cli --json                    # Machine-readable JSON output
 npx cto-ai-cli --help                    # Show all options
+
+# Phase 5 — CI/CD Quality Gate
+npx cto-ai-cli --ci                      # Run quality gate (exits 1 on failure)
+npx cto-ai-cli --ci --threshold 80       # Set minimum score (default: 70)
+npx cto-ai-cli --ci --json               # JSON output for CI pipelines
+
+# Phase 7 — Learning Mode
+npx cto-ai-cli --learn                   # Show feedback model & cross-repo intelligence
+npx cto-ai-cli --feedback                # Alias for --learn
+npx cto-ai-cli --predict                 # Predict relevant files for a task
+npx cto-ai-cli --learn --json            # Export learning data as JSON
+
+# Phase 8 — Code Review
+npx cto-ai-cli --review                  # Smart PR review analysis
+npx cto-ai-cli --review --json           # JSON output for CI
 ```
 
 Flags can be combined: `npx cto-ai-cli --fix --audit --report --compare`
@@ -437,6 +454,185 @@ const result = await interceptRequest(messages, config, analysis);
 
 ---
 
+## Learning Mode
+
+CTO learns from your usage patterns to improve context selection over time. Three engines work together:
+
+### Feedback Engine (`--learn` / `--feedback`)
+
+Tracks which context selections lead to accepted AI output.
+
+```bash
+npx cto-ai-cli --learn                   # Full learning dashboard
+npx cto-ai-cli --learn --json            # Export for team sharing
+```
+
+**v2.0 Features:**
+
+| Feature | Description |
+|---------|-------------|
+| **EWMA Temporal Decay** | Recent feedback weighs more (α=0.15). Old patterns fade naturally. |
+| **Bayesian Confidence (Wilson Score)** | Avoids over-trusting sparse data. 1/1 ≠ 100% confidence. |
+| **Session Tracking** | Groups related feedback for per-session analysis. |
+| **A/B Strategy Comparison** | Compare different context strategies with statistical rigor. |
+| **Team Export/Import** | Share learned models across teams with weighted merge (local 70%, team 30%). |
+
+### Predictor Engine (`--predict`)
+
+Predicts which files are relevant for a task based on historical patterns.
+
+```bash
+npx cto-ai-cli --predict --context "fix auth bug"   # Predict files for a task
+npx cto-ai-cli --predict --json                      # JSON predictions
+```
+
+The predictor uses:
+- **Task type frequency** — which files were selected for similar task types (3× weight)
+- **Keyword frequency** — which files correlate with task keywords (2× weight)
+- **General selection frequency** — files selected in >30% of all observations
+- **Co-selection patterns** — files that tend to be selected together
+
+### Cross-Repo Intelligence
+
+Learns patterns across repositories. Stored in `~/.cto/global-intelligence.json`.
+
+- **Project fingerprinting** — stack, size class, structure pattern
+- **Archetype matching** — "TypeScript medium-size projects with tests"
+- **Universal patterns** — patterns that work across >50% of project types
+
+### Programmatic API
+
+```typescript
+import {
+  recordFeedback,
+  loadFeedbackModel,
+  getFeedbackBoosts,
+  exportFeedbackForTeam,
+  importTeamFeedback,
+  wilsonLowerBound,
+  renderFeedbackReport,
+  renderCrossRepoReport,
+} from 'cto-ai-cli/engine';
+import {
+  recordSelection,
+  predictRelevantFiles,
+  getPredictorBoosts,
+  loadModel,
+  getModelStats,
+} from 'cto-ai-cli/engine';
+import {
+  recordCrossRepoSelection,
+  predictFromCrossRepo,
+  loadGlobalModel,
+  getCrossRepoStats,
+  computeFingerprint,
+} from 'cto-ai-cli/engine';
+
+// Record feedback
+const model = await recordFeedback('/path/to/project', {
+  task: 'fix auth bug',
+  contextHash: 'abc123',
+  filesIncluded: ['src/auth.ts', 'src/types.ts'],
+  tokensUsed: 5000,
+  budget: 50000,
+  outcome: { accepted: true, compilable: true, timeToAcceptMs: 3000 },
+  sessionId: 'sess-1',       // optional: group feedback
+  strategy: 'experimental',  // optional: A/B testing
+});
+
+// Get boosts for context selection
+const boosts = await getFeedbackBoosts('/path/to/project', 'fix auth');
+// Map<string, number> — file path → boost value
+
+// Wilson score for statistical confidence
+const confidence = wilsonLowerBound(8, 10); // 8 successes out of 10
+// ~0.49 — 95% confident the true rate is ≥49%
+
+// Team sharing
+const exported = await exportFeedbackForTeam('/path/to/project', 'my-project');
+const merged = await importTeamFeedback('/other/project', exported);
+
+// Predict relevant files
+const predictions = await predictRelevantFiles('/path', 'fix auth', analysis);
+// { filePath, predictedScore, reasons }[]
+```
+
+### Storage
+
+| File | Scope | Description |
+|------|-------|-------------|
+| `.cto/feedback.json` | Per-project | Raw feedback entries (last 1000) |
+| `.cto/feedback-model.json` | Per-project | Rebuilt model with EWMA, Bayesian, sessions |
+| `.cto/predictor.json` | Per-project | ML predictor model |
+| `~/.cto/global-intelligence.json` | Cross-repo | Global archetype and pattern data |
+
+---
+
+## Code Review
+
+Context-aware PR review intelligence. Analyzes git diffs, detects breaking changes, finds missing files, and generates AI-ready review prompts.
+
+### Usage
+
+```bash
+npx cto-ai-cli --review                  # Full review analysis
+npx cto-ai-cli --review --json           # JSON output for CI
+```
+
+Generates:
+- **Terminal dashboard** — review quality score, breaking changes, missing files, impact radius
+- **`.cto/review-prompt.md`** — AI-ready review prompt with full file contents
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| **Diff Parsing** | Parses git diffs into structured DiffHunk[] with additions/deletions |
+| **Breaking Change Detection** | Removed exports, type changes, function signature changes, deleted files with dependents |
+| **Missing File Detection** | Sibling type files, test files, importers of changed exports, barrel index files |
+| **Impact Radius** | BFS on dependency graph: direct dependents, transitive (2-hop), affected tests |
+| **Review Quality Score** | 5-factor weighted score: PR size (25%), focus (20%), breaking changes (25%), completeness (15%), blast radius (15%) |
+| **Review Prompt Generation** | Context-rich prompt with breaking changes, missing files, and file contents for top-risk files |
+
+### Review Quality Score
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A+/A/A- | 85-100 | Small, focused PR with no breaking changes |
+| B+/B/B- | 70-84 | Manageable PR, some issues to review |
+| C+/C/C- | 55-69 | Large or unfocused PR, needs careful review |
+| D+/D/D- | 40-54 | Risky PR with breaking changes or missing files |
+| F | <40 | Very large, unfocused, or highly risky PR |
+
+### Breaking Change Severity
+
+| Severity | Trigger |
+|----------|--------|
+| **Critical** | Deleted file with dependents, removed export with >3 dependents |
+| **High** | Removed export, interface property removed, function signature changed |
+| **Medium** | Export changed with no direct dependents |
+
+### Programmatic API
+
+```typescript
+import { analyzeForReview, renderReviewSummary } from 'cto-ai-cli/engine';
+import type { ReviewResult, ReviewOptions } from 'cto-ai-cli/engine';
+
+const result: ReviewResult = await analyzeForReview(analysis, {
+  baseBranch: 'main',        // default: 'main'
+  depth: 2,                  // dependency expansion depth
+  maxPromptFiles: 20,        // max files in review prompt
+});
+
+console.log(result.breakingChanges);    // BreakingChange[]
+console.log(result.missingFiles);       // MissingFile[]
+console.log(result.impactRadius);       // { directlyAffected, transitivelyAffected, riskScore }
+console.log(result.reviewQuality);      // { score, grade, factors }
+console.log(result.reviewPrompt);       // Full AI-ready review prompt
+```
+
+---
+
 ## MCP Server
 
 CTO exposes 19 tools via the Model Context Protocol.
@@ -679,8 +875,11 @@ src/
 │   ├── multi-model.ts       # Per-model optimization
 │   ├── predictor.ts         # ML-based prediction (learns from usage)
 │   ├── semantic.ts          # Semantic domain analysis
-│   ├── feedback.ts          # Output feedback loop
-│   └── cross-repo.ts        # Cross-repo intelligence
+│   ├── feedback.ts          # Output feedback loop (v2: EWMA, Bayesian, A/B, team)
+│   ├── cross-repo.ts        # Cross-repo intelligence
+│   ├── code-review.ts       # Context-aware PR review engine
+│   ├── monorepo.ts          # Monorepo intelligence
+│   └── quality-gate.ts      # CI/CD quality gate
 ├── interact/            # Interaction Optimization
 │   ├── orchestrator.ts      # Full pipeline
 │   ├── router.ts            # Model routing