octocode-cli 1.2.5 → 1.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-cli",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
   "keywords": [
     "octocode",
@@ -25,21 +25,20 @@
     "directory": "packages/octocode-cli"
   },
   "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
-  "license": "PolyForm-Small-Business-1.0.0",
+  "license": "MIT",
   "bin": "./out/octocode-cli.js",
   "dependencies": {
     "@inquirer/prompts": "^8.1.0",
-    "@napi-rs/keyring": "^1.2.0",
     "@octokit/auth-oauth-device": "^8.0.3",
     "@octokit/oauth-methods": "^6.0.2",
     "@octokit/request": "^10.0.7",
+    "octocode-shared": "workspace:^",
     "open": "^11.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.29",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^9.18.0",
-    "octocode-shared": "workspace:^",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.0",
@@ -49,7 +48,7 @@
     "node": ">=20.12.0"
   },
   "files": [
-    "out/octocode-cli.js",
+    "out",
     "skills",
     "assets/example.png",
     "README.md",
@@ -60,6 +59,8 @@
     "build": "yarn lint && vite build",
     "build:dev": "vite build",
     "clean": "rm -rf out/",
+    "prepack": "cp -r ../../skills ./skills",
+    "postpack": "rm -rf ./skills",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",
     "start": "node ./out/octocode-cli.js",
@@ -70,7 +71,8 @@
     "validate:mcp": "npx tsx scripts/validate-mcp-registry.ts",
     "validate:mcp:json": "npx tsx scripts/validate-mcp-registry.ts --json",
     "validate:skills": "npx tsx scripts/validate-skills-marketplace.ts",
-    "validate:skills:json": "npx tsx scripts/validate-skills-marketplace.ts --json"
+    "validate:skills:json": "npx tsx scripts/validate-skills-marketplace.ts --json",
+    "verify": "yarn lint && yarn typecheck && yarn test && yarn validate:mcp && yarn validate:skills"
   },
   "type": "module"
 }

package/skills/README.md

@@ -1,165 +1,142 @@
-# Octocode Skills
+# OctoCode Skills
 
-Pre-built Claude Code skills for enhanced AI-assisted research and development.
+Specialized AI agent skills that extend OctoCode's capabilities.
 
-## Available Skills
+---
 
-| Skill | Description | Flow |
-|-------|-------------|------|
-| `octocode-research` | Evidence-first code forensics (local & GitHub) | PREPARE → DISCOVER → ANALYZE → OUTPUT |
-| `octocode-local-search` | Local-first code exploration and discovery | DISCOVER → PLAN → EXECUTE → VERIFY → OUTPUT |
-| `octocode-implement` | Research-driven feature implementation from specs | SPEC → CONTEXT → PLAN → RESEARCH → IMPLEMENT → VALIDATE |
-| `octocode-plan` | Adaptive research & implementation planning | UNDERSTAND → RESEARCH → PLAN → IMPLEMENT → VERIFY |
-| `octocode-pr-review` | Defects-first PR review across 6+ domains | CONTEXT → CHECKPOINT → ANALYSIS → FINALIZE → REPORT |
-| `octocode-roast` | Brutally honest code review with comedic flair | SCOPE → ROAST → INVENTORY → SPOTLIGHT → REDEMPTION |
+## When to Use What
 
-## Installation
+| Your Need | Skill | Example Trigger |
+|-----------|-------|-----------------|
+| Code search, exploration, research (local + external) | **Researcher** | "Find X in codebase", "Where is Y?", "Who calls Z?", "Trace this flow", "How does library X work?" |
+| Complex multi-phase research with sessions & checkpoints | **Research** | "Deep-dive into auth end-to-end", "Compare React vs Vue state", "Research and review PR changes" |
+| Plan implementation steps before coding | **Plan** | "Plan this refactor", "Research & plan this feature" |
+| Technical decisions requiring formal RFC with alternatives | **RFC** | "Create RFC for caching", "Design doc for API v2", "How should we build X?" |
+| Review a pull request or local changes | **PR Reviewer** | "Review PR #123", "Review my changes", "Is this PR safe to merge?" |
+| Repo-wide code quality scan (duplicates, complexity, cycles) | **Local Code Scan** | "Analyze code quality", "Find duplicates", "Find dependency cycles", "Scan for tech debt" |
+| Brutal code criticism with fixes | **Roast** | "Roast my code", "Find code sins", "What's wrong with this?" |
+| Strengthen prompts / agent instructions | **Prompt Optimizer** | "Optimize this SKILL.md", "Agent skips steps" |
+| Generate repo documentation | **Documentation Writer** | "Document this project", "Create developer docs" |
 
