opencode-matrixx-v2 0.0.0-stage → 1.1.0

package/dist/features/builtin-commands/templates/handoff.d.ts

@@ -0,0 +1 @@
+export declare const HANDOFF_TEMPLATE = "# Handoff Command\n\n## Purpose\n\nUse /handoff when:\n- The current session context is getting too long and quality is degrading\n- You want to start fresh while preserving essential context from this session\n- The context window is approaching capacity\n\nThis creates a detailed context summary written to .matrixx/handoff.md. The next session loads it via /pickup.\n\n---\n\n# PHASE 0: VALIDATE REQUEST\n\nBefore proceeding, confirm:\n- [ ] There is meaningful work or context in this session to preserve\n- [ ] The user wants to create a handoff summary (not just asking about it)\n\nIf the session is nearly empty or has no meaningful context, inform the user there is nothing substantial to hand off.\n\n---\n\n# PHASE 1: GATHER PROGRAMMATIC CONTEXT\n\nExecute these tools to gather concrete data:\n\n1. session_read({ session_id: \"$SESSION_ID\" }) \u2014 full session history\n2. task_list() \u2014 current task progress\n3. Bash({ command: \"git diff --stat HEAD~10..HEAD\" }) \u2014 recent file changes\n4. Bash({ command: \"git status --porcelain\" }) \u2014 uncommitted changes\n\nAnalyze the gathered outputs to understand:\n- What the user asked for (exact wording)\n- What work was completed\n- What tasks remain incomplete\n- What decisions were made\n- What files were modified or discussed\n- What patterns, constraints, or preferences were established\n\n---\n\n# PHASE 2: CALL HANDOFF TOOL\n\nCall the `handoff` tool with `action=\"create\"` and the data you gathered. The tool validates the input and writes the handoff file automatically \u2014 no manual file writing needed.\n\nUse these field mappings for the tool arguments:\n\n```\nhandoff({\n  action: \"create\",\n  topics: [\"tag1\", \"tag2\"],              // Min 1 topic tag, from session context\n  user_requests: \"verbatim user msg\",     // REQUIRED \u2014 exact wording from session_read\n  goal: \"single sentence\",                // REQUIRED \u2014 what should be done next\n  work_completed: [\"did X\", \"did Y\"],     // REQUIRED \u2014 first-person bullet points\n  current_state: \"state description\",     // REQUIRED \u2014 current codebase/task state\n  pending_tasks: [\"task1\", \"task2\"],      // Optional \u2014 tasks not yet completed\n  key_files: [{path, purpose}],           // Optional \u2014 max 10, workspace-relative paths\n  important_decisions: [{decision, rationale}], // Optional \u2014 key decisions made\n  explicit_constraints: [\"verbatim\"],     // Optional \u2014 verbatim constraints only\n  context_for_continuation: \"...\"         // Optional \u2014 additional context\n})\n```\n\n---\n\n# PHASE 3: INFORM USER\n\nAfter the tool call completes, inform the user:\n\n```\nHandoff saved to .matrixx/handoff.md. Use /pickup in a new opencode session to load this context.\n```\n\n---\n\n# IMPORTANT CONSTRAINTS\n\n- DO gather programmatic context before calling the tool (Phase 1 is mandatory)\n- DO extract user_requests verbatim from session_read output (do not paraphrase)\n- DO keep goal to a single sentence\n- DO use workspace-relative paths for key_files\n- DO NOT attempt to create new sessions programmatically\n- DO NOT exceed 10 files in key_files (max 10)\n- DO NOT include sensitive information (API keys, credentials, secrets)\n- DO use first person perspective for work_completed items\n- DO use plain text with bullets for descriptions (no markdown headers)\n";

package/dist/features/builtin-commands/templates/humanize.d.ts

@@ -0,0 +1 @@
+export declare const HUMANIZE_TEMPLATE = "# Humanize Command\n\n## Usage\n```\n/humanize [target] [--mode=text|comments|code|all] [--dry-run]\n\nArguments:\n  target: What to humanize. Can be:\n    - File path: src/auth/handler.ts / docs/guide.md\n    - Directory: src/features/\n    - Glob: src/**/*.ts\n    - Inline prose: quoted string \"...\" (text mode)\n    - Omitted: defaults to git-changed files (git diff --name-only HEAD~1), else src/\n\nOptions:\n  --mode: Pipeline mode (default: all when target is code file/dir; text when target is prose/md or quoted string)\n    - text: prose quality only (clarity, concision, natural voice)\n    - comments: comment quality only (slop categories 1, 4)\n    - code: code quality only (slop categories 2, 3, 5, 6, 7)\n    - all: route each finding to its mode and run the full pipeline\n\n  --dry-run: Report findings WITHOUT modifying anything (default: false)\n```\n\n## What This Command Does\n\nRaises prose, comment, and code quality to a natural human standard through a\nguided, approval-gated pipeline. Three modes route findings to the right rules:\n\n1. **text** - Prose quality: clarity, concision, natural voice, structure.\n2. **comments** - Comment quality: slop Categories 1 and 4. Rewrite or delete;\n   preserve intent-bearing comments (why, not what).\n3. **code** - Code quality: slop Categories 2, 3, 5, 6, 7. Simplify without\n   behavior change.\n4. **all** - Route each finding to its mode and run the full pipeline.\n\n**Quality-focused only. NO-detector-evasion: this command does NOT include,\nsuggest, or facilitate any detector-bypass techniques or guidance. No\nobfuscation tricks, no \"beat the detector\" heuristics, no paraphrase-to-evade\npatterns. Quality improvements only.**\n\n---\n\n# PHASE 0: VALIDATE REQUEST (MANDATORY FIRST STEP)\n\n## Step 0.1: Parse Target and Mode\n\n| Input | Interpretation |\n|-------|---------------|\n| File path (src/auth/handler.ts, docs/guide.md) | Scan that file only |\n| Directory path (src/features/) | Scan all source files in directory |\n| Glob pattern (src/**/*.ts) | Scan matching files |\n| Quoted string (\"...\") | Inline prose, text mode |\n| No argument | git-changed files (git diff --name-only HEAD~1), else src/ |\n\nMode routing:\n- Target is code file/dir/glob -> default mode: all\n- Target is prose/md file or quoted string -> default mode: text\n- Explicit --mode always wins over the default\n\n## Step 0.2: Detect --dry-run Flag\n\nIf --dry-run is present or user says \"just show me\" / \"report only\":\n- Set dry-run mode: report findings WITHOUT modifying anything\n- Skip PHASE 3 (guided fix) entirely; stop after the Phase 2 report\n\n## Step 0.3: Create Initial Todos\n\n```\ntask_create({ items: [\n  {\"subject\": \"PHASE 1: Scan/Detect - run applicable detectors per mode\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 2: Report - structured findings with severity and status\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 3: Guided Fix - per-finding approval, never auto-apply\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 4: Verify - diagnostics, typecheck, lint, tests\", \"priority\": \"high\"}\n]})\n```\n\n---\n\n# PHASE 1: SCAN/DETECT\n\n**Mark PHASE 1 as in_progress.**\n\n## 1.1: Text Mode \u2014 Prose-Quality Rules\n\nFor prose files (.md, .txt) and quoted strings, flag:\n\n- **clarity** - one idea per sentence, active voice preference, concrete over abstract\n- **concision** - cut filler, no redundant hedges\n- **natural voice** - varied sentence length, no formulaic openers/closers; avoid\n  formulaic phrasing as a quality matter (never as evasion)\n- **structure** - logical flow, scannable headings\n\n## 1.2: Comments Mode \u2014 Categories 1 and 4\n\n### Category 1: Verbose Comments (LOW)\n\nComments restating the obvious; empty JSDoc. Detection: ast_grep_search\n(`// $COMMENT` where $COMMENT matches obvious patterns), grep for known AI\ncomment phrases. Flag: `// Loop through each item`, `// Initialize variable`,\n`// Return result`, block comments repeating the function signature.\n\n### Category 4: Generic AI Phrasing (LOW)\n\nCode comments and documentation with AI-typical phrasing. Detection: grep -i\ncase-insensitive for the 17 flagged phrases: \"It's worth noting that\",\n\"It is important to note\", \"It is important to mention\",\n\"Let's step through this\", \"In conclusion\", \"As previously mentioned\",\n\"It should be noted that\", \"It's crucial to understand\",\n\"Let's break this down\", \"The beauty of this approach\",\n\"This is a classic example of\", \"Essentially, what this does is\",\n\"In the world of\", \"When it comes to\", \"One might argue that\",\n\"It goes without saying\".\n\n## 1.3: Code Mode \u2014 Categories 2, 3, 5, 6, 7\n\n### Category 2: Redundant Error Handling (MEDIUM)\n\nEmpty catch blocks (`catch (e) {}`), catch-log-rethrow\n(`catch(e) { console.error(e); throw e; }`), over-wrapped try/catch,\n`catch (error: any)` (unknown preferred). Detection: ast_grep_search for\n`catch($$$) { $$$ }`, lsp_find_references for redundant null checks.\n\n### Category 3: Over-Engineered Patterns (HIGH)\n\nSingle-implementation interfaces, builder-for-3-props, single strategy,\nAbstract*Factory*Manager naming, deep generics. Detection:\nlsp_find_references to check single implementations, ast_grep_search for class\nnames containing \"Abstract\", \"Factory\", \"Builder\", \"Manager\", grep for\n*Abstract*, *Factory*, *Proxy*, *Singleton* patterns.\n\n### Category 5: Cargo-Cult Boilerplate (MEDIUM)\n\nCopy-pasted error blocks, redundant guards, console.log in prod, TODO stubs.\nDetection: grep for repeated identical blocks, ast_grep_search for try/catch\nin every function, grep for TODO/FIXME/HACK in non-test files.\n\n### Category 6: Padding/Verbosity (LOW)\n\nEmpty @returns tags, obvious @param descriptions, redundant annotations\n(`const x: string = \"hello\"`), unnecessary intermediates\n(`const result = doSomething(); return result;`), unused destructured vars.\nDetection: ast_grep_search for redundant casts and arrow wrappers, grep for\nempty @returns, lsp_diagnostics for unused variables.\n\n### Category 7: Weird Codegen Artifacts (MEDIUM-HIGH)\n\nMixed import styles, mixed async styles, unused imports, `import *` for one\nsymbol, inline types belonging in shared files, magic numbers,\nlanguage-mismatched conventions. Detection: grep for mixed module systems,\nlsp_diagnostics for unused imports, ast_grep_search for inline type\ndefinitions that should be shared.\n\nBatching: for --all or large scopes, process files in groups of 5.\nDedupe findings; group by file with line ranges.\n\n**Mark PHASE 1 as completed.**\n\n---\n\n# PHASE 2: REPORT\n\n**Mark PHASE 2 as in_progress.**\n\nPresent a structured report:\n\n```\n## Humanize Report\n\n### Scan Target: [path]\n### Mode: [text|comments|code|all]\n### Findings: [N] ([X] text, [Y] comments, [Z] code)\n\n| Category | Count | Severity |\n|----------|-------|----------|\n| Prose quality | N | LOW |\n| 1. Verbose Comments | N | LOW |\n| 2. Redundant Error Handling | N | MEDIUM |\n| 3. Over-Engineered Patterns | N | HIGH |\n| 4. Generic AI Phrasing | N | LOW |\n| 5. Cargo-Cult Boilerplate | N | MEDIUM |\n| 6. Padding/Verbosity | N | LOW |\n| 7. Codegen Artifacts | N | MEDIUM-HIGH |\n\n### Findings by File\n\n#### [SEVERITY] Category N: Title \u2014 Location\n- **Location**: line X-Y\n- **Current**: [original text/code]\n- **Suggestion**: [proposed rewrite/simplification]\n- **Severity**: [LOW|MEDIUM|HIGH|MEDIUM-HIGH]\n- **Status**: PENDING\n```\n\nIf --dry-run mode: present the report and STOP. Do not proceed to Phase 3.\n\n```\nThis was a dry-run analysis. No code was modified.\nTo apply fixes, run: /humanize [same-target] [--mode=...]\n```\n\n**Mark PHASE 2 as completed.**\n\n---\n\n# PHASE 3: GUIDED FIX\n\n**Mark PHASE 3 as in_progress.**\n\nFor each finding, present the diff and ask the user:\n\n1. **Apply** - apply this fix\n2. **Skip** - mark as reviewed and acceptable\n3. **Snooze** - skip for now, flag for later review\n4. **Adjust** - user provides an alternative fix\n\nBatch support: user can say \"apply all LOW\" or \"apply all for file X\" to\nbatch-approve.\n\n**NEVER auto-apply fixes without user approval.** ALWAYS show the proposed\nchange before applying. ALWAYS run lsp_diagnostics after each edit. Mark each\nfinding as FIXED / SKIPPED.\n\n**Mark PHASE 3 as completed.**\n\n---\n\n# PHASE 4: VERIFY\n\n**Mark PHASE 4 as in_progress.**\n\nAfter all fixes applied:\n\n1. lsp_diagnostics on all changed files - no new errors\n2. `bun run typecheck` - no new type errors\n3. `bun run lint` - no new lint errors\n4. Run affected tests - no new failures\n\nGenerate a summary report (fixed count, skipped count, files modified,\nverification results).\n\n**Mark PHASE 4 as completed.**\n\n---\n\n# CRITICAL RULES\n\n## NEVER DO\n- Include, suggest, or facilitate any detector-evasion or detector-bypass\n  techniques, heuristics, or guidance of any kind\n- NEVER auto-apply fixes without explicit user approval per finding or batch\n- Skip lsp_diagnostics after an edit\n- Proceed with new type errors, new lint errors, or new test failures\n- Modify behavior when simplifying code (quality refactors only)\n- Use `as any`, `@ts-ignore`, `@ts-expect-error` to suppress fix side effects\n\n## ALWAYS DO\n- Parse target, mode, and --dry-run before scanning\n- Route each finding to its mode (text/comments/code)\n- Show the proposed diff and wait for approval before editing\n- Run lsp_diagnostics after each edit\n- Verify with typecheck, lint, and affected tests in Phase 4\n- Keep todos updated in real-time\n\n## ABORT CONDITIONS\nIf any of these occur, STOP and consult user:\n- Type errors appear after a fix (new, not pre-existing)\n- Lint errors appear after a fix (new, not pre-existing)\n- Tests fail after a fix (new failures, not pre-existing)\n- More than 20 findings in a single file (likely misconfiguration)\n\n<user-request>\n$ARGUMENTS\n</user-request>\n";

