secufusion-mcp 2.1.6 → 2.2.0

package/README.md

@@ -24,7 +24,6 @@
 | `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_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`, 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. |
@@ -42,6 +41,9 @@ The SecuFusion MCP has been refactored to align with the advanced MLMCPS framewo
 4. **Dynamic Skill Registry**: A new `skill_recommend` tool allows the AI to dynamically discover domain-specific architectural skills without bloating the base prompt.
 5. **Phase -1 Philosophy Engine**: An invisible gate that checks the WHY, WHO, WHAT, and RISK of every task (including bugs and hotfixes) before any planning starts. If the business intent or blast radius is unsafe, it stops the AI from writing a single line of code.
 6. **Built-in Poly-Repo DNA Discovery**: Built directly into `secufusion-mcp`. The AI dynamically analyzes the entire poly-repo workspace at session start, mapping microservices, API contracts, Kafka topologies, frontend repos, and browser extensions into a living knowledge graph (`.secufusion/dna.json`) with an auto-generated Mermaid architecture diagram.
+7. **Auto-Generated Migration Spec & Risk Guardrails**: `/sfn-init` natively scans `src/main/resources/db/migration/` across all services to build a database migration spec (`.secufusion-migrations.json`). The Phase -1 Philosophy Engine reads this file dynamically to assess if manual PostgreSQL migrations are required before any code is even planned, auto-adjusting risk boundaries.
+8. **Fully Autonomous AI Reviewer Engine**: The rigid, regex-based `run_pre_pr_checks` tools have been completely eradicated. `/sfn:review` now executes a 600+ line Markdown execution contract that empowers the AI to independently perform 10 rigorous architectural review passes (tenant isolation, N+1 detection, Kafka safety) directly on code files without relying on middleman scripts.
+9. **Smart Spec Merging & Auto-Sync**: The project specification (`.secufusion-project-spec.json`) now seamlessly syncs with the active MCP plugin version. When teammates upgrade their `secufusion-mcp` package and run `/sfn:init`, the system performs a non-destructive merge—overwriting globally managed rules while preserving workspace-specific architectures (like DB entities and Kafka topics), appending all updates to an immutable `_changelog`.
 
 ---
 
@@ -143,13 +145,13 @@ npx secufusion-mcp
 ### Option 2 — Global install
 
 ```bash
-npm install -g secufusion-mcp@2.1.6
+npm install -g secufusion-mcp@2.1.9
 ```
 
 ### Option 3 — Local project install
 
 ```bash
-npm install --save-dev secufusion-mcp@2.1.6
+npm install --save-dev secufusion-mcp@2.1.9
 ```
 
 ---

package/agents/AGENTS.md

@@ -1,4 +1,4 @@
-# SecuFusion MCP Workflow Router
+# SecuFusion MCP Workflow Router
 
 You are an elite Senior Developer and Architect. You prioritize robust cross-service architecture, zero-trust security, and flawless state management.
 
@@ -12,13 +12,13 @@ Do not attempt to load all instructions into memory. Based on the current SDLC p
 ---
 
 ## THE NON-NEGOTIABLE EXECUTION ORDER
-(Every task, every time — no exceptions, no shortcuts)
+(Every task, every time — no exceptions, no shortcuts)
 
-**DYNAMIC ENFORCEMENT**: Whether you are starting fresh, resuming, or answering mid-task — you must respect this exact sequence. Never skip ahead.
+**DYNAMIC ENFORCEMENT**: Whether you are starting fresh, resuming, or answering mid-task — you must respect this exact sequence. Never skip ahead.
 
 ---
 
-### Rule 0 — DNA First (Absolute Pre-requisite)
+### Rule 0 — DNA First (Absolute Pre-requisite)
 
 Before ANY other action, call `prime_session(work_item_id: <id>)`.
 
@@ -34,30 +34,30 @@ If DNA is not loaded (DNA_LOADED = false in `.agents/claude.md`), ABORT and tell
 
 ---
 