-### Option 1: CLI Command
+---
 
-```bash
-octocode skills install
-```
+## Skills Overview
 
-This copies all skills to `~/.claude/skills/` for global availability.
+### 1. OctoCode Researcher
+**Location:** `octocode-researcher/`
 
-### Option 2: Manual Copy
+**The default research skill.** Direct code exploration via Octocode MCP tools — local codebase (LSP semantic navigation, search, structure) and external (GitHub, npm/PyPI, PRs). Lightweight, no server needed. Use for most research tasks.
 
-Copy skill folders to your Claude skills directory:
+| When | Example |
+|------|---------|
+| Local search + LSP | "Find auth logic", "Where is X defined?", "Who calls Y?" |
+| External research | "How does library X work?", "Find a caching package" |
+| Cross-boundary | "How does our code use dependency Z?" |
 
-```bash
-# Global (all projects)
-cp -r skills/octocode-* ~/.claude/skills/
+---
 
-# Project-specific
-cp -r skills/octocode-* .claude/skills/
-```
+### 2. OctoCode Research (HTTP Server)
+**Location:** `octocode-research/`
 
-## Skill Details
+HTTP server mode for complex, multi-phase research. Adds session management, checkpoints, and persistent context on top of Octocode MCP tools. Phases: Init → Context → Fast-path → Plan → Research → Output. Use when research spans multiple domains and benefits from state persistence.
 
-### octocode-research
+| When | Example |
+|------|---------|
+| Multi-domain deep dive | "Research how auth works end-to-end" |
+| Comparative analysis | "Compare React vs Vue state management" |
+| Persistent sessions | "Continue researching from last checkpoint" |
 
-**Use when**: Answering questions about codebases, implementations, dependencies, or bugs. Researching code across local workspace AND GitHub repositories.
+---
 
-Features:
-- Local-first strategy (prefer local tools over shell commands)
-- GitHub code forensics across repositories
-- Cross-domain transitions (Local ↔ GitHub)
-- node_modules inspection with `noIgnore=true`
-- Multi-agent parallelization for independent hypotheses
-- Validation pattern: Discover → Verify → Cross-check → Confirm
+### 3. OctoCode Plan
+**Location:** `octocode-plan/`
 
-### octocode-local-search
+Evidence-based implementation planning. Understand → Research (delegates to Researcher/Research) → Plan → Implement. Use when you know the general approach and need actionable steps.
 
-**Use when**: Exploring unfamiliar codebases, searching for patterns locally, understanding project structure, finding implementations in your workspace.
+| When | Example |
+|------|---------|
+| Multi-step work | "Plan auth refactor", "Plan API v2" |
+| Non-trivial tasks | "Research & plan this feature" |
 
-Features:
-- Local-only focus (no GitHub tools)
-- Structured discovery with `localViewStructure`, `localSearchCode`, `localFindFiles`, `localGetFileContent`
-- Interactive planning with user checkpoints
-- node_modules inspection with `noIgnore=true`
-- Token-efficient workflows with discovery mode
-- Multi-agent parallelization for independent research domains
+---
 
-### octocode-implement
+### 4. OctoCode RFC Generator
+**Location:** `octocode-rfc-generator/`
 
-**Use when**: Implementing features from specification documents (MD files, PRDs, tickets), building new functionality in large/unfamiliar codebases, or executing task lists with proper research.
+For technical decisions that need formal evaluation. Understand → Research → Draft RFC with alternatives → Validate → Implementation plan. Use when multiple approaches are viable and you need to reason through trade-offs before committing.
 
