secufusion-mcp 1.0.17 → 1.0.18

package/README.md

@@ -10,12 +10,12 @@
 
 ## What is this?
 
-`secufusion-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that plugs into AI coding assistants (Claude Desktop, Cursor, Cline, etc.) and gives them **nine powerful tools** to enforce SecuFusion's engineering standards throughout the development lifecycle:
+`secufusion-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that plugs into AI coding assistants (Claude Desktop, Cursor, Cline, etc.) and gives them **ten powerful tools** to enforce SecuFusion's engineering standards throughout the development lifecycle:
 
 | Tool | Phase | What it does |
 |---|---|---|
 | `manage_project_spec` | **Phase 00** — Session Start | Loads `.secufusion-project-spec.json` — full project DNA (ports, repos, domains, coding patterns, golden rules) |
-| `manage_task` | **Phase 0.7 / 1 / 2 / 4** — Task Lifecycle | Creates `.secufusion/tasks/WI-{id}/` folder with spec, progress, decisions, files-touched, scenarios, and PR summary |
+| `manage_task` | **Phase 0.7 / 1 / 2 / 4** — Task Lifecycle | Creates dynamically named `.secufusion/tasks/{id}-{slug}/` folder with spec, progress, decisions, files-touched, scenarios, and PR summary |
 | `get_task_history` | **Phase 0 / 1** — Cross-Task Intelligence | Retrieves the full history of a past task before starting similar work |
 | `search_tasks` | **Phase 0 / 1** — Cross-Task Intelligence | Keyword search across all past task files — prevents re-solving solved problems |
 | `get_pattern_from_task` | **Phase 1** — Cross-Task Intelligence | Extracts reusable decisions, file patterns, and test scenarios from a completed task |
@@ -23,6 +23,7 @@
 | `log_rejected_pattern` | **Phase 3** — Course Correction | Records bad patterns to `.rejected-patterns.json` so they are never repeated |
 | `run_pre_pr_checks` | **Phase 4** — PR Handoff | Discovers modified microservices and gates PRs via AST-level linters + structural checks |
 | `get_secufusion_rules` | **Setup** | Returns the `AGENTS.md` rules for AI clients that don't natively support MCP Resources |
+| `classify_task` | **Phase 0.5** — Task Classification | **NEW** — Deep multi-pass analysis engine. Classifies any task as `BACKEND_ONLY`, `FRONTEND_ONLY`, `FULL_STACK`, or `EXTENSION_ONLY` based on root cause (where the fix lives), not surface symptoms. Must be the first tool called on any task. |
 
 ---
 
