secufusion-mcp 2.1.0 → 2.1.2

package/README.md

@@ -15,16 +15,18 @@
 | 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 dynamically named `.secufusion/tasks/{id}-{slug}/` 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 (the HOW layer: spec, progress, decisions, files-touched). |
+| `spec_create_intent` | **Phase 1** — Planning | **NEW in v2.1** — Creates the Markdown intent file (the WHY layer: business goal, PM, ACs, polyglot service map). |
+| `spec_read_intent` | **Phase 0 / 1** — Session Start | **NEW in v2.1** — Reads the Markdown intent file and ticks AC checkboxes. |
+| `spec_next_number` | **Phase 1** — Planning | **NEW in v2.1** — Generates the next sequential ID for intent files. |
 | `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 |
-| `(Removed)` | **Phase 4** — PR Handoff | *Replaced by native MD generation protocol in v1.0.58* |
 | `run_pre_pr_checks_with_reviewer_agent` | **Phase 4** — PR Handoff | **NEW** — Unified 3-tier PR gate. Runs mechanical checks, AI file reviews, and context-aware task evaluation in a single pass. |
 | `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. |
+| `classify_task` | **Phase 0.5** — Task Classification | **NEW** — Deep multi-pass analysis engine. Classifies any task as `BACKEND_ONLY`, `FRONTEND_ONLY`, etc. based on root cause. |
 | `prime_session` | **Phase 0** — Session Start | **NEW** — Hyper-efficient session startup. Combines Phase 00 (spec) and Phase 0 (task) into one call using Thin Indexes to optimize context tokens. |
 | `skill_recommend` | **Phase 1** — Planning | **NEW** — Dynamically recommends and retrieves domain-specific coding skills from `skills-catalog.json`. |
 
@@ -53,9 +55,45 @@ A new standalone Claude plugin has been introduced: **SecuFusion DNA Discovery M
 
 ---
 
-## ⚡ The Shift: Problem-Statement Driven → Project-Level Spec Driven
+## ⚡ The Shift: "WHY before HOW" Spec-Driven Workflow (v2.1)
+
+This is the biggest architectural upgrade to the SecuFusion MCP, fundamentally changing how the AI approaches a new task.
+
+### The Problem
+Previously, the AI acted as a blind code-generator. When given a task (e.g. "Add MFA"), it would immediately jump into writing code or initializing tracking infrastructure (`.secufusion/tasks/`), without understanding **why** the feature was being built, who requested it, or the business risk. Furthermore, its AST parsers were limited to Java/TypeScript, leaving Go, Python, or Rust services completely invisible.
+
+### The v2.1 Solution: The Two-Layer Architecture
+Every task now requires **two complementary files** that the AI reads together:
+
+```
+.secufusion/
+├── tasks/WI-2847/              ← HOW layer  (code truth, AST-driven, JSON)
+│   ├── progress.json           ← pending/completed ACs
+│   └── decisions.json          ← architectural decisions log
+│
+└── intents/                    ← WHY layer  (business truth, human-driven, Markdown)
+    └── 0001-WI-2847-add-mfa-enforcement.md
+        ├── Business Goal       ← why is this being built?
+        ├── PM Owner            ← who owns it?
+        ├── Acceptance Criteria ← tickable checkboxes
+        ├── Service Map         ← polyglot bridge (Go, Python, Rust...)
+        └── Risk Assessment     ← what breaks if we don't ship?
+```
+
+### The Polyglot Bridge
+The new `spec_create_intent` tool captures a `services_involved` array that is **language-agnostic**. You can list a Go microservice, a Python Lambda, or a COBOL batch job. The AI reads this declaration and knows those services are in scope without needing a custom AST parser.
+
+### The New `/sfn:plan` Flow
+When you type `/sfn:plan WI-2847 Add MFA`:
+1. **The Pushback (Phase 1):** The AI will **NOT** immediately start planning. It will stop and ask you: *"Why are we building this? What business problem does it solve? What is the risk if we don't?"*
+2. **The WHY (Phase 1.5):** You answer, and the AI generates the Markdown intent file (`spec_create_intent`).
+3. **The HOW (Phase 2):** Only then does it initialize the code tracking infrastructure (`manage_task`).
+4. **Context & Classify (Phase 3/4):** The AI loads the AST (`prime_session`), flags architectural risks (`classify_task`), and yields for your approval.
+5. **The Plan (Phase 5):** The AI outputs the strict implementation plan.
 