package/dist/features/builtin-commands/templates/init-deep.d.ts

@@ -0,0 +1 @@
+export declare const INIT_DEEP_TEMPLATE = "# /init-deep\n\nGenerate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.\n\n## Usage\n\n```\n/init-deep                      # Update mode: modify existing + create new where warranted\n/init-deep --create-new         # Read existing \u2192 remove all \u2192 regenerate from scratch\n/init-deep --max-depth=2        # Limit directory depth (default: 3)\n```\n\n---\n\n## Workflow (High-Level)\n\n1. **Discovery + Analysis** (concurrent)\n   - Fire background explore agents immediately\n   - Main session: bash structure + LSP codemap + read existing AGENTS.md\n2. **Score & Decide** - Determine AGENTS.md locations from merged findings\n3. **Generate** - Root first, then subdirs in parallel\n4. **Review** - Deduplicate, trim, validate\n\n<critical>\n**task_create ALL phases. Mark in_progress \u2192 completed in real-time.**\n```\ntask_create({ items: [\n  { subject: \"discovery\", priority: \"high\", description: \"Fire explore agents + LSP codemap + read existing\" },\n  { subject: \"scoring\", priority: \"high\", description: \"Score directories, determine locations\" },\n  { subject: \"generate\", priority: \"high\", description: \"Generate AGENTS.md files (root + subdirs)\" },\n  { subject: \"review\", priority: \"medium\", description: \"Deduplicate, validate, trim\" }\n]})\n```\n</critical>\n\n---\n\n## Phase 1: Discovery + Analysis (Concurrent)\n\n**Mark \"discovery\" as in_progress.**\n\n### Fire Background Explore Agents IMMEDIATELY\n\nDon't wait\u2014these run async while main session works.\n\n```\n// Fire all at once, collect results later\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore project structure\", run_in_background=true, prompt=\"Project structure: PREDICT standard patterns for detected language \u2192 REPORT deviations only\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find entry points\", run_in_background=true, prompt=\"Entry points: FIND main files \u2192 REPORT non-standard organization\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find conventions\", run_in_background=true, prompt=\"Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) \u2192 REPORT project-specific rules\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find anti-patterns\", run_in_background=true, prompt=\"Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments \u2192 LIST forbidden patterns\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore build/CI\", run_in_background=true, prompt=\"Build/CI: FIND .github/workflows, Makefile \u2192 REPORT non-standard patterns\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find test patterns\", run_in_background=true, prompt=\"Test patterns: FIND test configs, test structure \u2192 REPORT unique conventions\")\n```\n\n<dynamic-agents>\n**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:\n\n| Factor | Threshold | Additional Agents |\n|--------|-----------|-------------------|\n| **Total files** | >100 | +1 per 100 files |\n| **Total lines** | >10k | +1 per 10k lines |\n| **Directory depth** | \u22654 | +2 for deep exploration |\n| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |\n| **Monorepo** | detected | +1 per package/workspace |\n| **Multiple languages** | >1 | +1 per language |\n\n```bash\n# Measure project scale first\ntotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)\ntotal_lines=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" -o -name \"*.go\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')\nlarge_files=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')\nmax_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)\n```\n\nExample spawning:\n```\n// 500 files, 50k lines, depth 6, 15 large files \u2192 spawn 5+5+2+1 = 13 additional agents\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Analyze large files\", run_in_background=true, prompt=\"Large file analysis: FIND files >500 lines, REPORT complexity hotspots\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore deep modules\", run_in_background=true, prompt=\"Deep modules at depth 4+: FIND hidden patterns, internal conventions\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find shared utilities\", run_in_background=true, prompt=\"Cross-cutting concerns: FIND shared utilities across directories\")\n// ... more based on calculation\n```\n</dynamic-agents>\n\n### Main Session: Concurrent Analysis\n\n**While background agents run**, main session does:\n\n#### 1. Bash Structural Analysis\n```bash\n# Directory depth + file counts\nfind . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c\n\n# Files per directory (top 30)\nfind . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30\n\n# Code concentration by extension\nfind . -type f \\( -name \"*.py\" -o -name \"*.ts\" -o -name \"*.tsx\" -o -name \"*.js\" -o -name \"*.go\" -o -name \"*.rs\" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20\n\n# Existing AGENTS.md / CLAUDE.md\nfind . -type f \\( -name \"AGENTS.md\" -o -name \"CLAUDE.md\" \\) -not -path '*/node_modules/*' 2>/dev/null\n```\n\n#### 2. Read Existing AGENTS.md\n```\nFor each existing file found:\n  Read(filePath=file)\n  Extract: key insights, conventions, anti-patterns\n  Store in EXISTING_AGENTS map\n```\n\nIf `--create-new`: Read all existing first (preserve context) \u2192 then delete all \u2192 regenerate.\n\n#### 3. LSP Codemap (if available)\n```\nLspServers()  # Check availability\n\n# Entry points (parallel)\nLspDocumentSymbols(filePath=\"src/index.ts\")\nLspDocumentSymbols(filePath=\"main.py\")\n\n# Key symbols (parallel)\nLspWorkspaceSymbols(filePath=\".\", query=\"class\")\nLspWorkspaceSymbols(filePath=\".\", query=\"interface\")\nLspWorkspaceSymbols(filePath=\".\", query=\"function\")\n\n# Centrality for top exports\nLspFindReferences(filePath=\"...\", line=X, character=Y)\n```\n\n**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.\n\n### Collect Background Results\n\n```\n// After main session analysis done, collect all task results\nfor each task_id: background_output(task_id=\"...\")\n```\n\n**Merge: bash + LSP + existing + explore findings. Mark \"discovery\" as completed.**\n\n---\n\n## Phase 2: Scoring & Location Decision\n\n**Mark \"scoring\" as in_progress.**\n\n### Scoring Matrix\n\n| Factor | Weight | High Threshold | Source |\n|--------|--------|----------------|--------|\n| File count | 3x | >20 | bash |\n| Subdir count | 2x | >5 | bash |\n| Code ratio | 2x | >70% | bash |\n| Unique patterns | 1x | Has own config | explore |\n| Module boundary | 2x | Has index.ts/__init__.py | bash |\n| Symbol density | 2x | >30 symbols | LSP |\n| Export count | 2x | >10 exports | LSP |\n| Reference centrality | 3x | >20 refs | LSP |\n\n### Decision Rules\n\n| Score | Action |\n|-------|--------|\n| **Root (.)** | ALWAYS create |\n| **>15** | Create AGENTS.md |\n| **8-15** | Create if distinct domain |\n| **<8** | Skip (parent covers) |\n\n### Output\n```\nAGENTS_LOCATIONS = [\n  { path: \".\", type: \"root\" },\n  { path: \"src/hooks\", score: 18, reason: \"high complexity\" },\n  { path: \"src/api\", score: 12, reason: \"distinct domain\" }\n]\n```\n\n**Mark \"scoring\" as completed.**\n\n---\n\n## Phase 3: Generate AGENTS.md\n\n**Mark \"generate\" as in_progress.**\n\n<critical>\n**File Writing Rule**: If AGENTS.md already exists at the target path \u2192 use `Edit` tool. If it does NOT exist \u2192 use `Write` tool.\nNEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results.\n</critical>\n\n### Root AGENTS.md (Full Treatment)\n\n```markdown\n# PROJECT KNOWLEDGE BASE\n\n**Generated:** {TIMESTAMP}\n**Commit:** {SHORT_SHA}\n**Branch:** {BRANCH}\n\n## OVERVIEW\n{1-2 sentences: what + core stack}\n\n## STRUCTURE\n\\`\\`\\`\n{root}/\n\u251C\u2500\u2500 {dir}/    # {non-obvious purpose only}\n\u2514\u2500\u2500 {entry}\n\\`\\`\\`\n\n## WHERE TO LOOK\n| Task | Location | Notes |\n|------|----------|-------|\n\n## CODE MAP\n{From LSP - skip if unavailable or project <10 files}\n\n| Symbol | Type | Location | Refs | Role |\n|--------|------|----------|------|------|\n\n## CONVENTIONS\n{ONLY deviations from standard}\n\n## ANTI-PATTERNS (THIS PROJECT)\n{Explicitly forbidden here}\n\n## UNIQUE STYLES\n{Project-specific}\n\n## COMMANDS\n\\`\\`\\`bash\n{dev/test/build}\n\\`\\`\\`\n\n## NOTES\n{Gotchas}\n```\n\n**Quality gates**: 50-150 lines, no generic advice, no obvious info.\n\n### Subdirectory AGENTS.md (Parallel)\n\nLaunch writing tasks for each location:\n\n```\nfor loc in AGENTS_LOCATIONS (except root):\n  task(category=\"broadcast\", load_skills=[], run_in_background=false, description=\"Generate AGENTS.md\", prompt=\\`\n    Generate AGENTS.md for: ${loc.path}\n    - Reason: ${loc.reason}\n    - 30-80 lines max\n    - NEVER repeat parent content\n    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS\n  \\`)\n```\n\n**Wait for all. Mark \"generate\" as completed.**\n\n---\n\n## Phase 4: Review & Deduplicate\n\n**Mark \"review\" as in_progress.**\n\nFor each generated file:\n- Remove generic advice\n- Remove parent duplicates\n- Trim to size limits\n- Verify telegraphic style\n\n**Mark \"review\" as completed.**\n\n---\n\n## Final Report\n\n```\n=== init-deep Complete ===\n\nMode: {update | create-new}\n\nFiles:\n  [OK] ./AGENTS.md (root, {N} lines)\n  [OK] ./src/hooks/AGENTS.md ({N} lines)\n\nDirs Analyzed: {N}\nAGENTS.md Created: {N}\nAGENTS.md Updated: {N}\n\nHierarchy:\n  ./AGENTS.md\n  \u2514\u2500\u2500 src/hooks/AGENTS.md\n```\n\n---\n\n## Anti-Patterns\n\n- **Static agent count**: MUST vary agents based on project size/depth\n- **Sequential execution**: MUST parallel (explore + LSP concurrent)\n- **Ignoring existing**: ALWAYS read existing first, even with --create-new\n- **Over-documenting**: Not every dir needs AGENTS.md\n- **Redundancy**: Child never repeats parent\n- **Generic content**: Remove anything that applies to ALL projects\n- **Verbose style**: Telegraphic or die";

package/dist/features/builtin-commands/templates/matrix-loop.d.ts

@@ -0,0 +1,2 @@
+export declare const MATRIX_LOOP_TEMPLATE = "You are starting a Matrix Loop - a self-referential development loop that runs until task completion.\n\n## How Matrix Loop Works\n\n1. You will work on the task continuously\n2. When you believe the task is FULLY complete, output: `<promise>{{COMPLETION_PROMISE}}</promise>`\n3. If you don't output the promise, the loop will automatically inject another prompt to continue\n4. Maximum iterations: Configurable (default 100)\n\n## Rules\n\n- Focus on completing the task fully, not partially\n- Don't output the completion promise until the task is truly done\n- Each iteration should make meaningful progress toward the goal\n- If stuck, try different approaches\n- Use todos to track your progress\n\n## Exit Conditions\n\n1. **Completion**: Output your completion promise tag when fully complete\n2. **Max Iterations**: Loop stops automatically at limit\n3. **Cancel**: User runs `/cancel-loop` command\n\n## Your Task\n\nParse the arguments below and begin working on the task. The format is:\n`\"task description\" [--completion-promise=TEXT] [--max-iterations=N]`\n\nDefault completion promise is \"DONE\" and default max iterations is 100.";
+export declare const CANCEL_LOOP_TEMPLATE = "Cancel the currently active Matrix Loop.\n\nThis will:\n1. Stop the loop from continuing\n2. Clear the loop state file\n3. Allow the session to end normally\n\nCheck if a loop is active and cancel it. Inform the user of the result.";

package/dist/features/builtin-commands/templates/pickup.d.ts

