secufusion-mcp 2.1.6 → 2.2.0

package/mcp/dist/server.js

@@ -6,13 +6,13 @@
  * Provides developer-workflow tooling for the SecuFusion platform:
  *   - manage_feature_spec  : create / update task blueprints (.current-task-spec.md)
  *   - log_rejected_pattern : record bad patterns so they are never repeated (.rejected-patterns.json)
- *   - run_pre_pr_checks    : gate PRs via AST-level linters (ESLint / Maven Checkstyle) + structural checks
+ *   - /sfn:review          : AI-driven reviewer that validates architecture, patterns, and guardrails
  *
  * Guardrails enforced:
  *   1. TENANT SAFETY AUTOMATED: Active scanning of *Repository.java for tenantId scoping.
  *   2. Code hygiene (console.log, unused vars, formatting) enforced via ESLint / Checkstyle — not regex.
  *   3. No hardcoded UAT/Prod IPs or environment URLs.
- *   4. Every modified JPA @Entity must have a matching Flyway SQL migration.
+ *   4. Every modified JPA @Entity must have a matching manual migration script (applied against PostgreSQL before deployment).
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -49,18 +49,16 @@ function getWorkspaceRoot() {
     const rootMarkers = [".git", "package.json", "pom.xml", ".secufusion-project-spec.json", ".agents"];
     for (let i = 0; i < 10; i++) {
         for (const marker of rootMarkers) {
-            if (fs.existsSync(path.join(currentDir, marker))) {
+            if (fs.existsSync(path.join(currentDir, marker)))
                 return currentDir;
-            }
         }
         const parent = path.dirname(currentDir);
         if (parent === currentDir)
-            break; // Reached filesystem root
+            break;
         currentDir = parent;
     }
-    return ROOT; // Fallback to ROOT directory
+    return ROOT;
 }
-/** Resolve a path relative to workspace root (where the MCP server is invoked). */
 function resolve(file) {
     return path.resolve(getWorkspaceRoot(), file);
 }
@@ -72,6 +70,17 @@ function readFileSafe(filePath) {
         return null;
     }
 }
