secufusion-mcp 1.0.57 → 1.0.59

package/AGENTS.md

@@ -485,10 +485,12 @@ STEP 2: call manage_task(action: "complete", work_item_id: <id>)
         — Only permitted after APPROVED or DISCUSS verdict
         — Marks status complete, auto-generates pr-summary.md
 
-STEP 3: call generate_ado_comments(work_item_id, layman_summary, technical_deep_dive)
-        — Generates two ADO board comments:
-          1. Layman Summary: non-technical explanation of business value
-          2. Technical Deep-Dive: architectural changes and implementation details
+STEP 3: Generate and save PR & ADO Documents manually
+        — Read files-touched.json, decisions.json, and scenarios.json from the task folder
+        — Generate ado-comments.md and pr-comment.md inside .secufusion/tasks/{id}-{slug}/
+        — Follow the strict templates and guardrails defined in the [Document Generation Protocol] section
+        — Present the documents to the developer for review
+        — call manage_task(action: "log_decision", decision: "ADO comments and PR comment generated")
 ```
 
 ### Hard enforcement
@@ -717,3 +719,123 @@ Before Phase 0.7 plan presentation:
 ❌ Do NOT skip `get_task_history` if a match exists — "I remember it" is not a substitute  
 ❌ Do NOT re-solve a solved problem — task history exists precisely to prevent this  
 ❌ Re-using a rejected pattern found in task history is a violation even if you disagree with the rejection  
+
+## Document Generation Protocol
+(For Phase 4 — PR Handoff)
+
+### ADO Comments Template (`ado-comments.md`)
+**Audience:** Technical and Non-Technical stakeholders on the Azure DevOps board.
+**Format rules:**
+- Layman summary: NO class names, NO method names, NO technical terms. Pure English.
+- Technical deep-dive: BE specific. Exact class names, exact method names, exact file paths. Source from `files-touched.json`.
+- Tables must have content in every cell. If unknown → "not recorded".
+- Max 2 sentences in any single prose paragraph.
+- Max 600 words.
+
+```markdown
+## Layman Summary
+{layman_summary — 2-3 sentences max}
+
+## Technical Deep-Dive
+{If auth/permission gating exists:}
+> Both endpoints gated by `{permission}` authority.
+
+### Scenarios Handled
+**Happy path:**
+{happy_path from scenarios.json — one sentence}
+
+**Sad paths handled:**
+{for each sad_path in scenarios.json:}
+- {sad_path description} → {how handled}
+
+**Security cases:**
+{for each security_case in scenarios.json:}
+- {security concern} → {enforcement}
+
+### What did NOT change
+| Area | Status |
+|---|---|
+| DB migration | {✅ Not required / ⚠️ Created: V{n}__...sql} |
+| Kafka topics | {✅ No new topics / ⚠️ New topic: {name}} |
+| {other_service}-api | {✅ No changes / ⚠️ Changes required} |
+| API contract | {✅ No breaking changes / ⚠️ See decisions} |
+
+---
+*Generated by SecuFusion MCP · {service} · {work_item_id}*
+```
+
+### PR Comment Template (`pr-comment.md`)
+**Audience:** Busy Developer Reviewers reading the PR description.
+**Format rules:**
+- Group changes by WHAT changed, not by file name (e.g., "New endpoint: GET /path", "Test coverage: N scenarios").
+- ✅ for things NOT changing is equally important.
+- Guardrails section is mandatory.
+- Max 400 words. Condense changes table if longer.
+
+```markdown
+# {task_type_emoji} {work_item_id}: {title}
+
+> **Type:** {task_type_display} · **Service:** `{service}` · **Work Item:** [{work_item_id}]({devops_url}/{work_item_id})
+
+---
+## Summary
+{2-3 sentences MAX. What changed and why.}
+
+---
+## Changes
+| Area | What changed |
+|---|---|
+| {logical area} | {what changed in plain terms} |
+
+---
+## Affected Service
+- `{service-name}`
+
+---
+## Impact
+- ✅ No functional or behavioral changes {OR describe actual behavioral change}
+- ✅ No DB migration required {OR: ⚠️ Flyway migration V{n} included}
+- ✅ No Kafka topic changes {OR: ⚠️ New topic: {name}}
+- ✅ No API contract changes {OR: ⚠️ New endpoints: see Changes above}
+
+---
+## Scenarios
+**Happy path:** {happy_path one line}
+
+**Sad paths handled:**
+- {what fails} → {how handled}
+
+---
+## Guardrails
+- ✅ No `console.log` / `System.out.println` in source
+- ✅ No hardcoded UAT/Prod URLs or IPs
+- ✅ `tenantId` scoping maintained on all queries
+- ✅ No `@Entity` changes — Flyway not required
+- ✅ All pre-PR checks passed
+
+{if any rejected patterns were relevant:}
+**Patterns avoided:**
+- Rejected pattern #{id}: {short description}
+```
+
+### Task Type Emoji Map
+- bug → 🐛
+- user_story → 📖
+- feature → ✨
+- hotfix → 🚨
+- refactor → 🔄
+- chore → 🧹
+
+### Presentation Format
+When presenting to the developer, output this exactly:
+```text
+────────────────────────────────────────────────
+✅ Two documents generated for {work_item_id}:
+
+📄 ADO Comments  → paste into WI comment thread
+📄 PR Comment    → paste into PR description
+
+Review below. Say LGTM to confirm, or tell me what to change.
+────────────────────────────────────────────────
+```
+Then show the full `ado-comments.md` followed by a `────────────────────────────────` divider, followed by the full `pr-comment.md`.

package/README.md

@@ -21,7 +21,7 @@
 | `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 |