@@ -0,0 +1 @@
+export declare const PICKUP_TEMPLATE = "# Pickup Command\n\n## Purpose\n\nUse /pickup to load handoff context from a previous session.\n\n---\n\n# PHASE 1: READ HANDOFF\n\nCall handoff({ action: \"read\" }) to load the handoff context.\n\nIf the response starts with Error:, inform the user:\n\"No handoff context found. Run /handoff in a previous session first to create one.\"\nThen STOP \u2014 do not proceed.\n\n---\n\n# PHASE 2: ACKNOWLEDGE\n\nSummarize the loaded context to the user:\n- What the previous session was working on (Goal)\n- What was completed (Work Completed)\n- What remains (Pending Tasks)\n\nThen state: \"Handoff context loaded. Ready to continue.\"\n\n---\n\n# PHASE 3: ARCHIVE\n\nCall handoff({ action: \"archive\" }) to mark the handoff as consumed.\nThis prevents it from being picked up again.\n\n---\n\n# CONSTRAINTS\n\n- DO call the handoff tool \u2014 do not read files directly\n- DO NOT modify the handoff content \u2014 use it as-is\n- DO begin working immediately if the user included a task with /pickup\n";

package/dist/features/builtin-commands/templates/plan-review.d.ts

@@ -0,0 +1 @@
+export declare const PLAN_REVIEW_TEMPLATE = "You are running a post-execution completion review of a finished plan.\n\n## Triggering \u2014 LOCKED\n\nThis command is the ONLY trigger for a completion review. There is no other one:\nno hook invokes it, no `session.idle` path invokes it, no `progress.isComplete`\npath invokes it, and no Niobe step invokes it. A hook cannot run an agent,\nso with explicit-only triggering there is deliberately NO automatic attach point.\nThat is the design, not a gap. Never install one, and never offer to.\n\n## WHAT TO DO, IN THIS ORDER\n\n1. **Resolve the plan, or stop.** Take the plan name from `<user-request>`. Call\n   `plan_list`, then `plan_tasks` for the named plan. `plan_list` SILENTLY SKIPS\n   non-kebab filenames, so a non-kebab plan name yields an EMPTY resolution\n   rather than an error. If the requested plan is absent from the result, ERROR\n   CLEARLY AND STOP: name the plan, state that `plan_list` returned no match, and\n   create no report file. Never proceed on an empty or partial resolution, and\n   never substitute a different plan.\n\n2. **Gather the deterministic inputs.** Read the plan with `plan_read` and call\n   `gatherCompletionReviewInputs({ directory, planPath })`. This is pure: no\n   model, no network, no mutation. DoD is NEVER merged into `isComplete`, and\n   task\u2192plan linkage is a convention, not a foreign key \u2014 both are labelled\n   `heuristic` for that reason.\n\n3. **Evaluate the admission gate BEFORE anything else.** Read\n   `evaluateAdmission({ progress, admission })` from the gathered facts. It reads\n   T2's output and re-reads nothing.\n\n4. **Delegate the MODEL dimensions to the `merovingian` agent.** Pass it the\n   gathered context and the report skeleton. It supplies dimensions 2, 3, 4, 6\n   and 8. It must never write the report into the plan file.\n\n5. **Compute the DETERMINISTIC dimensions.** Call `evaluateReview` with\n   `missingModelSections` supplied as INPUT:\n   `detectMissingModelSections(buildSectionIndex(planContent))`. Do not let the\n   evaluator re-parse. Dimensions 1, 5 and 7 are code-computed. Pass each\n   dimension's `reason` through as `rationale`; do not invent your own wording.\n\n6. **Render and write the report.** Run `buildReviewDirCommand()` in bash first\n   (`mkdir -p \".matrixx/reviews\"`), then call `writeReviewReport(input)`. It\n   writes `.matrixx/reviews/<plan>.md` and the `.json` sidecar together, and\n   never opens the plan file. `generatedAt` is a caller-supplied input.\n\n7. **Report the path back to the user.** Give the absolute report path and the\n   sidecar path. Do not modify the plan.\n\n## THE ADMISSION GATE \u2014 never on `isComplete` alone\n\n`isComplete` derives solely from the plan's own checkboxes, and those checkboxes\nare flipped by the very fuzzy text-similarity heuristic the gatherer refuses to\ntrust. Admitting on `isComplete` alone would decide admission on the exact\nartifact the report then labels untrustworthy. Admission therefore requires BOTH:\n\n- **a.** `isComplete === true` AND `needsTriage === false`\n  (`needsTriage` is checked FIRST, because a zero-checkbox plan arrives with\n  `isComplete: true` by vacuity), **and**\n- **b.** at least one INDEPENDENT corroborating terminal signal \u2014 a linked task\n  in terminal status or a notepad `## Completion` stamp \u2014 whose records account\n  for the plan's declared work.\n\nThis admission gate is a HEURISTIC and may be wrong in BOTH directions: it can refuse a genuinely finished plan whose checkboxes were never flipped, and it can admit a genuinely unfinished one. The recorded state below is a finding about the plan, not ground truth.\n\n### Three states\n\n- **`agree`** \u2014 `isComplete === true && !needsTriage && corroboration present &&\n  corroboration accounts for the plan`. The report records which signal admitted\n  the plan.\n- **`disagree`** \u2014 the signals conflict. **PROCEED and record `gateDisagreement`**\n  as `{ checkboxesSaysComplete, corroborationSaysComplete, resolved: \"proceed\",\n  reason }`, naming BOTH signals. Never silently pick a winner. Hard refusal is\n  reserved for exactly two cases: vacuous completeness (`needsTriage: true`) or\n  both signals saying incomplete.\n- **`unavailable`** \u2014 corroboration is structurally absent (0 linked tasks AND\n  0 stamps). Admit on `isComplete` + `needsTriage === false`, record\n  `gateEvidence: \"unavailable\"` and the one-line reason below. You\n  MUST NOT emit a `gateDisagreement` here \u2014 every legacy plan would then look\n  like a disagreement and the field would be noise.\n  Reason to record: corroboration is structurally absent: `metadata.planName` appears in 0 of 48 task files, and a `## Completion` stamp in 1 of 19 notepad buckets.\n  `gateDisagreement` is real but diagnostic-only: no code reads it; the renderer\n  shows it to the human reader.\n\n## THE FOUR REQUIRED PARTS\n\nThe report must carry all four, each under its own heading, and none is skipped\nwhen its data is absent:\n\n- **Summary**\n- **Score**\n- **Complexity**\n- **Required Effort**\n\n## CRITICAL\n\n- Never write the report into the plan file. The plan records intent and progress;\n  prose corrupts both, and a report appended there makes the progress counters\n  absorb paragraphs they were never meant to count.\n- A low score is ADVISORY. Nothing in this pipeline halts, retries or rejects a\n  plan because of the number, and `unscorable` is never rendered as 0 \u2014 a\n  not-scored plan emits no number at all.\n- On an unfinished plan, create NO report file and invoke NO agent. Say the plan\n  is not scorable yet.\n";

package/dist/features/builtin-commands/templates/preset.d.ts

@@ -0,0 +1 @@
+export declare const PRESET_TEMPLATE = "You are managing the active model preset.\n\nThis command is provided by the Matrixx plugin. It uses the built-in `preset` tool to list, show, or switch model presets \u2014 no external scripts or direct config edits needed.\n\n## Usage\n\n```\n/preset                  \u2192 List available presets and mark the active one\n/preset list             \u2192 List available presets\n/preset show [<name>]    \u2192 Show a preset's agent/category model assignments (defaults to active)\n/preset set <name>       \u2192 Switch the active preset for the current session (live)\n/preset set <name> --save [--global|--project] \u2192 Also persist active_preset to config\n```\n\n## Step 1: Determine the action\n\nParse the arguments passed to this command:\n\n- No arguments or `list` \u2192 call `preset` with `action: \"list\"`.\n- `show` \u2192 call `preset` with `action: \"show\"` (optionally `name`).\n- `set <name>` \u2192 call `preset` with `action: \"set\"`, `name: \"<name>\"`.\n- `set <name> --save` \u2192 also pass `save: true`; `--global` \u2192 `scope: \"global\"`, `--project` (default) \u2192 `scope: \"project\"`.\n\n## Step 2: Call the built-in `preset` tool\n\nUse the `preset` tool with the resolved arguments. The tool validates the preset name, applies the session overlay (delegate-task categories switch immediately), and \u2014 with `--save` \u2014 persists `active_preset` to the project (`.opencode/matrixx.jsonc`) or global (`~/.config/opencode/matrixx.jsonc`) config.\n\nThe tool handles all validation and file operations \u2014 do NOT edit config files directly.\n\n## Step 3: Confirm and instruct\n\nAfter a successful switch:\n\n1. Report the tool's output to the user.\n2. Note that delegate-task categories use the new preset immediately (session-scoped live switch).\n3. If `--save` was used, tell the user the persisted `active_preset` takes effect for builtin agents on the next session.\n\n## Important constraints\n\n- Use the built-in `preset` tool. Do NOT bypass it by editing config files directly.\n- Do not invent preset names \u2014 if the requested name is unknown, report the available presets and stop.\n- `--save` without a scope defaults to project scope.";

package/dist/features/builtin-commands/templates/quality-assurance.d.ts

@@ -0,0 +1 @@
+export declare const QUALITY_ASSURANCE_TEMPLATE = "# Quality Assurance Command\n\n## Usage\n\n```\n/quality-assurance [--scope=file|module|project] [--target-grade=B] [--max-iterations=3] [--target=<path>]\n```\n\nDefaults: --scope=project, --target-grade=B, --max-iterations=3.\n\nArguments:\n  --scope: Assurance scope (default: project)\n    - file: Single file only (requires --target=<path>)\n    - module: Module/directory scope (requires --target)\n    - project: Entire codebase\n  --target-grade: Grade to reach before stopping (default: B). Grades A-F.\n  --max-iterations: Bounded loop cap (default: 3). Values >3 require an explicit user flag.\n  --target: Path restricting edits when --scope=file (or a module path when --scope=module). Required for file and module scope.\n\nThis loop is BOUNDED with a fixed cap. It never loops without a bound and never chases perfection without a cap.\n\n## Protocol Loop (fixed order, bounded)\n\nRun these steps in this exact order per iteration:\n\n1. **Baseline.** Run /quality-audit for the current --scope/--target. Keep the\n   baseline report path. The baseline grade, perDimension (each: status +\n   exitCode + evidence), exitCodes map, scope, timestamp/generatedAt\n   (caller-supplied, never self-generated), targetGrade, and iterations fields\n   form the only input the rest of the iteration may use.\n2. **Oracle delta-plan.** Consult the oracle agent for a minimal fix list derived\n   from the baseline report ONLY. No new scope, no new dimensions, no fresh\n   exploration beyond the baseline evidence. Read-only step.\n3. **Smith gate.** Pass the oracle delta-plan through the smith gate per the\n   plan-review doctrine BEFORE any edits: admission check first, then approval.\n   Blocked plans stop the iteration with no edits. Read-only step.\n4. **TDD implement.** TDD RED-GREEN-REFACTOR semantics ALWAYS, per tdd-enforcer:\n   RED (write a failing test first), GREEN (minimum code to pass), REFACTOR\n   (clean up, tests stay green). The main session writes the tests itself; never\n   delegate test authorship. This is the ONLY step that MAY Edit/Write source\n   files, strictly within --scope/--target only. Verify after each change\n   (lsp_diagnostics clean, tests pass) before proceeding.\n5. **Verify.** Re-run /quality-audit on the same --scope/--target and compare\n   grades (new grade vs old grade). Write the iteration report (see below) with\n   iterations incremented.\n\n## Stop Conditions (any one stops the loop)\n\n- Grade >= target: the verify grade meets or exceeds --target-grade.\n- Zero-delta: new grade == old grade with no new fixes remaining.\n- Iteration cap reached: iterations == --max-iterations (default 3).\n\nWhen any stop condition fires, stop immediately. No post-review step follows:\nthe merovingian agent is invoked ONLY by the explicit `/plan-review` command,\nnever automatically and never as part of this loop.\n\n## Report Contract (same as audit)\n\nEach iteration writes `.matrixx/quality/<scope>-<timestamp>.md` + the `.json`\nsidecar together (timestamp caller-supplied, unique per run, last-write-wins).\nThe JSON carries grade (A-F), perDimension (each: status + exitCode +\nevidence; the silent-failures entry MUST also record `waiverFile` (or null) plus\n`waived` and `stale` counts), exitCodes map, scope, timestamp/generatedAt (caller-supplied),\ntargetGrade, and iterations (incremented each iteration). Exits: 0=pass /\n1=warnings / 2=errors. v1 is advisory-only: a low grade never halts, retries,\nor rejects. Never write to `.matrixx/plans/`; never open or mutate a plan file.\n\n## Forbid-List\n\nIdentical to the audit forbid-list EXCEPT the TDD-implement step MAY Edit/Write\nsource files strictly within --scope/--target only:\n\n- All other steps (baseline, oracle delta-plan, smith gate, verify) are\n  read-only: NO Edit/Write to source, NO lsp_rename, NO\n  non-dryRun ast_grep_replace, NO task_create/task_update, NO plan_update.\n- Report writes are report + sidecar only.\n- Per-iteration wall-clock timeout 300 (5 min). Exceeding the timeout stops the\n  iteration and records the timeout in the report.\n- No scope expansion mid-loop: --scope/--target are fixed when the loop starts.\n- No --max-iterations value >3 without an explicit user flag.\n- No auto-PR, no merge, no master push, no new agents/tools/skills.\n\n## Critical\n\n- The loop is bounded with default 3. There is no unbounded mode.\n- Low grades are ADVISORY. Nothing here auto-merges or publishes.\n\n<user-request>\n$ARGUMENTS\n</user-request>\n";