@@ -400,6 +401,16 @@ These rules are enforced automatically — the AI will never violate them:
 ✅ Over-flag > under-flag: always present a breaking change report if in doubt
 ```
 
+**classify_task — Deep Analysis Engine** (runs first on every task, before anything else):
+```
+✅ Weighted signal tiers: service names = 10pts, tech constructs = 5pts, generic = 1pt
+✅ Root-cause extraction: classifies by WHERE THE FIX LIVES, not where the symptom appears
+✅ Negation detection: "not a UI issue" removes frontend signal weight
+✅ Bug disambiguation: data-correctness/exception/auth/CRUD/performance bugs → +backend
+✅ Confidence gate: HIGH only when score ratio ≥ 1.8× AND Tier 1/2 signal matched
+✅ Persists to .secufusion/classifications/{id}.json — no re-classification on resume
+```
+
 ---
 
 ## File Outputs
@@ -407,13 +418,13 @@ These rules are enforced automatically — the AI will never violate them:
 | File | Description | Commit? |
 |---|---|---|
 | `.secufusion-project-spec.json` | **Project DNA** — all services, ports, patterns, golden rules. Generated once, read every session | ✅ Yes |
-| `.secufusion/registry.json` | Index of all work items ever initialized — used by `search_tasks` | ✅ Yes |
-| `.secufusion/tasks/WI-{id}/spec.json` | Task spec — title, description, ACs, tags, status | ✅ Yes |
-| `.secufusion/tasks/WI-{id}/progress.json` | AC tracking — pending, completed, next_step | ✅ Yes |
-| `.secufusion/tasks/WI-{id}/decisions.json` | Architectural decisions log (including rollback strategy) | ✅ Yes |
-| `.secufusion/tasks/WI-{id}/files-touched.json` | All files modified with change summaries | ✅ Yes |
-| `.secufusion/tasks/WI-{id}/scenarios.json` | Test scenarios (unit / integration / e2e / manual) | ✅ Yes |
-| `.secufusion/tasks/WI-{id}/pr-summary.md` | Auto-generated PR summary on `manage_task complete` | ✅ Yes |
+| `.secufusion/registry.json` | Index of all initialized work items and their exact dynamic folder names — used by `search_tasks` | ✅ Yes |
+| `.secufusion/tasks/{id}-{slug}/spec.json` | Task spec — title, description, ACs, tags, status | ✅ Yes |
+| `.secufusion/tasks/{id}-{slug}/progress.json` | AC tracking — pending, completed, next_step | ✅ Yes |
+| `.secufusion/tasks/{id}-{slug}/decisions.json` | Architectural decisions log (including rollback strategy) | ✅ Yes |
+| `.secufusion/tasks/{id}-{slug}/files-touched.json` | All files modified with change summaries | ✅ Yes |
+| `.secufusion/tasks/{id}-{slug}/scenarios.json` | Test scenarios (unit / integration / e2e / manual) | ✅ Yes |
+| `.secufusion/tasks/{id}-{slug}/pr-summary.md` | Auto-generated PR summary on `manage_task complete` | ✅ Yes |
 | `.secufusion-state.json` | **Legacy** branch-scoped state — still works via `manage_branch_state` | ✅ Yes |
 | `.rejected-patterns.json` | Cumulative log of all rejected patterns across sessions | ✅ Yes |
 | `.secufusion-tokens.json` | Persistent tracking of session-wide LLM token usage and cost | ❌ No |
@@ -433,16 +444,20 @@ These rules are enforced automatically — the AI will never violate them:
 │  Phase 0     │  manage_task (action=read_summary)  OR  search_tasks          │
 │  Resume      │  → Token-efficient status view → resume next_step instantly   │
 ├──────────────┼──────────────────────────────────────────────────────────────┤
-│  Phase 0.5   │  CLASSIFY: BACKEND_ONLY / FRONTEND_ONLY / FULL_STACK          │
-│  Ownership   │  Step 3: Performance risk scan (GREEN/AMBER/RED verdict)      │
-│  Check       │  Step 4: Breaking change scan (endpoints/entities/Kafka/ext)  │
+│  Phase 0.5   │  classify_task → 5-pass deep analysis engine                  │
+│  Ownership   │  Pass 1: Weighted signal scoring (Tier 1-4)                   │
+│  Check       │  Pass 2: Negation detection per sentence                      │
+│              │  Pass 3: Root-cause phrase extraction (fix location, not symptom) │
+│              │  Pass 4: Bug disambiguation matrix                            │
+│              │  Pass 5: Confidence gate (ratio ≥ 1.8× + Tier 1/2 required)  │
+│              │  → allowed_next_action: PROCEED / CONFIRM / STOP              │
 ├──────────────┼──────────────────────────────────────────────────────────────┤
 │  Phase 0.7   │  Present full plan (scope, files, ACs, perf, rollback)        │
 │  Plan Gate   │  → STOP and wait for "proceed" / "adjust" / "cancel"          │
 │              │  → manage_task (action=initialize) only after proceed          │
 ├──────────────┼──────────────────────────────────────────────────────────────┤
 │  Phase 1     │  search_tasks → get_task_history → manage_task initialize      │
-│  Planning    │  → Creates .secufusion/tasks/WI-{id}/ with all 5 files        │
+│  Planning    │  → Creates dynamic .secufusion/tasks/{id}-{slug}/ with all 5 files │
 ├──────────────┼──────────────────────────────────────────────────────────────┤
 │  Phase 2     │  manage_task: update_spec / log_file_touched /                │
 │  Execution   │              log_decision / add_scenario                       │
@@ -517,7 +532,7 @@ So that sensitive dashboard actions are protected against compromised credential
 4. If MFA fails 3 times, the account should be temporarily locked for 15 minutes.
 ```
 
