milens 0.6.3 → 0.6.5

package/.agents/skills/milens-code-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: milens-code-review
+description: Automated Code Review — PR analysis, symbol deep-dive, dead code detection, tech debt grep, and review report
+---
+
+# milens-code-review — Automated Code Review
+
+Analyze a PR or local changes with multi-layered review: risk scoring, symbol deep-dives, dead code audit, tech debt search, and a structured report.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_review_pr` | List changed files + affected symbols with risk scores |
+| `mcp_milens_review_symbol` | Deep-dive on a single symbol (role, heat, dependents, test status) |
+| `mcp_milens_context` | Incoming references + outgoing dependencies |
+| `mcp_milens_find_dead_code` | Find exported symbols with zero references |
+| `mcp_milens_grep` | Text search for tech debt markers and dangerous patterns |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: PR Overview
+
+Start with the full PR-level assessment.
+
+```
+mcp_milens_review_pr({repo: "<workspaceRoot>"})
+```
+
+Review the output for:
+- **Changed files** — what was touched
+- **Affected symbols** — each with a risk score (CRITICAL, HIGH, MEDIUM, LOW)
+- **Risk summary** — distribution of risk levels across the change
+
+### Step 2: Deep-Dive on High-Risk Symbols
+
+For every symbol rated CRITICAL or HIGH, perform a deep-dive.
+
+```
+mcp_milens_review_symbol({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+What you get:
+- **Role** — what the symbol does in the architecture
+- **Heat** — frequency of changes, complexity, fan-in/fan-out
+- **Dependents count** — how many things break if this is wrong
+- **Test status** — whether it has test coverage
+
+### Step 3: Context for High-Risk Symbols
+
+Still for CRITICAL/HIGH symbols, get 360° context.
+
+```
+mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+This reveals:
+- **Incoming references** — who depends on this symbol
+- **Outgoing calls** — what this symbol depends on
+- **Re-export chains** — if the symbol is re-exported through barrel files
+
+### Step 4: Dead Code Audit
+
+Check for exported symbols with zero references (potential dead code).
+
+```
+mcp_milens_find_dead_code({repo: "<workspaceRoot>", limit: 20})
+```
+
+Flag any dead code that is:
+- Newly introduced by this PR
+- In files touched by this PR
+- Adjacent to changed code (same module)
+
+### Step 5: Tech Debt Search
+
+Search for tech debt markers and debugging remnants.
+
+```
+mcp_milens_grep({pattern: "TODO|FIXME|HACK|console\\.(log|debug)", scope: "code", repo: "<workspaceRoot>"})
+```
+
+Also check for:
+- Commented-out code
+- `@ts-ignore` or `@ts-expect-error` (TypeScript)
+- `# noqa` or `# type: ignore` (Python)
+- Empty catch blocks
+
+### Step 6: Produce Review Report
+
+Consolidate findings into a review report with these sections:
+
+1. **Summary** — files changed, risk distribution
+2. **Symbol Deep-Dives** — one entry per CRITICAL/HIGH symbol with findings from Steps 2-3
+3. **Dead Code** — symbols flagged from Step 4, with recommendations
+4. **Tech Debt** — markers found in Step 5, with severity
+5. **Recommendations** — prioritized list of actions (blocking vs. non-blocking)
+6. **Verdict** — APPROVED / NEEDS CHANGES / BLOCKED
+
+## Example Session
+
+### Input
+
+```
+"review the PR for branch feature/auth-refactor"
+```
+
+### Tool Calls
+
+**Step 1 — PR overview:**
+```
+mcp_milens_review_pr({repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Changed files (4):
+  src/auth/login.ts          [modified]
+  src/auth/tokens.ts         [new]
+  src/auth/types.ts          [modified]
+  src/middleware/auth.ts     [modified]
+
+Affected symbols:
+  authenticate    [function]  CRITICAL  — 15 dependents, no tests
+  generateToken   [function]  HIGH      — 8 dependents, 1 test
+  UserSession     [interface] MEDIUM    — 5 dependents
+  validateRole    [function]  LOW       — 2 dependents
+```
+
+**Step 2 — Deep-dive on CRITICAL symbol:**
+```
+mcp_milens_review_symbol({name: "authenticate", repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Symbol: authenticate [function] — CRITICAL
+  Role: core auth entry point, all protected routes depend on it
+  Heat: 23 commits in last 90 days, 87% modification rate
+  Dependents: 15 (12 direct callers + 3 middleware wrappers)
+  Test status: 0 tests, 0% coverage
+  Complexity: high (cyclomatic 14, 5 branching paths)
+```
+
+**Step 3 — Context:**
+```
+mcp_milens_context({name: "authenticate", repo: "/home/user/project"})
+```
+
+**Output:** 15 incoming refs (routes, middleware), 4 outgoing deps (token validation, user lookup, logger, rate limiter)
+
+**Step 4 — Dead code:**
+```
+mcp_milens_find_dead_code({repo: "/home/user/project", limit: 20})
+```
+
+**Output:** `legacyAuthCheck` in the same module has 0 references — candidate for removal.
+
+**Step 5 — Tech debt:**
+```
+mcp_milens_grep({pattern: "TODO|FIXME|HACK|console\\.(log|debug)", scope: "code", repo: "/home/user/project"})
+```
+
+**Output:** 3 matches — 1 `console.log` in tokens.ts, 2 `TODO` comments in login.ts.
+
+**Step 6 — Report produced** (see report format above).
+
+## Best Practices
+
+1. **Don't skip the deep-dive.** CRITICAL symbols demand `review_symbol` + `context` — surface-level review misses cascading failures.
+2. **Dead code in the diff is a red flag.** If a new symbol has zero references, question whether it belongs in this PR.
+3. **Tech debt in new code is a blocker.** `console.log`, `FIXME`, or debug code should not ship. Flag it as blocking.
+4. **Risk score drives review depth.** HIGH/CRITICAL = full deep-dive. MEDIUM = quick context check. LOW = skip unless it's a new file.
+5. **Produce a written report.** Don't just run the tools — consolidate findings into a review document the team can reference.
+
+## Quality Gate
+
+| Criteria | Pass | Fail |
+|---|---|---|
+| PR review tool | Review completes without errors | Tool fails or returns partial data |
+| Risk assessment | All CRITICAL/HIGH symbols deep-dived | Any CRITICAL symbol skipped |
+| Dead code check | No newly introduced dead code | New dead code found in changed files |
+| Tech debt grep | No debug code (`console.log`, etc.) | Debug/leftover code in diff |
+| Report completeness | All 6 report sections filled | Missing sections or incomplete findings |

package/.agents/skills/milens-debugger/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: milens-debugger
+description: Root Cause Analysis — execution trace, blast radius, dependency paths, deep context, and ranked hypotheses with fix suggestions
+---
+
+# milens-debugger — Root Cause Analysis
+
+Debug issues by tracing execution flow, analyzing blast radius, exploring dependency paths, and producing ranked root cause hypotheses with fix suggestions and regression risk assessment.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_trace` | Execution flow from entrypoints to target (or reverse) |
+| `mcp_milens_context` | 360° symbol view: incoming refs + outgoing deps |
+| `mcp_milens_impact` | Blast radius: what breaks if target changes |
+| `mcp_milens_explain_relationship` | Shortest path between two symbols |
+| `mcp_milens_smart_context` | Intent-aware context for debug intent |
+| `mcp_milens_overview` | Combined context + impact + grep in one call |
+| `mcp_milens_grep` | Text search across all files (templates, configs, error messages) |
+| `mcp_milens_review_symbol` | Deep-dive single symbol risk assessment |
+| `mcp_milens_get_type_hierarchy` | Class inheritance chain |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: Understand the Target
+
+Get deep context on the problematic symbol.
+
+```
+mcp_milens_smart_context({name: "<targetSymbol>", intent: "debug", repo: "<workspaceRoot>"})
+```
+
+This returns execution paths, data flow, dependencies, and test coverage in one call.
+
+### Step 2: Trace Execution
+
+Map how code reaches the target from entrypoints.
+
+```
+mcp_milens_trace({name: "<targetSymbol>", direction: "to", repo: "<workspaceRoot>"})
+```
+
+For downstream impact, trace forward:
+
+```
+mcp_milens_trace({name: "<targetSymbol>", direction: "from", repo: "<workspaceRoot>"})
+```
+
+### Step 3: Blast Radius
+
+Understand what breaks if the target is modified.
+
+```
+mcp_milens_impact({target: "<targetSymbol>", depth: 3, repo: "<workspaceRoot>"})
+```
+
+Pay special attention to depth-1 dependents — these WILL break.
+
+### Step 4: Dependency Paths
+
+For each suspect dependency, trace the exact connection path.
+
+```
+mcp_milens_explain_relationship({from: "<suspect>", to: "<targetSymbol>", repo: "<workspaceRoot>"})
+```
+
+### Step 5: Full Context View
+
+Get a 360° view of the target and its immediate neighbors.
+
+```
+mcp_milens_context({name: "<targetSymbol>", repo: "<workspaceRoot>"})
+```
+
+Check both incoming (who calls this) and outgoing (what this calls).
+
+### Step 6: Text Search for Clues
+
+Search for error messages, TODOs, or related patterns.
+
+```
+mcp_milens_grep({pattern: "<errorMessage or keyword>", repo: "<workspaceRoot>"})
+```
+
+Use `include` to narrow scope (e.g., `"**/*.ts"`, `"**/*.md"`).
+
+### Step 7: Class Hierarchy
+
+If the target is a class, check its inheritance chain.
+
+```
+mcp_milens_get_type_hierarchy({name: "<ClassName>", repo: "<workspaceRoot>"})
+```
+
+### Step 8: Risk Assessment
+
+Deep-dive the target's risk profile.
+
+```
+mcp_milens_review_symbol({name: "<targetSymbol>", repo: "<workspaceRoot>"})
+```
+
+### Step 9: Root Cause Hypotheses
+
+Rank hypotheses by likelihood:
+
+| # | Hypothesis | Evidence | Confidence | Suggested Fix | Regression Risk |
+|---|---|---|---|---|---|
+| 1 | | | HIGH/MEDIUM/LOW | | |
+| 2 | | | | | |
+| 3 | | | | | |
+
+Each hypothesis MUST cite specific tools and their output as evidence.
+
+## Quality Gate
+
+### PASS if:
+- [x] Execution trace complete (both directions)
+- [x] Blast radius analyzed to depth 3
+- [x] At least 3 dependency paths traced
+- [x] Full 360° context captured
+- [x] Text search performed for error messages/keywords
+- [x] At least 3 ranked hypotheses with evidence citations
+- [x] Fix suggestions include regression risk assessment
+
+### FAIL if:
+- [ ] Any step skipped without documented reason
+- [ ] Hypotheses lack tool evidence citations
+- [ ] Fix suggestions have no regression risk assessment
+- [ ] Only one hypothesis considered (lack of thoroughness)
+
+## Never Skip
+
+1. Always run `mcp_milens_smart_context` first — it is the most efficient starting point for debugging
+2. Never skip blast radius analysis — a fix that introduces new breakage is not a fix
+3. Always cite specific tool outputs as evidence for each hypothesis
+4. Always include regression risk in fix suggestions
+5. If dead code is suspected, run `mcp_milens_find_dead_code` to check for unused symbols in the trace path

package/.agents/skills/milens-eval/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: milens-eval
+description: Evaluation & Quality Gate — plan, implement, verify scope, review risk, run tests, check coverage, and pass/fail
+---
+
+# milens-eval — Evaluation & Quality Gate
+
+A structured quality gate for feature development: plan tests, implement changes, verify scope, review risks, run impacted tests, check coverage gaps, and produce a pass/fail verdict.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_test_plan` | Generate test strategy before implementation |
+| `mcp_milens_detect_changes` | Verify only expected files changed after implementation |
+| `mcp_milens_review_pr` | Risk assessment of the changes |
+| `mcp_milens_test_impact` | Identify and run affected test files |
+| `mcp_milens_test_coverage_gaps` | Verify no new untested critical symbols introduced |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: Plan Tests (Before Implementation)
+
+Before writing code, plan the test strategy.
+
+```
+mcp_milens_test_plan({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+This provides:
+- **Mock strategy** — what dependencies to isolate
+- **Test scenarios** — happy path, error states, edge cases
+- **Affected test files** — existing test files that may need updates
+
+Review the plan to ensure it covers:
+- Core functionality (happy path)
+- Input validation (error handling)
+- Integration points (service boundaries)
+- Edge cases (null, empty, boundary values)
+
+### Step 2: Implement Changes
+
+Write the actual code changes. This is the implementation phase:
+1. Write or update the target symbol(s)
+2. Implement tests following the plan from Step 1
+3. Follow existing code conventions and patterns
+4. No `console.log`, no commented-out code, no debug artifacts
+
+### Step 3: Detect Changes
+
+Verify the scope of changes matches expectations.
+
+```
+mcp_milens_detect_changes({repo: "<workspaceRoot>"})
+```
+
+Check:
+- **Expected files present** — all intended modifications are listed
+- **No unexpected files** — no config drift, accidental staging, or side effects
+- **No missing files** — if a file you expected to change is absent, investigate
+
+### Step 4: Review Risk
+
+Assess the quality and risk of the changes.
+
+```
+mcp_milens_review_pr({repo: "<workspaceRoot>"})
+```
+
+Focus on:
+- **CRITICAL symbols** — any symbol rated CRITICAL needs thorough review
+- **Risk distribution** — how many HIGH/MEDIUM/LOW symbols changed
+- **Review suggestions** — automated findings to address
+
+### Step 5: Run Tests
+
+Identify and run all affected tests.
+
+```
+mcp_milens_test_impact({repo: "<workspaceRoot>"})
+```
+
+This returns the list of test files impacted by the changes. Run them all:
+- If any test fails: fix before proceeding
+- If a test you didn't expect is affected: investigate why
+- If a test you expected is missing: your test files may not be indexed
+
+### Step 6: Check Coverage Gaps
+
+Verify no new untested critical symbols were introduced.
+
+```
+mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>", limit: 20})
+```
+
+Review the output:
+- **Newly introduced symbols** — should have test coverage
+- **Pre-existing gaps** — note them but don't fail the gate (they're not new)
+- **HIGH risk + no tests** — if any HIGH-risk symbol in the change has no tests, this is a failure
+
+### Step 7: Quality Gate Verdict
+
+Apply the pass/fail criteria (see Quality Gate section below) and produce a verdict:
+
+**PASSED:**
+- All test files pass
+- No CRITICAL review_pr findings
+- No unexpected files in detect_changes
+- No new HIGH-risk uncovered symbols
+
+**CONDITIONAL PASS:**
+- All tests pass
+- CRITICAL review_pr findings are acknowledged and documented with remediation plan
+- Minor unexpected files that are harmless (lockfile updates)
+
+**FAILED:**
+- Any test fails
+- Hardcoded secrets found
+- Blast radius exceeds safe threshold without justification
+- New HIGH-risk symbols with zero test coverage
+
+## Example Session
+
+### Input
+
+```
+"evaluate the feature branch for the new rate limiter"
+```
+
+### Tool Calls
+
+**Step 1 — Test plan:**
+```
+mcp_milens_test_plan({name: "RateLimiter", repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Test Plan for RateLimiter:
+  Mock strategy: stub Redis client, stub clock
+  Tests:
+    1. allows requests within limit
+    2. blocks requests exceeding limit
+    3. resets counter after window expires
+    4. handles Redis connection failure gracefully
+  Affected: src/__tests__/middleware.test.ts (new)
+```
+
+**Step 2 — Implement** rate limiter class and tests.
+
+**Step 3 — Detect changes:**
+```
+mcp_milens_detect_changes({repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Changed files:
+  src/middleware/rateLimiter.ts        [new]
+  src/__tests__/middleware.test.ts     [new]
+  src/middleware/index.ts              [modified]  — barrel export
+```
+
+3 files — all expected.
+
+**Step 4 — Review risk:**
+```
+mcp_milens_review_pr({repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Affected symbols:
+  RateLimiter        [class]   MEDIUM — 2 callers, 4 tests
+  applyRateLimit     [function] LOW    — 0 callers (internal helper)
+
+No CRITICAL findings. 1 LOW suggestion: add JSDoc to RateLimiter class.
+```
+
+**Step 5 — Test impact:**
+```
+mcp_milens_test_impact({repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Affected test files:
+  src/__tests__/middleware.test.ts (new)
+```
+
+Run tests: `npm test -- middleware.test.ts` — all 4 pass.
+
+**Step 6 — Coverage gaps:**
+```
+mcp_milens_test_coverage_gaps({repo: "/home/user/project", limit: 20})
+```
+
+**Output:** No new HIGH-risk symbols introduced. 3 pre-existing LOW/medium gaps unrelated to this change.
+
+**Step 7 — Verdict: PASSED.**
+
+## Best Practices
+
+1. **Test plan before code, not after.** Step 1 exists to prevent "I'll test it later." Write the plan, review it, then implement.
+2. **detect_changes is your safety net.** If it shows a `package-lock.json` change you didn't intend, something went wrong. Investigate every unexpected file.
+3. **Treat CRITICAL review findings as blockers.** Don't rationalize them away. A CRITICAL finding means the change introduces significant risk.
+4. **Coverage gaps are relative to the change.** Don't fail the gate because of pre-existing gaps. Fail only if the change itself introduces new uncovered critical symbols.
+5. **Conditional passes need a deadline.** If you issue a "Conditional Pass," document exactly what must be fixed and by when. An open-ended conditional is a failed gate in disguise.
+
+## Quality Gate
+
+| Criteria | Pass | Fail |
+|---|---|---|
+| Test plan exists | Test plan generated with ≥3 scenarios | No test plan or < 3 scenarios |
+| Change scope | `detect_changes` shows only expected files | Unexpected files in diff (unless harmless) |
+| Review risk | No CRITICAL findings | Unresolved CRITICAL findings |
+| Test execution | All `test_impact` files pass | Any test file fails |
+| Coverage gaps | No new HIGH-risk symbols without tests | New HIGH-risk symbol has 0 test coverage |
+| Gate verdict | PASSED or CONDITIONAL PASS (with documented remediation) | FAILED — must fix and re-run evaluation |