milens 0.6.2 → 0.6.4

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 |

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

@@ -0,0 +1,227 @@
+---
+name: milens-plan
+description: Implementation Planning — research codebase, analyze impact, plan tests, and produce a structured implementation plan
+---
+
+# milens-plan — Implementation Planning
+
+Research the codebase end-to-end before writing code: understand structure, trace execution, assess blast radius, plan tests, and produce a structured plan following the ECC Planner specification.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_codebase_summary` | High-level project overview (languages, file count, domain count) |
+| `mcp_milens_domains` | Module clusters showing logical groupings |
+| `mcp_milens_routes` | API endpoints inventory with handler mappings |
+| `mcp_milens_smart_context` | Intent-aware symbol analysis (edit intent) |
+| `mcp_milens_edit_check` | Pre-edit safety: callers, export status, re-export chains, warnings |
+| `mcp_milens_trace` | Execution flow from entrypoints to target |
+| `mcp_milens_impact` | Blast radius: what breaks if target changes |
+| `mcp_milens_test_plan` | Mock strategy + test scenarios for a symbol |
+| `mcp_milens_test_coverage_gaps` | Related untested symbols |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: Project Overview
+
+Understand the codebase at a high level.
+
+```
+mcp_milens_codebase_summary({repo: "<workspaceRoot>"})
+```
+
+Captures: languages, file counts, total symbols, top-level domains, entry points.
+
+### Step 2: Domain Structure
+
+Map module clusters to understand logical groupings.
+
+```
+mcp_milens_domains({repo: "<workspaceRoot>"})
+```
+
+Shows which files form cohesive modules based on the dependency graph. Helps identify:
+- Where the target code lives
+- Which domains interact with it
+- Natural boundaries for the change
+
+### Step 3: API Surface (optional)
+
+If the project is a web service, inventory the endpoints.
+
+```
+mcp_milens_routes({repo: "<workspaceRoot>"})
+```
+
+Useful when the change touches:
+- Route handlers
+- Middleware
+- Request/response types
+- Authentication/authorization
+
+### Step 4: Target Analysis
+
+Zoom in on the specific symbol to change.
+
+```
+mcp_milens_smart_context({name: "<symbolName>", intent: "edit", repo: "<workspaceRoot>"})
+```
+
+The `edit` intent returns: callers, export status, and immediate blast radius — only what matters for editing.
+
+### Step 5: Pre-Edit Safety Check
+
+Run `edit_check` for pre-edit warnings.
+
+```
+mcp_milens_edit_check({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+This returns:
+- **Callers** — who calls this symbol
+- **Export status** — whether it's public API
+- **Re-export chains** — barrel file re-exports that extend blast radius
+- **Warnings** — breaking change risks, high fan-in, etc.
+
+### Step 6: Execution Flow
+
+Trace how the target gets called at runtime.
+
+```
+mcp_milens_trace({name: "<symbolName>", direction: "to", repo: "<workspaceRoot>"})
+```
+
+Shows the call chains from entrypoints down to this symbol. Critical for understanding:
+- What triggers this code
+- What data flows into it
+- What side effects it may have
+
+### Step 7: Blast Radius
+
+Assess the full impact of the proposed change.
+
+```
+mcp_milens_impact({target: "<symbolName>", depth: 3, repo: "<workspaceRoot>"})
+```
+
+Shows all symbols that break if the target changes, up to the specified depth.
+- If depth-1 dependents > 5: **STOP and warn** before proceeding
+- If depth-3 dependents > 20: **consider a facade or adapter pattern**
+
+### Step 8: Test Strategy
+
+Plan the testing approach.
+
+```
+mcp_milens_test_plan({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+Covers:
+- Mock strategy (what to isolate)
+- Test scenarios (happy path, edge cases, error handling)
+- Affected test files
+
+### Step 9: Coverage Gaps (optional)
+
+Check for related symbols that lack test coverage.
+
+```
+mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>", limit: 10})
+```
+
+If neighboring symbols are untested, consider adding tests as part of the change.
+
+### Step 10: Produce Implementation Plan
+
+Consolidate all findings into a structured plan:
+
+1. **Executive Summary** — what changes, why, at what risk level
+2. **Codebase Context** — domains, routes, and structure (from Steps 1-3)
+3. **Symbol Analysis** — target details, callers, execution flow (from Steps 4-6)
+4. **Impact Assessment** — blast radius, breaking change risks, dependents map (from Step 7)
+5. **Test Strategy** — test plan, mock strategy, coverage gaps (from Steps 8-9)
+6. **Implementation Steps** — ordered, actionable steps with file paths
+7. **Risk Mitigation** — rollback plan, feature flags, phased deployment options
+
+## Example Session
+
+### Input
+
+```
+"plan a change to add rate limiting to the login handler"
+```
+
+### Tool Calls
+
+**Step 1:**
+```
+mcp_milens_codebase_summary({repo: "/home/user/project"})
+```
+
+**Output:** TypeScript project, 120 files, 850 symbols, 5 domains (auth, routes, db, utils, config).
+
+**Step 2:**
+```
+mcp_milens_domains({repo: "/home/user/project"})
+```
+
+**Output:** `auth` domain contains login handler, token manager, session store.
+
+**Step 4:**
+```
+mcp_milens_smart_context({name: "loginHandler", intent: "edit", repo: "/home/user/project"})
+```
+
+**Output:** 3 callers (Express route, rate limiter middleware, integration test), no re-exports.
+
+**Step 5:**
+```
+mcp_milens_edit_check({name: "loginHandler", repo: "/home/user/project"})
+```
+
+**Output:** 3 callers, exported, no re-export chains, **WARNING: exported function — changing signature is a breaking change.**
+
+**Step 6:**
+```
+mcp_milens_trace({name: "loginHandler", direction: "to", repo: "/home/user/project"})
+```
+
+**Output:** Chain: `Express router → authMiddleware → loginHandler → tokenService.sign()`
+
+**Step 7:**
+```
+mcp_milens_impact({target: "loginHandler", depth: 3, repo: "/home/user/project"})
+```
+
+**Output:** Depth-1: 3 dependents (route, integration test, auth docs). Depth-2: 8 dependents. Depth-3: 14 dependents. **No STOP threshold breached.**
+
+**Step 8:**
+```
+mcp_milens_test_plan({name: "loginHandler", repo: "/home/user/project"})
+```
+
+**Output:** Mock `tokenService`, `userStore`. 4 test scenarios: valid login, invalid password, rate limit exceeded, database failure.
+
+**Step 10 — Plan produced** (see plan format above).
+
+## Best Practices
+
+1. **Never skip impact analysis.** Even a "small" change can ripple through re-export chains. `impact` catches what intuition misses.
+2. **Use `edit` intent for `smart_context`** when planning edits — it omits irrelevant detail and focuses on callers and blast radius.
+3. **Stop at depth-3 for impact.** Deeper assessment rarely changes the implementation strategy but adds noise.
+4. **Trace before planning.** Understanding the execution path prevents "add rate limiter after JWT decode" mistakes where ordering matters.
+5. **Write the plan before the code.** The structured plan from Step 10 is the deliverable. Implementation follows the plan — not the other way around.
+
+## Quality Gate
+
+| Criteria | Pass | Fail |
+|---|---|---|
+| Codebase overview | All 3 overview tools succeed (summary, domains, routes) | Any tool fails or returns empty |
+| Target analysis | `smart_context` + `edit_check` both run | Either tool skipped for the target symbol |
+| Impact assessment | `impact` at depth 3 completed, dependents counted | Impact not run or depth < 3 |
+| Blast radius check | < 5 depth-1 dependents OR user warned and confirmed | > 5 depth-1 dependents without user confirmation |
+| Test plan | `test_plan` covers happy path, edge cases, and errors | Less than 3 scenarios in the plan |
+| Implementation plan | All 7 sections of the plan filled | Missing sections or incomplete analysis |

package/.agents/skills/milens-refactor-clean/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: milens-refactor-clean
+description: Safe Refactoring with Blast Radius Check — find dead code, verify impact, remove safely, and verify test coverage
+---
+
+# milens-refactor-clean — Safe Refactoring with Blast Radius Check
+
+Identify dead or unwanted code, verify it's truly unused via context and text search, assess blast radius, remove safely, and confirm only expected files changed.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_find_dead_code` | Find exported symbols with zero incoming references |
+| `mcp_milens_context` | Verify a symbol is truly unused (incoming refs check) |
+| `mcp_milens_impact` | Blast radius assessment before removal |
+| `mcp_milens_grep` | Text search for symbol name in configs, templates, docs |
+| `mcp_milens_detect_changes` | Post-refactor verification of changed files |
+| `mcp_milens_test_impact` | Identify affected test files to run |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: Find Candidates
+
+Identify exported symbols with zero incoming code references.
+
+```
+mcp_milens_find_dead_code({repo: "<workspaceRoot>", limit: 30})
+```
+
+The output lists symbols that the static analysis graph shows as unreferenced. These are removal candidates.
+
+**Important caveats:**
+- Symbols used only via reflection, `eval`, or dynamic imports won't show references
+- Side-effect-only imports (e.g., `import "./init"`) may look unused
+- Config-based routing (React Router, NestJS decorators) may not resolve to references
+
+### Step 2: Verify Truly Unused
+
+For each candidate, run context to confirm zero incoming references.
+
+```
+mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+Look at the **incoming references** count:
+- **0 incoming refs** — likely safe to remove
+- **1+ incoming refs** — the symbol is used via paths the dead code detector missed; do NOT remove without further investigation
+
+### Step 3: Check Text References
+
+Even if context shows 0 code references, the symbol may appear in non-code files.
+
+```
+mcp_milens_grep({pattern: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+Check for matches in:
+- **Config files** — `.json`, `.yaml`, `.toml`, `.env`
+- **Template files** — `.html`, `.vue`, `.jsx`, `.tsx` (usage in markup)
+- **Documentation** — `*.md`, `*.mdx`
+- **Route definitions** — string-based routing (Express, FastAPI)
+- **Package scripts** — `package.json` scripts referencing the symbol
+
+### Step 4: Assess Blast Radius
+
+Before deleting, understand what removing the symbol would affect (even if nothing references it now — for safety).
+
+```
+mcp_milens_impact({target: "<symbolName>", depth: 3, repo: "<workspaceRoot>"})
+```
+
+Check:
+- **Depth-1 dependents** — should be 0 for true dead code
+- **Transitive dependents** — if > 0, something references this indirectly
+
+### Step 5: Remove the Code
+
+After verification, remove:
+1. The symbol itself (function, class, interface, etc.)
+2. Its imports if they're now unused
+3. Related tests (now orphaned)
+
+### Step 6: Verify Change Scope
+
+Confirm only expected files changed.
+
+```
+mcp_milens_detect_changes({repo: "<workspaceRoot>"})
+```
+
+Check that:
+- Only the files you intended to modify appear
+- No config files, lockfiles, or unrelated modules changed
+- No accidental deletions
+
+### Step 7: Run Affected Tests
+
+Identify and run tests impacted by the removal.
+
+```
+mcp_milens_test_impact({repo: "<workspaceRoot>"})
+```
+
+This lists test files that reference the removed code or its dependents. Run all affected tests to ensure nothing is broken.
+
+## Example Session
+
+### Input
+
+```
+"remove unused utility functions from the helpers module"
+```
+
+### Tool Calls
+
+**Step 1 — Find candidates:**
+```
+mcp_milens_find_dead_code({repo: "/home/user/project", limit: 30})
+```
+
+**Output:**
+```
+1. formatDateLegacy    [function]  src/utils/helpers.ts:45
+2. unusedValidator     [function]  src/utils/helpers.ts:78
+3. OldUserType         [interface] src/types/legacy.ts:12
+4. debugLog            [function]  src/utils/helpers.ts:102
+```
+
+**Step 2 — Verify context for each:**
+```
+mcp_milens_context({name: "formatDateLegacy", repo: "/home/user/project"})
+```
+
+**Output:** 0 incoming refs, 1 outgoing dep (calls `toISOString`). Safe to remove.
+
+```
+mcp_milens_context({name: "unusedValidator", repo: "/home/user/project"})
+```
+
+**Output:** 0 incoming refs. Safe to remove.
+
+```
+mcp_milens_context({name: "debugLog", repo: "/home/user/project"})
+```
+
+**Output:** 3 incoming refs — used in `server.ts`, `logger.ts`, `middleware.ts`. NOT dead code — skip.
+
+**Step 3 — Text search for remaining candidates:**
+```
+mcp_milens_grep({pattern: "formatDateLegacy", repo: "/home/user/project"})
+```
+
+**Output:** 1 match in `docs/migration-guide.md` — documentation reference only, still safe to remove with a docs update.
+
+```
+mcp_milens_grep({pattern: "OldUserType", repo: "/home/user/project"})
+```
+
+**Output:** 0 matches across all files. Fully dead.
+
+**Step 4 — Impact check:**
+```
+mcp_milens_impact({target: "formatDateLegacy", depth: 3, repo: "/home/user/project"})
+```
+
+**Output:** Depth-1: 0 dependents. No blast radius.
+
+**Step 5 — Remove `formatDateLegacy` and `OldUserType`** in file editor
+
+**Step 6 — Verify scope:**
+```
+mcp_milens_detect_changes({repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Changed files:
+  src/utils/helpers.ts    [modified] — expected
+  src/types/legacy.ts     [modified] — expected
+  docs/migration-guide.md [modified] — expected (updated reference)
+```
+
+**Step 7 — Test impact:**
+```
+mcp_milens_test_impact({repo: "/home/user/project"})
+```
+
+**Output:** 2 affected test files — `src/__tests__/helpers.test.ts`, `src/__tests__/types.test.ts`. Both pass after updating.
+
+## Best Practices
+
+1. **Context beats dead-code detection.** A symbol tagged as "dead" by the detector may still be used via dynamic patterns. Always verify with `context` before deleting.
+2. **Grep is the backstop.** `context` only catches code-level references. `grep` catches template usage, string-based routing, config files, and docs. Never skip Step 3.
+3. **Remove in small batches.** Delete 1-3 symbols per commit. Large-scale deletion makes `detect_changes` harder to verify and `git bisect` harder to use.
+4. **Update docs proactively.** If `grep` finds documentation references, update or remove them in the same commit. Stale docs referencing deleted symbols are worse than no docs.
+5. **Test impact is not optional.** Removing code can break tests that import the symbol directly. Run `test_impact` and fix before committing.
+
+## Quality Gate
+
+| Criteria | Pass | Fail |
+|---|---|---|
+| Dead code identified | `find_dead_code` returns candidates | Tool fails or returns empty (with large codebase) |
+| Verification complete | `context` + `grep` run for every candidate marked for removal | Any candidate removed without both checks |
+| Blast radius safe | All removed symbols have 0 depth-1 dependents | Any symbol with dependents removed without justification |
+| Change scope clean | `detect_changes` shows only expected files | Unexpected files in the diff |
+| Tests pass | All `test_impact` files pass | Any affected test file fails |