-**The AI automatically classifies the task, presents a plan, and upon approval, calls `manage_task` to initialize `.secufusion/tasks/WI-2847/`:**
+**The AI automatically classifies the task, presents a plan, and upon approval, calls `manage_task` to initialize the dynamic folder `.secufusion/tasks/2847-add-mfa-enforcement-for-admin-users-on-login/`:**
 ```json
 {
   "action": "initialize",
@@ -630,7 +645,7 @@ The SecuFusion MCP operates across three complementary layers to prevent AI amne
 
 **Layer 1 — Project Spec (permanent, project-scoped):** `.secufusion-project-spec.json` — loaded once per session via `manage_project_spec`. The AI never needs to be told what port a service runs on, what pattern to use for DTO mapping, or how tenantId flows through the system.
 
-**Layer 2 — Task Memory (persistent, work-item-scoped):** `.secufusion/tasks/WI-{id}/` — one folder per work item, initialized via `manage_task`. Tracks spec, progress, decisions, files touched, scenarios, and generates a `pr-summary.md` on completion. Cross-task intelligence via `search_tasks`, `get_task_history`, and `get_pattern_from_task` prevents re-solving solved problems.
+**Layer 2 — Task Memory (persistent, work-item-scoped):** `.secufusion/tasks/{id}-{slug}/` — one dynamically named folder per work item, initialized via `manage_task`. Tracks spec, progress, decisions, files touched, scenarios, and generates a `pr-summary.md` on completion. Cross-task intelligence via `search_tasks`, `get_task_history`, and `get_pattern_from_task` prevents re-solving solved problems.
 
 **Layer 3 — AST Guardrails (automated, quality-gating):** ESLint, Maven Checkstyle, tenant isolation scanner, Flyway checker, performance rules, rollback classification, and breaking change detection run at PR time. Cannot be bypassed without explicit `skip_checks`.
 
@@ -649,17 +664,21 @@ Phase 0:  manage_task read_summary  →  resumes active work item
       ↓
 You say: "WI-1042: Add audit log export"
       ↓
-Phase 0.5: classify BACKEND_ONLY/FRONTEND_ONLY/FULL_STACK
-          + performance risk scan + breaking change scan
+Phase 0.5: classify_task → 5-pass deep analysis (FIRST tool call, no exceptions)
+          → weighted scores + root-cause phrases + negation + bug heuristics
+          → allowed_next_action: PROCEED (backend) / CONFIRM (mixed) / STOP (frontend)
+          + performance risk scan (GREEN/AMBER/RED)
+          + breaking change scan (endpoints/entities/Kafka/extension)
       ↓
 Phase 0.7: plan presented → developer approves ("proceed")
       ↓
-Phase 1: manage_task initialize  →  .secufusion/tasks/WI-1042/ created
+Phase 1: search_tasks (always) → get_task_history → manage_task initialize
+       → .secufusion/tasks/1042-add-audit-log-export/ created
       ↓
-Phase 2: code + log_file_touched + log_decision + add_scenario
+Phase 2: code + log_file_touched + log_decision + add_scenario (ALL mandatory)
       ↓
 Phase 4: manage_task complete  →  pr-summary.md generated
-       + run_pre_pr_checks     →  must pass before raising PR
+       + run_pre_pr_checks (fix → recheck loop until ZERO errors) → then PR
 ```
 
 ### Reusing across projects (Global Bundling)
@@ -676,6 +695,16 @@ Depending on your AI client's capabilities, you can load the rules instantly by
 
 *(If you prefer the legacy method, you can still copy `.agents/AGENTS.md` and `.secufusion-project-spec.json` into your project root).*
 