-This is the biggest architectural upgrade to the SecuFusion MCP.
+---
+
+## ⚡ The Shift: Problem-Statement Driven → Project-Level Spec Driven
 
 ### 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:

package/agents/AGENTS.md

@@ -19,10 +19,11 @@ Do not attempt to load all instructions into memory. Based on the current SDLC p
 **DYNAMIC ENFORCEMENT**: You must dynamically adhere to these rules at all times. Whether you are starting a fresh task, resuming an interrupted session, or answering a mid-task prompt, you must strictly respect this sequence and never skip ahead.
 
 1. **Rule 0 (Pre-requisite to all rules) — Load Project DNA First**: Before ANY other action, call `prime_session(work_item_id: <id>)`. This is Phase 00. Without the project DNA loaded, you are not allowed to reason, classify, plan, or code. Period.
-2. **Rule 1 - ReAct (Reason, Observe, Act) First**: After DNA is loaded, you MUST deeply reason about the problem statement. Apply the ReAct framework: analyze the problem, observe context, and formulate a high-level solution hypothesis.
-3. **Rule 2 - Classify Second**: Only after you have reasoned through the problem statement, you MUST call the `classify_task` tool. This will formally categorize the task and lock in architectural boundaries.
-4. **Rule 3 - STRICT YIELD (Stop and Wait)**: Immediately after classifying the task, you MUST YIELD YOUR TURN. **DO NOT CHAIN TOOL CALLS.** Output the classification, ask the user for the "green signal," and STOP.
-5. **Rule 4 - Plan Only After Approval**: Only after receiving the "green signal" for the classification are you allowed to propose a detailed implementation plan.
-6. **Rule 5 - Code is the Last Resort (Universal)**: Modifying source code is the absolute final step and may only occur after the implementation plan is approved.
+2. **Rule 1 - Clarify Business Intent (WHY before HOW)**: For any new task, you MUST pause and ask the user for the business intent, goal, and risk. YIELD until this is clarified, then call `spec_create_intent`. Do not initialize task tracking (`manage_task`) until the WHY is captured.
+3. **Rule 2 - ReAct (Reason, Observe, Act) First**: After intent is clarified and DNA is loaded, you MUST deeply reason about the problem statement. Apply the ReAct framework: analyze the problem, observe context, and formulate a high-level solution hypothesis.
+4. **Rule 3 - Classify Second**: Only after you have reasoned through the problem statement, you MUST call the `classify_task` tool. This will formally categorize the task and lock in architectural boundaries.
+5. **Rule 4 - STRICT YIELD (Stop and Wait)**: Immediately after classifying the task, you MUST YIELD YOUR TURN. **DO NOT CHAIN TOOL CALLS.** Output the classification, ask the user for the "green signal," and STOP.
+6. **Rule 5 - Plan Only After Approval**: Only after receiving the "green signal" for the classification are you allowed to propose a detailed implementation plan.
+7. **Rule 6 - Code is the Last Resort (Universal)**: Modifying source code is the absolute final step and may only occur after the implementation plan is approved.
 
 ---

package/agents/planner.md

@@ -60,6 +60,24 @@ There are NO circumstances under which Phase 00 can be skipped, abbreviated, or
 
 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,33 +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 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
+## 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**
 
@@ -51,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:
 

package/package.json

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