secufusion-mcp 2.1.6 → 2.2.0

package/commands/sfn-code.md

@@ -1,4 +1,4 @@
----
+---
 description: Execute the approved implementation plan. Switches to the Coder Persona and writes code precisely as planned, using rejected-pattern memory to avoid past mistakes.
 argument-hint: <ticket-id>  e.g. WI-123
 ---
@@ -20,7 +20,19 @@ Task: **$ARGUMENTS**
 
 Call `get_pattern_from_task(work_item_id: "$ARGUMENTS")` to retrieve any rejected patterns logged for this task. If patterns exist, internalize them as hard constraints — **do not repeat them under any circumstances.**
 
-## Phase 2 — Implement
+## Phase 2 — Load Migration Context
+
+**Before writing a single line of code**, read `.secufusion-migrations.json` from the workspace root (or `scripts/` subfolder).
+
+From this file, load for each service involved in this task:
+- `current_state.next_suggested` — the correct next migration filename
+- `organization.version_gaps` — version numbers that MUST NOT be reused
+- `mcp_guardrails.naming_pattern_to_enforce` — the regex all filenames must match
+- `content_conventions.comment_style` — how to write the migration header block
+
+If the file is not found: warn the user and continue, but flag any DB changes as requiring manual migration creation before deploy.
+
+## Phase 3 — Implement
 
 Execute the plan file step by step:
 
@@ -29,21 +41,75 @@ Execute the plan file step by step:
 - On every new DB query: check for N+1 patterns and missing indexes. Flag before writing.
 - On every Kafka publish: verify it is async / non-blocking. Flag synchronous calls.
 
-After each logical step, call `manage_task(action: "update", work_item_id: "$ARGUMENTS", status: "in_progress", notes: "<what was just completed>")` to track progress.
+### Migration awareness during implementation
+
+After writing any of the following:
+- New `@Entity` class
+- New `@Column` on an existing entity
+- Modified `@Column` (type, nullable, length change)
+- Removed `@Column` or `@Table`
+- New `@Table` or renamed table
+
+**IMMEDIATELY stop and do the following:**
+
+1. Read `.secufusion-migrations.json` (already loaded in Phase 2).
+2. Identify which service this file belongs to from its path (e.g. `sfn-events-api/src/...`).
+3. Look up `current_state.next_suggested` for that service.
+4. Check `organization.version_gaps` — do NOT use any of those version numbers.
+5. Warn the developer:
 
-## Phase 3 — Self-Review
+```
+⚠️  DB CHANGE DETECTED
+File:    {entity file path}
+Service: {inferred service name}
+
+A migration script is required before this can be deployed.
+
+Next migration for this service: {next_suggested from .secufusion-migrations.json}
+Location: src/main/resources/db/migration/
+
+🔴 IMPORTANT: SecuFusion applies migration scripts MANUALLY.
+   Nothing runs automatically on boot.
+   You MUST run the script against the target PostgreSQL database
+   BEFORE deploying this code.
+
+Shall I draft the migration script now?
+Reply YES and I will create a draft following:
+  - Naming: {naming_pattern_description from .secufusion-migrations.json}
+  - Comment header style: {comment_style from content_conventions}
+  - IF NOT EXISTS guards where applicable
+  - Index in same file for any new filterable column
+  - Constraint naming: {constraint_naming from content_conventions}
+```
+
+**If the developer says YES:**
+- Draft the migration SQL.
+- Show the draft for review — do NOT write the file until the developer approves.
+- After approval, log the new file with `manage_task(action: "log_file_touched")`.
+
+After each logical step, call `manage_task(action: "update_spec", work_item_id: "$ARGUMENTS", next_step: "<what was just completed>")` to track progress.
+
+## Phase 4 — Self-Review
 
 Before handing off, perform a fast self-review against the Acceptance Criteria in `plan.md`. For each criterion, confirm it is met with a `file:line` citation.
 