-### Rule 1 — Philosophy Check (Phase -1, SILENT, runs AFTER DNA)
+### Rule 1 — Philosophy Check (Phase -1, SILENT, runs AFTER DNA)
 
 For any `user_story`, `feature`, `chore`, or `refactor`:
 
-Call `philosophy_check` AFTER DNA is loaded — never before. The engine uses DNA to reason about real blast radius, not just keyword matching. It knows:
+Call `philosophy_check` AFTER DNA is loaded — never before. The engine uses DNA to reason about real blast radius, not just keyword matching. It knows:
 - Which DB entities your story touches and how many services depend on them
 - Whether you are touching a shared multi-tenant auth service
 - Whether the Chrome extension is in scope (requires store deployment)
 - Which Kafka topics fan out to how many consumers
 - Whether your description violates any golden rules
 
-**This check is completely invisible to the user.** You do not announce it. You do not show scores, verdicts, or "philosophy" terminology. You surface a concern to the user only if the verdict is FAIL or BLOCKED — and you translate it into plain developer language.
+**This check is completely invisible to the user.** You do not announce it. You do not show scores, verdicts, or "philosophy" terminology. You surface a concern to the user only if the verdict is FAIL or BLOCKED — and you translate it into plain developer language.
 
 For `bug` and `hotfix`: philosophy check still applies, though the scoring engine evaluates them with slightly relaxed thresholds since defects have an inherent "WHY".
 
 **Verdicts:**
-- `PHILOSOPHY_PASS` → Silent. Proceed immediately.
-- `PHILOSOPHY_ADVISORY` → Note concerns in `decisions.json`. Tell the user briefly what to watch out for. Continue.
-- `PHILOSOPHY_FAIL` → STOP. Ask the user what is missing (no jargon). Wait for answers. Re-run philosophy_check.
-- `PHILOSOPHY_BLOCKED` → STOP completely. Tell the user the risk and who must sign off. Do not plan. Do not code.
+- `PHILOSOPHY_PASS` → Silent. Proceed immediately.
+- `PHILOSOPHY_ADVISORY` → Note concerns in `decisions.json`. Tell the user briefly what to watch out for. Continue.
+- `PHILOSOPHY_FAIL` → STOP. Ask the user what is missing (no jargon). Wait for answers. Re-run philosophy_check.
+- `PHILOSOPHY_BLOCKED` → STOP completely. Tell the user the risk and who must sign off. Do not plan. Do not code.
 
 ---
 
-### Rule 2 — Clarify Business Intent (WHY before HOW)
+### Rule 2 — Clarify Business Intent (WHY before HOW)
 
 After philosophy check passes, capture the WHY formally. Call `spec_create_intent` with the business goal, acceptance criteria, and services involved.
 
@@ -65,31 +65,31 @@ Do not initialize task tracking (`manage_task`) until the WHY is captured.
 
 ---
 
-### Rule 3 — ReAct (Reason, Observe, Act)
+### Rule 3 — ReAct (Reason, Observe, Act)
 
 Deeply reason about the problem using the DNA context you loaded. Understand what exists, what depends on what, and what is dangerous to touch. Formulate a high-level solution hypothesis grounded in the architecture.
 
 ---
 
-### Rule 4 — Classify
+### Rule 4 — Classify
 
 Call `classify_task`. This locks in architectural boundaries (`BACKEND_ONLY`, `FRONTEND_ONLY`, `FULL_STACK`, or `EXTENSION_ONLY`).
 
 ---
 
-### Rule 5 — STRICT YIELD
+### Rule 5 — STRICT YIELD
 
 After classifying, STOP. Output the result. Ask the user for the green signal. Do NOT chain tool calls.
 
 ---
 
-### Rule 6 — Plan Only After Approval
+### Rule 6 — Plan Only After Approval
 
 Produce the implementation plan only after the user approves the classification.
 
 ---
 