-| `generate_ado_comments` | **Phase 4** — PR Handoff | Generates distinct Layman and Technical Deep-Dive summaries for the Azure DevOps board |
+| `(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. |
@@ -233,20 +233,13 @@ This writes to `.rejected-patterns.json`:
 ---
 
 ### 3. generate_ado_comments
+### 3. Native Document Generation (v1.0.58+)
 
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `work_item_id` | string | Yes | Azure DevOps work item ID |
-| `layman_summary` | string | Yes | Non-technical explanation of the business value and what was resolved |
-| `technical_deep_dive` | string | Yes | Comprehensive breakdown of the architectural changes and optimizations |
-
-**Example — Generate ADO board comments:**
-
-```
-Ask: "Prepare the PR for work item 1042."
-```
+Instead of using a generic tool, the agent natively generates two highly structured files based on strict `AGENTS.md` templates:
+- **`ado-comments.md`**: For the Azure DevOps board (Layman summary + Technical Deep-Dive).
+- **`pr-comment.md`**: For the PR Description (Changes, Impact, Scenarios, Guardrails).
 
-The AI will complete the task, then call `generate_ado_comments`. The output is explicitly formatted for the developer to paste into the Azure DevOps board.
+The AI constructs these dynamically by reading `scenarios.json`, `decisions.json`, and `files-touched.json`, and presents them to the developer.
 
 ---
 
@@ -428,7 +421,7 @@ These rules are enforced automatically — the AI will never violate them:
 ├──────────────┼──────────────────────────────────────────────────────────────┤
 │  Phase 4     │  run_pre_pr_checks_with_reviewer_agent                        │
 │  PR Handoff  │  → manage_task (action=complete) → pr-summary.md generated    │
-│              │  → generate_ado_comments → Layman & Technical Deep-Dive (ADO) │
+│              │  → Document Generation (ado-comments.md, pr-comment.md)         │
 └──────────────┴──────────────────────────────────────────────────────────────┘
 ```
 
@@ -647,7 +640,7 @@ Phase 2: code + log_file_touched + log_decision + add_scenario (ALL mandatory)
       ↓
 Phase 4: run_pre_pr_checks_with_reviewer_agent → APPROVED / DISCUSS
        → manage_task complete  →  pr-summary.md generated