+For every migration script created in this task, verify:
+- [ ] Filename matches the naming pattern from `.secufusion-migrations.json`
+- [ ] Version number is the correct next (not a gap, not already used)
+- [ ] File has a comment header with WHY context
+- [ ] IF NOT EXISTS guards used for CREATE TABLE
+- [ ] Indexes included in same file for new filterable columns
+
 If any criterion is unmet, fix it now before reporting.
 
-## Phase 4 — Handoff
+## Phase 5 — Handoff
 
 Call `manage_task(action: "complete", work_item_id: "$ARGUMENTS")` to mark the task as coded.
 
 Report to the user:
 - Files created/modified
 - ACs met (with file:line)
+- Migration scripts created (with manual run reminder)
 - Any open risks or deferred items
 
-> 🚀 Implementation complete. Run `/sfn-review` to run the zero-tolerance PR gate checks.
+> 🚀 Implementation complete. Run `/sfn-review $ARGUMENTS` to run the zero-tolerance PR gate checks.

package/commands/sfn-init.md

@@ -1,57 +1,527 @@
 ---
-description: Prime the SecuFusion ecosystem — scan the entire codebase, map the architectural DNA, generate the architecture diagram, and write it to .secufusion/dna.json. Run this once when you first clone a repo.
-argument-hint: (no args) — run from the root of the repo
+description: "Bootstrap the SecuFusion workspace. Generates .secufusion-project-spec.json and .secufusion-migrations.json on first run. On re-run, performs a version-aware merge — updates MCP-owned rules and terminology while preserving workspace-discovered data. Safe to run at any time."
+argument-hint: "(no args) — run from the repo root. Safe to re-run after MCP updates."
 ---
 
-You are executing the **sfn-init** bootstrap command for the SecuFusion ecosystem.
+You are executing the **sfn-init** bootstrap command.
 
-**This is a learn-first command.** Your job is to deeply understand THIS project before writing anything. Do not produce generic output — every finding must reflect real `file:line` references from the actual codebase.
+This command is safe to re-run at any time. It never blindly overwrites.
+On re-run it detects what changed and merges intelligently.
 
-## Phase 1 — SCAN the Repository
+---
+
+## STEP 0 — Check what already exists and whether it is current
+
+### 0.1 — Locate all three files
+
+```
+.secufusion-project-spec.json
+  → Check workspace root first
+  → Check up to 3 parent directories
+  → Check same directory as the MCP server binary
+
+.secufusion-migrations.json
+  → Check workspace root
+  → Check scripts/ subfolder
+
+.secufusion/dna.json
+  → Check .secufusion/ in workspace root
+```
+
+### 0.2 — For .secufusion-project-spec.json: version check
+
+If the file exists, read its `_meta.mcp_spec_version` field.
+
+**Read the currently installed MCP version** from the `package.json` of the
+`secufusion-mcp` npm package. Locate it using this priority:
+
+```
+1. package.json in the same directory as the MCP server binary (most reliable)
+2. npm list -g secufusion-mcp  → parse the version from output (e.g. "secufusion-mcp@2.1.9")
+3. The "version" field in the nearest package.json walking up from server binary location
+```
+
+This installed version IS the MCP canonical version. It changes automatically when the
+developer publishes a new npm version (`npm publish`). No manual version tracking required.
+
+**Version decision table:**
+
+| Workspace file exists? | `mcp_spec_version` matches? | Action |
+|---|---|---|
+| NO | — | Fresh install → generate from scratch (Phase 1 + 2) |
+| YES | YES (up to date) | No changes needed → skip Phase 2, load and report |
+| YES | NO (stale) | Merge required → run Phase 1 scan + Phase 2 MERGE |
+| YES | field missing (very old) | Treat as stale → run merge |
+
+### 0.3 — For .secufusion-migrations.json
+
+If exists: check if any new `.sql` files exist in migration folders that are NOT
+recorded in this file → if yes, trigger migration refresh in Phase 3.
+If not exists: generate it.
+
+### 0.4 — For .secufusion/dna.json
+
+If exists and `scannedAt` is less than 7 days ago: use existing, skip Phase 4 scan.
+If exists and older than 7 days: offer refresh — ask user: "DNA is X days old. Refresh? (Y/n)"
+If not exists: generate it.
+
+### 0.5 — Report what will happen
+
+Before doing any work, tell the user:
+
+```
+📋 Init plan for this workspace:
+
+  .secufusion-project-spec.json  → {FRESH INSTALL | UP TO DATE | MERGE REQUIRED (v{old} → v{new})}
+  .secufusion-migrations.json    → {GENERATE | UP TO DATE | REFRESH (new SQL files detected)}
+  .secufusion/dna.json           → {GENERATE | UP TO DATE | REFRESH OFFERED (X days old)}
+
+Proceeding...
+```
+
+Do not ask for confirmation before proceeding — just report the plan and execute.
+The user can interrupt if they disagree.
+
+---
+
+## PHASE 1 — Scan the repository (runs on fresh install OR merge)
 