-Features:
-- Reads and parses task specifications from MD files
-- Deep codebase research before writing code
-- LSP tools for semantic code intelligence (`lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy`)
-- Pattern discovery to follow existing codebase conventions
-- Impact analysis before modifying code
-- Test-driven implementation with validation gates
-- User checkpoints at key decision points
-- Multi-agent parallelization for independent tasks
+| When | Example |
+|------|---------|
+| Technical decisions | "Create RFC for caching layer", "How should we build X?" |
+| Migrations / refactors | "RFC for auth migration", "Design doc for API v2" |
+| Architecture choices | "Should we use Redis or Memcached?", "Propose new pattern" |
 
-Core Principle: "Read 10x more than you write. Measure twice, cut once."
+---
 
-### octocode-plan
+### 5. OctoCode Prompt Optimizer
+**Location:** `octocode-prompt-optimizer/`
 
-**Use when**: Implementing features requiring research-driven planning, tackling complex multi-step tasks, building new functionality with proper validation, or when you need structured implementation with approval gates.
+Turns weak prompts into enforceable protocols. Gates, FORBIDDEN lists, failure analysis. Preserves intent, adds reliability.
 
-Features:
-- Adaptive execution flow: UNDERSTAND → RESEARCH → PLAN → IMPLEMENT → VERIFY
-- Evidence-based coding with pattern validation from high-quality repos
-- Interactive mode with user checkpoints at key decision points
-- Goal classification (RESEARCH_ONLY, ANALYSIS, CREATION, FEATURE, BUG, REFACTOR)
-- Research synthesis with confidence levels
-- Plan approval gates before implementation
-- Multi-agent parallelization for independent research domains
-- Structured output to `.octocode/plan/{session-name}/`
+| When | Example |
+|------|---------|
+| Prompts ignored | "Agent keeps skipping steps" |
+| New/weak instructions | "Optimize this SKILL.md", "Make prompt reliable" |
 
-Core Principle: "Research Before Code. Verify Patterns. Follow the Plan. Green Build Required."
+*Not for:* Short prompts (<50 lines), already-optimized docs.
 
-### octocode-pr-review
+---
 
-**Use when**: Reviewing pull requests for bugs, security vulnerabilities, architecture problems, performance issues, and code quality.
+### 6. OctoCode Documentation Writer
+**Location:** `octocode-documentation-writer/`
 
-Domain Reviewers:
-- 🐛 Bug (runtime errors, logic flaws, resource leaks)
-- 🏗️ Architecture (pattern violations, circular dependencies)
-- ⚡ Performance (O(n²), memory leaks, blocking ops)
-- 🎨 Code Quality (naming, conventions, DRY violations)
-- 🔗 Duplicate Code (missed reuse opportunities)
-- 🚨 Error Handling (swallowed exceptions, poor diagnostics)
-- 🔄 Flow Impact (breaking changes, altered data paths)
+6-phase pipeline: Discovery → Questions → Research → Orchestration → Writing → QA. Produces 16+ docs with validation.
 
-### octocode-roast
+| When | Example |
+|------|---------|
+| New/outdated docs | "Generate documentation", "Update docs" |
+| Onboarding | "Create docs for new devs" |
 
-**Use when**: You want entertainment with your code review, finding antipatterns, or humorous feedback.
+---
 
-Features:
-- Sin severity classification (FELONY → WAR CRIME → PARKING TICKET)
-- Personalized zingers based on actual patterns found
-- Multiple roast personas (Gordon Ramsay, Disappointed Dad, Tech Bro, Israeli Sabra, etc.)
-- User checkpoint before fixes (Redemption Arc)
-- Actionable fixes with before/after
+### 7. OctoCode Roast
+**Location:** `octocode-roast/`
 
-## Skill Structure
+Brutal code critique with file:line citations. Severity: gentle → nuclear. Sin registry, user picks fixes. Cites or dies.
 
-Each skill follows Anthropic's best practices:
+| When | Example |
+|------|---------|
+| Code critique | "Roast my code", "Find antipatterns" |
+| Honest feedback | "What's wrong with my code?" |
 