package/dist/features/builtin-commands/templates/quality-audit.d.ts

@@ -0,0 +1 @@
+export declare const QUALITY_AUDIT_TEMPLATE = "You are running a read-only deterministic quality audit (v1 advisory-only).\n\n## Usage\n\n```\n/quality-audit [--scope=file|module|project] [--target=<path>]\n```\n\n- --scope: file | module | project (default: project).\n  - file: single --target path only.\n  - module: the directory containing --target.\n  - project: full tree.\n- --target: path scoping the audit. Optional for project scope; required for file and module scope.\n- Diff-scoped fast path: when the working tree has uncommitted changes, restrict\n  gathering to changed files first (UNVERIFIED CLAIM: exact git-diff refspec\n  origin/dev...HEAD vs staged is unverified \u2014 use whatever diff the session\n  provides and record which refspec was used as evidence).\n- Invalid --scope value is a hard error: `error: invalid --scope '<v>'\n  (expected file|module|project)`, exit 2, no report written.\n- Typo rule: /qualiti-assurance is a typo, no alias. Any unknown /quality-*\n  variant is an error, never an alias or auto-correction.\n- v1 advisory-only: this command never fails the build, never gates CI, only\n  reports. Exit-code mapping 0/1/2 reserved: 0 = pass, 1 = warnings, 2 = errors.\n\n## WHAT TO DO, IN THIS ORDER\n\n1. **Resolve the scope, or stop.** Parse --scope and --target from\n   <user-request>. Resolve --target against the working tree. If the target is\n   unresolvable (missing path, invalid --scope value, file or module scope\n   without a target), ERROR AND STOP: state the scope, the target, and why resolution\n   failed, and create no report file. Never proceed on an empty or partial\n   resolution, and never substitute a different target.\n\n2. **Gather the deterministic read-only inputs.** All gathering is read-only;\n   run nothing that mutates source. Collect, in this order:\n   - `tsc --noEmit` (typecheck) on the scope.\n   - `biome check src/` (lint, src-only).\n   - `bun test` with mock-heavy isolation per script/run-ci.sh\n     (isolated runs for mock-heavy entries listed in script/mock-heavy-list.txt,\n     then the catch-all exclusion).\n   - silent-failure-scanner on the scope (tool: silent_failure_scan).\n     If the scope provides a committed waiver file, pass it as `waivers` (never invent a waiver path; never accept one under gitignored `.matrixx/`).\n   - Conditional validators, ONLY when the scope touches those domains:\n     dashboard-flux-validator for Grafana/Flux dashboards,\n     market-symbol-validator for market-symbol code,\n     staleness-gap-checker for market-data feed samples.\n     Skip inapplicable validators as N/A (see threshold table).\n   - lsp_diagnostics (read-only) for files in scope as corroborating evidence.\n   Record each tool's raw exit code and output as evidence.\n\n3. **Compute the DETERMINISTIC grade from exit codes only.** The grade is a pure\n   function of per-dimension exit codes and warning/error counts. No model\n   judgment enters the grade. The silent-failures dimension uses the filtered\n   exit code (after waivers).\n\n   Per-dimension mapping (threshold rule per dimension):\n   - exit 0 \u2192 pass\n   - exit 1 \u2192 warn\n   - exit 2 \u2192 fail\n   - N/A \u2192 status N/A + exitCode null, excluded from grade computation\n     (does not count toward warning/error tallies).\n\n   Grade threshold table (fixed numbers, no approximations):\n\n   | Condition | Grade |\n   |-----------|-------|\n   | all dimensions exit 0 with 0 errors + 0 warnings | A |\n   | any dimension exit 1 with 0 exit-2, and warning-dimensions <= 1 | B |\n   | any dimension exit 1 with 0 exit-2, and warning-dimensions >= 2 | C |\n   | any dimension exit 2 with exactly 1 error-dimension | D |\n   | any dimension exit 2 with >= 2 error-dimensions | F |\n\n   Rules:\n   - N/A dimensions carry status N/A and exitCode null and are excluded from\n     grade computation entirely.\n   - Dimensions evaluated: typecheck, lint, tests, silent-failures,\n     flux (conditional), market-symbols (conditional), staleness (conditional),\n     diagnostics (corroborating).\n   - Sentinel, tank, and neo prose goes to an advisory appendix and MUST NOT\n     change the grade. The grade derives from tool exit codes only.\n\n4. **Delegate the ADVISORY dimensions to sentinel, tank, and neo.** These agents\n   supply prose only (architecture notes from sentinel, adversarial notes from\n   tank, exploratory notes from neo) for the advisory appendix. Their output is\n   never a grade input and MUST NOT change the grade. They must never write the\n   report and never touch source.\n\n5. **Render and write the report.** Run `mkdir -p .matrixx/quality` in bash\n   first, then write `.matrixx/quality/<scope>-<timestamp>.md` and the\n   same-basename `.json` sidecar together. `generatedAt`/timestamp is a\n   caller-supplied input \u2014 never self-generate it. Report JSON keys: grade\n   (A-F), perDimension (one entry per rubric dimension with status + exitCode +\n   evidence), exitCodes map, scope, timestamp/generatedAt (caller-supplied),\n   targetGrade (assurance only), iterations (assurance only). The silent-failures\n   entry MUST also record `waiverFile` (or null) plus `waived` and `stale` counts.\n   Never touch\n\n6. **Report the paths back to the user.** Give the absolute report path and the\n   sidecar path plus the grade and per-dimension exit codes. Do not modify any\n   plan.\n\n## FORBID LIST \u2014 hard denials inside this audit\n\n- NO Edit/Write to source files.\n- NO lsp_rename.\n- NO non-dryRun ast_grep_replace (dryRun preview reads are allowed; applying is denied).\n- NO task_create / NO task_update.\n- NO plan_update and never touch .matrixx/plans.\n- Writes = report+sidecar only: the ONLY writable paths are\n  .matrixx/quality/<scope>-<timestamp>.md plus its same-basename .json sidecar\n  (after mkdir -p .matrixx/quality). No staging, no network, no other writes.\n\n<user-request>\n$ARGUMENTS\n</user-request>";

package/dist/features/builtin-commands/templates/refactor.d.ts