-Call the following MCP tools to scan the repository. Run all 4 **concurrently in a single message**:
+Run all 4 tools **concurrently in a single message**:
 
-1. `scan_repository_stack` — identify language, framework, package manager, microservices, DB entities, build/test commands. Flag if monorepo.
-2. `extract_domain_models` — map all domain entities, their fields, and relationships.
-3. `extract_api_endpoints` — map all REST/GraphQL endpoints, their methods, and owning services.
-4. `extract_event_topics` — map all Kafka/event-bus topics, producers, and consumers.
+1. `scan_repository_stack(workspace_root: <workspace_root>)`
+   → Identifies language, framework, package manager, services, build/test commands
+   → Detects if this is a monorepo
 
-## Phase 2 — WRITE the DNA
+2. `extract_domain_models(workspace_root: <workspace_root>)`
+   → Maps all domain entities, their fields, and relationships
+   → Identifies @Entity classes, their columns, and inter-entity relationships
+   → Note: "Device" in older code may mean a Browser install, not a physical machine
 
-Once all scans complete:
+3. `extract_api_endpoints(workspace_root: <workspace_root>)`
+   → Maps all REST endpoints, HTTP methods, and owning services
+   → Identifies gateway routes vs direct service-to-service calls
+
+4. `extract_event_topics(workspace_root: <workspace_root>)`
+   → Maps all Kafka topics, producers, and consumers per service
+   → Flag any topics with no confirmed consumer (dead topic risk)
+
+**While scans run, note:**
+- Which services have a `src/main/resources/db/migration/` folder → these have manual migrations
+- Which services have NO migration folder → these are schema-free
+- Any service making direct REST calls that bypass the gateway
+- Any Kafka topics with producers but no consumers (dead topics)
+- Any inconsistency between "Device" and "Machine" naming in entity classes
+
+---
+
+## PHASE 2 — Generate or merge the spec file
+
+After scans complete, write or update `.secufusion-project-spec.json` at the workspace root.
+
+This file is the **permanent memory of the project**. Every MCP tool reads it.
+
+### If FRESH INSTALL (file did not exist)
+
+Generate from scratch using the structure below. Proceed to Required structure.
+
+### If MERGE REQUIRED (file exists but is stale)
+
+The spec has two kinds of sections with different owners:
+
+```
+MCP-OWNED sections (always updated from MCP defaults when stale):
+  _meta              — version, timestamps, warnings
+  terminology        — Device vs Machine rules (you defined these)
+  golden_rules       — the non-negotiable rules (you defined these)
+  coding_style       — naming conventions (you defined these)
+  platform           — auth provider, event bus, migration strategy
+
+WORKSPACE-OWNED sections (preserved from scan, updated with new scan results):
+  microservices      — discovered from actual source code
+  kafka_topics       — discovered from actual @KafkaListener / @KafkaProducer
+  cross_service_call_graph — discovered from actual RestTemplate / WebClient calls
+  services_with_migrations    — discovered from actual migration folders
+  services_without_migrations — discovered from actual source structure
+  frontend           — discovered from package.json / framework detection
+  chrome_extension   — discovered from actual source
+```
+
+**Merge procedure (in order):**
+
+1. **Backup first**
+   Copy existing file to `.secufusion-project-spec.json.backup-{YYYYMMDD-HHMMSS}`
+   Never lose the old state. Confirm backup written.
+
+2. **Preserve workspace-owned data**
+   Read all WORKSPACE-OWNED sections from the existing file.
+   Hold them in memory — they will survive the merge.
+
+3. **Re-scan workspace-owned sections**
+   Run Phase 1 scans to refresh: microservices, kafka_topics, call graph, migration lists.
+   Merge scan results with preserved data:
+   - If a service exists in both: keep existing config, update `kafka_produces` / `kafka_consumes` from scan
+   - If a service is new in scan: add it
+   - If a service was in old file but scan found it no longer exists: flag it with `"status": "NOT_FOUND_IN_LAST_SCAN"` — do NOT silently delete it
+
+4. **Overwrite MCP-owned sections**
+   Replace `_meta`, `terminology`, `golden_rules`, `coding_style`, `platform` entirely
+   with the current MCP defaults. These are the sections you update when you push
+   a new version of the MCP. They propagate to every coworker on next init.
+
+5. **Update `_meta.mcp_spec_version` and append to `_changelog`**
+
+   Read the installed npm version from `package.json` — this is the new `mcp_spec_version`.
+   Set `_meta.mcp_spec_version` to this value.
+   Set `_meta.generated_at` to now (ISO timestamp).
+
+   Then **append a new entry** to the `_changelog` array in the spec file.
+   The `mcp_spec_version` in this entry is the npm package version that ran init:
 
