secufusion-mcp 2.0.1 → 2.1.1

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,26 @@ 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`.
+
+---
+
+## Phase 0.25 — Clarify and Capture Business Intent (The WHY Layer)
+(TRIGGER: when a **NEW** task, feature, or bug is received that has no existing tracking)
+
+Before thinking about *how* to implement the task, you must understand *why* it is needed.
+1. **Analyze** the requested task.
+2. **Ask** the user clarifying questions if the following are not completely clear:
+   - Why is this being built? What user or business problem does it solve?
+   - What is already there, and is this actually needed?
+   - What is the business risk if not delivered?
+3. **YIELD** and wait for the user to clarify the business intent. Do not proceed until the intent is clear.
+
+Once the intent is clarified:
+1. Call `manage_task(action: "initialize", ...)` to initialize the task tracking (The HOW layer).
+2. Call `spec_create_intent(...)` to capture the clarified business intent (The WHY layer).
+
+Only after both of these are created may you proceed to Phase 0.5.
 
 ---
 

package/commands/sfn-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Architect a solution for a task or Jira ticket using the loaded DNA. Creates a dedicated task workspace, classifies the work, and produces a strict implementation plan awaiting your approval.
+description: Architect a solution for a task or Jira ticket using the loaded DNA. Clarifies business intent, creates a dedicated task workspace, classifies the work, and produces a strict implementation plan awaiting your approval.
 argument-hint: <ticket-id or feature description>  e.g. WI-123 or "add user login endpoint"
 ---
 
@@ -15,21 +15,42 @@ Task / Ticket: **$ARGUMENTS**
 2. If `DNA_LOADED` is `false` or `null`, **ABORT immediately** and tell the user:
    > ❌ Project DNA is not loaded. Please run `/sfn:init` first.
 
-## Phase 1 — Initialize the Task Workspace
+## Phase 1 — Clarify and Capture Business Intent (The WHY Layer)
 
+Before thinking about *how* to implement the task, you must understand *why* it is needed.
+1. Analyze the requested task. 
+2. Ask the user clarifying questions if the following are not completely clear:
+   - Why is this being built? What user or business problem does it solve?
+   - What is already there, and is this actually needed?
+   - What is the business risk if not delivered?
+3. **YIELD** and wait for the user to clarify the business intent. Do not proceed to Phase 2 until the intent is clear.
+
+Once the intent is clarified, call `spec_create_intent` with:
+- `work_item_id`: the ticket ID or a slugified version of the description
+- `title`: short human-readable title
+- `business_goal`: The clarified business problem it solves.
+- `acceptance_criteria`: Given/When/Then ACs gathered from the ticket/clarification.
+- `services_involved`: **Polyglot service map** — list every service this touches, regardless of language (Java, Go, Python, TypeScript).
+- `risk`: business risk if not delivered.
+
+> 💡 This creates `.secufusion/intents/<num>-WI-<id>-<slug>.md` — a human-readable file capturing the WHY.
+
+## Phase 2 — Initialize the Task Workspace (The HOW Layer)
+
+Now that the *why* is captured, initialize the *how* tracking.
 Call `manage_task` with:
 ```
 action: "initialize"
-work_item_id: <the ticket ID or a slugified version of the description>
+work_item_id: <same ID as above>
 ```
 This creates the dedicated workspace folder at `.secufusion/tasks/<id>/` and begins tracking progress. Do not proceed until this call succeeds.
 
-## Phase 2 — Load Context
+## Phase 3 — 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.
 2. Read the `.secufusion-project-spec.json` from the project root to understand the golden rules, constraints, and acceptance criteria boundaries for this project.
 
-## Phase 3 — Classify the Task
+## Phase 4 — Classify the Task
 
 Call `classify_task` with the task description: **$ARGUMENTS**
 
@@ -39,7 +60,7 @@ This formally categorizes the work (Feature, Bug, Refactor, Security, Performanc
 
 Wait for explicit approval before continuing.
 
-## Phase 4 — Write the Implementation Plan (After Approval)
+## Phase 5 — Write the Implementation Plan (After Approval)
 
 Read `.agents/planner.md` for the Planner Persona instructions and produce a strict, step-by-step implementation plan that includes:
 
@@ -49,8 +70,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.1",
+  "version": "2.1.1",
   "type": "module",
   "description": "SecuFusion MCP server - developer workflow tooling with guardrails",
   "main": "mcp/dist/server.js",