@@ -0,0 +1 @@
+export declare const REFACTOR_TEMPLATE = "# Intelligent Refactor Command\n\n## Usage\n```\n/refactor <refactoring-target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]\n\nArguments:\n  refactoring-target: What to refactor. Can be:\n    - File path: src/auth/handler.ts\n    - Symbol name: \"AuthService class\"\n    - Pattern: \"all functions using deprecated API\"\n    - Description: \"extract validation logic into separate module\"\n\nOptions:\n  --scope: Refactoring scope (default: module)\n    - file: Single file only\n    - module: Module/directory scope\n    - project: Entire codebase\n\n  --strategy: Risk tolerance (default: safe)\n    - safe: Conservative, maximum test coverage required\n    - aggressive: Allow broader changes with adequate coverage\n```\n\n## What This Command Does\n\nPerforms intelligent, deterministic refactoring with full codebase awareness. Unlike blind search-and-replace, this command:\n\n1. **Understands your intent** - Analyzes what you actually want to achieve\n2. **Maps the codebase** - Builds a definitive codemap before touching anything\n3. **Assesses risk** - Evaluates test coverage and determines verification strategy\n4. **Plans meticulously** - Creates a detailed plan with Plan agent\n5. **Executes precisely** - Step-by-step refactoring with LSP and AST-grep\n6. **Verifies constantly** - Runs tests after each change to ensure zero regression\n\n---\n\n# PHASE 0: INTENT GATE (MANDATORY FIRST STEP)\n\n**BEFORE ANY ACTION, classify and validate the request.**\n\n## Step 0.1: Parse Request Type\n\n| Signal | Classification | Action |\n|--------|----------------|--------|\n| Specific file/symbol | Explicit | Proceed to codebase analysis |\n| \"Refactor X to Y\" | Clear transformation | Proceed to codebase analysis |\n| \"Improve\", \"Clean up\" | Open-ended | **MUST ask**: \"What specific improvement?\" |\n| Ambiguous scope | Uncertain | **MUST ask**: \"Which modules/files?\" |\n| Missing context | Incomplete | **MUST ask**: \"What's the desired outcome?\" |\n\n## Step 0.2: Validate Understanding\n\nBefore proceeding, confirm:\n- [ ] Target is clearly identified\n- [ ] Desired outcome is understood\n- [ ] Scope is defined (file/module/project)\n- [ ] Success criteria can be articulated\n\n**If ANY of above is unclear, ASK CLARIFYING QUESTION:**\n\n```\nI want to make sure I understand the refactoring goal correctly.\n\n**What I understood**: [interpretation]\n**What I'm unsure about**: [specific ambiguity]\n\nOptions I see:\n1. [Option A] - [implications]\n2. [Option B] - [implications]\n\n**My recommendation**: [suggestion with reasoning]\n\nShould I proceed with [recommendation], or would you prefer differently?\n```\n\n## Step 0.3: Create Initial Todos\n\n**IMMEDIATELY after understanding the request, create todos:**\n\n```\ntask_create({ items: [\n  {\"subject\": \"PHASE 1: Codebase Analysis - launch parallel explore agents\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 2: Build Codemap - map dependencies and impact zones\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 3: Test Assessment - analyze test coverage and verification strategy\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 5: Execute Refactoring - step-by-step with continuous verification\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 6: Final Verification - full test suite and regression check\", \"priority\": \"high\"}\n]})\n```\n\n---\n\n# PHASE 1: CODEBASE ANALYSIS (PARALLEL EXPLORATION)\n\n**Mark phase-1 as in_progress.**\n\n## 1.1: Launch Parallel Explore Agents (BACKGROUND)\n\nFire ALL of these simultaneously using `task`:\n\n```\n// Agent 1: Find the refactoring target\ntask(\n  subagent_type=\"trinity\",\n  run_in_background=true,\n  prompt=\"Find all occurrences and definitions of [TARGET]. \n  Report: file paths, line numbers, usage patterns.\"\n)\n\n// Agent 2: Find related code\ntask(\n  subagent_type=\"trinity\", \n  run_in_background=true,\n  prompt=\"Find all code that imports, uses, or depends on [TARGET].\n  Report: dependency chains, import graphs.\"\n)\n\n// Agent 3: Find similar patterns\ntask(\n  subagent_type=\"trinity\",\n  run_in_background=true,\n  prompt=\"Find similar code patterns to [TARGET] in the codebase.\n  Report: analogous implementations, established conventions.\"\n)\n\n// Agent 4: Find tests\ntask(\n  subagent_type=\"trinity\",\n  run_in_background=true,\n  prompt=\"Find all test files related to [TARGET].\n  Report: test file paths, test case names, coverage indicators.\"\n)\n\n// Agent 5: Architecture context\ntask(\n  subagent_type=\"trinity\",\n  run_in_background=true,\n  prompt=\"Find architectural patterns and module organization around [TARGET].\n  Report: module boundaries, layer structure, design patterns in use.\"\n)\n```\n\n## 1.2: Direct Tool Exploration (WHILE AGENTS RUN)\n\nWhile background agents are running, use direct tools:\n\n### LSP Tools for Precise Analysis:\n\n```typescript\n// Find definition(s)\nLspGotoDefinition(filePath, line, character)  // Where is it defined?\n\n// Find ALL usages across workspace\nLspFindReferences(filePath, line, character, includeDeclaration=true)\n\n// Get file structure\nLspDocumentSymbols(filePath)  // Hierarchical outline\nLspWorkspaceSymbols(filePath, query=\"[target_symbol]\")  // Search by name\n\n// Get current diagnostics\nlsp_diagnostics(filePath)  // Errors, warnings before we start\n```\n\n### AST-Grep for Pattern Analysis:\n\n```typescript\n// Find structural patterns\nast_grep_search(\n  pattern=\"function $NAME($$$) { $$$ }\",  // or relevant pattern\n  lang=\"typescript\",  // or relevant language\n  paths=[\"src/\"]\n)\n\n// Preview refactoring (DRY RUN)\nast_grep_replace(\n  pattern=\"[old_pattern]\",\n  rewrite=\"[new_pattern]\",\n  lang=\"[language]\",\n  dryRun=true  // ALWAYS preview first\n)\n```\n\n### Grep for Text Patterns:\n\n```\ngrep(pattern=\"[search_term]\", path=\"src/\", include=\"*.ts\")\n```\n\n## 1.3: Collect Background Results\n\n```\nbackground_output(task_id=\"[agent_1_id]\")\nbackground_output(task_id=\"[agent_2_id]\")\n...\n```\n\n**Mark phase-1 as completed after all results collected.**\n\n---\n\n# PHASE 2: BUILD CODEMAP (DEPENDENCY MAPPING)\n\n**Mark phase-2 as in_progress.**\n\n## 2.1: Construct Definitive Codemap\n\nBased on Phase 1 results, build:\n\n```\n## CODEMAP: [TARGET]\n\n### Core Files (Direct Impact)\n- `path/to/file.ts:L10-L50` - Primary definition\n- `path/to/file2.ts:L25` - Key usage\n\n### Dependency Graph\n```\n[TARGET] \n\u251C\u2500\u2500 imports from: \n\u2502   \u251C\u2500\u2500 module-a (types)\n\u2502   \u2514\u2500\u2500 module-b (utils)\n\u251C\u2500\u2500 imported by:\n\u2502   \u251C\u2500\u2500 consumer-1.ts\n\u2502   \u251C\u2500\u2500 consumer-2.ts\n\u2502   \u2514\u2500\u2500 consumer-3.ts\n\u2514\u2500\u2500 used by:\n    \u251C\u2500\u2500 handler.ts (direct call)\n    \u2514\u2500\u2500 service.ts (dependency injection)\n```\n\n### Impact Zones\n| Zone | Risk Level | Files Affected | Test Coverage |\n|------|------------|----------------|---------------|\n| Core | HIGH | 3 files | 85% covered |\n| Consumers | MEDIUM | 8 files | 70% covered |\n| Edge | LOW | 2 files | 50% covered |\n\n### Established Patterns\n- Pattern A: [description] - used in N places\n- Pattern B: [description] - established convention\n```\n\n## 2.2: Identify Refactoring Constraints\n\nBased on codemap:\n- **MUST follow**: [existing patterns identified]\n- **MUST NOT break**: [critical dependencies]\n- **Safe to change**: [isolated code zones]\n- **Requires migration**: [breaking changes impact]\n\n**Mark phase-2 as completed.**\n\n---\n\n# PHASE 3: TEST ASSESSMENT (VERIFICATION STRATEGY)\n\n**Mark phase-3 as in_progress.**\n\n## 3.1: Detect Test Infrastructure\n\n```bash\n# Check for test commands\ncat package.json | jq '.scripts | keys[] | select(test(\"test\"))'\n\n# Or for Python\nls -la pytest.ini pyproject.toml setup.cfg\n\n# Or for Go\nls -la *_test.go\n```\n\n## 3.2: Analyze Test Coverage\n\n```\n// Find all tests related to target\ntask(\n  subagent_type=\"trinity\",\n  run_in_background=false,  // Need this synchronously\n  prompt=\"Analyze test coverage for [TARGET]:\n  1. Which test files cover this code?\n  2. What test cases exist?\n  3. Are there integration tests?\n  4. What edge cases are tested?\n  5. Estimated coverage percentage?\"\n)\n```\n\n## 3.3: Determine Verification Strategy\n\nBased on test analysis:\n\n| Coverage Level | Strategy |\n|----------------|----------|\n| HIGH (>80%) | Run existing tests after each step |\n| MEDIUM (50-80%) | Run tests + add safety assertions |\n| LOW (<50%) | **PAUSE**: Propose adding tests first |\n| NONE | **BLOCK**: Refuse aggressive refactoring |\n\n**If coverage is LOW or NONE, ask user:**\n\n```\nTest coverage for [TARGET] is [LEVEL].\n\n**Risk Assessment**: Refactoring without adequate tests is dangerous.\n\nOptions:\n1. Add tests first, then refactor (RECOMMENDED)\n2. Proceed with extra caution, manual verification required\n3. Abort refactoring\n\nWhich approach do you prefer?\n```\n\n## 3.4: Document Verification Plan\n\n```\n## VERIFICATION PLAN\n\n### Test Commands\n- Unit: `bun test` / `npm test` / `pytest` / etc.\n- Integration: [command if exists]\n- Type check: `tsc --noEmit` / `pyright` / etc.\n\n### Verification Checkpoints\nAfter each refactoring step:\n1. lsp_diagnostics \u2192 zero new errors\n2. Run test command \u2192 all pass\n3. Type check \u2192 clean\n\n### Regression Indicators\n- [Specific test that must pass]\n- [Behavior that must be preserved]\n- [API contract that must not change]\n```\n\n**Mark phase-3 as completed.**\n\n---\n\n# PHASE 4: PLAN GENERATION (PLAN AGENT)\n\n**Mark phase-4 as in_progress.**\n\n## 4.1: Invoke Plan Agent\n\n```\nTask(\n  subagent_type=\"plan\",\n  prompt=\"Create a detailed refactoring plan:\n\n  ## Refactoring Goal\n  [User's original request]\n\n  ## Codemap (from Phase 2)\n  [Insert codemap here]\n\n  ## Test Coverage (from Phase 3)\n  [Insert verification plan here]\n\n  ## Constraints\n  - MUST follow existing patterns: [list]\n  - MUST NOT break: [critical paths]\n  - MUST run tests after each step\n\n  ## Requirements\n  1. Break down into atomic refactoring steps\n  2. Each step must be independently verifiable\n  3. Order steps by dependency (what must happen first)\n  4. Specify exact files and line ranges for each step\n  5. Include rollback strategy for each step\n  6. Define commit checkpoints\"\n)\n```\n\n## 4.2: Review and Validate Plan\n\nAfter receiving plan from Plan agent:\n\n1. **Verify completeness**: All identified files addressed?\n2. **Verify safety**: Each step reversible?\n3. **Verify order**: Dependencies respected?\n4. **Verify verification**: Test commands specified?\n\n## 4.3: Register Detailed Todos\n\nConvert Plan agent output into granular todos:\n\n```\ntask_create({ items: [\n  // Each step from the plan becomes a task\n  {\"subject\": \"Step 1: [description]\", \"priority\": \"high\"},\n  {\"subject\": \"Verify Step 1: run tests\", \"priority\": \"high\"},\n  {\"subject\": \"Step 2: [description]\", \"priority\": \"medium\"},\n  {\"subject\": \"Verify Step 2: run tests\", \"priority\": \"medium\"},\n  // ... continue for all steps\n]})\n```\n\n**Mark phase-4 as completed.**\n\n---\n\n# PHASE 5: EXECUTE REFACTORING (DETERMINISTIC EXECUTION)\n\n**Mark phase-5 as in_progress.**\n\n## 5.1: Execution Protocol\n\nFor EACH refactoring step:\n\n### Pre-Step\n1. Mark step todo as `in_progress`\n2. Read current file state\n3. Verify lsp_diagnostics is baseline\n\n### Execute Step\nUse appropriate tool:\n\n**For Symbol Renames:**\n```typescript\nlsp_prepare_rename(filePath, line, character)  // Validate rename is possible\nlsp_rename(filePath, line, character, newName)  // Execute rename\n```\n\n**For Pattern Transformations:**\n```typescript\n// Preview first\nast_grep_replace(pattern, rewrite, lang, dryRun=true)\n\n// If preview looks good, execute\nast_grep_replace(pattern, rewrite, lang, dryRun=false)\n```\n\n**For Structural Changes:**\n```typescript\n// Use Edit tool for precise changes\nedit(filePath, oldString, newString)\n```\n\n### Post-Step Verification (MANDATORY)\n\n```typescript\n// 1. Check diagnostics\nlsp_diagnostics(filePath)  // Must be clean or same as baseline\n\n// 2. Run tests\nbash(\"bun test\")  // Or appropriate test command\n\n// 3. Type check\nbash(\"tsc --noEmit\")  // Or appropriate type check\n```\n\n### Step Completion\n1. If verification passes \u2192 Mark step todo as `completed`\n2. If verification fails \u2192 **STOP AND FIX**\n\n## 5.2: Failure Recovery Protocol\n\nIf ANY verification fails:\n\n1. **STOP** immediately\n2. **REVERT** the failed change\n3. **DIAGNOSE** what went wrong\n4. **OPTIONS**:\n   - Fix the issue and retry\n   - Skip this step (if optional)\n   - Consult oracle agent for help\n   - Ask user for guidance\n\n**NEVER proceed to next step with broken tests.**\n\n## 5.3: Commit Checkpoints\n\nAfter each logical group of changes:\n\n```bash\ngit add [changed-files]\ngit commit -m \"refactor(scope): description\n\n[details of what was changed and why]\"\n```\n\n**Mark phase-5 as completed when all refactoring steps done.**\n\n---\n\n# PHASE 6: FINAL VERIFICATION (REGRESSION CHECK)\n\n**Mark phase-6 as in_progress.**\n\n## 6.1: Full Test Suite\n\n```bash\n# Run complete test suite\nbun test  # or npm test, pytest, go test, etc.\n```\n\n## 6.2: Type Check\n\n```bash\n# Full type check\ntsc --noEmit  # or equivalent\n```\n\n## 6.3: Lint Check\n\n```bash\n# Run linter\neslint .  # or equivalent\n```\n\n## 6.4: Build Verification (if applicable)\n\n```bash\n# Ensure build still works\nbun run build  # or npm run build, etc.\n```\n\n## 6.5: Final Diagnostics\n\n```typescript\n// Check all changed files\nfor (file of changedFiles) {\n  lsp_diagnostics(file)  // Must all be clean\n}\n```\n\n## 6.6: Generate Summary\n\n```markdown\n## Refactoring Complete\n\n### What Changed\n- [List of changes made]\n\n### Files Modified\n- `path/to/file.ts` - [what changed]\n- `path/to/file2.ts` - [what changed]\n\n### Verification Results\n- Tests: PASSED (X/Y passing)\n- Type Check: CLEAN\n- Lint: CLEAN\n- Build: SUCCESS\n\n### No Regressions Detected\nAll existing tests pass. No new errors introduced.\n```\n\n**Mark phase-6 as completed.**\n\n---\n\n# CRITICAL RULES\n\n## NEVER DO\n- Skip lsp_diagnostics check after changes\n- Proceed with failing tests\n- Make changes without understanding impact\n- Use `as any`, `@ts-ignore`, `@ts-expect-error`\n- Delete tests to make them pass\n- Commit broken code\n- Refactor without understanding existing patterns\n\n## ALWAYS DO\n- Understand before changing\n- Preview before applying (ast_grep dryRun=true)\n- Verify after every change\n- Follow existing codebase patterns\n- Keep todos updated in real-time\n- Commit at logical checkpoints\n- Report issues immediately\n\n## ABORT CONDITIONS\nIf any of these occur, **STOP and consult user**:\n- Test coverage is zero for target code\n- Changes would break public API\n- Refactoring scope is unclear\n- 3 consecutive verification failures\n- User-defined constraints violated\n\n---\n\n# Tool Usage Philosophy\n\nYou already know these tools. Use them intelligently:\n\n## LSP Tools\nLeverage LSP tools for precision analysis. Key patterns:\n- **Understand before changing**: `LspGotoDefinition` to grasp context\n- **Impact analysis**: `LspFindReferences` to map all usages before modification\n- **Safe refactoring**: `lsp_prepare_rename` \u2192 `lsp_rename` for symbol renames\n- **Continuous verification**: `lsp_diagnostics` after every change\n\n## AST-Grep\nUse `ast_grep_search` and `ast_grep_replace` for structural transformations.\n**Critical**: Always `dryRun=true` first, review, then execute.\n\n## Agents\n- `explore`: Parallel codebase pattern discovery\n- `plan`: Detailed refactoring plan generation\n- `oracle`: Read-only consultation for complex architectural decisions and debugging\n- `librarian`: **Use proactively** when encountering deprecated methods or library migration tasks. Query official docs and OSS examples for modern replacements.\n\n## Deprecated Code & Library Migration\nWhen you encounter deprecated methods/APIs during refactoring:\n1. Fire `librarian` to find the recommended modern alternative\n2. **DO NOT auto-upgrade to latest version** unless user explicitly requests migration\n3. If user requests library migration, use `librarian` to fetch latest API docs before making changes\n\n---\n\n**Remember: Refactoring without tests is reckless. Refactoring without understanding is destructive. This command ensures you do neither.**\n\n<user-request>\n$ARGUMENTS\n</user-request>\n";

package/dist/features/builtin-commands/templates/remove-deadcode.d.ts