+### Dynamic Task Folders (v1.0.17+)
+
+As of version **1.0.17**, the MCP server automatically generates human-readable, safe folder names for all new tasks using the task's title.
+
+When you pass a title like `"BUG-1140: Tenant deletion reports failure"` to `manage_task initialize`, the server strips bad characters, truncates the string safely, and generates a perfect folder name:
+`.secufusion/tasks/BUG-1140-tenant-deletion-reports-failure/`
+
+- **Backward Compatible:** The AI only ever needs to supply the `work_item_id` (e.g. `BUG-1140`) for subsequent updates. The server instantly finds the correct folder via `registry.json` (O(1) lookup) or falls back to a prefix scan for legacy `WI-{id}` folders.
+- **OS Safe:** Automatically trims trailing dashes and clamps lengths to prevent Windows `MAX_PATH` errors.
+
 ---
 
 ## Talking to the AI — What You'll Ever Say
@@ -702,7 +731,94 @@ Once all three layers are in place, you interact completely naturally:
 
 **Before Phase 0.5 + 0.7:** The AI started coding immediately with no ownership check or explicit plan.
 
-**After Phase 0.5 + 0.7:** The AI classifies the task (backend/frontend/full-stack), runs a performance risk and breaking change scan, presents a complete plan with rollback strategy, and **waits for your approval before writing a single line of code**.
+**After Phase 0.5 + 0.7:** The AI calls `classify_task` first (no exceptions). The deep analysis engine classifies by root cause — not surface symptoms — runs a performance risk and breaking change scan, presents a complete plan with rollback strategy, and **waits for your approval before writing a single line of code**.
+
+**Before strict AGENTS.md:** Each phase was a soft bullet list with suggestions. The AI could skip steps.
+
+**After strict AGENTS.md:** Every phase has a MANDATORY tool-call sequence in code-block format, an explicit ❌ prohibition list, and a hard gate. Skipping any step is a named violation.
+
+---
+
+## Tool 10: `classify_task` — Deep Analysis Engine
+
+The **mandatory first step** for every task without exception. Classifies a task as `BACKEND_ONLY`, `FRONTEND_ONLY`, `FULL_STACK`, or `EXTENSION_ONLY` using a 5-pass deep analysis pipeline.
+
+> **Core principle:** Classifies by **where the fix lives** — not where the symptom appears.
+> `"Dashboard shows wrong device count"` → fix is in the API/DB query → **BACKEND_ONLY**
+> `"Button layout is broken"` → fix is in the React component → **FRONTEND_ONLY**
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `work_item_id` | string | Yes | Azure DevOps work item ID, e.g. `BUG-1140` or `2847` |
+| `title` | string | Yes | Full task title from Azure DevOps |
+| `description` | string | Yes | Full task description / problem statement — paste everything |
+| `task_type` | enum | Yes | `bug` \| `user_story` \| `feature` \| `hotfix` \| `refactor` \| `chore` |
+
+**The 5 analysis passes:**
+
+| Pass | What it does |
+|---|---|
+| **Pass 1 — Weighted signal tiers** | Tier 1: service names = 10pts each (e.g. `sfn-events`, `DeviceRepository`). Tier 2: tech constructs = 5pts (e.g. `NullPointerException`, `@Query`, `Flyway`). Tier 3: domain terms = 2-3pts. Tier 4: generic words = 1pt. |
+| **Pass 2 — Negation detection** | Scans each sentence. `"not a UI issue"` → frontend penalty. `"backend is fine"` → backend penalty. Each negated sentence subtracts 8pts from the relevant domain. |
+| **Pass 3 — Root-cause phrase extraction** | 25 backend patterns + 9 frontend patterns matched via regex. `"shows wrong count"` → +12 backend. `"data not saved"` → +12 backend. `"layout broken"` → +10 frontend. |
+| **Pass 4 — Bug disambiguation matrix** | For `task_type: bug`: data-correctness → +15 backend, exception/crash → +15 backend, auth/permission → +12 backend, CRUD failure → +12 backend, performance → +10 backend. |
+| **Pass 5 — Confidence gate** | `HIGH` only when dominant score ≥ 1.8× second-place **AND** at least one Tier 1/2 signal matched. Generic words alone cannot produce HIGH confidence. |
+
+**Output — `allowed_next_action`:**
+
+| Value | Meaning | What the AI does |
+|---|---|---|
+| `PROCEED` | `BACKEND_ONLY` HIGH confidence | Moves directly to Phase 0.7 plan presentation |
+| `CONFIRM` | Mixed / LOW / extension | Presents analysis report, waits for developer YES |
+| `STOP` | `FRONTEND_ONLY` | Hard stop — routes to frontend team, no code written |
+
+**Mixed signal resolution:** Backend dominates only when `backendScore ≥ 2.5× frontendScore`. Below that threshold → `FULL_STACK` (requires confirmation).
+
+**Persistence:** Result saved to `.secufusion/classifications/{work_item_id}.json`. Resuming a classified task skips re-classification and loads the prior result.
+
+**Example output for a bug:**
+```
+✅ BACKEND_ONLY (HIGH confidence)
+
+Weighted scores: Backend=47 | Frontend=3 | Extension=0
+Score ratio: 15.7x dominant
+Root-cause evidence: [BE+12] data correctness → backend query | [BE+12] persistence failure → backend
+Bug heuristic: data-correctness bug → +15 backend (API/DB likely source)
+Classification reason: Backend dominates (47 vs FE:3 EXT:0) — frontend signals are noise
+
+Proceeding to plan presentation. No developer confirmation needed.
+```
+
+---
+
+## What Changed — Strict Enforcement Update
+
+### `classify_task` — Deep analysis engine (replaces keyword counting)
+
+| Before | After |
+|---|---|
+| Flat keyword counting — every word scored equally | 4-tier weighted scoring — service names = 10× generic words |
+| `"dashboard"` → scored as frontend | Root-cause phrases — `"shows wrong count on dashboard"` → backend +12 |
+| No negation awareness | Sentence-level negation — `"not a UI issue"` removes frontend weight |
+| Bug heuristic: default to backend only on LOW confidence | 5-category bug disambiguation matrix (+12–15pts per category) |
+| HIGH confidence even on equal scores | HIGH only when ratio ≥ 1.8× AND Tier 1/2 signal matched |
+| Mixed signals → always FULL_STACK | Backend dominates at 2.5× → classified BACKEND_ONLY, frontend treated as noise |
+
+### `AGENTS.md` — All phases rewritten to strict enforcement
+
+| Phase | Before | After |
+|---|---|---|
+| **Phase 00** | Bullet list, no gate | MANDATORY 3-step sequence + ❌ prohibition list |
+| **Phase 0 (Resume)** | `"Call read_summary, begin executing"` | Explicit STEP 1/2/3 + ❌ list (no guessing, no re-reading) |
+| **Phase 0.7 (Plan Gate)** | `"Build a plan"`, soft suggestions | Every plan section is **mandatory** — omitting any = violation. Explicit proceed/adjust/cancel contract. |
+| **Phase 1 (Planning)** | `"Call search_tasks if relevant"` | `search_tasks` is **unconditional** — STEP 1 always, even if "sure" there's no prior work |
+| **Phase 2 (Execution)** | Bullet suggestions | MANDATORY code block for all 4 tool calls + `next_step` contract with explicit VIOLATION labels |
+| **Phase 3 (Correction)** | `"Immediately call log_rejected_pattern"` | Explicit STEP 1/2/3 + ❌ list — log immediately, not end of session |
+| **Phase 4 (PR Handoff)** | `"Call complete → run checks → fix if error"` | Explicit STEP 1-4 **fix → recheck loop** until ZERO errors |
+| **Guardrails** | Mixed soft/hard language | All `should` → `MUST`, all `avoid` → `FORBIDDEN`, linter errors explicitly blocking |
+| **Cross-Task Intelligence** | Prose bullets | MANDATORY STEP 1-4 sequence + ❌ list |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secufusion-mcp",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "type": "module",
   "description": "SecuFusion MCP server - developer workflow tooling with guardrails",
   "main": "index.js",