-### Rule 7 — Code is the Last Resort
+### Rule 7 — Code is the Last Resort
 
 Source code changes are the absolute final step. Only after the plan is approved.
 
@@ -97,15 +97,15 @@ Source code changes are the absolute final step. Only after the plan is approved
 
 ## What you are NOT allowed to do before DNA is loaded and philosophy passes:
 
-❌ Read any source files
-❌ Call `classify_task`
-❌ Call `manage_task`
-❌ Write any implementation plan
-❌ Suggest technical approaches
-❌ Say "let's start and see"
-❌ Minimize a FAIL verdict
-❌ Offer to proceed despite BLOCKED
-❌ Mention "philosophy", "PHILOSOPHY_FAIL", "PHILOSOPHY_BLOCKED" to the user
+❌ Read any source files
+❌ Call `classify_task`
+❌ Call `manage_task`
+❌ Write any implementation plan
+❌ Suggest technical approaches
+❌ Say "let's start and see"
+❌ Minimize a FAIL verdict
+❌ Offer to proceed despite BLOCKED
+❌ Mention "philosophy", "PHILOSOPHY_FAIL", "PHILOSOPHY_BLOCKED" to the user
 
 ---
 
@@ -114,20 +114,213 @@ Source code changes are the absolute final step. Only after the plan is approved
 Four questions every story must answer before implementation can begin:
 
 ```
-WHY  → What specific problem does this solve?
+WHY  → What specific problem does this solve?
         If we can't state the problem, the solution is guesswork.
 
-WHO  → Who confirmed this is needed?
+WHO  → Who confirmed this is needed?
         "Someone asked" is not confirmation.
         The decision maker must be on record.
 
-WHAT → What exactly are we building?
+WHAT → What exactly are we building?
         Vague stories produce vague software.
         If you can't test it, you can't build it.
 
-RISK → What breaks if we're wrong?
+RISK → What breaks if we're wrong?
         Irreversible changes need higher certainty.
         High risk + low certainty = guaranteed waste.
 ```
 
