secufusion-mcp 1.0.10 → 1.0.12

package/README.md

@@ -1,6 +1,6 @@
 # SecuFusion MCP Server
 
-> **Developer workflow tooling for the SecuFusion platform** — enforces zero-trust architecture standards, tracks task specs, and gates PRs with automated guardrail checks.
+> **Project-level spec driven AI workflow tooling for the SecuFusion platform** — loads full project DNA at session start, enforces zero-trust architecture standards, tracks task specs, and gates PRs with automated guardrail checks.
 
 [![npm version](https://img.shields.io/npm/v/secufusion-mcp)](https://www.npmjs.com/package/secufusion-mcp)
 [![license](https://img.shields.io/npm/l/secufusion-mcp)](./LICENSE)
@@ -10,13 +10,58 @@
 
 ## 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 three 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 **eight powerful tools** to enforce SecuFusion's engineering standards throughout the development lifecycle:
 
 | Tool | Phase | What it does |
 |---|---|---|
-| `manage_branch_state` | Planning & Execution | Manages a `.secufusion-state.json` tracker tied to the active Git branch |
-| `log_rejected_pattern` | Course Correction | Records bad patterns to `.rejected-patterns.json` so they are never repeated |
-| `run_pre_pr_checks` | PR Handoff | Discovers modified microservices across the workspace and gates PRs via AST-level linters + structural checks |
+| `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 |
+| `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 |
+| `manage_branch_state` | Legacy — Branch State | Backward-compatible branch-scoped JSON state tracker (for tasks before `manage_task`) |
+| `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 |
+
+---
+
+## ⚡ The Shift: Problem-Statement Driven → Project-Level Spec Driven
+
+This is the biggest architectural upgrade to the SecuFusion MCP.
+
+### Before (problem-statement driven)
+The AI started every session **cold**. It had zero knowledge of the codebase and relied entirely on the developer feeding context through a work item description. Every session began with implicit questions:
+- *"Which port does sfn-iam-api run on?"*
+- *"How do you extract tenantId from the JWT?"*
+- *"What's the coding pattern for DTO mapping?"*
+
+The AI was **reactive** — it knew only what you told it about the current task.
+
+### After (project-level spec driven)
+The AI starts every session by reading `.secufusion-project-spec.json` — a single file containing the **entire project's DNA**:
+
+```
+✅ All microservice ports, repos, Eureka names, domains
+✅ Table ownership per service
+✅ Inter-service call graph
+✅ Kafka topics produced/consumed per service
+✅ Keycloak realm + client config per service
+✅ Coding patterns (DTO mapping, @Transactional style, tenant passing)
+✅ Golden rules (tenant isolation layers, authority rules, banned patterns)
+✅ Flyway migration state per service
+```
+
+The AI is now **proactively context-aware** — it knows your entire architecture before you say a single word about the task:
+
+| Before | After |
+|---|---|
+| You explain the service every session | AI already knows all services |
+| You describe the coding pattern | AI reads it from the spec |
+| AI asks which port to use | AI looks it up from the spec |
+| Context resets between sessions | Project knowledge is permanent |
+| Spec is task-scoped | Spec is project-scoped |
+
+> **One-time setup:** Generate `.secufusion-project-spec.json` once using the extraction prompt. From that point, every AI session starts fully informed.
 
 ---
 
@@ -246,6 +291,60 @@ The AI will call:
 
 ---
 
+### 4. `manage_project_spec`
+
+Loads and manages `.secufusion-project-spec.json` — the permanent project memory file. **Called automatically at the start of every session (Phase 00)** before any task begins.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `action` | enum | Yes | `read` \| `get_service` \| `get_golden_rules` \| `get_coding_patterns` \| `update` |
+| `service_name` | string | No | **(For `get_service`)** Name of the microservice, e.g. `sfn-events-api` |
+| `update_path` | string | No | **(For `update`)** Dot-notation path, e.g. `microservices.sfn-iam-api.port` |
+| `update_value` | any | No | **(For `update`)** New value to set at `update_path` |
+
+**Actions:**
+
+| Action | Returns | Token cost |
+|---|---|---|
+| `read` | Full spec (all services, all patterns, all rules) | High — use once at session start |
+| `get_service` | Only the block for the requested microservice | Low — use when focused on one service |
+| `get_golden_rules` | `golden_rules` block + `rejected_patterns` | Low — use before any architectural decision |
+| `get_coding_patterns` | `coding_patterns` block | Low — use before writing any new class |
+| `update` | Confirmation of surgical dot-notation write | Low — never overwrites the full file |
+
+**Example — Session start (reads full project context):**
+```json
+{ "action": "read" }
+```
+
+**Example — Focused lookup before writing a service:**
+```json
+{ "action": "get_service", "service_name": "sfn-iam-api" }
+```
+
+**Example — Check golden rules before an architectural decision:**
+```json
+{ "action": "get_golden_rules" }
+```
+
+**Example — Surgical port update (never overwrites the full file):**
+```json
+{
+  "action": "update",
+  "update_path": "microservices.sfn-iam-api.port",
+  "update_value": 9005
+}
+```
+
+**File location resolution order:**
+1. Same directory as `index.js`
+2. `process.cwd()`
+3. Walk up from `cwd` (up to 5 levels)
+
+---
+
 ## Guardrails Summary
 
 These rules are enforced automatically — the AI will never violate them:
@@ -259,38 +358,87 @@ These rules are enforced automatically — the AI will never violate them:
 ✅ Token Efficiency: Every tool response includes a 📊 Telemetry receipt tracking input/output tokens, cost, and the Session Total
 ```
 
+**Performance Guardrails** (enforced whenever writing queries, Kafka consumers, or cross-service calls):
+```
+✅ All GET service methods use @Transactional(readOnly = true)
+✅ No repository method called inside a for/forEach loop — batch with findAllById/saveAll
+✅ Every new query column that is filtered/sorted has a CREATE INDEX in the Flyway migration
+✅ Kafka listeners never do synchronous DB writes or REST calls — offload to @Async
+✅ Every RestTemplate/WebClient call has an explicit timeout and fallback
+```
+
+**Rollback Guardrails** (enforced on every Flyway migration, API contract change, Kafka schema change):
+```
+✅ SAFE migration (additive) — safe to roll back by reverting code
+⚠️  RISKY migration (NOT NULL without DEFAULT) — requires compensating migration
+🚫 DANGEROUS migration (DROP/RENAME) — requires explicit developer confirmation before writing
+✅ API hard cutover (removing /v1/ or a field) — requires confirmation; prefer /v2/ + deprecation first
+✅ Kafka schema change — coordinated deployment of producer + all consumers; flagged in rollback plan
+✅ Every manage_task initialize logs a rollback strategy starter entry in decisions.json
+```
+
+**Breaking Change Detection** (run as Step 4 in Phase 0.5 before any plan is written):
+```
+✅ Check 1: Endpoint consumers — who calls this endpoint? Flag if response shape changes
+✅ Check 2: Entity/table consumers — @Query annotations across all repos for this column
+✅ Check 3: Kafka topic consumers — coordinated deployment required if schema changes
+✅ Check 4: Chrome extension — silent breaks invisible until users report them
+✅ Over-flag > under-flag: always present a breaking change report if in doubt
+```
+
 ---
 
 ## File Outputs
 
-| File | Description |
-|---|---|
-| `.secufusion-state.json` | Living task blueprint — tracks pending/completed ACs per branch |
-| `.rejected-patterns.json` | Cumulative log of all rejected patterns across sessions |
-| `.secufusion-tokens.json` | Persistent tracking of session-wide LLM token usage and cost |
-
-> **Tip:** Commit `.secufusion-state.json` and `.rejected-patterns.json` to your repo. Do **not** commit `.secufusion-tokens.json`.
+| 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-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 |
+
+> **Tip:** Commit the entire `.secufusion/` folder and `.rejected-patterns.json` to your repo. Do **not** commit `.secufusion-tokens.json`.
 
 ---
 
 ## Workflow Overview
 
 ```
-┌─────────────────────────────────────────────────────┐
-│                 SecuFusion MCP Workflow              │
-├──────────────┬──────────────────────────────────────┤
-│  Phase 1     │  manage_branch_state (action=init)    │
-│  Planning    │  → Initializes .secufusion-state.json │
-├──────────────┼──────────────────────────────────────┤
-│  Phase 2     │  manage_branch_state (action=update)  │
-│  Execution   │  → Resolve ACs & define next_step     │
-├──────────────┼──────────────────────────────────────┤
-│  Phase 3     │  log_rejected_pattern                 │
-│  Correction  │  → Record mistakes to avoid repeat    │
-├──────────────┼──────────────────────────────────────┤
-│  Phase 4     │  run_pre_pr_checks                    │
-│  PR Handoff  │  → Must pass before raising PR        │
-└──────────────┴──────────────────────────────────────┘
+┌──────────────┬──────────────────────────────────────────────────────────────┐
+│  Phase 00    │  manage_project_spec (action=read)                            │
+│  Session     │  → Loads full project DNA from .secufusion-project-spec.json  │
+│  Start       │  → AI knows ALL services, ports, patterns, golden rules       │
+├──────────────┼──────────────────────────────────────────────────────────────┤
+│  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.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        │
+├──────────────┼──────────────────────────────────────────────────────────────┤
+│  Phase 2     │  manage_task: update_spec / log_file_touched /                │
+│  Execution   │              log_decision / add_scenario                       │
+├──────────────┼──────────────────────────────────────────────────────────────┤
+│  Phase 3     │  log_rejected_pattern                                          │
+│  Correction  │  → Record mistakes to avoid repeat                             │
+├──────────────┼──────────────────────────────────────────────────────────────┤
+│  Phase 4     │  manage_task (action=complete) → pr-summary.md generated      │
+│  PR Handoff  │  run_pre_pr_checks → must pass before raising PR              │
+└──────────────┴──────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -337,22 +485,38 @@ Add this to your MCP client config and restart. That's it.
 
 ### Step 2 — Start a new task (Planning phase)
 
-Just paste your Azure DevOps work item ID and description directly into the chat. No special syntax needed.
+Just paste your Azure DevOps work item ID and description directly into the chat. A good problem statement includes the raw user story and acceptance criteria. No special syntax needed.
 
 **You type:**
 ```
-WI-2847: Add MFA enforcement for admin users on login.
-Admin users must be forced through TOTP verification before
-accessing any dashboard route. Exempt service accounts.
+WI-2847: Add MFA enforcement for admin users on login
+
+**User Story:**
+As a security administrator,
+I want to enforce TOTP-based Multi-Factor Authentication (MFA) for all users with the ADMIN role,
+So that sensitive dashboard actions are protected against compromised credentials.
+
+**Acceptance Criteria:**
+1. Any user with the ADMIN role attempting to log in must be prompted for a TOTP token after password verification.
+2. The system must validate the TOTP token against the user's registered MFA device.
+3. Service accounts (role = SERVICE_ACCOUNT) are exempt from MFA, even if they possess admin privileges.
+4. If MFA fails 3 times, the account should be temporarily locked for 15 minutes.
 ```
 
-**The AI automatically calls `manage_branch_state` and creates/initializes `.secufusion-state.json`:**
+**The AI automatically classifies the task, presents a plan, and upon approval, calls `manage_task` to initialize `.secufusion/tasks/WI-2847/`:**
 ```json
 {
-  "task": "WI-2847: Add MFA enforcement",
-  "pending_acs": ["AC-1: Auth flow", "AC-2: Redirects", "AC-3: Exemptions"],
-  "completed_acs": [],
-  "next_step": "Implement MFA logic in AuthController"
+  "action": "initialize",
+  "work_item_id": "2847",
+  "title": "Add MFA enforcement for admin users on login",
+  "description": "Enforce TOTP-based MFA for ADMIN roles, exempting service accounts, with account lockout on 3 failed attempts.",
+  "acceptance_criteria": [
+    "Prompt ADMIN users for TOTP token post-password",
+    "Validate TOTP token",
+    "Exempt SERVICE_ACCOUNT role",
+    "Lock account for 15m after 3 failed attempts"
+  ],
+  "tags": ["security", "auth", "mfa"]
 }
 ```
 
@@ -379,17 +543,19 @@ I've finished the tenantId scoping on all queries and written the unit tests.
 Update the state.
 ```
 
-The AI calls `manage_branch_state` with `action=update` and the state updates:
+The AI calls `manage_task` with `action=update_spec` and the state updates:
 
 ```json
 {
-  "task": "WI-2847: Add MFA enforcement",
-  "pending_acs": ["AC-3: Exemptions"],
-  "completed_acs": ["Add tenantId scoping", "Add unit tests"],
-  "next_step": "Implement exemption logic for service accounts"
+  "action": "update_spec",
+  "work_item_id": "2847",
+  "pending_acs": ["Exempt SERVICE_ACCOUNT role", "Lock account for 15m after 3 failed attempts"],
+  "completed_acs": ["Prompt ADMIN users for TOTP token post-password", "Validate TOTP token"],
+  "next_step": "Implement exemption logic for service accounts in AuthController"
 }
 ```
 
+
 ---
 
 ### Step 5 — Course correction (if the AI does something wrong)
@@ -444,46 +610,42 @@ Scanned directory: C:\projects\secufusion-backend
 
 ---
 
-## How It Works (The 2 Layers)
-
-To prevent AI amnesia or generic bad habits across your projects, the SecuFusion MCP relies on structured branch-aware JSON and native AST tooling.
+## How It Works (The 3 Layers)
 
-## Phase 0 — Resume (TRIGGER: new session, switching branches, or user says "resume" or "continue")
-- Call `manage_branch_state` with `action: "read"`. The tool will automatically detect the current Git branch and return the structured JSON state for that specific branch. Do not re-read requirements; immediately begin executing the item explicitly listed in the `next_step` field.
+The SecuFusion MCP operates across three complementary layers to prevent AI amnesia, enforce architecture standards, and gate code quality:
 
-## Phase 1 — Planning (TRIGGER: user assigns a task or work item)
-- Call `manage_branch_state` with `action: "initialize"`. Pass the `task_description` and `reference_file_path`. The tool will generate a branch-bound JSON state file tracking the Acceptance Criteria (ACs) as a structured array of pending tasks, keyed to your active Git branch.
+**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.
 
-## Phase 2 — Execution (TRIGGER: as you complete ACs, or before ending a session/response)
-- Call `manage_branch_state` with `action: "update"`. Move completed items from `pending_acs` to `completed_acs`.
-- CRITICAL: You must explicitly write a clear, actionable instruction into the `next_step` parameter (e.g., "Implement browserUsage map in DeviceActivitySummaryDTO"). This ensures your future self can resume instantly without parsing the full spec.
+**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.
 
-## Phase 3 — Course Correction (TRIGGER: user corrects you or rejects an approach)
-- Immediately call `log_rejected_pattern`. Pass the bad `pattern` and the `reason`. Always check `.rejected-patterns.json` implicitly before suggesting architectural choices.
-
-## Phase 4 — PR Handoff (TRIGGER: user says "prepare PR" or "run checks")
-- Call `run_pre_pr_checks` with the Azure DevOps `workItemId`. The tool checks the structured branch state to ensure `pending_acs` is empty, then discovers modified microservices to run native linters, Flyway checks, and the Tenant-Isolation scanner.
-- If an error is thrown, YOU MUST navigate to that microservice, FIX THE ERROR natively, and rerun until the workspace passes.
-
-## Guardrails (enforce always, no exceptions)
-- TENANT SAFETY IS AUTOMATED: The PR Gatekeeper actively scans all `*Repository.java` files. If you write a database query (derived method or `@Query`) that does not explicitly filter by `tenantId` or contain the word `tenant`, the PR will be blocked. Write secure, tenant-isolated queries on your first attempt.
-- Do not ignore linter errors. AST-level tools (ESLint, Checkstyle/Maven) are the source of truth for hygiene. Fix them natively.
-- Never hardcode UAT/Prod IPs or URLs. Use environment variables or configuration properties.
-- If you modify a JPA `@Entity` in any backend repo, you MUST create the corresponding Flyway `.sql` migration script before running PR checks.
-```
+**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`.
 
 ### How it all wires together
 
 ```
-mcp_config.json       →  starts the server (tools available)
+mcp_config.json                →  starts the server (8 tools available)
       +
-.agents/AGENTS.md     →  tells AI when to invoke each tool (the invoker)
+.agents/AGENTS.md              →  tells AI when to invoke each tool
+      ↓
+★ SESSION STARTS
+      ↓
+Phase 00: manage_project_spec  →  AI loads full project DNA
+      ↓
+Phase 0:  manage_task read_summary  →  resumes active work item
       ↓
 You say: "WI-1042: Add audit log export"
       ↓
-AI reads AGENTS.md → Phase 1 triggered → calls manage_branch_state
+Phase 0.5: classify BACKEND_ONLY/FRONTEND_ONLY/FULL_STACK
+          + performance risk scan + breaking change scan
+      ↓
+Phase 0.7: plan presented → developer approves ("proceed")
+      ↓
+Phase 1: manage_task initialize  →  .secufusion/tasks/WI-1042/ created
+      ↓
+Phase 2: code + log_file_touched + log_decision + add_scenario
       ↓
-.secufusion-state.json initialized for your Git branch
+Phase 4: manage_task complete  →  pr-summary.md generated
+       + run_pre_pr_checks     →  must pass before raising PR
 ```
 
 ### Reusing across projects
@@ -502,9 +664,9 @@ mcp_config.json       ← global, never changes
 
 ---
 
-## Talking to the AI — 5 Things You'll Ever Say
+## Talking to the AI — What You'll Ever Say
 
-Once both layers are in place, you interact completely naturally:
+Once all three layers are in place, you interact completely naturally:
 
 | Situation | What you say |
 |---|---|
@@ -513,10 +675,20 @@ Once both layers are in place, you interact completely naturally:
 | ❌ AI did something wrong | `Don't do X, do Y instead` |
 | 🚀 Ready for PR | `Run checks for WI-XXXX` or `Prepare PR` |
 | 🔄 Resuming after a break | `What's left?` or `Resume the current task` |
+| 🔍 Starting similar work | `Has this been done before?` — AI calls `search_tasks` |
+| 📋 Want the full plan first | AI automatically presents plan in Phase 0.7 — type `proceed` to start |
+
+**Before `manage_project_spec`:** The AI started cold every session. You explained ports, coding patterns, and tenantId flow every single time.
+
+**After `manage_project_spec`:** The AI reads `.secufusion-project-spec.json` at session start and **already knows your entire architecture**. You just describe the work.
+
+**Before `manage_task`:** The AI used a flat branch-state file with no cross-task memory.
+
+**After `manage_task`:** Every work item has its own structured folder. The AI tracks decisions, files, and scenarios per task. `search_tasks` finds related past work. `get_pattern_from_task` reuses proven approaches.
 
-**Before `AGENTS.md`:** You had to remember which tool to invoke and when.
+**Before Phase 0.5 + 0.7:** The AI started coding immediately with no ownership check or explicit plan.
 
-**After `AGENTS.md`:** You just describe work. The AI follows the 5-phase workflow automatically — no commands, no syntax, no manual tool calls.
+**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**.
 
 ---
 

package/index.js

@@ -677,6 +677,392 @@ server.tool("run_pre_pr_checks", "Run all SecuFusion pre-PR guardrail checks acr
         isError: hasErrors,
     }, inputChars);
 });
+// ─── Tool 4: manage_project_spec ─────────────────────────────────────────────
+server.tool("manage_project_spec", "Manages the .secufusion-project-spec.json file — the permanent project memory containing all service ports, repos, domains, infrastructure config, coding patterns, auth flow, and golden rules. Every session must read this before writing any code.", {
+    action: z
+        .enum(["read", "update", "get_service", "get_golden_rules", "get_coding_patterns"])
+        .describe("Action to perform: read (full spec), get_service (one microservice block), get_golden_rules (golden_rules + rejected_patterns), get_coding_patterns (coding_patterns block), update (surgical dot-notation write)."),
+    service_name: z
+        .string()
+        .optional()
+        .describe("Only for action=get_service. Name of the microservice to fetch, e.g. 'sfn-events-api'."),
+    update_path: z
+        .string()
+        .optional()
+        .describe("Only for action=update. Dot-notation path to the value to set, e.g. 'microservices.sfn-iam-api.port'."),
+    update_value: z
+        .any()
+        .optional()
+        .describe("Only for action=update. The new value to set at update_path."),
+}, async ({ action, service_name, update_path, update_value }) => {
+    const inputChars = JSON.stringify({ action, service_name, update_path, update_value }).length;
+    // ── Locate .secufusion-project-spec.json (3 candidate locations) ─────────
+    const SPEC_FILE = ".secufusion-project-spec.json";
+    const candidates = [];
+    // 1. Same directory as index.ts/index.js
+    candidates.push(path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")), SPEC_FILE));
+    // 2. process.cwd()
+    candidates.push(path.resolve(process.cwd(), SPEC_FILE));
+    // 3. Walk up from cwd until found (up to 5 levels)
+    let walkDir = process.cwd();
+    for (let i = 0; i < 5; i++) {
+        const parent = path.dirname(walkDir);
+        if (parent === walkDir)
+            break;
+        walkDir = parent;
+        candidates.push(path.join(walkDir, SPEC_FILE));
+    }
+    const specPath = candidates.find((p) => fs.existsSync(p)) ?? null;
+    if (!specPath) {
+        return appendTelemetry({
+            isError: true,
+            content: [{ type: "text", text: `Project spec not found. Run extraction prompt first.\n\nSearched:\n${candidates.map((p) => `  • ${p}`).join("\n")}` }],
+        }, inputChars);
+    }
+    // ── Parse spec ────────────────────────────────────────────────────────────
+    const raw = readFileSafe(specPath);
+    if (!raw) {
+        return appendTelemetry({
+            isError: true,
+            content: [{ type: "text", text: `Failed to read project spec at: ${specPath}` }],
+        }, inputChars);
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch (e) {
+        return appendTelemetry({
+            isError: true,
+            content: [{ type: "text", text: `Invalid JSON in project spec at: ${specPath}\n\nParse error: ${e.message}` }],
+        }, inputChars);
+    }
+    // ── action: read ──────────────────────────────────────────────────────────
+    if (action === "read") {
+        return appendTelemetry({
+            content: [{ type: "text", text: JSON.stringify(spec, null, 2) }],
+        }, inputChars);
+    }
+    // ── action: get_service ───────────────────────────────────────────────────
+    if (action === "get_service") {
+        if (!service_name) {
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: "ERROR: 'service_name' is required when action=get_service." }],
+            }, inputChars);
+        }
+        const microservices = spec.microservices;
+        const serviceBlock = microservices?.[service_name];
+        if (!serviceBlock) {
+            const available = microservices ? Object.keys(microservices).join(", ") : "none";
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: `Service '${service_name}' not found in spec.\n\nAvailable services: ${available}` }],
+            }, inputChars);
+        }
+        return appendTelemetry({
+            content: [{ type: "text", text: JSON.stringify({ [service_name]: serviceBlock }, null, 2) }],
+        }, inputChars);
+    }
+    // ── action: get_golden_rules ──────────────────────────────────────────────
+    if (action === "get_golden_rules") {
+        const goldenRules = spec.golden_rules;
+        const block = {
+            golden_rules: goldenRules ?? {},
+            rejected_patterns: goldenRules?.rejected_patterns ?? [],
+        };
+        return appendTelemetry({
+            content: [{ type: "text", text: JSON.stringify(block, null, 2) }],
+        }, inputChars);
+    }
+    // ── action: get_coding_patterns ───────────────────────────────────────────
+    if (action === "get_coding_patterns") {
+        const block = spec.coding_patterns ?? {};
+        return appendTelemetry({
+            content: [{ type: "text", text: JSON.stringify(block, null, 2) }],
+        }, inputChars);
+    }
+    // ── action: update ────────────────────────────────────────────────────────
+    if (action === "update") {
+        if (!update_path) {
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: "ERROR: 'update_path' is required when action=update." }],
+            }, inputChars);
+        }
+        if (update_value === undefined) {
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: "ERROR: 'update_value' is required when action=update." }],
+            }, inputChars);
+        }
+        // Deep set via dot-notation path
+        const keys = update_path.split(".");
+        let cursor = spec;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const val = cursor[keys[i]];
+            if (val === undefined || val === null || typeof val !== "object") {
+                return appendTelemetry({
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: Invalid update_path — '${keys.slice(0, i + 1).join(".")}' does not exist or is not an object.\n\nAttempted path: ${update_path}` }],
+                }, inputChars);
+            }
+            cursor = val;
+        }
+        const finalKey = keys[keys.length - 1];
+        const oldValue = cursor[finalKey];
+        cursor[finalKey] = update_value;
+        writeFile(specPath, JSON.stringify(spec, null, 2));
+        return appendTelemetry({
+            content: [{
+                    type: "text",
+                    text: `✅ Project spec updated.\n\n**Path:** ${update_path}\n**Old value:** ${JSON.stringify(oldValue)}\n**New value:** ${JSON.stringify(update_value)}\n**File:** ${specPath}`,
+                }],
+        }, inputChars);
+    }
+    return appendTelemetry({ content: [{ type: "text", text: "Invalid action." }] }, inputChars);
+});
+// ─── Task management helpers ──────────────────────────────────────────────────
+const TASKS_DIR = ".secufusion/tasks";
+const REGISTRY_FILE = ".secufusion/registry.json";
+function taskDir(workItemId) {
+    return resolve(`${TASKS_DIR}/WI-${workItemId}`);
+}
+function readJson(filePath) {
+    const raw = readFileSafe(filePath);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function readRegistry() {
+    return readJson(resolve(REGISTRY_FILE)) || [];
+}
+function writeRegistry(records) {
+    writeFile(resolve(REGISTRY_FILE), JSON.stringify(records, null, 2));
+}
+function upsertRegistry(entry) {
+    const records = readRegistry();
+    const idx = records.findIndex(r => r["work_item_id"] === entry["work_item_id"]);
+    if (idx === -1)
+        records.push(entry);
+    else
+        records[idx] = { ...records[idx], ...entry };
+    writeRegistry(records);
+}
+// ─── Tool 5: manage_task ─────────────────────────────────────────────────────
+server.tool("manage_task", "Manages structured task records in .secufusion/tasks/WI-{id}/. Each task gets its own folder with spec, progress, decisions, files-touched, and scenarios files. Use this instead of manage_branch_state for all new work items.", {
+    action: z
+        .enum(["initialize", "read", "update_spec", "add_scenario", "log_file_touched", "log_decision", "complete", "read_summary"])
+        .describe("Action: initialize (create task folder + files), read (full task data), update_spec (edit spec fields), add_scenario (append test scenario), log_file_touched (record modified file), log_decision (record architectural decision), complete (mark done + generate PR summary), read_summary (token-efficient summary)."),
+    work_item_id: z.string().describe("Azure DevOps work item ID, e.g. '2847'. Used to name the task folder WI-{id}."),
+    title: z.string().optional().describe("Task title. Required for 'initialize'."),
+    description: z.string().optional().describe("Task description. Used with 'initialize' or 'update_spec'."),
+    acceptance_criteria: z.array(z.string()).optional().describe("Array of AC strings. Used with 'initialize' or 'update_spec'."),
+    pending_acs: z.array(z.string()).optional().describe("Pending AC list. Used with 'update_spec'."),
+    completed_acs: z.array(z.string()).optional().describe("Completed AC list. Used with 'update_spec'."),
+    next_step: z.string().optional().describe("Next actionable step. Required for 'update_spec'."),
+    tags: z.array(z.string()).optional().describe("Tags for searchability, e.g. ['tenant', 'iam', 'security']."),
+    file_path: z.string().optional().describe("File path to log. Used with 'log_file_touched'."),
+    change_summary: z.string().optional().describe("One-line summary of the change. Used with 'log_file_touched'."),
+    decision: z.string().optional().describe("Architectural decision to record. Used with 'log_decision'."),
+    rationale: z.string().optional().describe("Why this decision was made. Used with 'log_decision'."),
+    scenario: z.string().optional().describe("Test scenario description. Used with 'add_scenario'."),
+    scenario_type: z.enum(["unit", "integration", "e2e", "manual"]).optional().describe("Test scenario type. Used with 'add_scenario'."),
+}, async ({ action, work_item_id, title, description, acceptance_criteria, pending_acs, completed_acs, next_step, tags, file_path, change_summary, decision, rationale, scenario, scenario_type }) => {
+    const inputChars = JSON.stringify({ action, work_item_id, title, description, acceptance_criteria, pending_acs, completed_acs, next_step, tags, file_path, change_summary, decision, rationale, scenario, scenario_type }).length;
+    const dir = taskDir(work_item_id);
+    const specPath = path.join(dir, "spec.json");
+    const progressPath = path.join(dir, "progress.json");
+    const decisionsPath = path.join(dir, "decisions.json");
+    const filesPath = path.join(dir, "files-touched.json");
+    const scenariosPath = path.join(dir, "scenarios.json");
+    const prSummaryPath = path.join(dir, "pr-summary.md");
+    if (action === "initialize") {
+        if (!title)
+            return appendTelemetry({ isError: true, content: [{ type: "text", text: "ERROR: 'title' is required for action=initialize." }] }, inputChars);
+        const now = new Date().toISOString();
+        const spec = { work_item_id, title, description: description || "", acceptance_criteria: acceptance_criteria || [], tags: tags || [], created_at: now, status: "active" };
+        const progress = { pending_acs: acceptance_criteria || [], completed_acs: [], next_step: "Review spec and begin implementation.", last_updated: now };
+        if (!fs.existsSync(specPath)) {
+            writeFile(specPath, JSON.stringify(spec, null, 2));
+            writeFile(progressPath, JSON.stringify(progress, null, 2));
+            writeFile(decisionsPath, JSON.stringify([], null, 2));
+            writeFile(filesPath, JSON.stringify([], null, 2));
+            writeFile(scenariosPath, JSON.stringify([], null, 2));
+        }
+        upsertRegistry({ work_item_id, title, status: "active", created_at: now, tags: tags || [] });
+        return appendTelemetry({ content: [{ type: "text", text: `✅ Task WI-${work_item_id} initialized.\n\n**Folder:** ${dir}\n**Title:** ${title}\n**ACs:** ${(acceptance_criteria || []).length}\n\n${JSON.stringify(spec, null, 2)}` }] }, inputChars);
+    }
+    if (!fs.existsSync(specPath)) {
+        return appendTelemetry({ isError: true, content: [{ type: "text", text: `ERROR: Task WI-${work_item_id} not found. Call action=initialize first.\n\nExpected folder: ${dir}` }] }, inputChars);
+    }
+    if (action === "read") {
+        const full = { spec: readJson(specPath), progress: readJson(progressPath), decisions: readJson(decisionsPath), files_touched: readJson(filesPath), scenarios: readJson(scenariosPath) };
+        return appendTelemetry({ content: [{ type: "text", text: JSON.stringify(full, null, 2) }] }, inputChars);
+    }
+    if (action === "read_summary") {
+        const spec = readJson(specPath) || {};
+        const progress = readJson(progressPath) || {};
+        const files = readJson(filesPath) || [];
+        const summary = { work_item_id, title: spec["title"], status: spec["status"], pending_acs: progress["pending_acs"] || [], completed_acs: progress["completed_acs"] || [], next_step: progress["next_step"], files_touched_count: files.length };
+        return appendTelemetry({ content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] }, inputChars);
+    }
+    if (action === "update_spec") {
+        if (!next_step)
+            return appendTelemetry({ isError: true, content: [{ type: "text", text: "ERROR: 'next_step' is required for action=update_spec." }] }, inputChars);
+        const now = new Date().toISOString();
+        if (description !== undefined || acceptance_criteria !== undefined || tags !== undefined) {
+            const spec = readJson(specPath) || {};
+            if (description !== undefined)
+                spec["description"] = description;
+            if (acceptance_criteria !== undefined)
+                spec["acceptance_criteria"] = acceptance_criteria;
+            if (tags !== undefined)
+                spec["tags"] = tags;
+            writeFile(specPath, JSON.stringify(spec, null, 2));
+        }
+        const progress = readJson(progressPath) || {};
+        if (pending_acs !== undefined)
+            progress["pending_acs"] = pending_acs;
+        if (completed_acs !== undefined)
+            progress["completed_acs"] = completed_acs;
+        progress["next_step"] = next_step;
+        progress["last_updated"] = now;
+        writeFile(progressPath, JSON.stringify(progress, null, 2));
+        return appendTelemetry({ content: [{ type: "text", text: `✅ Task WI-${work_item_id} updated.\n\n> **Next step:** ${next_step}\n\n**Progress:**\n${JSON.stringify(progress, null, 2)}` }] }, inputChars);
+    }
+    if (action === "log_file_touched") {
+        if (!file_path)
+            return appendTelemetry({ isError: true, content: [{ type: "text", text: "ERROR: 'file_path' is required for action=log_file_touched." }] }, inputChars);
+        const files = readJson(filesPath) || [];
+        const existing = files.findIndex((f) => f["file_path"] === file_path);
+        const entry = { file_path, change_summary: change_summary || "", logged_at: new Date().toISOString() };
+        if (existing === -1)
+            files.push(entry);
+        else
+            files[existing] = entry;
+        writeFile(filesPath, JSON.stringify(files, null, 2));
+        return appendTelemetry({ content: [{ type: "text", text: `✅ File logged for WI-${work_item_id}:\n\`${file_path}\` — ${change_summary || "(no summary)"}` }] }, inputChars);
+    }
+    if (action === "log_decision") {
+        if (!decision)
+            return appendTelemetry({ isError: true, content: [{ type: "text", text: "ERROR: 'decision' is required for action=log_decision." }] }, inputChars);
+        const decisions = readJson(decisionsPath) || [];
+        decisions.push({ id: decisions.length + 1, decision, rationale: rationale || "", logged_at: new Date().toISOString() });
+        writeFile(decisionsPath, JSON.stringify(decisions, null, 2));
+        return appendTelemetry({ content: [{ type: "text", text: `✅ Decision #${decisions.length} logged for WI-${work_item_id}:\n**Decision:** ${decision}\n**Rationale:** ${rationale || "(none)"}` }] }, inputChars);
+    }
+    if (action === "add_scenario") {
+        if (!scenario)
+            return appendTelemetry({ isError: true, content: [{ type: "text", text: "ERROR: 'scenario' is required for action=add_scenario." }] }, inputChars);
+        const scenarios = readJson(scenariosPath) || [];
+        scenarios.push({ id: scenarios.length + 1, type: scenario_type || "manual", scenario, added_at: new Date().toISOString() });
+        writeFile(scenariosPath, JSON.stringify(scenarios, null, 2));
+        return appendTelemetry({ content: [{ type: "text", text: `✅ Scenario #${scenarios.length} added to WI-${work_item_id}:\n[${scenario_type || "manual"}] ${scenario}` }] }, inputChars);
+    }
+    if (action === "complete") {
+        const spec = readJson(specPath) || {};
+        const progress = readJson(progressPath) || {};
+        const decisions = readJson(decisionsPath) || [];
+        const files = readJson(filesPath) || [];
+        const scenarios = readJson(scenariosPath) || [];
+        spec["status"] = "complete";
+        writeFile(specPath, JSON.stringify(spec, null, 2));
+        progress["completed_at"] = new Date().toISOString();
+        writeFile(progressPath, JSON.stringify(progress, null, 2));
+        upsertRegistry({ work_item_id, status: "complete" });
+        const prSummary = [
+            `# PR Summary — WI-${work_item_id}: ${spec["title"] || ""}`,
+            ``, `**Status:** Complete  `, `**Completed:** ${progress["completed_at"]}`, ``,
+            `## Acceptance Criteria`,
+            ...(progress["completed_acs"] || []).map(ac => `- ✅ ${ac}`),
+            ...((progress["pending_acs"] || []).length > 0 ? (progress["pending_acs"] || []).map(ac => `- ⚠️ ${ac}`) : []),
+            ``, `## Files Modified (${files.length})`,
+            ...files.map(f => `- \`${f["file_path"]}\`${f["change_summary"] ? ` — ${f["change_summary"]}` : ""}`),
+            ``, `## Architectural Decisions`,
+            ...decisions.map(d => `- **${d["decision"]}**${d["rationale"] ? `: ${d["rationale"]}` : ""}`),
+            ``, `## Test Scenarios (${scenarios.length})`,
+            ...scenarios.map(s => `- [${s["type"]}] ${s["scenario"]}`),
+        ].join("\n");
+        writeFile(prSummaryPath, prSummary);
+        return appendTelemetry({ content: [{ type: "text", text: `✅ Task WI-${work_item_id} marked complete.\n\n**PR summary generated:** ${prSummaryPath}\n\n${prSummary}` }] }, inputChars);
+    }
+    return appendTelemetry({ content: [{ type: "text", text: "Invalid action." }] }, inputChars);
+});
+// ─── Tool 6: get_task_history ─────────────────────────────────────────────────
+server.tool("get_task_history", "Retrieve the full history of a past task — spec, decisions, files touched, and scenarios. Use before starting similar work to understand how it was done before.", { work_item_id: z.string().describe("Work item ID of the past task to retrieve.") }, async ({ work_item_id }) => {
+    const inputChars = JSON.stringify({ work_item_id }).length;
+    const dir = taskDir(work_item_id);
+    if (!fs.existsSync(dir)) {
+        return appendTelemetry({ isError: true, content: [{ type: "text", text: `Task WI-${work_item_id} not found in ${resolve(TASKS_DIR)}.` }] }, inputChars);
+    }
+    const history = {
+        spec: readJson(path.join(dir, "spec.json")),
+        progress: readJson(path.join(dir, "progress.json")),
+        decisions: readJson(path.join(dir, "decisions.json")),
+        files_touched: readJson(path.join(dir, "files-touched.json")),
+        scenarios: readJson(path.join(dir, "scenarios.json")),
+    };
+    return appendTelemetry({ content: [{ type: "text", text: JSON.stringify(history, null, 2) }] }, inputChars);
+});
+// ─── Tool 7: search_tasks ─────────────────────────────────────────────────────
+server.tool("search_tasks", "Search all past tasks by keyword. Scans registry and task file contents. Use before starting a new task to find related past work and avoid re-solving solved problems.", {
+    keywords: z.string().describe("Space-separated search keywords, e.g. 'tenant isolation repository'."),
+    status_filter: z.enum(["active", "complete", "any"]).optional().default("any").describe("Filter results by task status."),
+}, async ({ keywords, status_filter = "any" }) => {
+    const inputChars = JSON.stringify({ keywords, status_filter }).length;
+    const registry = readRegistry();
+    if (registry.length === 0)
+        return appendTelemetry({ content: [{ type: "text", text: "No tasks found in registry. Initialize tasks first." }] }, inputChars);
+    const terms = keywords.toLowerCase().split(/\s+/).filter(Boolean);
+    const matches = [];
+    for (const entry of registry) {
+        if (status_filter !== "any" && entry["status"] !== status_filter)
+            continue;
+        const dir = taskDir(entry["work_item_id"]);
+        const blobs = [
+            JSON.stringify(entry),
+            readFileSafe(path.join(dir, "spec.json")) || "",
+            readFileSafe(path.join(dir, "progress.json")) || "",
+            readFileSafe(path.join(dir, "decisions.json")) || "",
+            readFileSafe(path.join(dir, "files-touched.json")) || "",
+            readFileSafe(path.join(dir, "scenarios.json")) || "",
+        ].join(" ").toLowerCase();
+        const hitCount = terms.filter(t => blobs.includes(t)).length;
+        if (hitCount > 0) {
+            const spec = readJson(path.join(dir, "spec.json")) || {};
+            matches.push({ work_item_id: entry["work_item_id"], title: entry["title"], status: entry["status"], tags: entry["tags"] || [], keyword_hits: hitCount, description_excerpt: (spec["description"] || "").slice(0, 120) });
+        }
+    }
+    matches.sort((a, b) => b["keyword_hits"] - a["keyword_hits"]);
+    if (matches.length === 0)
+        return appendTelemetry({ content: [{ type: "text", text: `No tasks matched keywords: "${keywords}"` }] }, inputChars);
+    return appendTelemetry({ content: [{ type: "text", text: `Found ${matches.length} task(s) matching "${keywords}":\n\n${JSON.stringify(matches, null, 2)}` }] }, inputChars);
+});
+// ─── Tool 8: get_pattern_from_task ────────────────────────────────────────────
+server.tool("get_pattern_from_task", "Extract reusable implementation patterns from a completed task — decisions made, files modified, and test scenarios used. Call this before implementing something similar to a past feature.", { work_item_id: z.string().describe("Work item ID of the past task to extract patterns from.") }, async ({ work_item_id }) => {
+    const inputChars = JSON.stringify({ work_item_id }).length;
+    const dir = taskDir(work_item_id);
+    if (!fs.existsSync(dir))
+        return appendTelemetry({ isError: true, content: [{ type: "text", text: `Task WI-${work_item_id} not found. Cannot extract patterns.` }] }, inputChars);
+    const spec = readJson(path.join(dir, "spec.json")) || {};
+    const decisions = readJson(path.join(dir, "decisions.json")) || [];
+    const files = readJson(path.join(dir, "files-touched.json")) || [];
+    const scenarios = readJson(path.join(dir, "scenarios.json")) || [];
+    const patterns = {
+        source_task: { work_item_id, title: spec["title"], status: spec["status"] },
+        architectural_decisions: decisions.map(d => ({ decision: d["decision"], rationale: d["rationale"] })),
+        files_pattern: files.map(f => f["file_path"]),
+        test_patterns: scenarios.map(s => ({ type: s["type"], scenario: s["scenario"] })),
+        tags: spec["tags"] || [],
+    };
+    return appendTelemetry({ content: [{ type: "text", text: `**Patterns from WI-${work_item_id}: ${spec["title"] || ""}**\n\n${JSON.stringify(patterns, null, 2)}` }] }, inputChars);
+});
 // ─────────────────────────────────────────────
 //  Start transport
 // ─────────────────────────────────────────────

package/package.json

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