-```
-{skill-name}/
-├── SKILL.md           # Main reference (<500 lines)
-└── references/        # Supporting documentation (optional)
-    ├── tool-reference.md
-    └── workflow-patterns.md
-```
+---
 
-## Shared Principles
+### 8. OctoCode Local Code Scan
+**Location:** `octocode-local-code-scan/`
 
-All skills follow these core principles:
+AST-based repo-wide code quality scanner. Detects duplicate function bodies, repeated control-flow patterns, high-complexity functions, dependency cycles, critical dependency chains, and dead modules. Produces a prioritized JSON report with file:line references and suggested fixes. Optionally uses tree-sitter for richer metadata. Pairs with Octocode MCP local + LSP tools for investigation.
 
-1. **Local-First**: Prefer local tools over shell commands
-2. **Research Before Action**: Always gather evidence first
-3. **User Checkpoints**: Ask before major actions
-4. **TodoWrite**: Track progress with tasks
-5. **Validation**: Green build required
-6. **No Time Estimates**: Never provide timing
-7. **Evidence Citing**: Include file paths and code references
+| When | Example |
+|------|---------|
+| Code quality audit | "Analyze code quality", "Scan for tech debt" |
+| Duplicate detection | "Find duplicate code", "Find repeated patterns" |
+| Dependency analysis | "Find dependency cycles", "Show critical paths" |
+| Complexity check | "Check complexity", "Find oversized functions" |
 
-## Creating Custom Skills
+---
 
-See `octocode-research/` as a template. Key guidelines:
+### 9. OctoCode Pull Request & Code Reviewer
+**Location:** `octocode-pull-request-reviewer/`
 
-1. **SKILL.md** - Main file with YAML frontmatter:
-   ```yaml
-   ---
-   name: skill-name
-   description: Use when [specific triggers]...
-   ---
-   ```
+Holistic code review via Octocode MCP: bugs, security, architecture, flow impact. Supports both **remote PRs** and **local changes** (staged/unstaged). 7 domains, LSP-powered flow tracing, evidence-backed, user checkpoint before deep dive.
 
-2. **Keep SKILL.md under 500 lines** - Use references/ for details
+> **Local Mode** requires `ENABLE_LOCAL=true` — see [README](https://github.com/bgauryy/octocode-mcp/blob/main/skills/octocode-pull-request-reviewer/README.md)
 
-3. **Description = When to Use** - Don't describe workflow, describe triggers
+| When | Example |
+|------|---------|
+| PR review | "Review PR #456", "Check this PR" |
+| Local changes | "Review my changes", "Review staged changes" |
+| Security/impact | "Is this safe to merge?" |
 
-4. **Test with pressure scenarios** before deploying
+---
 
-## More Info
-
-- [Claude Skills Documentation](https://support.anthropic.com/en/articles/10176498-how-to-use-custom-instructions-for-your-projects)
-- [Octocode MCP](https://octocode.ai)

package/skills/octocode-code-engineer/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebSearch",
+      "Bash(wc:*)",
+      "Bash(node:*)",
+      "Skill(octocode-local-code-quality)",
+      "Bash(tail:*)",
+      "Bash(npm install:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest:*)",
+      "Bash(cp:*)",
+      "Bash(npx tsc 2>&1 && cp -R /Users/guybary/Documents/octocode-mcp/skills/octocode-local-code-quality/ /Users/guybary/.claude/skills/octocode-local-code-quality/ 2>&1)",
+      "Bash(cat:*)"
+    ]
+  }
+}

package/skills/octocode-code-engineer/.octocode/rfc/RFC-code-engineer-weakness-fixes.md