+function readJson(filePath) {
+    const content = readFileSafe(filePath);
+    if (!content)
+        return null;
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
 function loadProjectSpec(wsRoot) {
     const SPEC_FILE = ".secufusion-project-spec.json";
     const candidates = [
@@ -100,9 +109,74 @@ function getCurrentBranch(cwd) {
         return "unknown-branch";
     }
 }
-// ─────────────────────────────────────────────
-//  Telemetry & Compression helpers
-// ─────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+//  Migration spec helpers
+//  Source of truth: .secufusion-migrations.json
+//  SecuFusion uses MANUAL migration scripts — NOT auto-applied on boot.
+//  Scripts must be run manually against PostgreSQL BEFORE deployment.
+//  Every tool that touches DB-related work calls these helpers.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Load .secufusion-migrations.json. Searches workspace root then scripts/ subfolder. */
+function loadMigrationSpec(wsRoot) {
+    const MIGRATION_FILE = ".secufusion-migrations.json";
+    const candidates = [
+        path.resolve(wsRoot, MIGRATION_FILE),
+        path.resolve(wsRoot, "scripts", MIGRATION_FILE),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c)) {
+            try {
+                return JSON.parse(readFileSafe(c) || "null");
+            }
+            catch { }
+        }
+    }
+    return null;
+}
+/** Return per-service migration context. Accepts exact or partial service names. */
+function getMigrationContextForService(migrationSpec, serviceName) {
+    if (!migrationSpec)
+        return null;
+    const services = migrationSpec.services ?? {};
+    if (services[serviceName])
+        return services[serviceName];
+    const key = Object.keys(services).find(k => k.includes(serviceName) || serviceName.includes(k.replace("sfn-", "").replace("-api", "")));
+    return key ? services[key] : null;
+}
+/** Return the next suggested migration filename (e.g. "V40__{description}.sql"). */
+function getNextMigrationVersion(migrationSpec, serviceName) {
+    if (!migrationSpec)
+        return null;
+    const guardrails = migrationSpec.mcp_guardrails ?? {};
+    const perService = guardrails.per_service_next_versions ?? {};
+    const serviceKey = Object.keys(perService).find(k => k.includes(serviceName) || serviceName.includes(k.replace("sfn-", "").replace("-api", "")));
+    if (serviceKey)
+        return perService[serviceKey].example ?? null;
+    const ctx = getMigrationContextForService(migrationSpec, serviceName);
+    return ctx?.current_state?.next_suggested ?? null;
+}
+/** Return confirmed gap version numbers for a service. Do NOT reuse these. */
+function getMigrationGaps(migrationSpec, serviceName) {
+    const ctx = getMigrationContextForService(migrationSpec, serviceName);
+    return ctx?.organization?.version_gaps ?? [];
+}
+/** Recursively find files whose name ends with the given suffix. */
+function findFilesRecursive(dir, suffix) {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                results.push(...findFilesRecursive(full, suffix));
+            else if (entry.name.endsWith(suffix))
+                results.push(full);
+        }
+    }
+    catch { }
+    return results;
+}
 function compressCode(code) {
     return code
         .replace(/\/\*[\s\S]*?\*\//g, "") // Remove multi-line comments
@@ -335,8 +409,8 @@ server.tool("log_rejected_pattern", "Record a coding pattern that was rejected b
 // ─── Tool 4: manage_project_spec ─────────────────────────────────────────────
 server.tool("manage_project_spec", "Manages the .secufusion-project-spec.json file — the permanent project memory containing all service ports, repos, domains, infrastructure config, coding patterns, auth flow, and golden rules. Every session must read this before writing any code.", {
     action: z
-        .enum(["read", "update", "get_service", "get_golden_rules", "get_coding_patterns"])
-        .describe("Action to perform: read (full spec), get_service (one microservice block), get_golden_rules (golden_rules + rejected_patterns), get_coding_patterns (coding_patterns block), update (surgical dot-notation write)."),
+        .enum(["read", "update", "get_service", "get_golden_rules", "get_coding_patterns", "get_migration_context"])
+        .describe("Action to perform: read (full spec), get_service (one microservice block), get_golden_rules (golden_rules + rejected_patterns), get_coding_patterns (coding_patterns block), update (surgical dot-notation write), get_migration_context (loads migration rules for a service)."),
     service_name: z
         .string()
         .optional()
@@ -465,6 +539,37 @@ server.tool("manage_project_spec", "Manages the .secufusion-project-spec.json fi
             content: [{ type: "text", text: JSON.stringify(block, null, 2) }],
         }, inputChars);
     }
+    // ── action: get_migration_context ─────────────────────────────────────────
+    if (action === "get_migration_context") {
+        if (!service_name) {
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: "ERROR: 'service_name' is required when action=get_migration_context." }],
+            }, inputChars);
+        }
+        const migSpec = loadMigrationSpec(getWorkspaceRoot());
+        if (!migSpec) {
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: "ERROR: .secufusion-migrations.json not found. Run /sfn:init to generate it." }],
+            }, inputChars);
+        }
+        const ctx = getMigrationContextForService(migSpec, service_name);
+        if (!ctx) {
+            return appendTelemetry({
+                isError: true,
+                content: [{ type: "text", text: `No migration context found for service: ${service_name}. (Does this service have a database?)` }],
+            }, inputChars);
+        }
+        // Return a combined payload of service context and global guardrails
+        const payload = {
+            service_context: ctx,
+            mcp_guardrails: migSpec.mcp_guardrails ?? {}
+        };
+        return appendTelemetry({
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        }, inputChars);
+    }
     // ── action: update ────────────────────────────────────────────────────────
     if (action === "update") {
         if (!update_path) {
@@ -590,47 +695,47 @@ server.tool("spec_create_intent", "Creates a structured Markdown intent file in
         ? (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._
+    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({
@@ -764,17 +869,6 @@ function generateNewTaskFolder(workItemId, title, tasksRoot) {
     }
     return path.join(tasksRoot, `${taskTypeStr}-${numericId}-${slug}`);
 }
-function readJson(filePath) {
-    const raw = readFileSafe(filePath);
-    if (!raw)
-        return null;
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
 function readRegistry() {
     return readJson(resolve(REGISTRY_FILE)) || [];
 }
@@ -1124,10 +1218,10 @@ server.tool("record_retrospective", "Records a structured retrospective after ta
     steps_actual: z.number().describe("How many implementation steps were actually needed."),
     unplanned_files: z.array(z.string()).optional().describe("Files that were modified but NOT in the plan."),
     missed_files: z.array(z.string()).optional().describe("Files that were in the plan but NOT touched."),
-    migration_risk_actual: z.string().optional().describe("Actual Flyway migration risk encountered. 'SAFE' | 'RISKY' | 'DANGEROUS' | 'NONE'"),
+    migration_risk_actual: z.string().optional().describe("Actual migration script risk encountered. 'SAFE' | 'RISKY' | 'DANGEROUS' | 'NONE'"),
     breaking_changes_actual: z.number().optional().describe("How many actual breaking changes were found. 0 if none."),
     performance_issues_found: z.boolean().optional().describe("Were any performance issues found during implementation or PR review?"),
-    pre_pr_attempts: z.number().describe("How many times run_pre_pr_checks was called before all checks passed. 1 = passed first attempt (perfect), 2+ = needed fixes"),
+    pre_pr_attempts: z.number().describe("How many times /sfn:review was called before all checks passed. 1 = passed first attempt (perfect), 2+ = needed fixes"),
     checks_that_failed: z.array(z.string()).optional().describe("List of check names that failed at least once."),
     scope_creep_detected: z.boolean().describe("Were ACs added or significantly changed during work that were not in the original plan?"),
     scope_creep_description: z.string().optional().describe("Only if scope_creep_detected=true. What changed and why."),
@@ -1518,13 +1612,32 @@ server.tool("philosophy_check", "MANDATORY PHASE -1 STEP — runs BEFORE classif
     const dnaRiskNotes = [];
     const text = `${title} ${description}`.toLowerCase();
     const wordCount = description.trim().split(/\s+/).length;
+    const mentionedServices = dnaServices.filter((s) => text.includes(s));
     // [DNA-1] DB entities mentioned in story — each known entity = real schema blast
-    const mentionedEntities = dnaEntities.filter(e => text.includes(e));
+    const mentionedEntities = dnaEntities.filter((e) => text.includes(e));
     if (mentionedEntities.length > 0) {
         const entityRisk = Math.min(mentionedEntities.length * 10, 40);
         dna_risk_bonus += entityRisk;
         dnaRiskNotes.push(`DB entities: ${mentionedEntities.join(", ")} (+${entityRisk})`);
     }
+    // [DNA-1b] Migration Spec Check
+    if (mentionedEntities.length > 0 || /\bmigration\b/i.test(text) || /\btable\b/i.test(text) || /\bcolumn\b/i.test(text)) {
+        const migSpec = loadMigrationSpec(wsRoot);
+        if (migSpec && mentionedServices.length > 0) {
+            mentionedServices.forEach((s) => {
+                const ctx = getMigrationContextForService(migSpec, s);
+                if (ctx && ctx.has_migrations) {
+                    dna_risk_bonus += 15;
+                    dnaRiskNotes.push(`[MIGRATION SPEC] Manual migration script required for ${s} (Next: ${ctx.next_suggested}) (+15)`);
+                }
+            });
+        }
+        else if (migSpec && mentionedEntities.length > 0) {
+            // If service isn't mentioned by name but entities are, we still want to warn globally
+            dna_risk_bonus += 10;
+            dnaRiskNotes.push(`[MIGRATION SPEC] DB touched. Ensure manual migration scripts are applied to PostgreSQL before deploy. (+10)`);
+        }
+    }
     // [DNA-2] Kafka topics — fan-out cascades to all consumers
     const mentionedTopics = dnaTopics.filter((t) => {
         const tn = (t.name || t.topic || "").toLowerCase();
@@ -1548,7 +1661,6 @@ server.tool("philosophy_check", "MANDATORY PHASE -1 STEP — runs BEFORE classif
         dnaRiskNotes.push("Shared multi-tenant auth — cross-tenant blast (+25)");
     }
     // [DNA-5] Polyglot service coordination — 3+ services = integration risk
-    const mentionedServices = dnaServices.filter(s => text.includes(s));
     if (mentionedServices.length >= 3) {
         dna_risk_bonus += 15;
         dnaRiskNotes.push(`Multi-service: ${mentionedServices.slice(0, 4).join(", ")} (+15)`);
@@ -1916,7 +2028,7 @@ server.tool("classify_task", "MANDATORY FIRST STEP for every task without except
     const corpus = (title + " " + description).toLowerCase();
     const BACKEND_SIGNALS = [
         "api", "endpoint", "service", "repository", "database", "db", "query",
-        "migration", "flyway", "kafka", "consumer", "producer", "topic",
+        "migration", "kafka", "consumer", "producer", "topic",
         "backend", "server", "rest", "json response", "payload",
         ...learnedSignals.backend, ...learnedSignals.phrase, ...learnedSignals.bug_category
     ];
@@ -2259,7 +2371,7 @@ server.tool("classify_task", "MANDATORY FIRST STEP for every task without except
         "topic", "message", "schema", "kafka", "producer", "consumer", "payload",
     ];
     const DB_CHANGE_SIGNALS = [
-        "column", "table", "migration", "flyway", "entity", "@entity",
+        "column", "table", "migration", "entity", "@entity",
         "schema", "alter", "add column", "drop column", "rename column",
     ];
     if (spec && spec.microservices) {
@@ -2615,7 +2727,7 @@ server.tool("analyze_impact", "Traces the SecuFusion inter-service call graph an
         }
         else if (change_type === "entity" || change_type === "field") {
             output += `- Check all \`@Query\` annotations across repositories for references to this field/entity\n`;
-            output += `- Include a Flyway migration — flag tier: SAFE/RISKY/DANGEROUS\n`;
+            output += `- Include a migration script in src/main/resources/db/migration/ -- MANUAL, run against PostgreSQL BEFORE deploy -- flag tier: SAFE/RISKY/DANGEROUS\n`;
         }
         else if (change_type === "kafka_topic") {
             output += `- Schema change requires coordinated deployment of producer + ALL consumers\n`;
@@ -2841,7 +2953,7 @@ server.tool("score_change_risk", "Quantifies the risk of a planned change BEFORE
         dbScore += 12;
         findings.push(`⚠️ DB: NOT NULL column without DEFAULT — RISKY (+12 pts). Will fail on non-empty table.`);
     }
-    else if (/flyway|migration|@entity|add column/.test(corpus)) {
+    else if (/migration|@entity|add column|alter table/.test(corpus)) {
         dbScore += 3;
         findings.push(`✅ DB: Additive migration detected — SAFE tier (+3 pts).`);
     }
@@ -3251,1330 +3363,6 @@ server.tool("suggest_test_scenarios", "Auto-generates a complete test plan from
     }
     return appendTelemetry({ content: [{ type: "text", text: out }] }, inputChars);
 });
-// ─── Tool 16: run_pre_pr_checks_with_reviewer_agent ──────────────────────────
-// Unified, single-call PR review system. Three sequential tiers that all share
-// the same file-reading pass — no duplicate I/O, no duplicate logic.
-//
-// ┌──────────────────────────────────────────────────────────────────────────┐
-// │ TIER 1 — Mechanical Checks (zero-tolerance, deterministic)               │
-// │   P1 TENANT_ISOLATION  — every Repository query scoped to tenantId       │
-// │   P2 N_PLUS_ONE        — no repository calls inside loops                │
-// │   P3 MISSING_INDEX     — new query columns have a migration index         │
-// │   P4 KAFKA_SYNC        — no sync DB/REST work inside @KafkaListener      │
-// │   P5 EARLY_RETURN      — no early returns; single exit point per method  │
-// ├──────────────────────────────────────────────────────────────────────────┤
-// │ TIER 2 — AI File Reviewer (runs after Tier 1 passes)                     │
-// │   Pass 6: reads each changed file and applies architectural heuristics    │
-// │   Checks: obvious comments, hardcoded URLs, missing @Transactional,      │
-// │   missing @PreAuthorize, debug statements, exception swallowing,          │
-// │   TypeScript `any` overuse, missing Flyway for @Entity, cross-service     │
-// │   calls without timeouts. Produces inline, file-level comments.           │
-// ├──────────────────────────────────────────────────────────────────────────┤
-// │ TIER 3 — Context Reviewer (runs after Tier 2 passes)                     │
-// │   Reads full task brain: spec, decisions, ACs, scenarios, files-touched  │
-// │   + project-spec golden_rules + rejected patterns.                        │
-// │   Cross-references to find: missed ACs, decision drift, scope creep,     │
-// │   rejected pattern violations, test coverage gaps, golden rule breaches.  │
-// │   Produces structured findings: CRITICAL / WARNING / INFO / PRAISE        │
-// └──────────────────────────────────────────────────────────────────────────┘
-//
-// Verdict: ✅ APPROVED | ❌ CHANGES_REQUESTED | 💬 DISCUSS
-// Cost:    Tracked per tier. Tier 1 is free. Tiers 2-3 have per-file cost.
-server.tool("run_pre_pr_checks_with_reviewer_agent", "Unified, single-call PR review system — runs BEFORE raising a PR. " +
-    "Three sequential tiers sharing one file-read pass: " +
-    "(1) Five deterministic mechanical checks (tenant isolation, N+1, missing index, Kafka sync, early returns). " +
-    "(2) AI file reviewer — reads each changed file and applies architectural heuristics (hardcoded URLs, missing annotations, debug statements, etc.). " +
-    "(3) Context reviewer — reads the full task brain (spec, ACs, decisions, scenarios) + project-spec golden rules and cross-references against all changed files. " +
-    "Verdict: APPROVED (merge ready) | CHANGES_REQUESTED (blocking issues) | DISCUSS (non-blocking concerns). " +
-    "Call this in Phase 4 after all ACs are complete. It replaces the former separate run_pre_pr_checks + reviewer_agent calls.", {
-    work_item_id: z.string().describe("Active work item ID, e.g. 'WI-1234'."),
-    skip_checks: z.array(z.enum(["tenant_isolation", "n_plus_one", "missing_index", "kafka_sync", "early_return", "ai_review", "context_review"])).optional().default([]).describe("Checks to skip. Mechanical: tenant_isolation | n_plus_one | missing_index | kafka_sync | early_return. " +
-        "Review tiers: ai_review (Tier 2) | context_review (Tier 3). " +
-        "Use sparingly — only for acknowledged legacy files or CI environments where context is unavailable."),
-    suppressions: z.array(z.object({
-        check: z.enum(["TENANT_ISOLATION", "N_PLUS_ONE", "MISSING_INDEX", "KAFKA_SYNC", "EARLY_RETURN"]),
-        method: z.string().describe("Method name to suppress, e.g. 'countOrphanedByDeviceUserId'"),
-        reason: z.string().describe("Mandatory justification for suppression")
-    })).optional().default([]).describe("Method-scoped suppressions with mandatory reasons.")
-}, async ({ work_item_id, skip_checks = [], suppressions = [] }) => {
-    try {
-        const cp = require('child_process');
-        const __dirname = require('url').fileURLToPath(new URL('.', import.meta.url));
-        const scriptPath = require('path').resolve(__dirname, '../../scripts/sfn-pr-check.js');
-        const args = JSON.stringify({ work_item_id, skip_checks, suppressions });
-        const output = cp.execFileSync(process.execPath, [scriptPath, args], { encoding: 'utf-8' });
-        return { content: [{ type: 'text', text: output }] };
-    }
-    catch (e) {
-        return { content: [{ type: 'text', text: e.stdout || e.message }], isError: true };
-    }
-});
-// Full-spectrum PR review system.
-//
-// Architecture: two-tier review pipeline
-//   Tier 1 — Mechanical checks (Passes 1-5): deterministic, zero-tolerance.
-//             Any failure = CHANGES_REQUESTED immediately, no AI pass runs.
-//   Tier 2 — AI Reviewer (Pass 6): thoughtful, contextual architectural review.
-//             Only runs after all mechanical checks pass.
-//             Produces nuanced verdicts: APPROVED / CHANGES_REQUESTED / DISCUSS.
-//
-// Checks:
-//   Pass 1 — TENANT_ISOLATION : every *Repository method scoped to tenantId
-//   Pass 2 — N_PLUS_ONE       : no repository calls inside loops
-//   Pass 3 — MISSING_INDEX    : new query columns should have a migration index
-//   Pass 4 — KAFKA_SYNC       : no sync DB/REST work inside @KafkaListener
-//   Pass 5 — EARLY_RETURN     : no early returns in Java/.ts methods
-//   Pass 6 — AI_REVIEWER      : thoughtful architectural review (runs after P1-5 clean)
-server.tool("run_pre_pr_checks", "Full-spectrum PR review system — runs BEFORE raising a PR. " +
-    "Tier 1: five mechanical checks (tenant isolation, N+1, missing index, Kafka sync, early returns). " +
-    "Tier 2: AI-powered architectural reviewer that reads every changed file and produces a thoughtful code review. " +
-    "Verdict: APPROVED (merge ready) | CHANGES_REQUESTED (blocking issues found) | DISCUSS (non-blocking concerns worth a conversation). " +
-    "Call this in Phase 4 after all ACs are complete. Add check names to skip_checks only for acknowledged legacy files.", {
-    work_item_id: z.string().describe("Active work item ID, e.g. 'WI-1234'."),
-    skip_checks: z.array(z.enum(["tenant_isolation", "n_plus_one", "missing_index", "kafka_sync", "early_return", "ai_review"])).optional().default([]).describe("Checks to skip. Options: tenant_isolation | n_plus_one | missing_index | kafka_sync | early_return | ai_review. " +
-        "Use sparingly — only for acknowledged legacy files that pre-date the rule."),
-    suppressions: z.array(z.object({
-        check: z.enum(["TENANT_ISOLATION", "N_PLUS_ONE", "MISSING_INDEX", "KAFKA_SYNC", "EARLY_RETURN"]),
-        method: z.string().describe("Method name to suppress, e.g. 'countOrphanedByDeviceUserId'"),
-        reason: z.string().describe("Mandatory justification for suppression")
-    })).optional().default([]).describe("Method-scoped suppressions with mandatory reasons.")
-}, async ({ work_item_id, skip_checks = [], suppressions = [] }) => {
-    const inputChars = JSON.stringify({ work_item_id, skip_checks, suppressions }).length;
-    const wsRoot = getWorkspaceRoot();
-    // ── Resolve task folder ────────────────────────────────────────────────
-    const registry = readRegistry();
-    const taskEntry = registry.find(r => r["work_item_id"] === work_item_id);
-    let taskDir = null;
-    if (taskEntry?.["folder_name"]) {
-        taskDir = path.resolve(wsRoot, `.secufusion/tasks/${taskEntry["folder_name"]}`);
-    }
-    if (!taskDir || !fs.existsSync(taskDir)) {
-        const tasksBase = path.resolve(wsRoot, ".secufusion/tasks");
-        if (fs.existsSync(tasksBase)) {
-            const folders = fs.readdirSync(tasksBase);
-            const match = folders.find(f => f.startsWith(work_item_id));
-            if (match)
-                taskDir = path.join(tasksBase, match);
-        }
-    }
-    if (!taskDir || !fs.existsSync(taskDir)) {
-        return appendTelemetry({
-            isError: true,
-            content: [{ type: "text", text: `❌ Task folder not found for ${work_item_id}. Call manage_task(initialize) first.` }]
-        }, inputChars);
-    }
-    // ── Load files-touched ─────────────────────────────────────────────────
-    const filesPath = path.join(taskDir, "files-touched.json");
-    let filesTouched = [];
-    try {
-        filesTouched = JSON.parse(readFileSafe(filesPath) || "[]");
-    }
-    catch { }
-    if (filesTouched.length === 0) {
-        return appendTelemetry({
-            content: [{ type: "text", text: `⚠️ No files logged for ${work_item_id}. Log files with manage_task(log_file_touched) before running checks.` }]
-        }, inputChars);
-    }
-    const fileRecords = [];
-    for (const ft of filesTouched) {
-        const abs = path.resolve(wsRoot, ft.file_path);
-        const raw = readFileSafe(abs) || "";
-        const ext = path.extname(ft.file_path).toLowerCase();
-        fileRecords.push({
-            file_path: ft.file_path,
-            change_summary: ft.change_summary,
-            content: raw,
-            lines: raw.split("\n"),
-            ext,
-            isJava: ext === ".java",
-            isTS: ext === ".ts" || ext === ".tsx",
-            isRepo: /Repository/i.test(path.basename(ft.file_path)) && ext === ".java",
-            isKafka: raw.includes("@KafkaListener") || raw.includes("KafkaListener"),
-            isMigration: ft.file_path.includes("migration") || ft.file_path.includes("flyway") || ext === ".sql",
-        });
-    }
-    const allFindings = [];
-    const passResults = [];
-    // ══════════════════════════════════════════════════════════════════════
-    // PASS 1 — TENANT_ISOLATION
-    // Rule: every Repository method must filter by tenantId
-    // ══════════════════════════════════════════════════════════════════════
-    const p1Findings = [];
-    const p1Suppressed = [];
-    if (!skip_checks.includes("tenant_isolation")) {
-        for (const f of fileRecords.filter(f => f.isRepo)) {
-            // Find method signatures in repository interface/class
-            const methodPattern = /(?:List|Optional|Page|long|int|boolean|void|[A-Z]\w+)\s+\w+\s*\([^)]*\)/g;
-            const queryAnnotations = [];
-            f.lines.forEach((line, idx) => {
-                if (/@Query\s*\(/i.test(line))
-                    queryAnnotations.push(idx);
-            });
-            // Check derived method names
-            f.lines.forEach((line, idx) => {
-                const derivedMatch = line.match(/(?:find|delete|count|exists)\w+By(\w+)/);
-                if (derivedMatch) {
-                    const byClause = derivedMatch[1].toLowerCase();
-                    if (!byClause.includes("tenantid") && !byClause.includes("tenant")) {
-                        let suppressionReason = "";
-                        const explicitSup = suppressions.find(s => s.check === "TENANT_ISOLATION" && (s.method === derivedMatch[0] || s.method.endsWith(`.${derivedMatch[0]}`)));
-                        if (explicitSup)
-                            suppressionReason = explicitSup.reason;
-                        else {
-                            for (let i = Math.max(0, idx - 5); i < idx; i++) {
-                                const match = f.lines[i].match(/@TenantScopeException\s*\(\s*"([^"]+)"\s*\)/i);
-                                if (match)
-                                    suppressionReason = match[1];
-                            }
-                        }
-                        if (suppressionReason) {
-                            p1Suppressed.push({ file: f.file_path, line: idx + 1, reason: suppressionReason, method: derivedMatch[0] });
-                        }
-                        else {
-                            p1Findings.push({
-                                check: "TENANT_ISOLATION",
-                                severity: "BLOCKING",
-                                file: f.file_path,
-                                line: idx + 1,
-                                message: `Derived query \`${line.trim()}\` does not filter by tenantId`,
-                                suggestion: "Rename to include AndTenantId: e.g. findByIdAndTenantId(UUID id, UUID tenantId)",
-                            });
-                        }
-                    }
-                }
-            });
-            // Check @Query annotations for tenantId
-            queryAnnotations.forEach(annotIdx => {
-                // Look at this line and next 3 lines for the query body
-                const queryBlock = f.lines.slice(annotIdx, annotIdx + 5).join(" ");
-                if (!/tenantId|tenant_id|:tenantId/i.test(queryBlock)) {
-                    let suppressionReason = "";
-                    let queryMethodName = "";
-                    const methodDeclMatch = queryBlock.match(/(?:List|Optional|Page|long|int|boolean|void|[A-Z]\w+)\s+(\w+)\s*\(/);
-                    if (methodDeclMatch)
-                        queryMethodName = methodDeclMatch[1];
-                    if (queryMethodName) {
-                        const explicitSup = suppressions.find(s => s.check === "TENANT_ISOLATION" && (s.method === queryMethodName || s.method.endsWith(`.${queryMethodName}`)));
-                        if (explicitSup)
-                            suppressionReason = explicitSup.reason;
-                    }
-                    if (!suppressionReason) {
-                        for (let i = Math.max(0, annotIdx - 5); i < annotIdx; i++) {
-                            const match = f.lines[i].match(/@TenantScopeException\s*\(\s*"([^"]+)"\s*\)/i);
-                            if (match)
-                                suppressionReason = match[1];
-                        }
-                    }
-                    if (suppressionReason) {
-                        p1Suppressed.push({ file: f.file_path, line: annotIdx + 1, reason: suppressionReason, method: queryMethodName || "@Query method" });
-                    }
-                    else {
-                        p1Findings.push({
-                            check: "TENANT_ISOLATION",
-                            severity: "BLOCKING",
-                            file: f.file_path,
-                            line: annotIdx + 1,
-                            message: `@Query at line ${annotIdx + 1} does not include tenantId filter`,
-                            suggestion: "Add WHERE e.tenantId = :tenantId to the JPQL/SQL query",
-                        });
-                    }
-                }
-            });
-        }
-    }
-    allFindings.push(...p1Findings);
-    passResults.push({ name: "TENANT_ISOLATION", skipped: skip_checks.includes("tenant_isolation"), passed: p1Findings.length === 0, count: p1Findings.length, suppressedCount: p1Suppressed.length });
-    // Auto-log suppressions to decisions.json
-    if (p1Suppressed.length > 0 && work_item_id) {
-        const tasksRoot = resolve(TASKS_DIR);
-        const dir = resolveTaskFolder(work_item_id, tasksRoot);
-        if (dir) {
-            const decisionsPath = path.join(dir, "decisions.json");
-            const decisions = readJson(decisionsPath) || [];
-            let modified = false;
-            for (const sup of p1Suppressed) {
-                const desc = `Exempted TENANT_ISOLATION on ${sup.method}`;
-                if (!decisions.some(d => d.decision === desc)) {
-                    decisions.push({
-                        id: decisions.length + 1,
-                        decision: desc,
-                        rationale: sup.reason,
-                        logged_at: new Date().toISOString()
-                    });
-                    modified = true;
-                }
-            }
-            if (modified)
-                writeFile(decisionsPath, JSON.stringify(decisions, null, 2));
-        }
-    }
-    // ══════════════════════════════════════════════════════════════════════
-    // PASS 2 — N_PLUS_ONE
-    // Rule: no repository method calls inside for/forEach loops
-    // ══════════════════════════════════════════════════════════════════════
-    const p2Findings = [];
-    if (!skip_checks.includes("n_plus_one")) {
-        for (const f of fileRecords.filter(f => f.isJava || f.isTS)) {
-            let braceDepth = 0;
-            let inLoop = false;
-            let loopStartDepth = -1;
-            f.lines.forEach((line, idx) => {
-                const openBraces = (line.match(/\{/g) || []).length;
-                const closeBraces = (line.match(/\}/g) || []).length;
-                const isLoopLine = /\b(for|forEach|stream\(\)|\.map\(|\.forEach\(|while\s*\()/i.test(line);
-                if (isLoopLine && !inLoop) {
-                    inLoop = true;
-                    loopStartDepth = braceDepth;
-                }
-                if (inLoop) {
-                    const repoCallPattern = /\.(findById|findByIdAndTenantId|findAll|findAllBy|save|saveAll|delete|deleteById|existsById|count)\s*\(/;
-                    if (repoCallPattern.test(line)) {
-                        p2Findings.push({
-                            check: "N_PLUS_ONE",
-                            severity: "BLOCKING",
-                            file: f.file_path,
-                            line: idx + 1,
-                            message: `Repository call \`${(line.match(repoCallPattern) || [""])[0]}\` detected inside a loop`,
-                            suggestion: "Extract IDs first, then use findAllById() / saveAll() outside the loop",
-                        });
-                    }
-                }
-                braceDepth += openBraces - closeBraces;
-                if (inLoop && braceDepth <= loopStartDepth) {
-                    inLoop = false;
-                    loopStartDepth = -1;
-                }
-            });
-        }
-    }
-    allFindings.push(...p2Findings);
-    passResults.push({ name: "N_PLUS_ONE", skipped: skip_checks.includes("n_plus_one"), passed: p2Findings.length === 0, count: p2Findings.length });
-    // ══════════════════════════════════════════════════════════════════════
-    // PASS 3 — MISSING_INDEX
-    // Rule: if a new Repository query filters/sorts by a column, the
-    // migration MUST contain a CREATE INDEX for that column
-    // ══════════════════════════════════════════════════════════════════════
-    const p3Findings = [];
-    if (!skip_checks.includes("missing_index")) {
-        // Collect columns referenced in queries across all repo files
-        const queryColumns = [];
-        for (const f of fileRecords.filter(f => f.isRepo)) {
-            f.lines.forEach((line, idx) => {
-                // Derived method columns: findByStatusAndTenantId → status, tenantId
-                const derivedMatch = line.match(/(?:find|delete|count|exists)\w+By([\w]+)/);
-                if (derivedMatch) {
-                    const parts = derivedMatch[1].replace(/And|Or/g, ",").split(",");
-                    for (const p of parts) {
-                        const col = p.charAt(0).toLowerCase() + p.slice(1);
-                        if (!["tenantId", "id"].includes(col)) {
-                            queryColumns.push({ col, file: f.file_path, line: idx + 1 });
-                        }
-                    }
-                }
-                // @Query WHERE clause columns
-                const whereMatch = line.match(/WHERE\s+\w+\.(\w+)\s*=/gi);
-                if (whereMatch) {
-                    for (const w of whereMatch) {
-                        const colMatch = w.match(/\.(\w+)\s*=/i);
-                        if (colMatch && !["tenantId", "id", "tenant_id"].includes(colMatch[1])) {
-                            queryColumns.push({ col: colMatch[1], file: f.file_path, line: idx + 1 });
-                        }
-                    }
-                }
-            });
-        }
-        // Check migrations for those columns
-        const migrationContent = fileRecords
-            .filter(f => f.isMigration)
-            .map(f => f.content.toLowerCase())
-            .join("\n");
-        for (const { col, file, line } of queryColumns) {
-            const snakeCol = col.replace(/([A-Z])/g, "_$1").toLowerCase();
-            const indexPattern = new RegExp(`create.*index.*${snakeCol}|create.*index.*${col.toLowerCase()}`, "i");
-            if (!indexPattern.test(migrationContent)) {
-                // Only flag if there's a migration file in this PR (otherwise we can't verify)
-                if (fileRecords.some(f => f.isMigration)) {
-                    p3Findings.push({
-                        check: "MISSING_INDEX",
-                        severity: "WARNING",
-                        file,
-                        line,
-                        message: `Query filters on column \`${col}\` but no CREATE INDEX found in migration files`,
-                        suggestion: `Add to Flyway migration: CREATE INDEX idx_<table>_${snakeCol} ON <table>(${snakeCol});`,
-                    });
-                }
-            }
-        }
-    }
-    allFindings.push(...p3Findings);
-    passResults.push({ name: "MISSING_INDEX", skipped: skip_checks.includes("missing_index"), passed: p3Findings.length === 0, count: p3Findings.length });
-    // ══════════════════════════════════════════════════════════════════════
-    // PASS 4 — KAFKA_SYNC
-    // Rule: @KafkaListener methods must NOT do synchronous DB/REST work inline
-    // ══════════════════════════════════════════════════════════════════════
-    const p4Findings = [];
-    if (!skip_checks.includes("kafka_sync")) {
-        for (const f of fileRecords.filter(f => f.isKafka)) {
-            let inKafkaListener = false;
-            let listenerDepth = 0;
-            f.lines.forEach((line, idx) => {
-                if (/@KafkaListener/.test(line)) {
-                    inKafkaListener = true;
-                    listenerDepth = 0;
-                }
-                if (inKafkaListener) {
-                    listenerDepth += (line.match(/\{/g) || []).length;
-                    listenerDepth -= (line.match(/\}/g) || []).length;
-                    // Detect sync repo/REST calls
-                    const syncCallPattern = /\.(save|saveAll|findById|findAll|delete|deleteById|restTemplate|webClient|getForObject|postForObject|exchange)\s*\(/;
-                    if (syncCallPattern.test(line)) {
-                        const isAsync = /@Async|CompletableFuture|\.async\(\)|executorService|threadPool/i.test(f.lines.slice(Math.max(0, idx - 3), idx + 1).join(" "));
-                        if (!isAsync) {
-                            p4Findings.push({
-                                check: "KAFKA_SYNC",
-                                severity: "BLOCKING",
-                                file: f.file_path,
-                                line: idx + 1,
-                                message: `Synchronous call \`${(line.match(syncCallPattern) || [""])[0]}\` inside @KafkaListener — blocks consumer thread`,
-                                suggestion: "Offload to @Async method or submit to a dedicated ExecutorService",
-                            });
-                        }
-                    }
-                    if (listenerDepth <= 0 && listenerDepth !== 0) {
-                        inKafkaListener = false;
-                    }
-                }
-            });
-        }
-    }
-    allFindings.push(...p4Findings);
-    passResults.push({ name: "KAFKA_SYNC", skipped: skip_checks.includes("kafka_sync"), passed: p4Findings.length === 0, count: p4Findings.length });
-    // ══════════════════════════════════════════════════════════════════════
-    // PASS 5 — EARLY_RETURN
-    // Rule: no early returns in methods. Single return point at method end.
-    // Applies to Java and TypeScript.
-    //
-    // Algorithm: inside each method body, any `return` statement that still
-    // has non-empty, non-closing-brace lines after it is an early return.
-    // This catches both single-line guard clauses (if (x) return null;)
-    // and nested-block early returns (if (x) { ... return y; }).
-    // ══════════════════════════════════════════════════════════════════════
-    const p5Findings = [];
-    if (!skip_checks.includes("early_return")) {
-        for (const f of fileRecords.filter(f => f.isJava || f.isTS)) {
-            let braceDepth = 0;
-            let methodStartLine = -1;
-            let methodBraceDepth = -1;
-            let inMethod = false;
-            let methodName = "";
-            // Collect all return line indices for current method, flush on method end
-            let methodReturnLines = [];
-            let methodBodyLines = []; // all non-empty line indices inside method
-            const flush = () => {
-                // The LAST return in the method is the valid single exit point.
-                // Every other return is an early return.
-                if (methodReturnLines.length > 1) {
-                    // All returns except the last are early
-                    for (const ri of methodReturnLines.slice(0, -1)) {
-                        p5Findings.push({
-                            check: "EARLY_RETURN",
-                            severity: "BLOCKING",
-                            file: f.file_path,
-                            line: ri + 1,
-                            message: `Early return in \`${methodName}()\` — violates single-exit rule`,
-                            suggestion: "Refactor: declare result at top, use nested if blocks, single return at method end",
-                        });
-                    }
-                }
-                else if (methodReturnLines.length === 1) {
-                    // Only one return — is it the last meaningful line of the method?
-                    const returnIdx = methodReturnLines[0];
-                    // Lines after the return inside the method body (non-empty, not just closing braces)
-                    const afterReturn = f.lines
-                        .slice(returnIdx + 1)
-                        .map((l, offset) => ({ l: l.trim(), absIdx: returnIdx + 1 + offset }))
-                        .filter(({ l }) => l.length > 0 && l !== "}" && l !== "};" && !l.startsWith("//"));
-                    // If there's meaningful code after the return before the method ends, it's an early return
-                    if (afterReturn.length > 0 && afterReturn[0].absIdx <= methodBodyLines[methodBodyLines.length - 1]) {
-                        p5Findings.push({
-                            check: "EARLY_RETURN",
-                            severity: "BLOCKING",
-                            file: f.file_path,
-                            line: returnIdx + 1,
-                            message: `Early return in \`${methodName}()\` — violates single-exit rule`,
-                            suggestion: "Refactor: declare result at top, use nested if blocks, single return at method end",
-                        });
-                    }
-                }
-                methodReturnLines = [];
-                methodBodyLines = [];
-            };
-            f.lines.forEach((line, idx) => {
-                const trimmed = line.trim();
-                const openBraces = (line.match(/\{/g) || []).length;
-                const closeBraces = (line.match(/\}/g) || []).length;
-                // Detect method/function start (before brace depth update)
-                const javaMethod = line.match(/(?:public|private|protected|static)\s+\S+\s+(\w+)\s*\(/);
-                const tsFunction = line.match(/(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\(|async\s+(\w+)\s*\()/);
-                const isMethodStart = (f.isJava && javaMethod) || (f.isTS && tsFunction);
-                if (isMethodStart && !inMethod) {
-                    inMethod = true;
-                    methodBraceDepth = braceDepth;
-                    methodStartLine = idx;
-                    methodReturnLines = [];
-                    methodBodyLines = [];
-                    methodName = (javaMethod?.[1] || tsFunction?.[1] || tsFunction?.[2] || tsFunction?.[3] || "unknown");
-                }
-                braceDepth += openBraces - closeBraces;
-                if (inMethod && idx > methodStartLine) {
-                    if (trimmed.length > 0)
-                        methodBodyLines.push(idx);
-                    // Track return statements (not in comments)
-                    const hasReturn = /\breturn\b/.test(line) && !/^\s*\/\//.test(line);
-                    if (hasReturn) {
-                        methodReturnLines.push(idx);
-                    }
-                    // End of method: brace depth drops back to where method started
-                    if (braceDepth <= methodBraceDepth) {
-                        flush();
-                        inMethod = false;
-                        methodBraceDepth = -1;
-                    }
-                }
-            });
-        }
-    }
-    allFindings.push(...p5Findings);
-    passResults.push({ name: "EARLY_RETURN", skipped: skip_checks.includes("early_return"), passed: p5Findings.length === 0, count: p5Findings.length });
-    // ── Tier 1 gate: if any mechanical check has BLOCKING findings → stop ──
-    const blockingFindings = allFindings.filter(f => f.severity === "BLOCKING");
-    const mechanicalPassed = blockingFindings.length === 0;
-    const reviewComments = [];
-    let aiCost = 0;
-    const AI_COST_PER_100_LINES = 0.0008; // ~$0.0008 per 100 lines reviewed
-    if (mechanicalPassed && !skip_checks.includes("ai_review")) {
-        for (const f of fileRecords) {
-            const lineCount = f.lines.length;
-            aiCost += (lineCount / 100) * AI_COST_PER_100_LINES;
-            // ── 6a: Comment quality check ─────────────────────────────────
-            const obviousComments = f.lines.filter(l => /\/\/\s*(get the|set the|loop|return|initialize|this method|this function|create a|update the)/i.test(l));
-            if (obviousComments.length > 0) {
-                reviewComments.push({
-                    file: f.file_path,
-                    kind: "concern",
-                    comment: `${obviousComments.length} obvious comment(s) detected (e.g. \`// Get the user\`, \`// Loop through list\`). ` +
-                        "Comments must explain WHY — the code explains WHAT. Remove or replace with rationale.",
-                });
-            }
-            // ── 6b: Hardcoded values ──────────────────────────────────────
-            const hardcodedUrls = f.lines.filter((l, i) => /https?:\/\/[0-9]{1,3}\.[0-9]{1,3}|localhost:[0-9]{4}|uat\.|staging\.|prod\./i.test(l) &&
-                !/test|spec|mock|comment|\/\//i.test(l));
-            if (hardcodedUrls.length > 0) {
-                const lineNums = f.lines.map((l, i) => ({ l, i }))
-                    .filter(({ l }) => /https?:\/\/[0-9]{1,3}\.[0-9]{1,3}|localhost:[0-9]{4}|uat\.|staging\.|prod\./i.test(l))
-                    .map(({ i }) => i + 1);
-                reviewComments.push({
-                    file: f.file_path,
-                    line: lineNums[0],
-                    kind: "concern",
-                    comment: `Hardcoded URL/IP detected on line(s) ${lineNums.join(", ")}. ` +
-                        "Move to application.properties / environment variables. This is a PR-blocking violation if merged.",
-                });
-            }
-            // ── 6c: @Transactional(readOnly) on GET service methods ───────
-            if (f.isJava && /Service/.test(path.basename(f.file_path))) {
-                const getMethods = f.lines
-                    .map((l, i) => ({ l, i }))
-                    .filter(({ l }) => /public.*(?:List|Page|Optional|DTO|Response)\s+\w+\s*\(/.test(l));
-                for (const { l, i } of getMethods) {
-                    const prevLines = f.lines.slice(Math.max(0, i - 3), i).join(" ");
-                    if (!/Transactional.*readOnly.*true|readOnly.*=.*true/.test(prevLines)) {
-                        reviewComments.push({
-                            file: f.file_path,
-                            line: i + 1,
-                            kind: "concern",
-                            comment: `Method \`${(l.match(/\w+\s*\(/) || [""])[0].trim()}\` returns data but lacks \`@Transactional(readOnly = true)\`. ` +
-                                "Read-only service methods MUST declare this — prevents dirty reads and enables DB optimizations.",
-                        });
-                        break; // One comment per file, not per method
-                    }
-                }
-            }
-            // ── 6d: Missing @PreAuthorize on controller methods ───────────
-            if (f.isJava && /Controller/.test(path.basename(f.file_path))) {
-                const publicEndpoints = f.lines
-                    .map((l, i) => ({ l, i }))
-                    .filter(({ l }) => /@(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|RequestMapping)/.test(l));
-                for (const { l, i } of publicEndpoints) {
-                    const prevLines = f.lines.slice(Math.max(0, i - 5), i).join(" ");
-                    const hasAuth = /PreAuthorize|permitAll|public\s*\/\*\*/.test(prevLines);
-                    if (!hasAuth) {
-                        reviewComments.push({
-                            file: f.file_path,
-                            line: i + 1,
-                            kind: "concern",
-                            comment: `Endpoint at line ${i + 1} appears to lack \`@PreAuthorize\`. ` +
-                                "Every non-public endpoint must declare an authority e.g. `@PreAuthorize(\"hasAuthority('domain.action')\")`.",
-                        });
-                    }
-                }
-            }
-            // ── 6e: console.log / System.out in production code ───────────
-            if (!f.file_path.includes("test") && !f.file_path.includes("spec")) {
-                const debugLines = f.lines
-                    .map((l, i) => ({ l, i }))
-                    .filter(({ l }) => /console\.log|System\.out\.print|e\.printStackTrace\(\)/.test(l));
-                if (debugLines.length > 0) {
-                    reviewComments.push({
-                        file: f.file_path,
-                        line: debugLines[0].i + 1,
-                        kind: "concern",
-                        comment: `Debug statement on line ${debugLines[0].i + 1} (\`${debugLines[0].l.trim()}\`). ` +
-                            "Use SLF4J logger or structured logging. Never leave console.log / System.out in production.",
-                    });
-                }
-            }
-            // ── 6f: Catch-all exception swallowing ────────────────────────
-            if (f.isJava) {
-                f.lines.forEach((line, idx) => {
-                    if (/catch\s*\(\s*Exception\s+/.test(line)) {
-                        const catchBlock = f.lines.slice(idx, idx + 5).join(" ");
-                        if (/\}\s*$/.test(catchBlock) && !/log\.|logger\.|throw/.test(catchBlock)) {
-                            reviewComments.push({
-                                file: f.file_path,
-                                line: idx + 1,
-                                kind: "concern",
-                                comment: `Broad \`catch (Exception e)\` at line ${idx + 1} may be swallowing errors silently. ` +
-                                    "Either log the exception with context or re-throw as a domain exception.",
-                            });
-                        }
-                    }
-                });
-            }
-            // ── 6g: TypeScript any type usage ─────────────────────────────
-            if (f.isTS && !f.file_path.includes("@ts-nocheck")) {
-                const anyLines = f.lines
-                    .map((l, i) => ({ l, i }))
-                    .filter(({ l }) => /:\s*any\b/.test(l) && !/\/\/.*:\s*any/.test(l));
-                if (anyLines.length > 2) {
-                    reviewComments.push({
-                        file: f.file_path,
-                        kind: "nitpick",
-                        comment: `${anyLines.length} uses of \`: any\` type found. ` +
-                            "Prefer explicit interfaces or generics. `any` defeats type safety — use `unknown` or define the shape.",
-                    });
-                }
-            }
-            // ── 6h: Missing Flyway migration for new @Entity ───────────────
-            if (f.isJava && /@Entity/.test(f.content)) {
-                const hasMigration = fileRecords.some(r => r.isMigration);
-                if (!hasMigration) {
-                    reviewComments.push({
-                        file: f.file_path,
-                        kind: "concern",
-                        comment: `New or modified \`@Entity\` class with no Flyway migration in this PR. ` +
-                            "Every JPA entity change MUST have a corresponding Flyway SQL migration.",
-                    });
-                }
-            }
-            // ── 6i: Praise well-structured code ───────────────────────────
-            const hasProperLogging = /log\.(info|debug|warn|error)\(/.test(f.content);
-            const hasTests = fileRecords.some(r => r.file_path.includes("Test") || r.file_path.includes("Spec"));
-            if (hasProperLogging && !f.file_path.includes("Test")) {
-                reviewComments.push({
-                    file: f.file_path,
-                    kind: "praise",
-                    comment: "Proper structured logging with SLF4J observed — good practice.",
-                });
-            }
-            // ── 6j: Cross-service call timeout check ──────────────────────
-            if (f.isJava && /RestTemplate|WebClient|FeignClient/i.test(f.content)) {
-                const hasTimeout = /connectTimeout|readTimeout|timeout/i.test(f.content);
-                if (!hasTimeout) {
-                    reviewComments.push({
-                        file: f.file_path,
-                        kind: "concern",
-                        comment: `RestTemplate/WebClient/FeignClient usage detected but no timeout configuration found. ` +
-                            "All cross-service calls MUST have explicit connectTimeout and readTimeout.",
-                    });
-                }
-            }
-        }
-    }
-    // ── Determine final verdict ────────────────────────────────────────────
-    const blockingReviewConcerns = reviewComments.filter(c => c.kind === "concern").length;
-    const questions = reviewComments.filter(c => c.kind === "question").length;
-    const nitpicks = reviewComments.filter(c => c.kind === "nitpick").length;
-    const praises = reviewComments.filter(c => c.kind === "praise").length;
-    let verdict;
-    let verdictReason;
-    if (blockingFindings.length > 0) {
-        verdict = "❌ CHANGES_REQUESTED";
-        verdictReason = `${blockingFindings.length} blocking mechanical check(s) must be resolved before this PR can merge.`;
-    }
-    else if (blockingReviewConcerns > 0) {
-        verdict = "❌ CHANGES_REQUESTED";
-        verdictReason = `All mechanical checks passed, but the reviewer found ${blockingReviewConcerns} architectural concern(s) that must be addressed.`;
-    }
-    else if (nitpicks > 0 || questions > 0) {
-        verdict = "💬 DISCUSS";
-        verdictReason = `All checks passed. ${nitpicks} nitpick(s) and ${questions} question(s) worth discussing — non-blocking but address before next iteration.`;
-    }
-    else {
-        verdict = "✅ APPROVED";
-        verdictReason = "All mechanical checks passed. Reviewer found no architectural concerns. PR is ready to merge.";
-    }
-    // ── Build output ──────────────────────────────────────────────────────
-    const totalChecked = fileRecords.length;
-    const skippedList = skip_checks.length > 0 ? ` (skipped: ${skip_checks.join(", ")})` : "";
-    let out = `## run_pre_pr_checks — ${work_item_id}\n\n`;
-    out += `📁 **${totalChecked} file(s) reviewed**${skippedList}\n\n`;
-    // ── Pass summary table ────────────────────────────────────────────────
-    out += `### Mechanical Checks (Tier 1)\n`;
-    out += `| Pass | Check | Status | Findings |\n|---|---|---|---|\n`;
-    for (const p of passResults) {
-        const statusIcon = p.skipped ? "⏭️ SKIPPED" : p.passed ? "✅ PASS" : "❌ FAIL";
-        const issueText = p.skipped ? "—" : (p.suppressedCount ? `${p.count} (${p.suppressedCount} suppressed)` : `${p.count}`);
-        out += `| P${passResults.indexOf(p) + 1} | ${p.name} | ${statusIcon} | ${issueText} |\n`;
-    }
-    // ── Blocking findings detail ──────────────────────────────────────────
-    if (blockingFindings.length > 0) {
-        out += `\n### ❌ Blocking Findings (${blockingFindings.length})\n`;
-        for (const f of blockingFindings) {
-            out += `\n**[${f.check}]** \`${f.file}\`${f.line ? ` line ${f.line}` : ""}\n`;
-            out += `> ${f.message}\n`;
-            out += `> 💡 *${f.suggestion}*\n`;
-        }
-    }
-    if (p1Suppressed.length > 0) {
-        out += `\n### 🛡️ Suppressed Findings (${p1Suppressed.length})\n`;
-        for (const sup of p1Suppressed) {
-            out += `\n**[TENANT_ISOLATION]** \`${sup.file}\` line ${sup.line}\n`;
-            out += `> Suppressed — ${sup.reason}\n`;
-        }
-    }
-    // ── Warning findings detail ───────────────────────────────────────────
-    const warnings = allFindings.filter(f => f.severity === "WARNING");
-    if (warnings.length > 0) {
-        out += `\n### ⚠️ Warnings (${warnings.length})\n`;
-        for (const f of warnings) {
-            out += `\n**[${f.check}]** \`${f.file}\`${f.line ? ` line ${f.line}` : ""}\n`;
-            out += `> ${f.message}\n`;
-            out += `> 💡 *${f.suggestion}*\n`;
-        }
-    }
-    // ── AI Reviewer comments ──────────────────────────────────────────────
-    if (!skip_checks.includes("ai_review")) {
-        if (!mechanicalPassed) {
-            out += `\n### 🤖 AI Reviewer (Pass 6)\n`;
-            out += `> ⏸️ Skipped — resolve mechanical check failures first.\n`;
-        }
-        else if (reviewComments.length > 0) {
-            out += `\n### 🤖 AI Reviewer (Pass 6) — ${reviewComments.length} comment(s)\n`;
-            const concerns = reviewComments.filter(c => c.kind === "concern");
-            const nits = reviewComments.filter(c => c.kind === "nitpick");
-            const qs = reviewComments.filter(c => c.kind === "question");
-            const ps = reviewComments.filter(c => c.kind === "praise");
-            if (concerns.length > 0) {
-                out += `\n#### 🔴 Concerns (must address)\n`;
-                for (const c of concerns) {
-                    out += `\n**\`${c.file}\`**${c.line ? ` line ${c.line}` : ""}\n`;
-                    out += `> ${c.comment}\n`;
-                }
-            }
-            if (nits.length > 0) {
-                out += `\n#### 🟡 Nitpicks (consider addressing)\n`;
-                for (const c of nits) {
-                    out += `\n**\`${c.file}\`**${c.line ? ` line ${c.line}` : ""}\n`;
-                    out += `> ${c.comment}\n`;
-                }
-            }
-            if (qs.length > 0) {
-                out += `\n#### 💬 Questions\n`;
-                for (const c of qs) {
-                    out += `\n**\`${c.file}\`**${c.line ? ` line ${c.line}` : ""}\n`;
-                    out += `> ${c.comment}\n`;
-                }
-            }
-            if (ps.length > 0) {
-                out += `\n#### ✅ Praise\n`;
-                for (const c of ps) {
-                    out += `- \`${c.file}\`: ${c.comment}\n`;
-                }
-            }
-            // Estimated cost
-            out += `\n> 💰 **AI Review cost:** ~$${aiCost.toFixed(4)} (${totalChecked} files × avg line count)\n`;
-        }
-        else {
-            out += `\n### 🤖 AI Reviewer (Pass 6)\n`;
-            out += `> ✅ No architectural concerns found across all ${totalChecked} changed file(s).\n`;
-            out += `> 💰 **AI Review cost:** ~$${aiCost.toFixed(4)}\n`;
-        }
-    }
-    // ── Final verdict ─────────────────────────────────────────────────────
-    out += `\n---\n`;
-    out += `## ${verdict}\n\n`;
-    out += `${verdictReason}\n`;
-    if (verdict === "✅ APPROVED") {
-        out += `\n**Next steps:**\n`;
-        out += `1. Call \`manage_task(action: "complete", work_item_id: "${work_item_id}")\`\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") {
-        out += `\n**Resolve all ❌ findings above, then re-run \`run_pre_pr_checks\` before raising the PR.**\n`;
-    }
-    else {
-        out += `\n**Address nitpicks/questions at your discretion, then raise the PR.**\n`;
-    }
-    return appendTelemetry({ content: [{ type: "text", text: out }] }, inputChars);
-});
-// ─── Tool 17: reviewer_agent ──────────────────────────────────────────────────
-// Context-aware architectural review agent. Called automatically in Phase 4
-// AFTER run_pre_pr_checks returns APPROVED or DISCUSS.
-//
-// Unlike run_pre_pr_checks (which runs deterministic pattern checks on raw code),
-// reviewer_agent works at the task-knowledge level:
-//   — Reads the full task brain: spec, decisions, ACs, scenarios, files-touched
-//   — Reads project-spec golden_rules and coding_style
-//   — Reads actual content of every changed file
-//   — Cross-references all of the above to find:
-//       • ACs with no matching file changes (missed requirements)
-//       • Architectural decisions not reflected in files (decision drift)
-//       • Changed files not mentioned in any decision (scope creep)
-//       • Rejected pattern violations in file content
-//       • Test scenario coverage gaps
-//       • Golden rule compliance per file
-//
-// Returns findings grouped by severity:
-//   🔴 CRITICAL   — blocks PR, must fix
-//   🟡 WARNING    — should address before merge
-//   🟢 INFO       — observations, not blocking
-//   ✅ PRAISE     — things done well
-//
-// Final verdict: APPROVED | CHANGES_REQUESTED | DISCUSS
-server.tool("reviewer_agent", "Context-aware architectural review agent — call this in Phase 4 AFTER run_pre_pr_checks returns APPROVED or DISCUSS. " +
-    "Reads the full task brain (spec, decisions, ACs, scenarios, files-touched) + project-spec golden rules + actual changed file contents. " +
-    "Cross-references all of them to find: missed ACs, decision drift, scope creep, rejected pattern violations, test coverage gaps, and golden rule breaches. " +
-    "Returns a structured review report with findings grouped by severity (CRITICAL / WARNING / INFO / PRAISE) and a final verdict. " +
-    "This is the final quality gate before manage_task(complete) is called.", {
-    work_item_id: z.string().describe("Active work item ID, e.g. 'WI-1234'."),
-    focus_areas: z.array(z.enum(["ac_coverage", "decision_drift", "scope_creep", "rejected_patterns", "test_coverage", "golden_rules", "all"])).optional().default(["all"]).describe("Which review areas to focus on. Default: all. " +
-        "Options: ac_coverage | decision_drift | scope_creep | rejected_patterns | test_coverage | golden_rules | all"),
-}, async ({ work_item_id, focus_areas = ["all"] }) => {
-    const inputChars = JSON.stringify({ work_item_id, focus_areas }).length;
-    const wsRoot = getWorkspaceRoot();
-    const runAll = focus_areas.includes("all");
-    const run = (area) => runAll || focus_areas.includes(area);
-    // ── 1. Resolve task folder ─────────────────────────────────────────────
-    const registry = readRegistry();
-    const taskEntry = registry.find(r => r["work_item_id"] === work_item_id);
-    let taskDir = null;
-    if (taskEntry?.["folder_name"]) {
-        taskDir = path.resolve(wsRoot, `.secufusion/tasks/${taskEntry["folder_name"]}`);
-    }
-    if (!taskDir || !fs.existsSync(taskDir)) {
-        const tasksBase = path.resolve(wsRoot, ".secufusion/tasks");
-        if (fs.existsSync(tasksBase)) {
-            const folders = fs.readdirSync(tasksBase);
-            const match = folders.find(f => f.startsWith(work_item_id));
-            if (match)
-                taskDir = path.join(tasksBase, match);
-        }
-    }
-    if (!taskDir || !fs.existsSync(taskDir)) {
-        return appendTelemetry({
-            isError: true,
-            content: [{ type: "text", text: `❌ Task folder not found for ${work_item_id}. Call manage_task(initialize) first.` }]
-        }, inputChars);
-    }
-    const spec = JSON.parse(readFileSafe(path.join(taskDir, "spec.json")) || "{}");
-    const progress = JSON.parse(readFileSafe(path.join(taskDir, "progress.json")) || "{}");
-    const decisions = JSON.parse(readFileSafe(path.join(taskDir, "decisions.json")) || "[]");
-    const filesTouched = JSON.parse(readFileSafe(path.join(taskDir, "files-touched.json")) || "[]");
-    const scenarios = JSON.parse(readFileSafe(path.join(taskDir, "scenarios.json")) || "[]");
-    // ── 3. Load project spec (golden rules + rejected patterns) ────────────
-    const SPEC_FILE = ".secufusion-project-spec.json";
-    const specCandidates = [
-        path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")), SPEC_FILE),
-        path.resolve(wsRoot, SPEC_FILE),
-    ];
-    const specPath = specCandidates.find(p => fs.existsSync(p)) ?? null;
-    let projectSpec = null;
-    if (specPath) {
-        try {
-            projectSpec = JSON.parse(readFileSafe(specPath) || "null");
-        }
-        catch { }
-    }
-    const goldenRules = projectSpec?.golden_rules || {};
-    const codingStyle = goldenRules.coding_style || {};
-    const authorityRules = goldenRules.authority_rules || [];
-    // Load rejected patterns
-    const REJECTED_FILE_PATH = resolve(".rejected-patterns.json");
-    let rejectedPatterns = [];
-    try {
-        rejectedPatterns = JSON.parse(readFileSafe(REJECTED_FILE_PATH) || "[]");
-    }
-    catch { }
-    const fileRecords = filesTouched.map(ft => {
-        const abs = path.resolve(wsRoot, ft.file_path);
-        const raw = readFileSafe(abs) || "";
-        const ext = path.extname(ft.file_path).toLowerCase();
-        return {
-            file_path: ft.file_path,
-            change_summary: ft.change_summary,
-            content: raw,
-            lines: raw.split("\n"),
-            ext,
-            isJava: ext === ".java",
-            isTS: ext === ".ts" || ext === ".tsx",
-            isTest: /test|spec/i.test(ft.file_path),
-            exists: fs.existsSync(abs),
-        };
-    });
-    const findings = [];
-    // ══════════════════════════════════════════════════════════════════════
-    // AREA 1 — AC COVERAGE
-    // Cross-reference every AC against files-touched change summaries.
-    // An AC with zero matches across all change summaries is likely missed.
-    // ══════════════════════════════════════════════════════════════════════
-    if (run("ac_coverage")) {
-        const allACs = [
-            ...(spec.acceptance_criteria || []),
-            ...(progress.completed_acs || []),
-            ...(progress.pending_acs || []),
-        ];
-        const uniqueACs = [...new Set(allACs)];
-        // Combined corpus: file paths + change summaries + decisions
-        const changeCorpus = [
-            ...fileRecords.map(f => f.file_path + " " + f.change_summary),
-            ...decisions.map(d => d.decision + " " + d.rationale),
-        ].join(" ").toLowerCase();
-        for (const ac of uniqueACs) {
-            if (!ac || ac.trim().length === 0)
-                continue;
-            // Extract key nouns/verbs from AC (3+ char words, excluding articles)
-            const keywords = ac.toLowerCase()
-                .split(/\s+/)
-                .filter(w => w.length > 3 && !/^(must|shall|should|the|and|for|with|that|this|when|from|into|not|does|will|have|been|each|only|any|all)$/.test(w));
-            const matchCount = keywords.filter(kw => changeCorpus.includes(kw)).length;
-            const coverage = keywords.length > 0 ? matchCount / keywords.length : 1;
-            if (coverage < 0.25) {
-                findings.push({
-                    severity: "CRITICAL",
-                    area: "AC_COVERAGE",
-                    title: `AC may not be implemented`,
-                    detail: `"${ac.substring(0, 100)}${ac.length > 100 ? "..." : ""}" — no matching file changes or decisions found`,
-                    action: "Verify this AC is addressed by a file in files-touched. If it is, update the change_summary to reflect it.",
-                });
-            }
-            else if (coverage < 0.5) {
-                findings.push({
-                    severity: "WARNING",
-                    area: "AC_COVERAGE",
-                    title: `AC has weak coverage signal`,
-                    detail: `"${ac.substring(0, 100)}${ac.length > 100 ? "..." : ""}" — only ${Math.round(coverage * 100)}% of keywords found in change summaries`,
-                    action: "Confirm this AC is fully satisfied. If so, enrich the change_summary for the relevant file.",
-                });
-            }
-        }
-        // Pending ACs check
-        if ((progress.pending_acs || []).length > 0) {
-            findings.push({
-                severity: "CRITICAL",
-                area: "AC_COVERAGE",
-                title: `${progress.pending_acs.length} AC(s) still pending`,
-                detail: progress.pending_acs.map(ac => `• ${ac}`).join("\n"),
-                action: "Complete all ACs before raising a PR. Call manage_task(update_spec) to move them to completed_acs.",
-            });
-        }
-    }
-    // ══════════════════════════════════════════════════════════════════════
-    // AREA 2 — DECISION DRIFT
-    // Every architectural decision in decisions.json should be traceable
-    // to at least one file in files-touched.
-    // ══════════════════════════════════════════════════════════════════════
-    if (run("decision_drift")) {
-        for (const dec of decisions) {
-            if (!dec.decision)
-                continue;
-            // Skip rollback/meta decisions (they don't produce files)
-            if (/rollback|strategy|tier|SAFE|RISKY|DANGEROUS/i.test(dec.decision))
-                continue;
-            const decKeywords = dec.decision.toLowerCase()
-                .split(/\s+/)
-                .filter(w => w.length > 4 && !/^(using|added|decided|chose|going|will|this|that|with|from|into|the|and|for)$/.test(w));
-            const fileCorpus = fileRecords.map(f => f.file_path + " " + f.change_summary).join(" ").toLowerCase();
-            const matchCount = decKeywords.filter(kw => fileCorpus.includes(kw)).length;
-            const traceability = decKeywords.length > 0 ? matchCount / decKeywords.length : 1;
-            if (traceability < 0.2 && decKeywords.length >= 3) {
-                findings.push({
-                    severity: "WARNING",
-                    area: "DECISION_DRIFT",
-                    title: `Decision #${dec.id} may not be reflected in code`,
-                    detail: `Decision: "${dec.decision?.substring(0, 120)}${(dec.decision?.length || 0) > 120 ? "..." : ""}"`,
-                    action: "Verify this decision was implemented. If the file exists but wasn't logged, call manage_task(log_file_touched).",
-                });
-            }
-        }
-    }
-    // ══════════════════════════════════════════════════════════════════════
-    // AREA 3 — SCOPE CREEP
-    // Files in files-touched that don't appear in any AC, decision, or spec
-    // description are potential scope creep.
-    // ══════════════════════════════════════════════════════════════════════
-    if (run("scope_creep")) {
-        const specCorpus = [
-            spec.title || "",
-            spec.description || "",
-            ...(spec.acceptance_criteria || []),
-            ...decisions.map(d => d.decision + " " + d.rationale),
-        ].join(" ").toLowerCase();
-        for (const f of fileRecords.filter(f => !f.isTest)) {
-            const basename = path.basename(f.file_path).replace(/\.[^.]+$/, "").toLowerCase();
-            // Split camelCase/PascalCase: DeviceController → device controller
-            const words = basename.replace(/([A-Z])/g, " $1").toLowerCase().trim().split(/[\s_-]+/).filter(w => w.length > 3);
-            const inSpec = words.some(w => specCorpus.includes(w));
-            if (!inSpec && words.length > 0) {
-                findings.push({
-                    severity: "INFO",
-                    area: "SCOPE_CREEP",
-                    title: `File may be outside task scope`,
-                    detail: `\`${f.file_path}\` — no mention of this component in spec, ACs, or decisions`,
-                    file: f.file_path,
-                    action: "If this file change is intentional, add a decision: manage_task(log_decision) explaining why it was touched.",
-                });
-            }
-        }
-    }
-    // ══════════════════════════════════════════════════════════════════════
-    // AREA 4 — REJECTED PATTERNS
-    // Scan file contents against .rejected-patterns.json
-    // ══════════════════════════════════════════════════════════════════════
-    if (run("rejected_patterns") && rejectedPatterns.length > 0) {
-        for (const f of fileRecords.filter(f => f.exists)) {
-            for (const rp of rejectedPatterns) {
-                if (!rp.pattern)
-                    continue;
-                // Build a simple keyword match from the pattern
-                const patternKeywords = rp.pattern.toLowerCase().split(/\s+/).filter(w => w.length > 4).slice(0, 4);
-                const fileContent = f.content.toLowerCase();
-                const matchCount = patternKeywords.filter(kw => fileContent.includes(kw)).length;
-                if (patternKeywords.length > 0 && matchCount / patternKeywords.length >= 0.75) {
-                    findings.push({
-                        severity: "CRITICAL",
-                        area: "REJECTED_PATTERNS",
-                        title: `Rejected pattern detected in file`,
-                        detail: `Pattern: "${rp.pattern}"\nReason: ${rp.reason || "See .rejected-patterns.json"}`,
-                        file: f.file_path,
-                        action: `This pattern was explicitly rejected (category: ${rp.category || "unknown"}). Refactor before merging.`,
-                    });
-                }
-            }
-        }
-    }
-    // ══════════════════════════════════════════════════════════════════════
-    // AREA 5 — TEST COVERAGE
-    // Are there test files in the touched set? Do scenarios have file coverage?
-    // ══════════════════════════════════════════════════════════════════════
-    if (run("test_coverage")) {
-        const testFiles = fileRecords.filter(f => f.isTest);
-        const sourceFiles = fileRecords.filter(f => !f.isTest && (f.isJava || f.isTS));
-        const unitScenarios = scenarios.filter(s => s.type === "unit");
-        const integrationScenarios = scenarios.filter(s => s.type === "integration");
-        if (sourceFiles.length > 0 && testFiles.length === 0) {
-            findings.push({
-                severity: "CRITICAL",
-                area: "TEST_COVERAGE",
-                title: "No test files in this PR",
-                detail: `${sourceFiles.length} source file(s) changed but zero test files logged in files-touched`,
-                action: "Add unit and integration tests. Call manage_task(log_file_touched) for each test file.",
-            });
-        }
-        else if (testFiles.length > 0) {
-            findings.push({
-                severity: "PRAISE",
-                area: "TEST_COVERAGE",
-                title: `${testFiles.length} test file(s) included`,
-                detail: testFiles.map(f => `• ${f.file_path}`).join("\n"),
-            });
-        }
-        if (unitScenarios.length === 0 && sourceFiles.length > 0) {
-            findings.push({
-                severity: "WARNING",
-                area: "TEST_COVERAGE",
-                title: "No unit test scenarios logged",
-                detail: "manage_task(add_scenario) with type='unit' was never called for this task",
-                action: "Log at least one unit test scenario, or call suggest_test_scenarios to auto-generate them.",
-            });
-        }
-        if (integrationScenarios.length === 0 && sourceFiles.some(f => /Controller/i.test(f.file_path))) {
-            findings.push({
-                severity: "WARNING",
-                area: "TEST_COVERAGE",
-                title: "Controller changed but no integration test scenarios",
-                detail: "A Controller file was modified but no integration scenarios were logged",
-                action: "Add an integration test scenario via manage_task(add_scenario) with type='integration'.",
-            });
-        }
-    }
-    // ══════════════════════════════════════════════════════════════════════
-    // AREA 6 — GOLDEN RULES compliance
-    // Check file content against project-spec golden_rules
-    // ══════════════════════════════════════════════════════════════════════
-    if (run("golden_rules")) {
-        // Coding style: no early returns (secondary check, run_pre_pr_checks is primary)
-        if (codingStyle.banned_pattern) {
-            for (const f of fileRecords.filter(f => f.isJava || f.isTS)) {
-                // Check for the most obvious banned pattern signatures
-                const hasBannedReturn = /if\s*\([^)]+\)\s*return\s+[^;]+;/.test(f.content);
-                if (hasBannedReturn && !f.isTest) {
-                    findings.push({
-                        severity: "WARNING",
-                        area: "GOLDEN_RULES",
-                        title: "Possible coding_style violation: early return pattern",
-                        detail: `\`${f.file_path}\` may contain early returns matching banned pattern: \`${codingStyle.banned_pattern}\``,
-                        file: f.file_path,
-                        action: "Run run_pre_pr_checks to confirm. Refactor to nested conditionals if flagged.",
-                    });
-                }
-            }
-        }
-        // Authority rules: controller methods need @PreAuthorize
-        if (authorityRules.length > 0) {
-            for (const f of fileRecords.filter(f => f.isJava && /Controller/.test(f.file_path) && !f.isTest)) {
-                const hasPreAuth = f.content.includes("@PreAuthorize");
-                const hasEndpoints = /@(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)/.test(f.content);
-                if (hasEndpoints && !hasPreAuth) {
-                    findings.push({
-                        severity: "CRITICAL",
-                        area: "GOLDEN_RULES",
-                        title: "Controller missing @PreAuthorize",
-                        detail: `\`${f.file_path}\` has endpoint mappings but no @PreAuthorize annotation`,
-                        file: f.file_path,
-                        action: "Add @PreAuthorize(\"hasAuthority('<domain>.<action>')\") to every non-public endpoint.",
-                    });
-                }
-                else if (hasEndpoints && hasPreAuth) {
-                    findings.push({
-                        severity: "PRAISE",
-                        area: "GOLDEN_RULES",
-                        title: "@PreAuthorize present on controller",
-                        detail: `\`${f.file_path}\` correctly uses @PreAuthorize for endpoint security`,
-                    });
-                }
-            }
-        }
-        // Tenant isolation spot check
-        for (const f of fileRecords.filter(f => f.isJava && /Repository/.test(f.file_path) && !f.isTest)) {
-            const hasTenantFilter = /tenantId|tenant_id|:tenantId/i.test(f.content);
-            const hasQueries = /@Query|findBy|deleteBy/i.test(f.content);
-            if (hasQueries && hasTenantFilter) {
-                findings.push({
-                    severity: "PRAISE",
-                    area: "GOLDEN_RULES",
-                    title: "Tenant isolation applied in repository",
-                    detail: `\`${f.file_path}\` correctly scopes queries with tenantId`,
-                });
-            }
-        }
-        // Flyway migration check for @Entity changes
-        const entityFiles = fileRecords.filter(f => f.isJava && /@Entity/.test(f.content) && !f.isTest);
-        const migrationFiles = fileRecords.filter(f => f.file_path.includes("migration") || f.ext === ".sql");
-        if (entityFiles.length > 0 && migrationFiles.length === 0) {
-            findings.push({
-                severity: "CRITICAL",
-                area: "GOLDEN_RULES",
-                title: "@Entity modified with no Flyway migration",
-                detail: `${entityFiles.length} @Entity file(s) touched: ${entityFiles.map(f => path.basename(f.file_path)).join(", ")}`,
-                action: "Create a Flyway migration for every schema change. Log it with manage_task(log_file_touched).",
-            });
-        }
-        else if (entityFiles.length > 0 && migrationFiles.length > 0) {
-            findings.push({
-                severity: "PRAISE",
-                area: "GOLDEN_RULES",
-                title: "@Entity change has matching Flyway migration",
-                detail: `${migrationFiles.map(f => path.basename(f.file_path)).join(", ")}`,
-            });
-        }
-    }
-    // ── General praise ─────────────────────────────────────────────────────
-    if (decisions.length >= 3) {
-        findings.push({
-            severity: "PRAISE",
-            area: "DECISIONS",
-            title: `${decisions.length} architectural decisions logged`,
-            detail: "Good decision logging discipline — future agents will benefit from this history.",
-        });
-    }
-    if (scenarios.length >= 5) {
-        findings.push({
-            severity: "PRAISE",
-            area: "TEST_COVERAGE",
-            title: `${scenarios.length} test scenarios logged`,
-            detail: "Comprehensive scenario coverage documented for this task.",
-        });
-    }
-    // ── Verdict ────────────────────────────────────────────────────────────
-    const criticals = findings.filter(f => f.severity === "CRITICAL");
-    const warnings = findings.filter(f => f.severity === "WARNING");
-    const infos = findings.filter(f => f.severity === "INFO");
-    const praises = findings.filter(f => f.severity === "PRAISE");
-    let verdict;
-    let verdictDetail;
-    if (criticals.length > 0) {
-        verdict = "❌ CHANGES_REQUESTED";
-        verdictDetail = `${criticals.length} critical finding(s) must be resolved. Fix them, update files-touched, then re-run reviewer_agent.`;
-    }
-    else if (warnings.length > 2) {
-        verdict = "💬 DISCUSS";
-        verdictDetail = `No critical issues. ${warnings.length} warnings worth reviewing before merge.`;
-    }
-    else if (warnings.length > 0) {
-        verdict = "✅ APPROVED";
-        verdictDetail = `No critical issues. ${warnings.length} minor warning(s) — address at your discretion.`;
-    }
-    else {
-        verdict = "✅ APPROVED";
-        verdictDetail = "Full context review passed. Task is well-documented and implementation is aligned with spec.";
-    }
-    // ── Build output ───────────────────────────────────────────────────────
-    let out = `## reviewer_agent — ${work_item_id}\n\n`;
-    // Task context summary
-    out += `### 📋 Task Context\n`;
-    out += `**Title:** ${spec.title || "(untitled)"}\n`;
-    out += `**Status:** ${spec.status || "(unknown)"}\n`;
-    out += `**ACs:** ${(spec.acceptance_criteria || []).length} total | `;
-    out += `${(progress.completed_acs || []).length} completed | `;
-    out += `${(progress.pending_acs || []).length} pending\n`;
-    out += `**Decisions logged:** ${decisions.length}\n`;
-    out += `**Files touched:** ${fileRecords.length} (${fileRecords.filter(f => !f.exists).length} missing from disk)\n`;
-    out += `**Scenarios logged:** ${scenarios.length} (${scenarios.filter(s => s.type === "unit").length} unit, ${scenarios.filter(s => s.type === "integration").length} integration, ${scenarios.filter(s => s.type === "manual").length} manual)\n`;
-    out += `**Focus areas:** ${focus_areas.join(", ")}\n\n`;
-    // Files reviewed
-    if (fileRecords.length > 0) {
-        out += `### 📁 Files Reviewed\n`;
-        for (const f of fileRecords) {
-            const missing = !f.exists ? " ⚠️ *(not found on disk)*" : "";
-            out += `- \`${f.file_path}\`${missing}\n`;
-            if (f.change_summary)
-                out += `  *${f.change_summary}*\n`;
-        }
-        out += "\n";
-    }
-    // CRITICAL findings
-    if (criticals.length > 0) {
-        out += `### 🔴 CRITICAL — Must Fix Before PR (${criticals.length})\n\n`;
-        for (const f of criticals) {
-            out += `**[${f.area}] ${f.title}**\n`;
-            out += `> ${f.detail.replace(/\n/g, "\n> ")}\n`;
-            if (f.action)
-                out += `> 🔧 *${f.action}*\n`;
-            out += "\n";
-        }
-    }
-    // WARNING findings
-    if (warnings.length > 0) {
-        out += `### 🟡 WARNING — Should Address (${warnings.length})\n\n`;
-        for (const f of warnings) {
-            out += `**[${f.area}] ${f.title}**\n`;
-            out += `> ${f.detail.replace(/\n/g, "\n> ")}\n`;
-            if (f.action)
-                out += `> 💡 *${f.action}*\n`;
-            out += "\n";
-        }
-    }
-    // INFO findings
-    if (infos.length > 0) {
-        out += `### 🟢 INFO — Observations (${infos.length})\n\n`;
-        for (const f of infos) {
-            out += `**[${f.area}] ${f.title}**\n`;
-            out += `> ${f.detail.replace(/\n/g, "\n> ")}\n`;
-            if (f.action)
-                out += `> 💡 *${f.action}*\n`;
-            out += "\n";
-        }
-    }
-    // PRAISE
-    const extSpec3 = specData.chrome_extension || specData["snf-browser-extn"] || specData.snf_browser_extn;
-    if (extSpec3 && extSpec3.repo) {
-        expectedServices.push(extSpec3.repo);
-    }
-    if (praises.length > 0) {
-        out += `### ✅ PRAISE\n`;
-        for (const f of praises) {
-            out += `- **${f.title}:** ${f.detail.replace(/\n/g, " ")}\n`;
-        }
-        out += "\n";
-    }
-    // Summary counts
-    out += `---\n`;
-    out += `| Severity | Count |\n|---|---|\n`;
-    out += `| 🔴 CRITICAL | ${criticals.length} |\n`;
-    out += `| 🟡 WARNING | ${warnings.length} |\n`;
-    out += `| 🟢 INFO | ${infos.length} |\n`;
-    out += `| ✅ PRAISE | ${praises.length} |\n\n`;
-    // Final verdict
-    out += `## ${verdict}\n\n${verdictDetail}\n`;
-    if (verdict === "✅ APPROVED") {
-        out += `\n**Next steps:**\n`;
-        out += `1. Call \`manage_task(action: "complete", work_item_id: "${work_item_id}")\`\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") {
-        out += `\n**Resolve all 🔴 CRITICAL findings, update files-touched if needed, then re-run \`reviewer_agent\`.**\n`;
-    }
-    else {
-        out += `\n**Discuss warnings with your team, then proceed with \`manage_task(complete)\`.**\n`;
-    }
-    return appendTelemetry({ content: [{ type: "text", text: out }] }, inputChars);
-});
-// ─── Resource & Prompt for Personas ──────────────────────────────────────────
-const AGENTS_DIR = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")), "../../agents");
-const PLANNER_MD_PATH = path.join(AGENTS_DIR, "planner.md");
-const CODER_MD_PATH = path.join(AGENTS_DIR, "coder.md");
-const REVIEWER_MD_PATH = path.join(AGENTS_DIR, "reviewer.md");
-const SKILLS_CATALOG_PATH = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")), "skills-catalog.json");
-server.prompt("secufusion_planner", "Starts a conversation with the SecuFusion planner workflow rules loaded (Phase 00 - Phase 1).", async () => {
-    const content = readFileSafe(PLANNER_MD_PATH);
-    if (!content)
-        throw new Error(`Rules file not found at ${PLANNER_MD_PATH}`);
-    return {
-        messages: [{ role: "user", content: { type: "text", text: `You are now the SecuFusion Planner. Here are your rules:\n\n${content}` } }]
-    };
-});
-server.prompt("secufusion_coder", "Starts a conversation with the SecuFusion coder workflow rules loaded (Phase 2 - Phase 3).", async () => {
-    const content = readFileSafe(CODER_MD_PATH);
-    if (!content)
-        throw new Error(`Rules file not found at ${CODER_MD_PATH}`);
-    return {
-        messages: [{ role: "user", content: { type: "text", text: `You are now the SecuFusion Coder. Here are your rules:\n\n${content}` } }]
-    };
-});
-server.prompt("secufusion_reviewer", "Starts a conversation with the SecuFusion reviewer workflow rules loaded (Phase 4 - Phase 5).", async () => {
-    const content = readFileSafe(REVIEWER_MD_PATH);
-    if (!content)
-        throw new Error(`Rules file not found at ${REVIEWER_MD_PATH}`);
-    return {
-        messages: [{ role: "user", content: { type: "text", text: `You are now the SecuFusion Reviewer. Here are your rules:\n\n${content}` } }]
-    };
-});
-// ─── Slash Commands (Aliases for Personas / Workflows) ───────────────────────
-server.prompt("sfn_spec", "Slash command to start Phase 0.5 (Classification) and Phase 1 (Planning)", async () => {
-    const content = readFileSafe(PLANNER_MD_PATH);
-    return { messages: [{ role: "user", content: { type: "text", text: `[Command: /sfn_spec]\nYou are in Spec/Planning mode. Execute Phase 00, Phase 0.5, and Phase 1 rules:\n\n${content}` } }] };
-});
-server.prompt("sfn_code", "Slash command to start Phase 2 (Execution) and Phase 3 (Course Correction)", async () => {
-    const content = readFileSafe(CODER_MD_PATH);
-    return { messages: [{ role: "user", content: { type: "text", text: `[Command: /sfn_code]\nYou are in Coder mode. Execute Phase 2 and Phase 3 rules:\n\n${content}` } }] };
-});
-server.prompt("sfn_review", "Slash command to start Phase 4 (PR Checks) and Phase 5 (Retrospective)", async () => {
-    const content = readFileSafe(REVIEWER_MD_PATH);
-    return { messages: [{ role: "user", content: { type: "text", text: `[Command: /sfn_review]\nYou are in Review mode. Execute Phase 4 and Phase 5 rules:\n\n${content}` } }] };
-});
 // ─── Tools ─────────────────────────────────────────────
 server.tool("skill_recommend", "Searches the skill catalog for matching domain skills based on keywords.", {
     keywords: z.array(z.string()).describe("Keywords to search for (e.g., 'kafka', 'react')")
@@ -4599,6 +3387,17 @@ server.tool("skill_recommend", "Searches the skill catalog for matching domain s
 });
 let watcher = null;
 function getEcosystemRoot(workspaceRoot) {
+    // If workspaceRoot itself already contains multiple sibling service repos
+    // (the flat-monorepo-of-repos layout), trust it as-is — don't walk up.
+    if (fs.existsSync(workspaceRoot)) {
+        const ownChildren = fs.readdirSync(workspaceRoot);
+        const ownSfnRepos = ownChildren.filter((c) => c.startsWith("sfn-") || c === "secufusion");
+        if (ownSfnRepos.length > 1) {
+            return workspaceRoot;
+        }
+    }
+    // Otherwise, workspaceRoot may be a single service repo (e.g. sfn-auth-api)
+    // opened on its own — walk up to find the shared ecosystem parent.
     const parentDir = path.dirname(workspaceRoot);
     if (fs.existsSync(parentDir)) {
         const parentChildren = fs.readdirSync(parentDir);
@@ -4673,7 +3472,65 @@ function getPolyRepoSourceFiles(ecosystemRoot) {
     }
     return allFiles;
 }
+function generateMigrationSpec(ecosystemRoot) {
+    const migrationsSpec = {
+        mcp_guardrails: {
+            naming_pattern_to_enforce: "^V\\d+__[a-z][a-z0-9_]*\\.sql$",
+            version_must_be_next_in_sequence: true,
+            no_gap_reuse_allowed: true,
+            apply_manually_to: "postgresql"
+        },
+        microservices: {}
+    };
+    try {
+        const dirs = fs.readdirSync(ecosystemRoot, { withFileTypes: true })
+            .filter(dirent => dirent.isDirectory() && !dirent.name.startsWith('.') && dirent.name !== 'node_modules')
+            .map(dirent => dirent.name);
+        for (const dir of dirs) {
+            const migrationPath = path.join(ecosystemRoot, dir, 'src', 'main', 'resources', 'db', 'migration');
+            if (fs.existsSync(migrationPath)) {
+                const files = fs.readdirSync(migrationPath).filter(f => f.endsWith('.sql'));
+                const versions = files
+                    .map(f => {
+                    const match = f.match(/^V(\d+)__/);
+                    return match ? parseInt(match[1], 10) : null;
+                })
+                    .filter(v => v !== null);
+                versions.sort((a, b) => a - b);
+                let latest = 0;
+                const gaps = [];
+                if (versions.length > 0) {
+                    latest = versions[versions.length - 1];
+                    for (let i = 1; i < latest; i++) {
+                        if (!versions.includes(i)) {
+                            gaps.push(i);
+                        }
+                    }
+                }
+                migrationsSpec.microservices[dir] = {
+                    has_migrations: true,
+                    path: "src/main/resources/db/migration/",
+                    current_state: {
+                        latest_version: latest,
+                        next_suggested: `V${latest + 1}__description_here.sql`
+                    },
+                    organization: {
+                        version_gaps: gaps,
+                        total_scripts: files.length
+                    }
+                };
+            }
+        }
+        const outPath = path.join(ecosystemRoot, '.secufusion-migrations.json');
+        fs.writeFileSync(outPath, JSON.stringify(migrationsSpec, null, 2), 'utf-8');
+    }
+    catch (e) {
+        console.error("Failed to generate migration spec", e);
+    }
+}
 function performFullExtraction(ecosystemRoot) {
+    // Generate Migration Spec on every extraction
+    generateMigrationSpec(ecosystemRoot);
     const sourceFiles = getPolyRepoSourceFiles(ecosystemRoot);
     const models = [];
     const apis = [];