secufusion-mcp 2.1.5 → 2.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "secufusion-mcp",
-  "description": "SecuFusion MSSP platform dev agent — project-level spec driven, tenant-isolation enforced, zero-trust guardrails. Slash commands: /sfn:task (classify+plan+init), /sfn:resume (instant context restore), /sfn:build (implement AC), /sfn:checks (pre-PR gates), /sfn:review (adversarial review), /sfn:pr (ADO+PR docs), /sfn:retro (retrospective), /sfn:init (dynamic DNA generation), /sfn:refresh (update stale docs), /sfn:doctor (health check), /sfn:estate (cross-service map), /sfn:impact (blast radius), /sfn:status (dashboard), /sfn:search (past tasks).",
-  "version": "2.0.0",
+  "description": "SecuFusion MSSP platform dev agent — project-level spec driven, tenant-isolation enforced, zero-trust guardrails. 5 Core Slash Commands: /sfn-init (dynamic DNA + architecture diagram + watcher), /sfn-plan (philosophy check + intent WHY + classify + plan), /sfn-code (spec-driven implementation), /sfn-review (zero-tolerance 3-tier PR gate), /sfn-explore (on-demand service graph or blast-radius analysis).",
+  "version": "2.1.6",
   "author": {
     "name": "Motivity Labs"
   },

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. |
@@ -36,23 +35,25 @@
 
 The SecuFusion MCP has been refactored to align with the advanced MLMCPS framework principles, bringing massive efficiency and UX improvements:
 
-1. **Persona-Driven Slash Commands**: The monolithic agent prompt has been split. You can now use `/sfn_spec`, `/sfn_code`, and `/sfn_review` in your AI chat to instantly summon the Planner, Coder, or Reviewer persona, ensuring razor-sharp focus per phase.
+1. **5 High-Impact Slash Commands**: The monolithic agent prompt and fragmented utility scripts are consolidated into 5 clean, focused commands: `/sfn-init`, `/sfn-plan`, `/sfn-code`, `/sfn-review`, and `/sfn-explore`.
 2. **Subprocess PR Checks**: Tier 1 mechanical checks (`TENANT_ISOLATION`, `N_PLUS_ONE`, etc.) are now extracted into a standalone CLI script (`scripts/sfn-pr-check.js`), allowing them to be run by the AI *or* natively within your CI/CD pipelines.
 3. **Thin Index Token Discipline**: Context bloat is gone. Tools like `manage_task(read)` and `prime_session` now return lightweight "Thin Indexes"—compact Markdown summaries with absolute file paths—so the AI only reads the full JSON via `view_file` when truly necessary.
 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. **Poly-Repo DNA Discovery**: Through the standalone `secufusion-dna-plugin`, the AI can dynamically analyze the entire codebase of any poly-repo project at session start. It maps out microservices, API contracts, event topologies, frontend repos, and the `snf-browser-extn` extension on the fly, creating a living knowledge graph.
+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`.
 
 ---
 
-## 🧬 SecuFusion DNA Discovery Plugin
+## 🧬 Built-In DNA Discovery & Architecture Exploration
 
-A new standalone Claude plugin has been introduced: **SecuFusion DNA Discovery MCP** (`secufusion-dna-plugin`). This plugin empowers agents to autonomously discover, analyze, and build a living knowledge graph of your entire software ecosystem when handed over to a new team member.
+`secufusion-mcp` includes native ecosystem-wide discovery tools:
 
-**Key Features:**
 - **Dynamic Stack Analysis:** Identifies Java/Spring, Node, Docker, and other frameworks on the fly.
-- **Slash Command Agents:** Use `/analyze`, `/map-architecture`, and `/blast-radius` directly in your AI chat to orchestrate complex codebase queries.
 - **Automated Dependency Mapping:** Generates cross-service dependency maps and evaluates the blast radius of potential changes.
+- **Interactive Commands:** Use `/sfn-init` to map your entire workspace and launch the watcher, and `/sfn-explore` on-demand to render Mermaid architecture graphs or analyze component blast radius.
 
 ---
 
@@ -144,13 +145,13 @@ npx secufusion-mcp
 ### Option 2 — Global install
 
 ```bash