-1. Write the combined findings to `.secufusion/dna.json` in the project root. Structure it as:
    ```json
    {
-     "scannedAt": "<ISO timestamp>",
-     "services": [],
-     "domainModels": [],
-     "apiEndpoints": [],
-     "eventTopics": [],
-     "architectureSummary": "<2-3 sentence human-readable summary>"
+     "mcp_spec_version": "{npm package version — e.g. 2.2.0}",
+     "date": "{YYYY-MM-DD}",
+     "author": "sfn-init auto-merge",
+     "summary": "Spec merged: secufusion-mcp@{old_version} → secufusion-mcp@{new_version}",
+     "sections_changed": ["{MCP-owned sections overwritten}"],
+     "added": [
+       "{new golden rule id}: {what it enforces}",
+       "{new terminology key}: {what it means}"
+     ],
+     "modified": [
+       "{rule id}: {what changed — e.g. severity WARNING → BLOCKER}"
+     ],
+     "removed": [
+       "{anything removed from golden_rules or terminology}"
+     ],
+     "workspace_changes": [
+       "{any service flagged NOT_FOUND_IN_LAST_SCAN}",
+       "{any new kafka topic discovered by scan}"
+     ],
+     "merge_impact": "MERGE — MCP-owned sections overwritten, workspace sections preserved",
+     "previous_mcp_version": "{old npm version}",
+     "backup_file": ".secufusion-project-spec.json.backup-{timestamp}"
    }
    ```
-2. Update the `<MEMORY>` block in `.agents/claude.md`:
-   - Set `DNA_LOADED` to `true`
-   - Set `LAST_INIT` to the current ISO timestamp
-   - Set `ARCHITECTURE_SUMMARY` to the 2-3 sentence summary from above
 
-## Phase 3 — REPORT
+   **Rule:** `_changelog` is append-only. Never delete an entry. Never modify a past entry.
+   The full history must be preserved so any developer can audit exactly what changed
+   on their machine and when.
+
+6. **Write merged file**
+   Write the final merged JSON to workspace root — with the updated `_changelog` included.
+   Report what changed:
+
+```
+✅ Spec merged: v{old} → v{new}
+
+Updated (MCP-owned):
+  • golden_rules: {n} rules (was {m})
+  • terminology: Device/Machine rules refreshed
+  • coding_style: updated
+  • platform: updated
+
+Preserved + refreshed (workspace-owned):
+  • microservices: {n} services ({m} newly discovered)
+  • kafka_topics: {n} topics ({m} newly discovered)
+  • {service}: flagged NOT_FOUND_IN_LAST_SCAN — verify if service was removed
 
-Summarize what was found:
-- Number of services, domain models, API endpoints, and event topics discovered
-- Any gaps or areas marked `(inferred)` that the human should verify
-- **CRITICAL CORE CHECK:** Explicitly verify that the DNA map contains mappings for **frontend**, **backend**, and **snf-browser-extn** (extension). If ANY of these 3 are missing, print a prominent warning listing exactly what is missing and what needs to be cloned/added.
-- Confirm that `.secufusion/dna.json` was written successfully
+Changelog entry appended: v{new} — {date}
+Backup: .secufusion-project-spec.json.backup-{timestamp}
+```
 