-       → generate_ado_comments  →  Layman + Technical Deep-Dive for ADO board
+       → Generate PR & ADO Documents natively using templates
 ```
 
 ### Reusing across projects (Global Bundling)

package/index.js

@@ -3366,7 +3366,7 @@ server.tool("run_pre_pr_checks_with_reviewer_agent", "Unified, single-call PR re
     if (verdict === "✅ APPROVED") {
         out += `\n**Next steps:**\n`;
         out += `1. \`manage_task(action: "complete", work_item_id: "${work_item_id}")\`\n`;
-        out += `2. \`generate_ado_comments\` → paste into ADO board\n`;
+        out += `2. Generate PR and ADO documents manually using AGENTS.md rules\n`;
         out += `3. Raise the PR\n`;
     }
     else if (verdict === "❌ CHANGES_REQUESTED") {
@@ -4010,7 +4010,7 @@ server.tool("run_pre_pr_checks", "Full-spectrum PR review system — runs BEFORE
     if (verdict === "✅ APPROVED") {
         out += `\n**Next steps:**\n`;
         out += `1. Call \`manage_task(action: "complete", work_item_id: "${work_item_id}")\`\n`;
-        out += `2. Call \`generate_ado_comments\` to prepare ADO board comments\n`;
+        out += `2. Generate PR and ADO documents manually as per Phase 4\n`;
         out += `3. Raise the PR\n`;
     }
     else if (verdict === "❌ CHANGES_REQUESTED") {
@@ -4509,7 +4509,7 @@ server.tool("reviewer_agent", "Context-aware architectural review agent — call
     if (verdict === "✅ APPROVED") {
         out += `\n**Next steps:**\n`;
         out += `1. Call \`manage_task(action: "complete", work_item_id: "${work_item_id}")\`\n`;
-        out += `2. Call \`generate_ado_comments\` to prepare ADO board comments\n`;
+        out += `2. Generate PR and ADO documents manually as per Phase 4\n`;
         out += `3. Raise the PR\n`;
     }
     else if (verdict === "❌ CHANGES_REQUESTED") {
@@ -4563,35 +4563,5 @@ server.tool("get_secufusion_rules", "Fetches the mandatory AGENTS.md workflow ru
         content: [{ type: "text", text: content }]
     }, 0);
 });
-server.tool("generate_ado_comments", "Generates and formats the final Azure DevOps board comments for a completed task. Call this in Phase 4 after PR checks pass.", {
-    work_item_id: z.string().describe("Azure DevOps work item ID, e.g. 'BUG-1140'."),
-    layman_summary: z.string().describe("A short, fundamental, non-technical explanation of the business value and what was resolved."),
-    technical_deep_dive: z.string().describe("A comprehensive, highly technical breakdown of the architectural changes, core optimizations, and exact implementation details.")
-}, async ({ work_item_id, layman_summary, technical_deep_dive }) => {
-    const inputChars = JSON.stringify({ work_item_id, layman_summary, technical_deep_dive }).length;
-    let out = `## ADO Board Comments for ${work_item_id}\n\n`;
-    out += `Please paste the following two comments into the Azure DevOps board:\n\n`;
-    out += `### 1. Layman Summary\n`;
-    out += `\`\`\`text\n${layman_summary}\n\`\`\`\n\n`;
-    out += `### 2. Technical Deep-Dive\n`;
-    out += `\`\`\`text\n${technical_deep_dive}\n\`\`\`\n\n`;
-    try {
-        const classifDir = resolve(".secufusion/classifications");
-        if (!fs.existsSync(classifDir)) {
-            fs.mkdirSync(classifDir, { recursive: true });
-        }
-        const commentsFile = path.join(classifDir, `${work_item_id}-comments.md`);
-        const mdContent = `# ADO Board Comments for ${work_item_id}\n\n` +
-            `*Generated at: ${new Date().toISOString()}*\n\n` +
-            `## 1. Layman Summary\n${layman_summary}\n\n` +
-            `## 2. Technical Deep-Dive\n${technical_deep_dive}\n`;
-        writeFile(commentsFile, mdContent);
-        out += `✅ Comments persisted to \`.secufusion/classifications/${work_item_id}-comments.md\`\n`;
-    }
-    catch (e) {
-        // ignore
-    }
-    return appendTelemetry({ content: [{ type: "text", text: out }] }, inputChars);
-});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

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