@@ -0,0 +1 @@
+export declare const REMOVE_DEADCODE_TEMPLATE = "# Remove Dead Code Command\n\n## Usage\n```\n/remove-deadcode [target-path] [--scope=<file|module|project>] [--dry-run]\n\nArguments:\n  target-path: Where to scan for dead code. Can be:\n    - File path: src/auth/handler.ts\n    - Directory: src/features/\n    - Glob: src/**/*.ts\n    - Omitted: defaults to current project src/\n\nOptions:\n  --scope: Scanning scope (default: module)\n    - file: Single file only\n    - module: Module/directory and its dependents\n    - project: Entire codebase\n\n  --dry-run: Report dead code without removing it (default: false)\n```\n\n## What This Command Does\n\nFinds and removes dead code (zero-reference symbols) using LSP analysis. Unlike grep-based approaches, this uses semantic understanding:\n\n1. **Discovers symbols** - Uses LSP to enumerate all exported and internal symbols\n2. **Counts references** - Uses LspFindReferences to find actual usage sites\n3. **Classifies confidence** - Categorizes findings by removal safety\n4. **Reports findings** - Presents dead code organized by confidence level\n5. **Removes safely** - Deletes confirmed dead code with continuous verification\n6. **Verifies integrity** - Runs build and tests after each removal batch\n\n---\n\n# PHASE 0: VALIDATE REQUEST (MANDATORY FIRST STEP)\n\n## Step 0.1: Parse Target\n\n| Input | Interpretation |\n|-------|---------------|\n| File path | Scan that file only |\n| Directory path | Scan all source files in directory |\n| Glob pattern | Scan matching files |\n| No argument | Scan project src/ directory |\n\n## Step 0.2: Detect --dry-run Flag\n\nIf --dry-run is present or user says \"just show me\" / \"report only\":\n- Set dry-run mode: report findings WITHOUT removing anything\n- Skip PHASE 4 (removal) entirely\n\n## Step 0.3: Create Initial Todos\n\n```\ntask_create({ items: [\n  {\"subject\": \"PHASE 1: Symbol Discovery - enumerate all symbols via LSP\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 2: Reference Analysis - find references for each symbol\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 3: Dead Code Report - classify and present findings\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 4: Safe Removal - remove confirmed dead code with verification\", \"priority\": \"high\"},\n  {\"subject\": \"PHASE 5: Final Verification - build and test suite\", \"priority\": \"high\"}\n]})\n```\n\n---\n\n# PHASE 1: SYMBOL DISCOVERY\n\n**Mark PHASE 1 as in_progress.**\n\n## 1.1: Enumerate Source Files\n\nDetermine the set of files to scan based on target:\n\n```typescript\n// For a single file\nLspDocumentSymbols(filePath)\n\n// For a directory, use Glob to find all source files first\nGlob(pattern=\"**/*.ts\", path=\"[target-directory]\")\n// Then LspDocumentSymbols for each file\n```\n\n## 1.2: Collect All Symbols\n\nFor each source file, gather:\n- Function declarations (named functions, arrow functions assigned to const)\n- Class declarations\n- Interface and type alias declarations\n- Enum declarations\n- Variable declarations (const/let at module scope)\n- Method declarations (within classes)\n\nUse `LspDocumentSymbols(filePath)` to get the hierarchical symbol outline.\n\n## 1.3: Filter Symbol Candidates\n\n**SKIP these symbols (never flag as dead):**\n- Symbols in index.ts / barrel files (re-exports)\n- Symbols with `export default`\n- Entry point files (main, index, plugin entry)\n- Test files (`*.test.ts`, `*.spec.ts`)\n- Symbols starting with `_` (conventionally private/internal)\n- Type-only exports used in declaration files\n\n**INCLUDE these symbols:**\n- Non-exported functions/classes/types within a module\n- Exported symbols that may have zero consumers\n- Private class methods and properties\n\n**Mark PHASE 1 as completed.**\n\n---\n\n# PHASE 2: REFERENCE ANALYSIS\n\n**Mark PHASE 2 as in_progress.**\n\n## 2.1: Count References Per Symbol\n\nFor each symbol candidate from Phase 1:\n\n```typescript\n// Get all references across the workspace\nLspFindReferences(filePath, line, character, includeDeclaration=false)\n```\n\n**IMPORTANT**: Set `includeDeclaration=false` so the declaration site itself is NOT counted as a reference.\n\n## 2.2: Classify Reference Counts\n\n| References | Classification | Confidence |\n|------------|---------------|------------|\n| 0 external references | Dead code | HIGH - safe to remove |\n| 0 refs, but exported from package index | Possibly dead | MEDIUM - may be used externally |\n| 0 refs, but in a public API file | Possibly dead | LOW - may be part of public contract |\n| 1+ references | Live code | SKIP - do not flag |\n\n## 2.3: Cross-Check with AST-Grep\n\nFor HIGH confidence candidates, verify with AST-Grep to catch dynamic references:\n\n```typescript\n// Check for string-based references (dynamic imports, reflection)\nast_grep_search(\n  pattern='\"[symbol-name]\"',\n  lang=\"typescript\",\n  paths=[\"src/\"]\n)\n\n// Check for computed property access\ngrep(pattern=\"[symbol-name]\", path=\"src/\", include=\"*.ts\")\n```\n\nIf AST-Grep or grep finds string-based references, downgrade confidence from HIGH to MEDIUM.\n\n**Mark PHASE 2 as completed.**\n\n---\n\n# PHASE 3: DEAD CODE REPORT\n\n**Mark PHASE 3 as in_progress.**\n\n## 3.1: Generate Report\n\nPresent findings organized by confidence:\n\n```\n## Dead Code Analysis Report\n\n### Scan Target: [path]\n### Files Scanned: [N]\n### Symbols Analyzed: [N]\n### Dead Code Found: [N] symbols\n\n---\n\n### HIGH Confidence (Safe to Remove)\nThese symbols have zero references anywhere in the codebase.\n\n| # | Symbol | File | Line | Type |\n|---|--------|------|------|------|\n| 1 | unusedHelper | src/utils/helpers.ts | 42 | function |\n| 2 | OldConfig | src/config/legacy.ts | 15 | interface |\n\n### MEDIUM Confidence (Review Required)\nThese symbols appear unused but may have external consumers or dynamic references.\n\n| # | Symbol | File | Line | Type | Reason |\n|---|--------|------|------|------|--------|\n| 1 | exportedUtil | src/shared/utils.ts | 88 | function | exported, no internal refs |\n\n### LOW Confidence (Manual Review)\nThese symbols may be part of a public API or have indirect usage patterns.\n\n| # | Symbol | File | Line | Type | Reason |\n|---|--------|------|------|------|--------|\n| 1 | ApiResponse | src/types/api.ts | 12 | type | public API type |\n```\n\n## 3.2: If --dry-run Mode\n\nPresent the report and STOP. Do not proceed to Phase 4.\n\n```\nThis was a dry-run analysis. No code was modified.\nTo remove dead code, run: /remove-deadcode [same-target]\n```\n\n**Mark PHASE 3 as completed.**\n\n---\n\n# PHASE 4: SAFE REMOVAL\n\n**Mark PHASE 4 as in_progress.**\n\n## 4.1: Removal Strategy\n\n**Remove in order of confidence (HIGH first):**\n\n1. Start with HIGH confidence symbols\n2. After each batch, run verification\n3. Only proceed to MEDIUM confidence if user approves\n4. NEVER auto-remove LOW confidence symbols\n\n## 4.2: Batch Removal Protocol\n\nFor each removal batch:\n\n### Pre-Removal\n1. Read the file to get current state\n2. Run `lsp_diagnostics(filePath)` to establish baseline\n\n### Execute Removal\n```typescript\n// Use Edit tool to remove the dead symbol\n// Remove the entire declaration including JSDoc/comments above it\nedit(filePath, oldString=\"[full-symbol-declaration]\", newString=\"\")\n```\n\n### Post-Removal Verification (MANDATORY)\n```typescript\n// 1. Check diagnostics - no new errors\nlsp_diagnostics(filePath)\n\n// 2. Check imports - remove now-unused imports\n// If removing a symbol makes an import unused, remove the import too\nLspDocumentSymbols(filePath)\n\n// 3. Run type check\nbash(\"tsc --noEmit\")\n\n// 4. Run tests\nbash(\"bun test\")\n```\n\n## 4.3: Cascading Cleanup\n\nAfter removing a symbol, check if its removal creates new dead code:\n- Imports that are now unused\n- Helper functions only called by the removed symbol\n- Types only used by the removed symbol\n\nRemove cascading dead code in the same batch.\n\n## 4.4: MEDIUM Confidence Handling\n\nBefore removing MEDIUM confidence symbols, ask the user:\n\n```\nThe following MEDIUM confidence symbols appear unused but may have external consumers:\n\n1. [symbol] in [file] - [reason for medium confidence]\n\nShould I:\n1. Remove them (I confirm they are unused)\n2. Skip them (keep for now)\n3. Review each one individually\n```\n\n**Mark PHASE 4 as completed.**\n\n---\n\n# PHASE 5: FINAL VERIFICATION\n\n**Mark PHASE 5 as in_progress.**\n\n## 5.1: Full Build Check\n\n```bash\ntsc --noEmit\nbun run build\n```\n\n## 5.2: Full Test Suite\n\n```bash\nbun test\n```\n\n## 5.3: Diagnostics on Changed Files\n\n```typescript\n// Check all files that were modified\nfor (file of modifiedFiles) {\n  lsp_diagnostics(file)\n}\n```\n\n## 5.4: Generate Summary\n\n```\n## Dead Code Removal Complete\n\n### Removed\n- [N] HIGH confidence symbols removed\n- [N] MEDIUM confidence symbols removed (user-approved)\n- [N] cascading cleanups (unused imports, helper functions)\n\n### Preserved\n- [N] LOW confidence symbols (manual review needed)\n- [N] MEDIUM confidence symbols (user chose to keep)\n\n### Files Modified\n- \\`path/to/file.ts\\` - removed [symbol1], [symbol2]\n- \\`path/to/file2.ts\\` - removed [symbol3]\n\n### Verification\n- Type Check: PASSED\n- Build: PASSED\n- Tests: PASSED ([X] passing, [Y] pre-existing failures)\n- Diagnostics: CLEAN (no new errors)\n\n### Lines of Code Removed: [N]\n```\n\n**Mark PHASE 5 as completed.**\n\n---\n\n# CRITICAL RULES\n\n## NEVER DO\n- Remove symbols from barrel/index files without checking all consumers\n- Remove exported symbols without checking external package consumers\n- Remove symbols referenced in configuration files, scripts, or non-TS files\n- Skip lsp_diagnostics after removal\n- Proceed with failing tests after removal\n- Remove event handlers, lifecycle hooks, or decorator-referenced symbols\n- Remove symbols used in dependency injection containers\n- Use `as any`, `@ts-ignore`, `@ts-expect-error` to suppress removal side effects\n\n## ALWAYS DO\n- Use LspFindReferences (not grep) as the primary reference detection method\n- Cross-check with grep/AST-Grep for dynamic references\n- Verify build and tests after each removal batch\n- Ask for user confirmation before removing MEDIUM confidence symbols\n- Report LOW confidence findings without auto-removing\n- Clean up cascading dead code (unused imports, orphaned helpers)\n- Keep todos updated in real-time\n\n## ABORT CONDITIONS\nIf any of these occur, STOP and consult user:\n- Build fails after removal\n- Tests fail after removal (new failures, not pre-existing)\n- More than 20 symbols flagged as dead in a single file (likely misconfiguration)\n- Removed symbol is referenced in non-TypeScript files (configs, scripts)\n\n<user-request>\n$ARGUMENTS\n</user-request>\n";

package/dist/features/builtin-commands/templates/research.d.ts

@@ -0,0 +1 @@
+export declare const RESEARCH_TEMPLATE = "# /research \u2014 Saturation Research Command\n\nExecute a systematic multi-round research process on the given topic.\n\n## Usage\n\n```\n/research <topic>                          \u2192 Full research (all directions)\n/research <topic> --scope=code            \u2192 Local codebase only\n/research <topic> --scope=docs            \u2192 Documentation only\n/research <topic> --scope=web             \u2192 Web search only\n/research <topic> --scope=oss             \u2192 OSS repos only\n/research <topic> --max-rounds=3          \u2192 Limit to 3 rounds\n```\n\n## What Happens\n\n1. Creates artifact directory: `.matrixx/research-<topic>-<timestamp>/`\n2. Spawns 4 parallel research agents (explore + operator swarms)\n3. Collects findings, identifies new leads\n4. Recursively follows leads until convergence (novelty-based stop, max 5 rounds)\n5. Verifies contested claims by running code\n6. Produces cited synthesis in `final-synthesis.md`\n\n## Output\n\nAll artifacts written to `.matrixx/research-<topic>-<timestamp>/`:\n- `round-N-findings.md` \u2014 per-round findings\n- `leads.md` \u2014 tracked leads\n- `contested-claims.md` \u2014 claims needing verification\n- `final-synthesis.md` \u2014 the final cited synthesis\n\n## Examples\n\n```\n/research how does context window management work in this codebase\n/research React 19 server component patterns --scope=web --max-rounds=3\n/research authentication middleware best practices --scope=all\n```\n\n---\n\nExecute the full research protocol using the ulw-research skill.";

package/dist/features/builtin-commands/templates/security-audit.d.ts