-## Phase 4 — ARCHITECTURE DIAGRAM
 
-Using the data now in `dna.json`, generate a comprehensive **Mermaid diagram** (`graph TD`) that visualizes:
+
+### If UP TO DATE (version matches)
+
+Do not rewrite the file. Load it and proceed directly to Phase 5.
+Report:
+```
+✅ .secufusion-project-spec.json is current (v{version}) — no changes needed.
+```
+
+
+
+### Required structure
+
+Write a JSON file with this exact top-level shape:
+
+```json
+{
+  "_meta": {
+    "version": "1.0",
+    "generated_at": "<ISO timestamp>",
+    "generation_source": "/sfn:init scan",
+    "warning": "Do not edit manually. Use manage_project_spec(action: update) to modify fields."
+  },
+  "platform": {
+    "name": "<project name>",
+    "type": "<platform type from scan>",
+    "tenancy_model": "<single-tenant | multi-tenant>",
+    "auth_provider": "<Keycloak | Auth0 | etc>",
+    "event_bus": "<Kafka | RabbitMQ | none>",
+    "database": "<PostgreSQL | MySQL | etc>",
+    "migration_strategy": "<MANUAL | Flyway auto | Liquibase>"
+  },
+  "terminology": {
+    "_critical": "Read before touching any entity named Device or Machine.",
+    "Device": "A BROWSER INSTALLATION — Chrome, Edge, Firefox on a machine. NOT a physical machine.",
+    "Machine": "A PHYSICAL ENDPOINT — laptop, desktop, workstation.",
+    "history": "The platform originally used Device to mean physical endpoint. Terminology was corrected in backend services and data models. Older code may still use legacy Device naming for what is now a Machine.",
+    "rules": [
+      "Before declaring a bug involving 'device': confirm whether it is a Browser (Device) or Physical Endpoint (Machine).",
+      "Naming inconsistency does NOT equal a bug — verify which entity is actually referenced.",
+      "Frontend labels do NOT map 1:1 to backend entity names."
+    ]
+  },
+  "microservices": {
+    "<service-name>": {
+      "language": "<Java | TypeScript | Go | ...>",
+      "framework": "<Spring Boot | Express | ...>",
+      "responsibility": "<one sentence>",
+      "gateway_route": "<route pattern or NOT_CONFIRMED>",
+      "has_database": true,
+      "has_migrations": true,
+      "migration_path": "src/main/resources/db/migration",
+      "migration_notes": "<version gaps or other notes>",
+      "kafka_produces": ["<topic-name>"],
+      "kafka_consumes": ["<topic-name>"],
+      "direct_rest_calls": {
+        "<target-service>": "<description and risk>"
+      }
+    }
+  },
+  "frontend": {
+    "repo": "<repo name>",
+    "language": "<TypeScript | JavaScript>",
+    "framework": "<React | Vue | Angular | ...>",
+    "gateway_connection": "<how it connects to backend>",
+    "terminology_note": "<UX normalization note if applicable>"
+  },
+  "chrome_extension": {
+    "repo": "<repo name>",
+    "language": "<Node + Go | ...>",
+    "gateway_connection": "<how it connects>",
+    "deployment": "<deployment mechanism>"
+  },
+  "kafka_topics": {
+    "<topic-name>": {
+      "producers": ["<service>"],
+      "consumers": ["<service>"],
+      "risk": "<normal | fan-out | two-producers | DEAD TOPIC>"
+    }
+  },
+  "cross_service_call_graph": {
+    "<caller> -> <callee>": "<mechanism and risk>"
+  },
+  "golden_rules": {
+    "<rule-id>": {
+      "rule": "<the rule>",
+      "severity": "<BLOCKER | WARNING>",
+      "reason": "<why it exists>"
+    }
+  },
+  "coding_style": {
+    "comments": "Explain WHY, never WHAT.",
+    "naming": "<casing conventions>",
+    "migration_naming": "<pattern>",
+    "constraint_naming": "<pattern>"
+  },
+  "services_with_migrations": ["<service-name>"],
+  "services_without_migrations": ["<service-name>"]
+}
+```
+
+### Mandatory golden rules to always include
+
+Regardless of what the scan finds, always write these rules into `golden_rules`.
+These are non-negotiable on SecuFusion:
+
+```json
+"tenant_isolation":      { "rule": "Every *Repository.java query method MUST filter by tenantId.", "severity": "BLOCKER" },
+"kafka_no_blocking":     { "rule": "@KafkaListener MUST NOT make synchronous HTTP calls or blocking DB writes.", "severity": "BLOCKER" },
+"migration_before_deploy": { "rule": "Every migration script MUST be run via psql BEFORE deploying code that depends on it.", "severity": "BLOCKER" },
+"no_flyway_auto_exec":   { "rule": "No spring.flyway.* config. No auto-execution on boot.", "severity": "BLOCKER" },
+"cross_service_timeout": { "rule": "Every RestTemplate/WebClient call MUST have explicit timeout + fallback.", "severity": "BLOCKER" },
+"no_hardcoded_env":      { "rule": "No hardcoded IPs, hostnames, ports, URLs, or credentials.", "severity": "BLOCKER" },
+"auth_required":         { "rule": "Every non-public controller method MUST have @PreAuthorize.", "severity": "BLOCKER" },
+"no_n_plus_one":         { "rule": "No repository calls inside loops.", "severity": "BLOCKER" },
+"index_with_migration":  { "rule": "New query columns MUST have CREATE INDEX in the same migration file.", "severity": "BLOCKER" },
+"no_swallowed_exceptions": { "rule": "Empty catch blocks are forbidden. Log, re-throw, or convert.", "severity": "BLOCKER" },
+"device_machine_terminology": { "rule": "Device = Browser. Machine = Physical endpoint. Confirm which entity before touching any code with these names.", "severity": "WARNING" }
+```
+
+### After writing the spec
+
+Confirm:
+```
+✅ .secufusion-project-spec.json written to {path}
+   Services mapped: {count}
+   Kafka topics mapped: {count}
+   Golden rules written: {count}
+   Migration services: {list}
+```
+
+---
+
+## PHASE 3 — Generate migration spec (only if it does not exist)
+
+If `.secufusion-migrations.json` does not exist:
+
+For each service in `services_with_migrations`:
+1. Read all `.sql` files in `src/main/resources/db/migration/`
+2. Parse the version numbers (`V{n}__description.sql`)
+3. Identify the highest version number
+4. Identify any gaps in the version sequence (e.g. V1, V2, V4 → gap at V3)
+5. Determine the next suggested version
+
+Write `.secufusion-migrations.json` at the workspace root with this structure:
+
+```json
+{
+  "services": {
+    "<service-name>": {
+      "has_migrations": true,
+      "migration_path": "src/main/resources/db/migration",
+      "naming_convention": {
+        "pattern": "V{n}__description.sql",
+        "examples_spread": ["V1__initial_schema.sql", "V2__add_tenant_id.sql"]
+      },
+      "content_conventions": {
+        "comment_style": "-- ===\n-- V{n}: Description\n-- WHY: Reason\n-- NOTE: Applied MANUALLY\n-- ===",
+        "constraint_naming": "chk_{table}_{field} for checks, idx_{table}_{column} for indexes"
+      },
+      "current_state": {
+        "highest_version_number": 5,
+        "next_suggested": "V6",
+        "all_versions": [1, 2, 3, 4, 5]
+      },
+      "organization": {
+        "version_gaps": [],
+        "notes": "No gaps — sequence is clean"
+      }
+    }
+  },
+  "mcp_guardrails": {
+    "naming_pattern_to_enforce": "^V\\d+__[a-z][a-z0-9_]*\\.sql$",
+    "never_reuse_gap_versions": true,
+    "manual_execution_only": true,
+    "execution_command": "psql -U <user> -d <database> -f <filename>"
+  }
+}
+```
+
+Confirm:
+```
+✅ .secufusion-migrations.json written to {path}
+   Services with migrations: {list}
+   Version gaps found: {list per service}
+```
+
+---
+
+## PHASE 4 — Generate dna.json (always — or refresh if asked)
+
+Write `.secufusion/dna.json` with the combined scan output:
+
+```json
+{
+  "scannedAt": "<ISO timestamp>",
+  "services": [ /* from scan_repository_stack */ ],
+  "domainModels": [ /* from extract_domain_models */ ],
+  "apiEndpoints": [ /* from extract_api_endpoints */ ],
+  "eventTopics": [ /* from extract_event_topics */ ],
+  "architectureSummary": "<2-3 sentence human-readable summary of the architecture>"
+}
+```
+
+---
+
+## PHASE 5 — Update session state
+
+Update `.agents/claude.md` MEMORY block:
+
+```json
+{
+  "DNA_LOADED": true,
+  "LAST_INIT": "<ISO timestamp>",
+  "ARCHITECTURE_SUMMARY": "<2-3 sentences from architectureSummary above>",
+  "ACTIVE_WORK_ITEM": null
+}
+```
+
+---
+
+## PHASE 6 — Report and diagram
+
+### Summary report
+
+```
+══════════════════════════════════════════════════════
+  SecuFusion Init Complete
+══════════════════════════════════════════════════════
+
+Files generated (or already existed):
+  ✅ .secufusion-project-spec.json  — {path}
+  ✅ .secufusion-migrations.json    — {path}
+  ✅ .secufusion/dna.json           — {path}
+  ✅ .agents/claude.md              — DNA_LOADED: true
+
+Discovered:
+  Services:       {count} ({list})
+  Domain models:  {count} entities
+  API endpoints:  {count}
+  Kafka topics:   {count} ({list dead topics with ⚠️})
+  Migrations:     {services with migrations}
+
+Warnings:
+  {any inferred routes or unconfirmed connections}
+  {any dead Kafka topics}
+  {any missing repos per spec expectations}
+
+══════════════════════════════════════════════════════
+```
+
+### Architecture diagram
+
+Generate a Mermaid `graph TD` diagram showing:
 - All microservices and their bounded contexts