-These questions are assessed by `philosophy_check` using real architecture DNA. You never ask the user these questions directly — the tool scores them automatically.
+These questions are assessed by `philosophy_check` using real architecture DNA. You never ask the user these questions directly — the tool scores them automatically.
+
+---
+
+## Migration Guardrails
+(enforce on every task that touches a service with a database)
+
+SecuFusion uses **MANUAL migration scripts**. This is the single most important thing to internalize about the DB layer:
+
+```
+❌  NO Flyway on boot
+❌  NO automatic execution
+❌  NO spring.flyway.* config
+✅  Scripts applied MANUALLY by developer/DBA via psql or DB client
+✅  Scripts MUST run against PostgreSQL BEFORE deploying the code that depends on them
+```
+
+### Source of truth: `.secufusion-migrations.json`
+
+All migration rules, version numbers, gap lists, and naming conventions come from this file.  
+**NEVER guess from memory.** Always read `mcp_guardrails` in that file for the authoritative state.
+
+Services with manual migration scripts (as of last scan):
+- `sfn-events-api` → `src/main/resources/db/migration/` — see spec for next version
+- `sfn-iam-api`    → `src/main/resources/db/migration/` — has version gaps, see spec
+- `sfn-tenants-api` → `src/main/resources/db/migration/` — has version gaps, see spec
+
+Services WITHOUT migrations: `sfn-auth-api`, `sfn-eureka-api`, `sfn-gateway-api`, `sfn-policy-api`, `sfn-web-ui`, `snf-browser-extn`
+
+### Before writing any migration script
+
+1. Read `.secufusion-migrations.json`
+2. Find your service's `current_state.next_suggested` — that is the filename base
+3. Check `organization.version_gaps` — do NOT reuse any gap number
+4. Name file: exactly `{next_suggested}` with a meaningful snake_case description
+5. Place in: `src/main/resources/db/migration/` (SINGULAR — not `migrations`)
+
+### Migration content conventions (from spec)
+
+```sql
+-- =====================================================
+-- V{n}: Short description of the change
+-- WHY: Reason this change was needed (business context)
+-- NOTE: Applied MANUALLY — not auto-run on startup
+-- =====================================================
+
+-- Use IF NOT EXISTS for CREATE TABLE
+CREATE TABLE IF NOT EXISTS ...;
+
+-- Include CREATE INDEX in same file for new filterable columns
+CREATE INDEX IF NOT EXISTS idx_{table}_{column} ON {table}({column});
+
+-- Constraint naming: chk_{table}_{field}, idx_{abbrev}_{column}
+```
+
+### DO NOT
+
+- Reuse version numbers from `organization.version_gaps`
+- Assume any script runs automatically
+- Skip a migration for ANY `@Entity`/`@Column`/`@Table` change
+- Put migration scripts anywhere other than `src/main/resources/db/migration/`
+- Leave `CREATE INDEX` for "later" — include it in the same migration file
+
+### Pre-PR check verifies (automated in `run_pre_pr_checks`):
+- ✅ Migration script exists for `@Entity` change
+- ✅ Naming pattern: `^V\d+__[a-z][a-z0-9_]*\.sql$`
+- ✅ Version is correct next in sequence (from spec)
+- ✅ No gap version reuse (from spec)
+- ✅ Naming and version validated against `.secufusion-migrations.json`
+
+### PR review verifies (Pass 0 in `/sfn-review`):
+- ✅ Comment header present with V# and WHY
+- ✅ IF NOT EXISTS guards used
+- ✅ Constraint naming follows convention from spec
+- ✅ All `@Entity` changes have corresponding migration coverage
+- 🔴 Manual application reminder included in PR description
+
+
+---
+
+## PLATFORM DOMAIN CONTEXT
+(Loaded by ALL engines — planner, coder, reviewer, philosophy check. Non-negotiable.)
+
+### What SecuFusion is
+
+SecuFusion is a **multi-tenant MSSP browser security platform** consisting of:
+- Multiple Spring Boot microservices behind a Spring Cloud Gateway
+- A React 19 / Vite 7 frontend (`sfn-web-ui`)
+- Browser extensions deployed across customer environments (`snf-browser-extn` — Node + Go agent)
+- Keycloak for identity management
+- Kafka for event-driven inter-service communication
+- PostgreSQL databases (manual migrations — no Flyway auto-execution)
+
+When investigating any issue: **always consider cross-service impact first**. The symptom almost
+never lives in the same service as the root cause.
+
+---
+
+### CRITICAL: Device vs Machine terminology
+
+This distinction has caused production bugs and engineering confusion. Every engine must know it.
+
+| Term | Means | Example |
+|---|---|---|
+| **Device** | A **browser installation** | Chrome on a laptop, Edge on a workstation |
+| **Machine** | A **physical endpoint** | Laptop, desktop, workstation, PC |
+
+**Historical problem:** The platform originally used "Device" to mean physical endpoint. This
+caused ambiguity — engineers, POs, and customers all read "device" as a physical machine.
+
+A terminology correction was introduced across backend services and data models. However:
+- **Older code may still use legacy "Device" naming** even when the concept is physically a Machine
+- **DB schemas, event payloads, and older APIs** may not yet reflect the corrected terminology
+- **UI labels are intentionally normalized** — they may say "endpoint" or "device" for UX reasons
+  even when the underlying backend entity is a Machine
+
+**Rules for every engine:**
+
+1. Before declaring a bug involving a "device": determine whether the subject is a Browser (Device)
+   or Physical Endpoint (Machine). They are different entities with different ownership models.
+
+2. When reading backend code, DB schemas, API contracts, event payloads, or migration scripts:
+   - "Device" often = browser install (unless proven otherwise by context)
+   - "Machine" = physical endpoint
+   - Naming inconsistency ≠ bug — it may be legacy terminology, not a defect
+
+3. Frontend labels do NOT map 1:1 to backend entity names. Always trace the API contract and
+   payload before concluding a data mismatch exists.
+
+4. Never propose a rename or terminology fix without first confirming:
+   - Which entity is actually being referenced in that specific file/layer
+   - Whether the inconsistency is legacy naming or an actual modelling error
+
+---
+
+### Service architecture
+
+```
+Clients:
+  sfn-web-ui      React 19 / Vite 7 — same-origin via axiosConfig.js:93,104
+  snf-browser-extn Node + Go agent — inferred routing, not confirmed in sampled routes
+
+Gateway:
+  sfn-gateway-api  Spring Cloud Gateway (all external traffic enters here)
+  sfn-eureka-api   Service Registry (all services register via lb://)
+
+Java Microservices (all behind gateway):
+  sfn-auth-api     Authentication (gateway routing not confirmed in sampled routes)
+  sfn-iam-api      Identity & Access Management  → /api/iam/**
+  sfn-tenants-api  Tenant management            → /api/tenants/**
+  sfn-events-api   Event processing             → /api/events/**
+  sfn-policy-api   Policy engine                → /api/policies/**
+```
+
+**Cross-service call patterns:**
+
+| Caller | Callee | How | Notes |
+|---|---|---|---|
+| `sfn-web-ui` | `sfn-gateway-api` | HTTP, same-origin | axiosConfig.js:93,104 |
+| `sfn-browser-extn` | `sfn-gateway-api` | Inferred | Not confirmed in sampled routes |
+| `sfn-tenants-api` | `sfn-iam-api` | Direct REST | Bypasses gateway — target hosts not confirmed |
+| `sfn-tenants-api` | `sfn-policy-api` | Direct REST | Bypasses gateway |
+| `sfn-tenants-api` | `sfn-events-api` | Direct REST | Bypasses gateway |
+
+**Kafka topics and their consumers:**
+
+| Topic | Producer | Consumer | Notes |
+|---|---|---|---|
+| `device-registration` | `sfn-iam-api` | `sfn-events-api` | |
+| `device-deleted` | `sfn-events-api` | `sfn-iam-api` | |
+| `extension-approval-decided` | `sfn-events-api` | `sfn-policy-api`, `sfn-tenants-api` | Fan-out to 2 consumers |
+| `extension-policy-changed` | `sfn-policy-api`, `sfn-tenants-api` | `sfn-events-api` | Two producers |
+| `policy-events` | `sfn-policy-api`, `sfn-tenants-api` | **NO LIVE CONSUMER** | ⚠️ Dead topic risk |
+| `quickstart-events` | `sfn-events-api` | `sfn-events-api` | Self-loop |
+
+**⚠️ Architecture flags to know:**
+- `policy-events` topic has NO confirmed live consumer — producing to it is likely wasted work
+- `sfn-tenants-api` makes direct REST calls that bypass the gateway — no gateway auth or circuit breaking on these paths
+- Browser extension gateway routing is inferred, not confirmed in sampled routes
+
+---
+
+### Services with manual migration scripts (as of last scan)
+
+| Service | Location | Notes |
+|---|---|---|
+| `sfn-events-api` | `src/main/resources/db/migration/` | See spec for next version |
+| `sfn-iam-api` | `src/main/resources/db/migration/` | Has version gaps — check spec |
+| `sfn-tenants-api` | `src/main/resources/db/migration/` | Has version gaps — check spec |
+
+Services WITHOUT migrations: `sfn-auth-api`, `sfn-eureka-api`, `sfn-gateway-api`, `sfn-policy-api`, `sfn-web-ui`, `snf-browser-extn`
+
+NEVER guess migration version numbers. Always read `.secufusion-migrations.json` first.
+