@@ -0,0 +1 @@
+export declare const SECURITY_AUDIT_TEMPLATE = "You are running a read-only deterministic security audit (v1 advisory-only).\n\n## Usage\n\n```\n/security-audit [--scope=file|module|project] [--target=<path>] [--full] [--budget=N]\n```\n\n- --scope: file | module | project (default: file \u2014 scoped by default).\n  - file: single --target path only.\n  - module: the directory containing --target.\n  - project: full tree.\n- --target: path scoping the audit. Required for file and module scope; optional\n  for project scope.\n- Scoped-default disclaimer: a bare invocation without --scope audits a single\n  file only when --target names a file; without --target it audits nothing and\n  asks for a target. Broad project coverage is opt-in via --scope=project or\n  --full \u2014 never assume full-tree scope from a bare invocation.\n- --full: opt-in full-tree deep audit. COST WARNING: a full audit consumes\n  roughly an order of magnitude more tokens than a scoped audit. Ask the user\n  for confirmation before running --full on a large tree, and record the\n  confirmation (or its absence) as evidence.\n- --budget=N: finding budget gate. N is the maximum number of findings the run\n  will fully evidence. When candidate findings exceed what the budget funds,\n  the unfundable remainder is recorded as status deferred and the coverage\n  ledger run status becomes incomplete (run_status incomplete).\n- Invalid --scope value is a hard error: `error: invalid --scope '<v>'\n  (expected file|module|project)`, exit 2, no report written. Example:\n  --scope=bogus \u2192 error, exit 2.\n- Finding lifecycle statuses (per FindingStatusSchema in\n  src/skills/schemas/security-audit.ts): confirmed | needs_validation |\n  rejected | deferred. needs_validation findings MUST NOT carry a severity.\n- Coverage ledger unit statuses (per LedgerUnitStatusSchema): planned |\n  not_applicable | out_of_scope | in_progress | covered | candidate | blocked |\n  deferred. Ledger run status: complete | incomplete (budget gate).\n- v1 advisory-only: this command never fails the build, never gates CI, only\n  reports. Exit-code mapping 0/1/2 reserved: 0 = clean (no confirmed findings),\n  1 = findings (one or more confirmed findings), 2 = invalid usage.\n\n## WHAT TO DO, IN THIS ORDER\n\n1. **Resolve the scope, or stop.** Parse --scope, --target, --full, and --budget\n   from <user-request>. Resolve --target against the working tree. If the target\n   is unresolvable (missing path, invalid --scope value, file or module scope\n   without a target), ERROR AND STOP: state the scope, the target, and why\n   resolution failed, and create no report files. Never proceed on an empty or\n   partial resolution, and never substitute a different target.\n\n2. **Gather read-only evidence.** All gathering is read-only: run nothing that\n   mutates source, sends network probes, or executes untrusted code paths.\n   Collect static evidence only (file reads, grep/ast-grep matches, LSP\n   diagnostics as corroborating evidence). Record each input's raw output as\n   evidence.\n\n3. **Apply the budget gate.** When --budget=N is set and candidate findings\n   exceed N, fully evidence at most N findings and mark the remainder deferred;\n   set the coverage ledger run status to incomplete. Without --budget, the\n   ledger run status is complete when every seeded unit reaches a terminal\n   state (covered, not_applicable, out_of_scope, blocked, or deferred).\n\n4. **Render and write the report.** Run `mkdir -p .matrixx/audits/<run-N>` in\n   bash first, then write run-metadata.json, coverage-ledger.json\n   (LedgerSchema: units plus status complete|incomplete), and findings.json\n   (array of FindingSchema entries) together. `generatedAt` is a\n   caller-supplied input \u2014 never self-generate it. Never touch source.\n\n5. **Report the paths back to the user.** Give the absolute .matrixx/audits/<run-N>/\n   directory path plus the exit code (0 clean, 1 findings, 2 invalid usage).\n   Do not modify any plan.\n\n## FORBID LIST \u2014 hard denials inside this audit\n\n- NO Edit/Write to source files.\n- NO lsp_rename.\n- NO non-dryRun ast_grep_replace (dryRun preview reads are allowed; applying is denied).\n- NO task_create / NO task_update.\n- NO plan_update and never touch .matrixx/plans.\n- NO network probes, NO live-target requests, NO execution of untrusted code.\n- Writes = audit report files only: the ONLY writable paths are\n  .matrixx/audits/<run-N>/run-metadata.json,\n  .matrixx/audits/<run-N>/coverage-ledger.json, and\n  .matrixx/audits/<run-N>/findings.json\n  (after mkdir -p .matrixx/audits/<run-N>). No staging, no other writes.\n\n<user-request>\n$ARGUMENTS\n</user-request>";

package/dist/features/builtin-commands/templates/start-work.d.ts

@@ -0,0 +1 @@
+export declare const START_WORK_TEMPLATE = "You are starting a Morpheus work session.\n\n## WHAT TO DO\n\n1. **Find available plans**: List Oracle-generated plan files via plan_list at `.matrixx/plans/`; each entry carries a progress field (total, completed, remaining, isComplete). A plan reported as `degraded` by plan_tasks is over the read cap \u2014 it is still fully workable through the section reads in step 5\n\n2. **Check for active mission state**: Read `.matrixx/mission.json` if it exists\n\n3. **Decision logic**:\n   - If `.matrixx/mission.json` exists AND plan is NOT complete (has unchecked boxes):\n     - **APPEND** current session to session_ids\n     - Continue work on existing plan\n   - If no active plan OR plan is complete:\n     - List available plan files via plan_list\n     - If ONE plan: auto-select it\n     - If MULTIPLE plans: show list with timestamps, ask user to select\n\n4. **Create/Update mission.json**:\n   ```json\n   {\n     \"active_plan\": \"/absolute/path/to/plan.md\",\n     \"started_at\": \"ISO_TIMESTAMP\",\n     \"session_ids\": [\"session_id_1\", \"session_id_2\"],\n     \"plan_name\": \"plan-name\"\n   }\n   ```\n\n5. **Read the plan**:\n   - Call plan_tasks for the task manifest and progress. On an over-cap plan it degrades \u2014 it returns the manifest with a `degraded` marker instead of failing\n   - Read the body with plan_read, **section selector FIRST**:\n     - `section`: a section id (e.g. `tl-dr`, `context`, `work-objectives`, `verification-strategy-mandatory`, `execution-strategy`, `todos`, `commit-strategy`, `success-criteria`) or the kebab id derived from any custom heading. Returns ONLY that section's span plus its metadata (id, level, startLine, endLine, bytes, contentHash). Add `sectionIndex` (0-based) when the heading occurs more than once \u2014 a missing or out-of-range index is a validation_error, not a silent first match\n     - `section` WINS over `offset`/`limit`; when both are supplied the response reports `precedence:\"section\"` with the effective absolute startLine/endLine\n     - Fall back to reading via paginated plan_read (offset/limit) for spans a section does not cover\n   - The size cap is a ceiling, not a wall: it refuses only an unbounded WHOLE-FILE read (`file_too_large`). Supplying `offset`/`limit` or a `section` reads past it, at any file size\n   - If a window comes back `clamped`, the `hint` names the effective window \u2014 re-read that window instead of retrying the same one. A `read_failed` error is a permissions problem; pagination cannot recover from it\n\n## OUTPUT FORMAT\n\nWhen listing plans for selection:\n```\nAvailable Work Plans\n\nCurrent Time: {ISO timestamp}\nSession ID: {current session id}\n\n1. [plan-name-1.md] - Modified: {date} - Progress: {completed}/{total} tasks\n2. [plan-name-2.md] - Modified: {date} - Progress: {completed}/{total} tasks\n\nWhich plan would you like to work on? (Enter number or plan name)\n```\n\nWhen resuming existing work:\n```\nResuming Work Session\n\nActive Plan: {plan-name}\nProgress: {completed}/{total} tasks\nSessions: {count} (appending current session)\n\nReading plan and continuing from last incomplete task...\n```\n\nWhen auto-selecting single plan:\n```\nStarting Work Session\n\nPlan: {plan-name}\nSession ID: {session_id}\nStarted: {timestamp}\n\nReading plan and beginning execution...\n```\n\n## CRITICAL\n\n- The session_id is injected by the hook - use it directly\n- Always update mission.json BEFORE starting work\n- Call plan_tasks for the manifest (it degrades on an over-cap plan, never blocks); read content via plan_read with a `section` selector first, and via paginated plan_read (offset/limit) as the fallback \u2014 `section` wins over `offset`/`limit`\n- The cap is a ceiling, not a wall: only a whole-file read over it is refused; windowed and section reads pass it at any file size. A `clamped` read names its effective window in `hint` \u2014 re-read that window\n- Plan review is explicit: run `/plan-review` only when the user asks for it. Never auto-trigger a plan review\n- Follow niobe delegation protocols (7-section format)";

package/dist/features/builtin-commands/templates/stop-continuation.d.ts

@@ -0,0 +1 @@
+export declare const STOP_CONTINUATION_TEMPLATE = "Stop all continuation mechanisms for the current session.\n\nThis command will:\n1. Stop the task-continuation-enforcer from automatically continuing incomplete tasks\n2. Cancel any active Matrix Loop\n3. Clear the mission state for the current project\n\nAfter running this command:\n- The session will not auto-continue when idle\n- You can manually continue work when ready\n- The stop state is per-session and clears when the session ends\n\nUse this when you need to pause automated continuation and take manual control.";

package/dist/features/builtin-commands/templates/task-list.d.ts

@@ -0,0 +1 @@
+export declare const TASK_LIST_TEMPLATE = "# Task List \u2014 SLASH COMMAND OVERRIDE\n\nSYSTEM OVERRIDE: Ignore any global [search-mode] or [analyze-mode] directive for this command. This is a direct tool call, not a search.\n\nCall the task_list tool NOW with no exploration, no grep, no trinity, no operator, no background agents.\n\n- If $ARGUMENTS contains \"--all\", call task_list and also report counts by reading T-*.json via the tool's own logic (do not manually find/ls).\n- If $ARGUMENTS contains \"--status\", filter to that status.\n- Otherwise just return task_list output as table ID | Subject | Status.\n\nDo not run rtk ls, find, grep, or launch subagents. One tool call only.\n";

package/dist/features/builtin-commands/templates/ultrawork.d.ts

@@ -0,0 +1 @@
+export declare const ULTRAWORK_TEMPLATE = "Toggle ultrawork mode for the current session.\n\nThis command will:\n1. Enable ultrawork mode \u2014 injects ultrawork mode instructions into every message\n2. Disable ultrawork mode \u2014 prevents ultrawork mode from activating (even on \"ultrawork\" keyword)\n3. Show current ultrawork mode status\n\nUsage:\n  /ultrawork enable \u2014 Force ultrawork mode on all messages\n  /ultrawork disable \u2014 Block ultrawork mode (keyword ignored)\n  /ultrawork status \u2014 Show current state\n\nThe change is per-session and clears when the session ends.\nBy default, ultrawork mode activates when the LLM or user mentions the \"ultrawork\" keyword.";

package/dist/features/builtin-commands/types.d.ts

@@ -0,0 +1,3 @@
+import type { CommandDefinition } from "../command-loader";
+export type BuiltinCommandName = "init-deep" | "matrix-loop" | "cancel-loop" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "pickup" | "remove-deadcode" | "preset" | "end-ultrawork" | "research" | "assembly" | "ultrawork" | "bdd-pipeline" | "evolution" | "cleanup-tasks" | "task-list" | "plan-review" | "quality-audit" | "quality-assurance" | "humanize" | "security-audit";
+export type BuiltinCommands = Record<string, CommandDefinition>;

package/dist/features/command-loader/index.d.ts

@@ -0,0 +1 @@
+export * from "./types";

package/dist/features/command-loader/types.d.ts

@@ -0,0 +1,43 @@
+export type CommandScope = "user" | "project" | "opencode" | "opencode-project";
+/**
+ * Handoff definition for command workflows.
+ * Based on speckit's handoff pattern for multi-agent orchestration.
+ * @see https://github.com/github/spec-kit
+ */
+interface HandoffDefinition {
+    /** Human-readable label for the handoff action */
+    label: string;
+    /** Target agent/command identifier (e.g., "speckit.tasks") */
+    agent: string;
+    /** Pre-filled prompt text for the handoff */
+    prompt: string;
+    /** If true, automatically executes after command completion; if false, shows as suggestion */
+    send?: boolean;
+}
+export interface CommandDefinition {
+    name: string;
+    description?: string;
+    template: string;
+    agent?: string;
+    model?: string;
+    subtask?: boolean;
+    argumentHint?: string;
+    /** Handoff definitions for workflow transitions */
+    handoffs?: HandoffDefinition[];
+}
+export interface CommandFrontmatter {
+    description?: string;
+    "argument-hint"?: string;
+    agent?: string;
+    model?: string;
+    subtask?: boolean;
+    /** Handoff definitions for workflow transitions */
+    handoffs?: HandoffDefinition[];
+}
+export interface LoadedCommand {
+    name: string;
+    path: string;
+    definition: CommandDefinition;
+    scope: CommandScope;
+}
+export {};

