secufusion-mcp 2.0.0 → 2.1.0

package/README.md

@@ -838,12 +838,159 @@ Proceeding to plan presentation. No developer confirmation needed.
 | **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 |
 
+
+---
+
+## 🏗️ v2.0.0 — Native Claude Plugin Architecture
+
+`secufusion-mcp@2.0.0` is a **complete architectural rebuild** of the MCP server into a native Claude Plugin. It unifies the MCP server, slash commands, personas, and hooks into a single self-contained, portable package following the enterprise-grade `ml-specs` plugin standard.
+
+### What Changed
+
+| Area | Before (≤ 1.2.8) | After (2.0.0) |
+|---|---|---|
+| **Plugin type** | Standalone MCP server only | Native Claude Plugin (`.claude-plugin/plugin.json` + `.mcp.json`) |
+| **Slash commands** | Disconnected — no wiring to server | Natively registered — appear in Claude IDE `/` command menu |
+| **Agent personas** | Scattered globally in `.agents/` | Self-contained inside `agents/` within the plugin package |
+| **Path portability** | Hardcoded absolute paths | Fully portable via `${CLAUDE_PLUGIN_ROOT}` |
+| **DNA plugin** | Separate `secufusion-dna-plugin` package | Fully merged into `secufusion-mcp` |
+| **TypeScript build** | Root-level compile | Isolated in `mcp/src/` → compiles to `mcp/dist/` |
+| **Repo validation** | Not present | Reads `.secufusion-project-spec.json` to verify all mandatory repos are cloned |
+| **Frontend/ext validation** | Not present | Checks `frontend.repo` and `chrome_extension.repo` from project spec |
+
+### New Package Structure
+
+```
+secufusion-mcp/
+├── .claude-plugin/
+│   └── plugin.json          ← Claude registers this as a native plugin
+├── .mcp.json                ← MCP server wired into the plugin (${CLAUDE_PLUGIN_ROOT} relative)
+├── agents/                  ← All agent personas (planner, coder, reviewer, claude, AGENTS.md)
+├── commands/                ← All slash command definitions (markdown)
+├── hooks/                   ← Lifecycle hooks (knowledge-drift.sh)
+├── mcp/
+│   ├── src/
+│   │   ├── server.ts        ← Main MCP server logic
+│   │   └── parsers/         ← Polyglot AST parsers (Java, TS, React, Config, Infra...)
+│   ├── dist/                ← Compiled output (what npm ships)
+│   └── tsconfig.json        ← Isolated TypeScript config
+├── scripts/
+│   ├── sfn-pr-check.js      ← Pre-PR mechanical guardrail runner
+│   └── utils.js
+└── package.json
+```
+
+### Merged: SecuFusion DNA Plugin
+
+The previously separate `secufusion-dna-plugin` is now fully merged into `secufusion-mcp`. There is no longer a need to install or configure it separately. All DNA discovery tools are available natively:
+
+- `scan_repository_stack` — discovers framework/stack and validates repos vs project spec
+- `extract_domain_models` — maps JPA entities and domain objects via AST
+- `extract_api_endpoints` — maps REST/GraphQL endpoints across all services
+- `extract_event_topics` — maps Kafka producers and consumers
+- `start_dna_watcher` — starts continuous background file watcher
+
+### Mandatory Repository Validation
+
+During `scan_repository_stack`, the server reads `.secufusion-project-spec.json` and cross-references:
+- All keys under `"microservices"` (e.g., `sfn-auth-api`, `sfn-events-api`)
+- The `"frontend.repo"` value (e.g., `sfn-web-ui`)
+- The `"chrome_extension.repo"` value (e.g., `snf-browser-extn`)
+
+If any of these are physically missing from your local workspace folder, a `[WARNING]` is emitted listing exactly which repositories need to be cloned before a complete DNA map can be built.
+
+---
+
+## ⚡ End-to-End Slash Command Workflow
+
+Once installed as a native Claude Plugin, all commands appear natively in the Claude IDE `/` command picker. Here is the complete daily workflow:
+
+### 🔁 Day Start — Setup & Discovery
+
+| Command | When to run | What it does |
+|---|---|---|
+| `/sfn-init` | First thing in the morning, or on a new machine | Scans your entire workspace, validates all mandatory repos are cloned against `.secufusion-project-spec.json`, parses AST across all services (Java, TypeScript, React), and builds `.secufusion/dna.json` — the living knowledge graph |
+| `/watch-dna` | Right after `/sfn-init` | Starts the `chokidar` background file watcher. From this point, every file save automatically re-triggers the relevant AST parser and keeps `dna.json` fresh — no manual re-runs needed |
+
+> **Mono-folder rule:** Keep all microservices, frontend, and extension repos inside one parent folder (e.g., `C:\Users\Yash\Desktop\secufi_full\`). The agent uses the parent folder as the ecosystem root and scans all siblings automatically.
+
+---
+
+### 📋 Phase 1 — Plan a Ticket
+
+| Command | When to run | What it does |
+|---|---|---|
+| `/sfn-plan <ticket-id or description>` | When you receive a new Azure DevOps ticket | Agent enters the `planner.md` persona. Reads `.secufusion-project-spec.json` for golden rules and coding patterns. Reads `dna.json` to determine which microservice owns the change. Outputs a structured `plan.md` with exact files to touch, rollback strategy, and breaking change scan. **Stops and waits for your green light.** |
+
+> **Why it stops:** This enforces the non-negotiable Rule 3 — `STRICT YIELD`. The agent must not start coding until you explicitly say "proceed".
+
+**Example:**
+```
+/sfn-plan TASK-2847: Add MFA enforcement for admin users on login
+```
+
+---
+
+### 🛠️ Phase 2 — Build the Feature
+
+| Command | When to run | What it does |
+|---|---|---|
+| `/sfn-code` | After you approve the plan | Agent switches to the `coder.md` persona and begins implementing **strictly according to the approved plan**. Enforces all coding patterns (correct `@Transactional` style, Tenant ID scoping, DTO mapping, Lombok style, exception handling). Every architectural mistake is immediately logged to `.rejected-patterns.json`. |
+
+---
+
+### ✅ Phase 3 — Review & Gate
+
+| Command | When to run | What it does |
+|---|---|---|
+| `/sfn-review` | After coding is done, before opening a PR | Agent enters the adversarial `reviewer.md` persona. Triggers `run_pre_pr_checks` — a 3-tier AST-level gate: (1) Mechanical guardrails (tenant isolation, N+1 queries, hardcoded URLs), (2) AI file-by-file code review, (3) Context-aware task evaluation against your spec. **Blocks the PR if Tier 1 violations are found.** |
+
+---
+
+### 🔍 Phase 4 — Architecture Discovery
+
+These commands can be run at any time to explore your codebase, independent of any active task.
+
+| Command | When to run | What it does |
+|---|---|---|
+| `/blast-radius <component>` | Before refactoring a shared entity, API, or Kafka topic | Reads `dna.json` and calculates exactly which services, endpoints, and consumers will break if the given component is changed. Prevents accidental breaking changes. |
+| `/map-architecture` | When onboarding a new dev or auditing the ecosystem | Generates a comprehensive bird's-eye view of all your services, domains, inter-service call graph, and Kafka topics sourced directly from the DNA graph. |
+| `/analyze` | When debugging a cross-service issue or doing a deep-dive on a subsystem | Performs a deep-dive AST analysis of a specific area, generating detailed dependency and data-flow maps. |
+
+---
+
+### 📊 The Full SDLC Flow at a Glance
+
+```
+Morning
+  ↓
+/sfn-init          ← Validate all repos, build DNA knowledge graph
+  ↓
+/watch-dna         ← Background watcher keeps DNA fresh all day
+  ↓
+New ticket arrives
+  ↓
+/sfn-plan TASK-XXX ← Plan is written + presented → you say "proceed"
+  ↓
+/sfn-code          ← Feature is implemented per plan, zero-trust guardrails active
+  ↓
+/sfn-review        ← 3-tier AST gate → PASS or BLOCK with specific violations
+  ↓
+PR opened ✅
+
+Need to investigate?
+  ↓
+/blast-radius       ← Impact analysis before any structural change
+/map-architecture   ← Full ecosystem overview
+/analyze            ← Deep subsystem inspection
+```
+
 ---
 
 ## Requirements
 
 - **Node.js** >= 18.0.0
-- An MCP-compatible AI client (Antigravity, Claude Desktop, Cursor, Cline, etc.)
+- An MCP-compatible AI client (Antigravity IDE, Claude Desktop, Cursor, Cline, etc.)
 
 ---
 

package/agents/planner.md

@@ -15,15 +15,23 @@ STEP 1 — ALWAYS, unconditionally:
 
 STEP 2 — if you need more details about a specific service not returned by prime_session:
   → call manage_project_spec(action: "get_service", service_name: <that service>)
+
+STEP 3 — ALWAYS, for any work item that has been initialized:
+  → call spec_read_intent(work_item_id: <active_id>)
+  This loads the WHY layer: business goal, PM owner, ACs, risk, and the Polyglot
+  Service Map (which lists services in Go/Python/Rust/any language even without AST parsers).
+  If the intent file does not exist yet, skip silently — do NOT block on this.
 ```
 
 After these calls complete, you now know:
-- All service ports, repos, domains
-- Table ownership per service
-- All inter-service REST calls
-- Kafka topics (produces/consumes per service)
-- Keycloak config and auth flow
-- Coding patterns and golden rules
+- All service ports, repos, domains (from AST + DNA)
+- Table ownership per service (from AST)
+- All inter-service REST calls (from AST)
+- Kafka topics (produces/consumes per service) (from AST)
+- Keycloak config and auth flow (from DNA)
+- Coding patterns and golden rules (from DNA)
+- **Business goal and PM intent** (from intent file — the WHY layer)
+- **Polyglot service map** — Go/Python/Rust/any service involved even if no AST parser exists
 
 You are NOW allowed to reason about the task. Not before.
 
@@ -34,6 +42,8 @@ You are NOW allowed to reason about the task. Not before.
 - Cannot validate task scope against architecture
 - Cannot enforce golden rules during classification
 - Will hallucinate service details from memory
+- **Will miss polyglot services with no AST parser** (Go, Python, Rust, etc.)
+- **Will lose PM/business context** when making architectural tradeoffs
 
 There are NO circumstances under which Phase 00 can be skipped, abbreviated, or substituted.
 
@@ -48,7 +58,8 @@ There are NO circumstances under which Phase 00 can be skipped, abbreviated, or
 ❌ Write any code  
 ❌ Proceed to Phase 0.5 or any other phase  
 
-The ONLY tool calls permitted before Phase 00 completes are `prime_session` and `manage_project_spec`.
+The ONLY tool calls permitted before Phase 00 completes are `prime_session`, `manage_project_spec`, and `spec_read_intent`.
+
 
 ---
 

package/commands/sfn-plan.md

@@ -24,6 +24,18 @@ work_item_id: <the ticket ID or a slugified version of the description>
 ```
 This creates the dedicated workspace folder at `.secufusion/tasks/<id>/` and begins tracking progress. Do not proceed until this call succeeds.
 
+## Phase 1.5 — Capture Business Intent (The WHY Layer)
+
+Immediately after `manage_task` initializes, call `spec_create_intent` with:
+- `work_item_id`: same ID as above
+- `title`: short human-readable title
+- `business_goal`: **Ask the user** if not provided — "Why is this being built? What user or business problem does it solve?"
+- `acceptance_criteria`: Given/When/Then ACs gathered from the ticket
+- `services_involved`: **Polyglot service map** — list every service this touches, regardless of language (Java, Go, Python, TypeScript). This is how Go/Rust/Python services are tracked even without AST parsers.
+- `risk`: business risk if not delivered
+
+> 💡 This creates `.secufusion/intents/<num>-WI-<id>-<slug>.md` — a human-readable file capturing the WHY. The JSON task folder captures the HOW. Together they give a complete picture.
+
 ## Phase 2 — Load Context
 
 1. Call `prime_session(work_item_id: <id>)` to efficiently load the project DNA state and relevant architectural context for this specific task.
@@ -49,8 +61,10 @@ Read `.agents/planner.md` for the Planner Persona instructions and produce a str
 - **Architectural Decisions** (with rationale grounded in the DNA)
 - **Risk Flags** (tenant isolation, N+1 risks, missing indexes, Kafka sync calls)
 - **Test Plan**
+- **Polyglot Impact** — for each service in the intent's Service Map that has no AST parser, note it explicitly and list what metadata is required (ports, topics, endpoints)
 
 Save the plan to `.secufusion/tasks/<id>/plan.md`.
 
 Present the plan and ask:
 > 📋 Plan ready. Review `plan.md` and approve to begin coding with `/sfn:code`.
+

package/mcp/dist/server.js

@@ -504,9 +504,202 @@ server.tool("manage_project_spec", "Manages the .secufusion-project-spec.json fi
     }
     return appendTelemetry({ content: [{ type: "text", text: "Invalid action." }] }, inputChars);
 });
-// ─── Task management helpers ──────────────────────────────────────────────────
+// ─── Business Intent Layer ────────────────────────────────────────────────────
+//  Bridges the Polyglot Flexibility & Business Intent gaps.
+//  Every work item gets BOTH:
+//    - A JSON task folder  (.secufusion/tasks/WI-XXXX/)  → code truth (AST-driven)
+//    - A Markdown intent file (.secufusion/intents/WI-XXXX.md) → why truth (human-driven)
+//  prime_session merges both into a single context block.
+// ─────────────────────────────────────────────────────────────────────────────
+const INTENTS_DIR = ".secufusion/intents";
 const TASKS_DIR = ".secufusion/tasks";
 const REGISTRY_FILE = ".secufusion/registry.json";
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[:\s]+/g, "-")
+        .replace(/[^a-z0-9-]+/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60);
+}
+function nextIntentNumber() {
+    const intentsRoot = resolve(INTENTS_DIR);
+    if (!fs.existsSync(intentsRoot))
+        return "0001";
+    const files = fs.readdirSync(intentsRoot).filter(f => f.endsWith(".md"));
+    if (files.length === 0)
+        return "0001";
+    const nums = files
+        .map(f => parseInt(f.split("-")[0], 10))
+        .filter(n => !isNaN(n));
+    const max = nums.length > 0 ? Math.max(...nums) : 0;
+    return String(max + 1).padStart(4, "0");
+}
+function parseIntentFrontmatter(raw) {
+    const result = {};
+    const match = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return result;
+    for (const line of match[1].split("\n")) {
+        const [key, ...rest] = line.split(":");
+        if (key && rest.length)
+            result[key.trim()] = rest.join(":").trim();
+    }
+    return result;
+}
+// ─── Tool: spec_next_number ───────────────────────────────────────────────────
+server.tool("spec_next_number", "Returns the next available 4-digit spec/intent number (e.g. 0031). Call before creating a new intent doc to ensure no collisions.", {}, async () => {
+    const inputChars = 0;
+    const next = nextIntentNumber();
+    return appendTelemetry({
+        content: [{ type: "text", text: JSON.stringify({ next_number: next, intents_dir: resolve(INTENTS_DIR) }, null, 2) }]
+    }, inputChars);
+});
+// ─── Tool: spec_create_intent ─────────────────────────────────────────────────
+server.tool("spec_create_intent", "Creates a structured Markdown intent file in .secufusion/intents/ for a work item. This captures the WHY behind the code: business goal, PM sign-off, acceptance criteria, risk, and polyglot service map. Complements manage_task (which captures the HOW). Call immediately after manage_task action=initialize.", {
+    work_item_id: z.string().describe("Azure DevOps work item ID, e.g. '2847'."),
+    title: z.string().describe("Short feature/bug title."),
+    business_goal: z.string().describe("1–3 sentences: why is this being built? What user or business problem does it solve?"),
+    pm_owner: z.string().optional().describe("Product Manager name or alias responsible for this feature."),
+    ticket_url: z.string().optional().describe("Full URL to the Azure DevOps / Jira ticket."),
+    acceptance_criteria: z.array(z.string()).describe("Given/When/Then ACs. Each string is one AC."),
+    out_of_scope: z.array(z.string()).optional().describe("Things explicitly NOT covered by this work item."),
+    risk: z.string().optional().describe("Business risk if not delivered. e.g. 'SOC 2 audit failure', 'Revenue at risk', 'Low'."),
+    services_involved: z.array(z.object({
+        name: z.string().describe("Service name, e.g. 'notification-api'"),
+        language: z.string().describe("Primary language, e.g. 'TypeScript', 'Java', 'Go', 'Python'"),
+        role: z.string().describe("Role in this feature, e.g. 'produces Kafka event', 'REST consumer'")
+    })).optional().describe("Polyglot service map — lists every service involved regardless of language. This is the polyglot bridge."),
+    notes: z.string().optional().describe("Any additional context, constraints, or dependencies.")
+}, async ({ work_item_id, title, business_goal, pm_owner, ticket_url, acceptance_criteria, out_of_scope, risk, services_involved, notes }) => {
+    const inputChars = JSON.stringify(arguments).length;
+    const num = nextIntentNumber();
+    const slug = slugify(title);
+    const filename = `${num}-WI-${work_item_id}-${slug}.md`;
+    const intentsRoot = resolve(INTENTS_DIR);
+    const filePath = path.join(intentsRoot, filename);
+    const acBlock = acceptance_criteria
+        .map((ac, i) => `- [ ] **AC${i + 1}:** ${ac}`)
+        .join("\n");
+    const oosBlock = (out_of_scope || []).length > 0
+        ? (out_of_scope || []).map(s => `- ${s}`).join("\n")
+        : "_None specified._";
+    const servicesBlock = (services_involved || []).length > 0
+        ? (services_involved || []).map(s => `| ${s.name} | ${s.language} | ${s.role} |`).join("\n")
+        : "| _(none specified)_ | — | — |";
+    const now = new Date().toISOString();
+    const content = `---
+work_item_id: ${work_item_id}
+title: ${title}
+status: Draft
+number: ${num}
+pm_owner: ${pm_owner || "TBD"}
+ticket_url: ${ticket_url || "TBD"}
+risk: ${risk || "TBD"}
+created_at: ${now}
+---
+
+# [WI-${work_item_id}] ${title}
+
+## 🎯 Business Goal
+
+${business_goal}
+
+## 📋 Acceptance Criteria
+
+${acBlock}
+
+## 🚫 Out of Scope
+
+${oosBlock}
+
+## 🌐 Service Map (Polyglot Bridge)
+
+| Service | Language | Role in this Feature |
+|---------|----------|----------------------|
+${servicesBlock}
+
+## ⚠️ Risk
+
+${risk || "_Not assessed._"}
+
+## 📝 Notes
+
+${notes || "_None._"}
+
+---
+_Intent file auto-generated by secufusion-mcp. Edit freely — this is the human layer._
+`;
+    writeFile(filePath, content);
+    return appendTelemetry({
+        content: [{
+                type: "text",
+                text: `✅ Intent spec created.\n\n**File:** ${filePath}\n**Number:** ${num}\n**Slug:** ${slug}\n\nThis file captures the WHY. The JSON task folder (.secufusion/tasks/) captures the HOW.\nBoth will be merged by prime_session for a complete context.\n\n---\n${content}`
+            }]
+    }, inputChars);
+});
+// ─── Tool: spec_read_intent ───────────────────────────────────────────────────
+server.tool("spec_read_intent", "Read the intent (WHY) file for a work item. Returns business goal, PM owner, acceptance criteria status, polyglot service map, and risk. Use alongside prime_session to get a complete picture of code truth + business intent.", {
+    work_item_id: z.string().describe("Work item ID to look up, e.g. '2847'."),
+    update_ac: z.object({
+        index: z.number().describe("0-based index of the AC to tick"),
+        checked: z.boolean().describe("true = mark as done (- [x]), false = uncheck (- [ ])")
+    }).optional().describe("Optionally tick or untick an acceptance criterion checkbox in the markdown.")
+}, async ({ work_item_id, update_ac }) => {
+    const inputChars = JSON.stringify({ work_item_id, update_ac }).length;
+    const intentsRoot = resolve(INTENTS_DIR);
+    if (!fs.existsSync(intentsRoot)) {
+        return appendTelemetry({ isError: true, content: [{ type: "text", text: `No intents directory found at ${intentsRoot}. Run spec_create_intent first.` }] }, inputChars);
+    }
+    const files = fs.readdirSync(intentsRoot).filter(f => f.endsWith(".md"));
+    const match = files.find(f => f.includes(`WI-${work_item_id}`));
+    if (!match) {
+        return appendTelemetry({ isError: true, content: [{ type: "text", text: `No intent file found for WI-${work_item_id} in ${intentsRoot}.\nCreate one with spec_create_intent.` }] }, inputChars);
+    }
+    const filePath = path.join(intentsRoot, match);
+    let raw = fs.readFileSync(filePath, "utf-8");
+    if (update_ac !== undefined) {
+        const acLines = raw.split("\n");
+        let acCount = 0;
+        for (let i = 0; i < acLines.length; i++) {
+            if (acLines[i].match(/^- \[[ x]\] \*\*AC\d+/)) {
+                if (acCount === update_ac.index) {
+                    acLines[i] = acLines[i].replace(/^- \[[ x]\]/, update_ac.checked ? "- [x]" : "- [ ]");
+                    break;
+                }
+                acCount++;
+            }
+        }
+        raw = acLines.join("\n");
+        fs.writeFileSync(filePath, raw, "utf-8");
+    }
+    const frontmatter = parseIntentFrontmatter(raw);
+    const acMatches = [...raw.matchAll(/^- \[([ x])\] \*\*AC(\d+):\*\* (.+)$/gm)];
+    const acs = acMatches.map(m => ({
+        index: parseInt(m[2], 10) - 1,
+        done: m[1] === "x",
+        text: m[3]
+    }));
+    const done = acs.filter(a => a.done).length;
+    const summary = {
+        work_item_id,
+        file: match,
+        status: frontmatter.status || "Draft",
+        title: frontmatter.title || "",
+        pm_owner: frontmatter.pm_owner || "TBD",
+        risk: frontmatter.risk || "TBD",
+        ticket_url: frontmatter.ticket_url || "",
+        ac_progress: `${done}/${acs.length} complete`,
+        acceptance_criteria: acs,
+    };
+    return appendTelemetry({
+        content: [{
+                type: "text",
+                text: `## Intent: WI-${work_item_id}\n\n\`\`\`json\n${JSON.stringify(summary, null, 2)}\n\`\`\`\n\n---\n### Full Intent Document\n\n${raw}`
+            }]
+    }, inputChars);
+});
 function resolveTaskFolder(workItemId, tasksRoot, registryData) {
     const registry = registryData || readRegistry();
     const entry = registry.find(t => t["work_item_id"] === workItemId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secufusion-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "SecuFusion MCP server - developer workflow tooling with guardrails",
   "main": "mcp/dist/server.js",