@@ -0,0 +1,255 @@
+# RFC: Code Engineer Skill — Weakness Fixes
+
+**Generated**: 2026-03-21
+**Scope**: `skills/octocode-code-engineer` — detectors, pipeline, documentation, CLI
+
+---
+
+## 1. Summary
+
+Fix all 14 weaknesses identified by running the code-engineer skill against itself. The changes span four areas: **detector accuracy** (thresholds, missing wiring, noise reduction), **pipeline behavior** (scope clarity, semantic confidence, cache), **documentation** (stale roadmap, thin concepts, missing fallbacks, category drift), and **test quality cross-referencing**. No architectural rewrites — surgical fixes anchored to exact file:line evidence.
+
+---
+
+## 2. Motivation
+
+The code-engineer skill self-scan revealed legitimate gaps that affect real users:
+
+- **False negatives**: `god-function` uses statement count only (threshold 100), so orchestration functions with MI=1.4 pass. `detectSemanticDeadExports` is **implemented but never wired** into `runSemanticDetectors`. `detectDeadFiles` exists in `cycle.ts:202-234` but is **never called** from `index.ts`.
+- **False positives / noise**: `unbounded-collection` fires on any function with 2+ loops and 5+ calls — no collection mutation check. `shotgun-surgery` has no allowlist for intentionally-shared utilities. Dead re-export count (94) inflated by `src/`↔`scripts/` duality.
+- **Missing config surface**: `shotgunThreshold` planned but not in `AnalysisOptions`/CLI. SDP `minDelta` hardcoded. `unbounded-collection` has no threshold config.
+- **Semantic underperformance**: 6 of 12 semantic detectors produce 0 findings due to strict prerequisites. Confidence is always "low" because `inferAnalysisLens` doesn't recognize semantic categories.
+- **Documentation drift**: `finding-categories.md` missing `mega-folder`, documents `redundant-re-export`/`redundant-comment` without implementations. `PILLAR_CATEGORIES` missing `message-chain`, `debug-log-leakage`, `sensitive-data-logging`. `concepts.md` missing abstractness, distance D, LCOM, hot-file scoring. Code Mode has no LSP fallback.
+
+---
+
+## 3. Detailed Fixes
+
+### Fix 1: God-function detector — add MI as secondary trigger
+
+**File**: `src/detectors/cohesion.ts:170-214`
+**Problem**: Only triggers on `statementCount > 100`. A function with 20 top-level statements but MI=1.4 escapes detection.
+**Fix**: Add secondary condition: fire if `fn.maintainabilityIndex !== undefined && fn.maintainabilityIndex < options.godFunctionMiThreshold` (default 10). This catches orchestration-heavy functions with collapsed MI.
+
+**Files to change**:
+- `src/types/constants.ts` — add `godFunctionMiThreshold: 10` to `DEFAULT_OPTS`
+- `src/types/interfaces.ts` — add `godFunctionMiThreshold` to `AnalysisOptions`
+- `src/pipeline/cli.ts` — add `--god-function-mi-threshold` flag
+- `src/detectors/cohesion.ts` — add MI check in `detectGodFunctions`
+- `src/index.ts` — pass `options.godFunctionMiThreshold` to detector
+- `scripts/` — rebuild after TS changes
+
+### Fix 2: Unbounded-collection — require collection mutation evidence
+
+**File**: `src/detectors/code-quality.ts:794-826`
+**Problem**: Fires on any function with `loops >= 2 && calls >= 5 && maxLoopDepth >= 2` — purely structural, no collection evidence.
+**Fix**:
+1. Add heuristic: function must also contain `.push(`, `.set(`, `.add(`, or array/map literal + loop pattern.
+2. Add configurable thresholds to `AnalysisOptions` and CLI.
+3. The collector already has `fn.effects` — check for collection-mutation effects.
+
+**Files to change**:
+- `src/detectors/code-quality.ts` — refine detection logic to check `fn.effects` or AST patterns
+- `src/types/constants.ts` — add `unboundedCollectionMinLoops: 2` etc. to `DEFAULT_OPTS`
+- `src/types/interfaces.ts` — add threshold to `AnalysisOptions`
+- `src/pipeline/cli.ts` — add CLI flag
+
+### Fix 3: Shotgun-surgery — add config surface + shared-utility allowlist
+
+**File**: `src/detectors/semantic.ts:597-642`
+**Problem**: Threshold 8 is hardcoded, not in CLI. Flags intentionally-shared utilities like `isTestFile`.
+**Fix**:
+1. Wire `shotgunThreshold` through `AnalysisOptions` → CLI (`--shotgun-threshold`).
+2. Add `excludePattern` option to skip paths matching `**/common/**`, `**/utils/**`, `**/shared/**` (configurable).
+3. Alternatively: raise default to 12 (current "high" boundary) to reduce noise on moderate sharing.
+
+**Files to change**:
+- `src/types/interfaces.ts` — add `shotgunThreshold` to `AnalysisOptions`
+- `src/types/constants.ts` — add default
+- `src/pipeline/cli.ts` — add `--shotgun-threshold`
+- `src/pipeline/main.ts:213-215` — pass `options.shotgunThreshold` to `runSemanticDetectors`
+- `src/detectors/semantic.ts` — accept utility-path exclusion
+
+### Fix 4: SDP violation — expose `minDelta` + lower source-instability gate
+
+**File**: `src/detectors/coupling.ts:17-71`
+**Problem**: `minDelta=0.15` and `iSrc < 0.5` gate are hardcoded. Only 1 finding means most edges fail the source-stability check.
+**Fix**: Add `sdpMinDelta` and `sdpMaxSourceInstability` to `AnalysisOptions`/CLI. Default `sdpMaxSourceInstability` to 0.6 (from 0.5) to widen the detection window slightly.
+
+**Files to change**:
+- `src/types/interfaces.ts` — add SDP options
+- `src/types/constants.ts` — add defaults
+- `src/pipeline/cli.ts` — add flags
+- `src/detectors/coupling.ts` — parameterize
+- `src/index.ts` — pass options
+
+### Fix 5: Wire `detectSemanticDeadExports` into pipeline
+
+**File**: `src/detectors/semantic.ts:735-756` (`runSemanticDetectors`)
+**Problem**: `detectSemanticDeadExports` is defined (line 10-50) but **never called** from `runSemanticDetectors`.
+**Fix**: Add `all.push(...detectSemanticDeadExports(profiles));` to `runSemanticDetectors`.
+
+**Files to change**:
+- `src/detectors/semantic.ts` — add call in `runSemanticDetectors`
+
+### Fix 6: Wire `detectDeadFiles` into main scan
+
+**File**: `src/detectors/cycle.ts:202-234`, `src/index.ts`
+**Problem**: `detectDeadFiles` is implemented and tested but never called from the main scan.
+**Fix**: Add call in `src/index.ts` alongside other dead-code detectors.
+
+**Files to change**:
+- `src/index.ts` — add `detectDeadFiles` call
+- `src/types/constants.ts` — ensure `dead-file` is in `PILLAR_CATEGORIES['dead-code']`
+
+### Fix 7: Semantic confidence — recognize semantic analysis lens
+
+**File**: `src/reporting/analysis.ts:175-236`
+**Problem**: `inferAnalysisLens` falls through to `'ast'` for all semantic categories. `defaultConfidence` then assigns `'low'` since `ast` + non-critical = low.
+**Fix**:
+1. Add semantic categories to `inferAnalysisLens` → return `'hybrid'` or new `'semantic'` lens.
+2. In `defaultConfidence`, treat `'semantic'` lens as `'medium'` confidence.
+
+**Files to change**:
+- `src/reporting/analysis.ts` — add semantic category recognition in `inferAnalysisLens`, update `defaultConfidence`
+- `src/types/interfaces.ts` — if adding `'semantic'` as a new `AnalysisLens` value
+
+### Fix 8: PILLAR_CATEGORIES drift — add missing categories
+
+**File**: `src/types/constants.ts:64-157`
+**Problem**: `message-chain`, `debug-log-leakage`, `sensitive-data-logging` are emitted by detectors but missing from `PILLAR_CATEGORIES`, so they don't appear in pillar-specific JSON files.
+**Fix**: Add missing categories to appropriate pillars.
+
+**Files to change**:
+- `src/types/constants.ts` — add `message-chain` to `code-quality`, add `debug-log-leakage` and `sensitive-data-logging` to `security`
+
+### Fix 9: `finding-categories.md` — sync with actual detectors
+
+**File**: `references/finding-categories.md`
+**Problem**: Missing `mega-folder`. Documents `redundant-re-export` and `redundant-comment` which have no detector implementation.
+**Fix**: Add `mega-folder`. Mark `redundant-re-export` and `redundant-comment` as "planned" or remove.
+
+### Fix 10: `concepts.md` — add missing metrics
+
+**File**: `references/concepts.md`
+**Problem**: Missing abstractness (A), distance from main sequence (D), LCOM/low-cohesion, hot-file/risk scoring, cyclomatic density mismatch.
+**Fix**: Add sections for each missing metric with formula and threshold. Fix cyclomatic density to reflect actual implementation (used inside MI and `function-optimization`, not as standalone category).
+
+### Fix 11: SKILL.md Code Mode — add LSP fallback
+
+**File**: `SKILL.md:240-278`
+**Problem**: Code Mode Steps 1-2 and 5 reference LSP tools with no fallback.
+**Fix**: Add "If LSP unavailable" bullet after Step 2 and Step 5, mirroring Audit Step 4 fallback (use `ast/search.js`, `localSearchCode`, scan JSON for dependency data, lower confidence).
+
+### Fix 12: Test-quality / untested-critical cross-reference
+
+**Problem**: `untested-critical-code` (graph-based, 25 findings) and `test-quality` (requires `testProfile` on test files) are orthogonal. Users see 25 untested modules but 100/100 test quality — confusing.
+**Fix**:
+1. In `summary.md` generation, add a note when `untested-critical-code > 0` but `test-quality` score is 100: "Test Quality reflects analyzed test files; see untested-critical-code for coverage gaps."
+2. In SKILL.md Test Strategy mode, document that `--include-tests` is needed for test-quality findings.
+
+**Files to change**:
+- `src/reporting/summary-md.ts` — add conditional note in test-quality section
+- `SKILL.md` — document `--include-tests` requirement in Test Strategy
+
+### Fix 13: Dead re-export src/scripts inflation
+
+**Problem**: 94 dead re-exports partly because `scripts/` JS mirror of `src/` TS inflates the count — both are scanned as separate module graphs.
+**Fix**: Add `--exclude` flag to CLI (or respect `.octocoderc` ignorePatterns) so users can exclude `scripts/` from scans. This is already partially supported through `options.scope` but not as an exclusion pattern.
+
+**Files to change**:
+- `src/pipeline/cli.ts` — add `--exclude <pattern>` flag
+- `src/types/interfaces.ts` — add `exclude` to `AnalysisOptions`
+- `src/analysis/discovery.ts` — filter excluded paths in `collectFiles`
+- `src/pipeline/main.ts` — apply exclude to dependency file collection
+
+### Fix 14: improvement-roadmap.md — mark implemented items
+
+**File**: `references/improvement-roadmap.md`
+**Problem**: 302 lines with no status markers. Items like file cache, test-quality detectors, graph analytics, output versioning are done but not marked.
+**Fix**: Add status column/badges: Done, In Progress, Planned. Remove or mark as aspirational items with no near-term plan (SARIF, mutation testing, persistent TS project service).
+
+---
+
+## 4. Drawbacks
+
+- **Fix 1 (MI threshold)**: MI can be unreliable for very small functions. The secondary trigger needs a minimum LOC guard (e.g. only fire MI check if `fn.lineCount > 30`).
+- **Fix 2 (collection mutation)**: AST heuristic for `.push`/`.set` may miss wrapper patterns. False negatives are acceptable since the current 110-finding noise is worse.
+- **Fix 7 (semantic lens)**: Adding `'semantic'` as a new lens value requires all consumers to handle it — check `graph.md` rendering, `summary-md.ts`, any external tooling.
+- **Fix 13 (--exclude)**: Another CLI flag adds complexity. Could instead auto-detect `scripts/` as build output (check for matching filenames in `src/`).
+
+---
+
+## 5. Alternatives Considered
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **A: Surgical fixes (this RFC)** | Targeted, low risk, each fix is independently testable | Doesn't address deeper architecture (e.g. detector plugin system) |
+| **B: Detector plugin system** | Extensible, clean separation | Major refactor, delays all fixes, overkill for current need |
+| **C: Config file (.octocoderc)** | Single place for all thresholds | Adds config-file discovery, parsing, validation complexity |
+
+**Recommendation**: Option A. Each fix is 1-3 files, independently testable. Option C can be a follow-up RFC for threshold management.
+
+---
+
+## 6. Implementation Plan
+
+### Phase 1: Critical wiring fixes (no threshold changes)
+
+| # | Fix | Files | Risk |
+|---|-----|-------|------|
+| 5 | Wire `detectSemanticDeadExports` | `semantic.ts` | Low |
+| 6 | Wire `detectDeadFiles` | `index.ts`, `constants.ts` | Low |
+| 8 | Fix `PILLAR_CATEGORIES` drift | `constants.ts` | Low |
+| 7 | Semantic confidence/lens fix | `analysis.ts`, possibly `interfaces.ts` | Low |
+
+### Phase 2: Threshold + config surface
+
+| # | Fix | Files | Risk |
+|---|-----|-------|------|
+| 1 | God-function MI threshold | `cohesion.ts`, `constants.ts`, `interfaces.ts`, `cli.ts`, `index.ts` | Medium |
+| 3 | Shotgun-surgery config | `semantic.ts`, `interfaces.ts`, `constants.ts`, `cli.ts`, `main.ts` | Medium |
+| 4 | SDP config exposure | `coupling.ts`, `interfaces.ts`, `constants.ts`, `cli.ts`, `index.ts` | Low |
+| 2 | Unbounded-collection refinement | `code-quality.ts`, `constants.ts`, `interfaces.ts`, `cli.ts` | Medium |
+| 13 | `--exclude` flag | `cli.ts`, `interfaces.ts`, `discovery.ts`, `main.ts` | Medium |
+
+### Phase 3: Documentation
+
+| # | Fix | Files | Risk |
+|---|-----|-------|------|
+| 9 | `finding-categories.md` sync | `references/finding-categories.md` | None |
+| 10 | `concepts.md` expansion | `references/concepts.md` | None |
+| 11 | Code Mode LSP fallback | `SKILL.md` | None |
+| 12 | Test-quality cross-reference | `summary-md.ts`, `SKILL.md` | Low |
+| 14 | Roadmap status update | `references/improvement-roadmap.md` | None |
+
+### Verification
+
+After each phase:
+1. `yarn build` — compile succeeds
+2. `yarn test` — all tests pass
+3. `node scripts/index.js --graph --flow --semantic` — re-scan self, verify:
+   - Phase 1: `semantic-dead-export` > 0, `dead-file` appears, semantic confidence upgrades
+   - Phase 2: `unbounded-collection` count drops, `god-function` detects MI-collapsed functions
+   - Phase 3: docs pass manual review
+
+---
+
+## 7. References
+
+### Local code evidence
+- `src/detectors/cohesion.ts:170-214` — god-function detector
+- `src/detectors/code-quality.ts:794-826` — unbounded-collection detector
+- `src/detectors/semantic.ts:597-642` — shotgun-surgery detector
+- `src/detectors/semantic.ts:10-50` — semantic-dead-export (unwired)
+- `src/detectors/semantic.ts:735-756` — `runSemanticDetectors` (missing calls)
+- `src/detectors/cycle.ts:202-234` — `detectDeadFiles` (unwired)
+- `src/detectors/coupling.ts:17-71` — SDP violation detector
+- `src/reporting/analysis.ts:175-236` — `inferAnalysisLens` + `defaultConfidence`
+- `src/types/constants.ts:64-157` — `PILLAR_CATEGORIES`
+- `src/pipeline/cache.ts:23-42` — cache load/invalidation
+- `src/pipeline/main.ts:505-522` — scope + features interaction
+- `references/finding-categories.md` — category documentation
+- `references/concepts.md` — metric definitions
+- `references/improvement-roadmap.md` — planned features
+- `SKILL.md:240-278` — Code Mode (no LSP fallback)