-npm install -g secufusion-mcp@2.1.4
+npm install -g secufusion-mcp@2.1.9
 ```
 
 ### Option 3 — Local project install
 
 ```bash
-npm install --save-dev secufusion-mcp@2.1.4
+npm install --save-dev secufusion-mcp@2.1.9
 ```
 
 ---
@@ -946,86 +947,45 @@ If any of these are physically missing from your local workspace folder, a `[WAR
 
 ## ⚡ 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. Silently runs the **Philosophy Engine (Phase -1)** to ensure the task's WHY and RISK are sound (even for bugs). Reads `.secufusion-project-spec.json` for golden rules and `dna.json` to determine blast radius. 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
+All commands are natively registered as Claude Plugins and appear directly in the Claude IDE `/` command picker. The workflow is streamlined into **5 core commands** with zero redundancy:
+
+| # | Command | Persona / Role | When to run | What it does |
+|---|---|---|---|---|
+| **1** | `/sfn-init` | Ecosystem Architect | First thing in morning, on new machine, or new clone | Bootstraps workspace, validates mandatory repos against `.secufusion-project-spec.json`, extracts domain models, API endpoints, Kafka topics, generates `.secufusion/dna.json`, builds full Mermaid architecture diagram, and launches continuous background file watcher (`chokidar`). |
+| **2** | `/sfn-plan <ticket-id or desc>` | `planner.md` | When starting any story, chore, feature, bug, or hotfix | Evaluates Phase -1 Philosophy gate (WHY/WHO/WHAT/RISK), creates Markdown business intent (`spec_create_intent`), primes session AST context (`prime_session`), classifies task boundaries (`classify_task`), enforces **Rule 5 STRICT YIELD** for your green light, then generates structured `plan.md`. |
+| **3** | `/sfn-code` | `coder.md` | After you approve the plan | Implements strictly according to the approved plan. Enforces zero-trust standards: mandatory tenant isolation on DB operations, proper `@Transactional` scoping, DTO mapping rules, and logs anti-patterns to `.rejected-patterns.json`. |
+| **4** | `/sfn-review` | `reviewer.md` | After coding is done, before opening a PR | Adversarial PR gate running 3 tiers in a single pass: (1) Mechanical AST guardrails (tenant isolation, N+1 queries, hardcoded endpoints), (2) AI file-by-file code review, (3) Context-aware task evaluation against spec. Blocks PR if Tier 1 violations exist. |
+| **5** | `/sfn-explore [map \| <component>]` | Architecture Explorer | On-demand for cross-service impact & system maps | Dual-mode architecture query: `/sfn-explore map` renders the full cross-service Mermaid architecture diagram; `/sfn-explore <component-or-path>` calculates blast radius and affected downstream consumers before making breaking changes. |
+
+---
+
+### 📊 The 5-Command SDLC Flow at a Glance
+
+```
+Morning / First Setup
+  │
+  ▼
+/sfn-init                    ← Scans workspace, writes dna.json, draws Mermaid diagram, starts watcher
+  │
+  ├─► /sfn-explore map        (Optional on-demand: view ecosystem graph)
+  │
+Ticket Arrives (Feature / Bug / Hotfix)
+  │
+  ▼
+/sfn-plan WI-XXXX            ← Phase -1 Philosophy check → Intent WHY → Prime → Classify → STRICT YIELD
+  │
+  ├─► User Approves Plan ✅
+  │
+  ▼
+/sfn-code                    ← Implement approved plan with zero-trust guardrails
+  │
+  ├─► /sfn-explore <comp>    (Optional: verify blast radius if touching shared interfaces)
+  │
+  ▼
+/sfn-review                  ← 3-Tier PR Gate: mechanical AST checks + AI review + spec matching
+  │
+  ▼
+PR Ready to Merge 🚀
 ```
 
 ---

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.
+