-- REST API call graph (which service calls which)
-- Kafka topic flow (producer → topic → consumer)
-- Frontend and `snf-browser-extn` connections to backend services
+- REST API call graph (which service calls which, including direct bypass calls)
+- Kafka topic flow (producer → topic → consumer, flag dead topics with ⚠️)
+- Frontend and extension connections to backend
+
+Render the diagram in your response.
+
+---
+
+## PHASE 7 — Handover instructions for new developers
+
+After generating everything, output this exactly:
+
+```
+══════════════════════════════════════════════════════
+  WORKSPACE READY
+
+  All memory files generated. This workspace is now
+  fully primed for SecuFusion MCP tooling.
+
+  Important files created:
+  • .secufusion-project-spec.json  — permanent project memory
+  • .secufusion-migrations.json    — migration version tracking
+  • .secufusion/dna.json           — architectural scan results
+
+  These files are generated from your local source code.
+  They are safe to commit to the repo so teammates get
+  them pre-populated on clone.
 
-Render the diagram directly in your response so the user can see the full ecosystem at a glance.
+  Next steps:
+  • To start a task: /sfn:plan <WI-ID>
+  • To review code:  /sfn:review <WI-ID>
+  • To refresh DNA:  /sfn:init (safe — will not overwrite existing spec)
 
-**Next step for the user:** Run `/sfn-plan <ticket-id>` to start your first task.
+  If you cloned this repo and these files already exist:
+  • You do not need to run /sfn:init
+  • The MCP is already primed and ready
+  • Run /sfn:plan <your-ticket> to start working
+══════════════════════════════════════════════════════
+```