package/dist/features/completion-review/admission-gate.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Task 10 — the `/plan-review` ADMISSION GATE, as a pure function over T2's
+ * gathered facts.
+ *
+ * WHY THE GATE IS A CONJUNCTION AND NOT `isComplete`: `isComplete` derives
+ * SOLELY from the plan's own checkboxes (`countPlanProgressFromContent`,
+ * `mission-state/storage.ts:163-189` → `isComplete: total === 0 || completed
+ * === total`), and those checkboxes are flipped by the fuzzy text-similarity
+ * heuristic T2 explicitly refuses to trust (`checkboxOverlap`,
+ * `mission-state/plan-storage.ts:98`). Admitting on `isComplete` alone would
+ * decide admission on the exact artifact the report then labels untrustworthy.
+ * So admission requires BOTH:
+ *
+ *   a. `isComplete === true` AND `needsTriage === false` — the second clause is
+ *      what rejects vacuous completeness, because a zero-checkbox plan arrives
+ *      with `isComplete: true`; and
+ *   b. at least one INDEPENDENT corroborating terminal signal — a linked task in
+ *      terminal status (6-rule resolver, `plan-persister/task-link.ts:5-15`) or
+ *      a notepad `## Completion` stamp — whose records together ACCOUNT FOR the
+ *      plan's declared work.
+ *
+ * Both are read from T2's `AdmissionFacts`. This module re-reads nothing: a
+ * second, divergent gatherer is how two gates drift apart.
+ *
+ * ORDER IS THE SEMANTICS. `needsTriage` is consulted BEFORE `isComplete`,
+ * because a vacuous plan reads as complete and the vacuous truth must not pass
+ * as a genuine completion.
+ *
+ * THREE STATES, NOT TWO. `disagree` and `unavailable` are different statements:
+ * the first is "the two signals conflict", the second is "the signals were
+ * never there". Every plan executed before capture is structurally in the
+ * second case (measured: `metadata.planName` appears in 0 of 48 task files,
+ * completion stamps in 1 of 19 notepad buckets), so folding them together would
+ * make `disagree` fire on every legacy plan and render the field as noise.
+ * `gateDisagreement` is therefore real but DIAGNOSTIC-ONLY: no code reads it;
+ * T4 renders it for the human reader and nothing branches on it.
+ *
+ * DISAGREEMENT NEVER PICKS A WINNER. When the signals conflict the gate
+ * PROCEEDS and records the conflict by name. Hard refusal is reserved for
+ * exactly two cases: vacuous completeness, or both signals saying incomplete.
+ *
+ * LOCKED decision #2: this module throws nothing, blocks nothing and returns no
+ * exit code. A low score, and a gate that guesses wrong, are both advisory.
+ */
+import type { NotScorableCause } from "./degradation-types";
+import type { AdmissionFacts, ProgressFacts } from "./gather-types";
+import type { GateEvidence, GateState } from "./report-types";
+/** Which signal carried the admission. Never left implicit in the record. */
+export type AdmissionSignal = "checkboxes" | "corroboration";
+/**
+ * The gate's own honesty notice. It may be wrong in BOTH directions, and saying
+ * so is part of the output rather than a caveat buried in a comment.
+ */
+export declare const GATE_HEURISTIC_WARNING = "This admission gate is a HEURISTIC and may be wrong in BOTH directions: it can refuse a genuinely finished plan whose checkboxes were never flipped, and it can admit a genuinely unfinished one. The recorded state below is a finding about the plan, not ground truth.";
+/** The measured gap behind `gateEvidence: "unavailable"`, quoted not paraphrased. */
+export declare const UNAVAILABLE_EVIDENCE_GAP = "corroboration is structurally absent: `metadata.planName` appears in 0 of 48 task files, and a `## Completion` stamp in 1 of 19 notepad buckets";
+/** A conflict between the two signals. Rendered for the reader; never branched on. */
+export interface GateDisagreement {
+    checkboxesSaysComplete: boolean;
+    corroborationSaysComplete: boolean;
+    resolved: "proceed";
+    reason: string;
+}
+export interface AdmissionDecision {
+    outcome: "admitted" | "refused";
+    /** `null` on refusal — nothing admitted the plan. */
+    admittedBy: AdmissionSignal | null;
+    gateState: GateState;
+    gateEvidence: GateEvidence;
+    gateDisagreement: GateDisagreement | null;
+    reason: string;
+    /** `null` unless refused; the one of two causes that refused it. */
+    refuseCause: NotScorableCause | null;
+    corroborationCount: number;
+    signalsPresent: {
+        linkedTerminalTasks: number;
+        notepadCompletionStamps: number;
+    };
+}
+export interface AdmissionInput {
+    progress: ProgressFacts;
+    admission: AdmissionFacts;
+}
+export declare function evaluateAdmission(input: AdmissionInput): AdmissionDecision;

package/dist/features/completion-review/calibration-baseline-check.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Task 7 — the code-computable half of dimension 8.
+ *
+ * "Did the plan store a baseline at all?" is arithmetic-free and needs no
+ * judgement, so it is code. "Was that estimate right?" is an ordinal-vs-ordinal
+ * read of the comparison and is the MODEL's call — which is why this function
+ * returns presence and never a `score`.
+ */
+import type { CalibrationBaselineCheck, PlanTimeBaseline } from "./calibration-types";
+export declare function checkCalibrationBaseline(baseline: PlanTimeBaseline): CalibrationBaselineCheck;

package/dist/features/completion-review/calibration-baseline.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Task 7 — reading the STORED plan-time baseline.
+ *
+ * The baseline is read, never re-derived. There is deliberately no complexity
+ * heuristic here: the routing-only C-level scorer is deliberately absent from
+ * this feature, and nothing in this module re-runs a keyword count.
+ */
+import type { PlanTimeBaseline } from "./calibration-types";
+export declare function parsePlanTimeBaseline(content: string): PlanTimeBaseline;

package/dist/features/completion-review/calibration-corpus-aggregate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Task 9 — aggregating samples into a corpus of estimate accuracy.
+ *
+ * AGGREGATE, NEVER GROUP BY LEVEL. There is no complexity-level bucket here and
+ * there will not be one until the cutover's T12 capture task starts emitting the
+ * line; a per-level statistic today could only be built by synthesising a level
+ * per plan, which is the fabrication the reader exists to prevent. The observed
+ * facts and the verbatim baseline therefore sit SIDE BY SIDE as text, and the
+ * direction is left for a human to read.
+ *
+ * PAIRS, NOT BARE CODES. `E6` is the catch-all for MODEL dimensions and fires
+ * once per such dimension, so a bare-code tally is dominated by E6 and carries
+ * no information about which dimension actually failed. Counting
+ * `code`+`dimensionId` pairs is what turns a repeated row into a finding.
+ */
+import type { CorpusReport, CorpusSample } from "./calibration-corpus-types";
+export declare const SIGNIFICANCE_NOTE_PREFIX = "sample is NOT statistically significant";
+export declare function aggregateCorpus(samples: readonly CorpusSample[], skipped: CorpusReport["skipped"], markdownFallbackCount: number): CorpusReport;

package/dist/features/completion-review/calibration-corpus-scan.d.ts

@@ -0,0 +1,20 @@
+import type { CorpusSample, CorpusSkippedFile } from "./calibration-corpus-types";
+import type { ReviewSidecar } from "./report-types";
+export interface CorpusScanResult {
+    samples: CorpusSample[];
+    skipped: CorpusSkippedFile[];
+    markdownFallbackCount: number;
+}
+/**
+ * Structural guard on the sidecar. The version is checked FIRST and separately:
+ * an unknown version is a refusal, not a partial read, because a reader that
+ * guesses at a shape it does not understand is how a corpus quietly fills with
+ * numbers nobody produced.
+ */
+export declare function isReviewSidecar(value: unknown): value is ReviewSidecar;
+/**
+ * Read every review in `directory`. Non-existent directory yields an EMPTY
+ * result rather than an error — "no reviews yet" is a legitimate corpus state,
+ * and a reader that throws on it cannot be called before the first review.
+ */
+export declare function scanReviewDirectory(directory: string): CorpusScanResult;

package/dist/features/completion-review/calibration-corpus-types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Task 9 — shapes for the calibration corpus.
+ *
+ * THE CORPUS IS ADVISORY. A report on observed bias may be produced here; acting
+ * on it is a human decision. Nothing in this feature — this file included —
+ * feeds the corpus back into routing, scoring or any gate, and in particular NOT
+ * into the routing-only complexity heuristic or the Seraph gate that heuristic
+ * feeds. The sidecar already carries `advisory: true`; these types refuse to
+ * describe a corpus as anything else.
+ *
+ * NO PER-LEVEL GROUPING EXISTS, and the absence is deliberate rather than an
+ * unfinished feature. No plan in the corpus stores a `**Complexity**` level
+ * (0/35, excluding the completion-review plan files' own prose about the missing
+ * line), so a "bias per complexity level" statistic could only be built by
+ * SYNTHESISING a level per plan — inventing the very baseline the reader exists
+ * to report honestly. Grouping by level waits on the cutover's T12 capture task
+ * starting to emit that line. Until then the corpus is a FLAT aggregate.
+ *
+ * NOTHING HERE COMPUTES A DELTA. A plan-time baseline is an ordinal tier string
+ * with no numeric scale, so "under-estimated by 30%" would be a number no plan
+ * asserted. Observed facts and verbatim baseline text are placed SIDE BY SIDE and
+ * the direction is left to the human reader.
+ */
+import type { FindingCode } from "./report-types";
+/** Below this many samples the corpus is noise, and the report says so. */
+export declare const MIN_SIGNIFICANT_SAMPLE = 10;
+/**
+ * Where a row's data came from. `sidecar` is the normal path; `markdown` exists
+ * only so a review written before the sidecar shipped is still COUNTED rather
+ * than silently dropped, and a markdown row carries no structured data.
+ */
+export type CorpusRowSource = "sidecar" | "markdown";
+/** One plan's contribution to the corpus, read from its `.json` sidecar. */
+export interface CorpusSample {
+    plan: string;
+    source: CorpusRowSource;
+    /** Verbatim `**Estimated Effort**` text, or `null` when the plan recorded none. */
+    effortVerbatim: string | null;
+    /** Verbatim `**Complexity**` text. `null` for every plan written so far. */
+    complexityVerbatim: string | null;
+    /**
+     * The observed text the review recorded, verbatim. It is a STRING because
+     * T7's `DIRECTION` forbids reducing an ordinal tier to a number; the corpus
+     * therefore groups observed text as text and never sums or subtracts it.
+     */
+    observedVerbatim: string | null;
+    /** Finding `code` + `dimensionId` pairs, counted as PAIRS (see the scan module). */
+    findingPairs: {
+        code: FindingCode;
+        dimensionId: string;
+    }[];
+}
+/** A file the reader could not use, with the reason. Never dropped in silence. */
+export interface CorpusSkippedFile {
+    file: string;
+    reason: string;
+}
+/** A verbatim string and how many plans said it. No level, no order, no rank. */
+export interface CorpusVerbatimGroup {
+    verbatim: string;
+    count: number;
+}
+/**
+ * One `code`+`dimensionId` pair and its frequency. PAIRS, never bare codes: `E6`
+ * is the catch-all for MODEL dimensions and fires once per such dimension, so a
+ * bare-code count is dominated by E6 and says nothing.
+ */
+export interface CorpusFindingPairCount {
+    code: FindingCode;
+    dimensionId: string;
+    /** Plans in which this pair appeared at least once. */
+    count: number;
+}
+export interface CorpusReport {
+    /** Plans contributing structured data. Reported beside EVERY statistic below. */
+    sampleCount: number;
+    /** `sampleCount >= MIN_SIGNIFICANT_SAMPLE`. Never inferred from anything else. */
+    significant: boolean;
+    /** Always populated: with `sampleCount` and the threshold, in words. */
+    significanceNote: string;
+    /** Reviews present only as markdown. Counted, but contributing no data. */
+    markdownFallbackCount: number;
+    /** Files the reader could not use, and why. `skipped.length` is the count. */
+    skipped: CorpusSkippedFile[];
+    /** Verbatim plan-time effort tiers, each with how many plans recorded it. */
+    effortTiers: CorpusVerbatimGroup[];
+    /**
+     * Verbatim complexity tiers. EMPTY today — no plan stores the line. It is
+     * reported rather than omitted so the absence is visible, not inferred.
+     */
+    complexityTiers: CorpusVerbatimGroup[];
+    /** The observed text each sidecar recorded, grouped verbatim. */
+    observedPhrases: CorpusVerbatimGroup[];
+    findingPairs: CorpusFindingPairCount[];
+}

package/dist/features/completion-review/calibration-corpus.d.ts

@@ -0,0 +1,5 @@
+import type { CorpusReport } from "./calibration-corpus-types";
+export type { CorpusFindingPairCount, CorpusReport, CorpusRowSource, CorpusSample, CorpusSkippedFile, CorpusVerbatimGroup, } from "./calibration-corpus-types";
+export { MIN_SIGNIFICANT_SAMPLE } from "./calibration-corpus-types";
+/** Read a reviews directory and aggregate it. A missing directory yields an empty corpus. */
+export declare function readCalibrationCorpus(reviewsDir?: string): CorpusReport;

package/dist/features/completion-review/calibration-observed.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Task 7 — the observed side of the comparison.
+ *
+ * Observed complexity is what execution demonstrably did: tasks executed, files
+ * touched, notepad blockers. It is never modelled, and never a re-run keyword
+ * heuristic over the plan text.
+ */
+import type { ObservedExecutionFacts } from "./calibration-types";
+import type { DriftFacts, ProgressFacts } from "./gather-types";
+export interface ObservedFactSources {
+    progress: ProgressFacts;
+    drift: DriftFacts;
+    /** `## Blockers` entries counted in the plan's notepads by the caller. */
+    notepadBlockerEntries: number;
+}
+export declare function collectObservedExecutionFacts(sources: ObservedFactSources): ObservedExecutionFacts;

package/dist/features/completion-review/calibration-render.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Task 7 — rendering sections (c) Complexity and (d) Required Effort.
+ *
+ * The shape is a COMPARISON, never a score: the plan's own words, reproduced
+ * verbatim, sitting BESIDE the facts execution demonstrably produced. No
+ * subtraction, no percentage, no "under-estimated by N" — an ordinal tier has no
+ * numeric scale, so any delta would be a number the plan never asserted.
+ *
+ * The absent-baseline path is handled FIRST because it is the common one: no
+ * plan in the corpus records a **Complexity** line, so the honest default is a
+ * section that renders and says why it is empty, not a section that invents a
+ * level to fill itself.
+ */
+import type { CalibrationComparison, CalibrationRenderInput } from "./calibration-types";
+export declare function renderCalibrationComparison(input: CalibrationRenderInput): CalibrationComparison;