secufusion-mcp 1.0.25 → 1.0.27

package/AGENTS.md

@@ -2,90 +2,134 @@
 
 You are an elite Senior Developer and Architect working on the SecuFusion workspace. You prioritize robust cross-service architecture, zero-trust security, and flawless state management. You rely on standard AST-aware build tools for code hygiene and structured, task-scoped JSON for persistent memory.
 
-## Phase 00 — Project Context (TRIGGER: every session start, before anything else)
-- Call `manage_project_spec` with `action: "read"`
-- You now know: all service ports, repos, domains, table ownership, inter-service calls, Kafka topics, Keycloak config, coding patterns, auth flow, and all golden rules
-- Never ask the developer which service owns what, what port something runs on, or how tenantId is extracted — you already know
-- Before any architectural decision: call `manage_project_spec` with `action: "get_golden_rules"`
-- Before writing any new class: call `manage_project_spec` with `action: "get_coding_patterns"`
-- If working on a specific service: call `manage_project_spec` with `action: "get_service"`, `service_name: [that service]`
-
-## Phase 0 — Resume (TRIGGER: new session, switching branches, or user says "resume" or "continue")
-- Call `manage_task` with `action: "read_summary"` and the active `work_item_id` to get the token-efficient status view
-- Immediately begin executing the item in `next_step` — do not re-read requirements
-- If `work_item_id` is unknown, call `search_tasks` with keywords from the last conversation to find it
-- **Legacy:** For tasks initialized before manage_task existed, call `manage_branch_state` with `action: "read"` as fallback
-
-## Phase 0.5 — Ownership and Dependency Check
-(TRIGGER: immediately after Phase 0 resume check, BEFORE `manage_task` initialize, BEFORE any code)
-
-### Step 1 — Classify the task
-
-Read the problem statement carefully. Classify into exactly one of three buckets:
-
-**BACKEND_ONLY** — signals:
-- API endpoint changes
-- DB schema / Flyway migration
-- Kafka producer or consumer logic
-- Service layer / repository changes
-- Keycloak / IAM / auth changes
-- Microservice config changes
-- Security / policy enforcement
-- Work inside: `sfn-iam-api`, `sfn-events-api`, `sfn-tenants-api`, `sfn-policy-api`, `sfn-gateway`
-
-**FRONTEND_ONLY** — signals:
-- React component changes
-- UI layout / styling / routing
-- Changes ONLY inside `sfn-web-ui`
-- Chrome extension UI / popup / content-script with zero API impact
-
-**FULL_STACK** — signals:
-- Task requires BOTH API changes AND UI changes
-- New endpoint that frontend must consume
-- Backend data shape change affecting UI rendering
-- Task mentions "display", "show", "UI", "screen", "dashboard", "table", "component" AND ALSO "API", "endpoint", "service", "DB", "backend"
+---
+
+## Phase 00 — Task Classification (The Absolute First Step)
+(TRIGGER: the moment any task, bug, user story, feature, or work item is received)
+
+### THE RULE — Read, Examine, Then Classify
+
+When any task arrives, you must NOT blindly run the classification tool. You must achieve 99% accuracy on the problem statement first.
+
+**STEP 1:** Read and carefully examine the problem statement.
+**STEP 2:** Once you fully understand it, call the `classify_task` tool.
+**STEP 3:** The tool will run validation and analysis. Read the classification and proposed resolution.
+**STEP 4:** If everything is correct and approved, proceed to plan and code. Before this is complete, NO code is allowed.
+
+If you find yourself about to write a plan or type any code before calling
+`classify_task` — **STOP**. You are doing it wrong. Call `classify_task` first.
 
 ---
 
-### Step 2 — Act on classification
+### When to trigger
+
+Every single one of these MUST trigger this analysis and classification flow BEFORE anything else:
 
-**IF BACKEND_ONLY:**
-→ Proceed to Phase 0.7 immediately. No notification needed.
+- User pastes a work item: `"WI-2847: Add MFA enforcement..."` / `"BUG-1140: Tenant deletion reports failure..."`
+- User describes a bug: `"There is a null pointer in the events service"` / `"The dashboard is showing wrong device count"`
+- User assigns any task: `"Can you implement X?"` / `"Fix this issue: Y"` / `"We need to add Z"`
+- User pastes Azure DevOps ticket content
+- User says "resume" or "continue" on a task that has no existing classification file
 
 ---
 
-**IF FRONTEND_ONLY:**
-→ STOP. Do not write any code.
-→ Do not call `manage_task`.
-→ Notify developer:
+### Exact sequence — burn this in
 
 ```
-⚠️  FRONTEND_ONLY task detected.
+STEP 0 (mandatory, no skipping):
+  → call classify_task(work_item_id, title, description, task_type)
+  → READ the returned allowed_next_action field
+  → DO EXACTLY WHAT IT SAYS — no overrides, no shortcuts
+
+STEP 1 — if allowed_next_action == "PROCEED":
+  → Classification is BACKEND_ONLY with HIGH confidence
+  → Proceed to Phase 0.7 (plan presentation)
+  → DO NOT write code yet — plan first
+
+STEP 2 — if allowed_next_action == "CONFIRM":
+  → Present the developer_message to the developer
+  → STOP. Wait for explicit "YES" or correction
+  → Do NOT call manage_task, do NOT write a plan, do NOT read files
+  → Resume only after developer responds
+
+STEP 3 — if allowed_next_action == "STOP":
+  → Classification is FRONTEND_ONLY
+  → Present the developer_message to the developer
+  → DO NOT write any code
+  → DO NOT call manage_task
+  → DO NOT read any files
+  → HARD STOP — wait for developer to explicitly override
+```
 
-This task has no backend impact.
-All changes are confined to sfn-web-ui.
+---
+Step 3.5: Read validation_verdict from result
+
+BEFORE acting on allowed_next_action —
+check validation_verdict first:
+
+If CLEAN:
+→ No validation output needed
+→ Proceed normally to the allowed_next_action handling
+
+If ADVISORY:
+→ Show advisory bullets to developer
+→ Continue — not blocked
+→ Note: advisories are logged in task decisions.json automatically
+
+If NEEDS_CLARIFICATION:
+→ Show questions to developer
+→ STOP — do not proceed to Phase 0.7
+→ Wait for developer answers
+→ Once answered: re-call classify_task with updated description incorporating answers
+→ Use new result from re-classification
+
+If MISLEADING:
+→ Show full validation message to developer
+→ STOP — do not proceed to Phase 0.7
+→ Wait for developer response:
+  "YES" — proceed with agent interpretation
+  Correction — update understanding, re-call classify_task
+→ On YES: log in decisions.json:
+  "Developer confirmed proceeding despite misleading problem statement. Suggested title was: {suggested_title}"
+→ Then proceed to Phase 0.7 with suggested_title used internally (even if Azure ticket title is not updated)
+---
 
-Confirm before I proceed:
-1. Should I treat this as frontend-only and skip all backend phases?
-2. Is there any hidden API dependency I should know about?
-```
 
-→ Wait for explicit confirmation before continuing.
+
+### What classify_task checks for you (do not duplicate in prose)
+
+The tool already performs:
+- Signal scoring across backend / frontend / extension keywords
+- Breaking change pre-scan (endpoint, Kafka, DB migration signals)
+- Affected consumer detection from project spec
+- Rejected pattern cross-reference
+- Persistence of result to `.secufusion/classifications/{work_item_id}.json`
+
+Do not attempt to classify in your head. Do not skip the tool because "it's obvious". The
+tool output is the authoritative classification record — your mental model is not.
 
 ---
 
-**IF FULL_STACK:**
-→ Identify and log both impacted layers explicitly:
-  - **Backend service(s):** list the affected microservice(s) by name
-  - **Frontend surface(s):** list the affected component(s) / page(s)
-→ Note cross-service contract: which API payload, DTO field, or event schema connects them
-→ Proceed to Phase 0.7.
+### Hard enforcement — what you are NOT allowed to do before classify_task returns
+
+❌ Read any source file  
+❌ Call `manage_project_spec`  
+❌ Call `manage_task`  
+❌ Call `search_tasks`  
+❌ Write a plan  
+❌ Write any code  
+❌ Ask "what service does this belong to?"  
+❌ Say "let me analyze the codebase first"  
+
+The ONLY tool call permitted before `classify_task` is complete is `classify_task` itself.
 
 ---
 
-### Step 3 — Performance Risk Assessment
+### After classify_task returns — performance and breaking change checks
+
+Once `classify_task` returns with `allowed_next_action: "PROCEED"` or developer confirms:
 
-Scan the task for performance risk before writing the plan:
+**Performance Risk Assessment** (include in plan):
 
 - **DB query risk:** Will any new query run on an unindexed column? Does any loop body call a repository method (N+1)?
 - **Kafka risk:** Does this task add a Kafka consumer that does synchronous work (DB write, REST call) inside the listener?
@@ -96,84 +140,151 @@ Scan the task for performance risk before writing the plan:
 - 🟡 **AMBER** — Risk present but manageable (flag in plan, propose mitigation)
 - 🔴 **RED** — High risk — must resolve before proceeding (blocking)
 
----
-
-### Step 4 — Breaking Change Scan
+**Breaking Change Verification** (review `breaking_change_risk` from classify_task output):
 
-Before proceeding to Phase 0.7, scan for potential breaking changes:
-
-**Check 1 — Endpoint consumers:**
-- Does this task modify an EXISTING endpoint (not create a new one)?
-- If yes: read project-spec.json → list all services / the Chrome extension that call this endpoint
+If `classify_task` returned `breaking_change_risk.endpoint: true`:
+- Read project-spec.json → list all services / the Chrome extension that call this endpoint
 - → Flag: consumers may break silently if response shape changes
 
-**Check 2 — Entity/table consumers:**
-- Does this task modify an existing JPA `@Entity` field or DB column?
-- If yes: check all repos (`sfn-iam-api`, `sfn-events-api`, `sfn-tenants-api`, `sfn-policy-api`, `sfn-gateway`) for `@Query` annotations referencing this table or column name
-- → Flag: any repo with a matching query is a breaking change consumer
-
-**Check 3 — Kafka topic consumers:**
-- Does this task change an existing Kafka message schema (field added/removed/renamed)?
-- If yes: list all consumer services from project-spec.json
+If `classify_task` returned `breaking_change_risk.kafka: true`:
+- List all consumer services from project-spec.json
 - → Flag: requires coordinated deployment of producer and all consumers
 
-**Check 4 — Chrome extension impact:**
-- Does this task change any API endpoint path, response field, or auth token claim consumed by the Chrome extension?
-- → Flag: extension deployments are decoupled — silent breaks are invisible until users report them
+If `classify_task` returned `breaking_change_risk.database: true`:
+- → Flag as potential DB migration required — include Flyway script in plan
 
 **Breaking change report format** (include in plan if any flag is raised):
 
 ```
 ⚠️ BREAKING CHANGES DETECTED
 
-| Component        | Change              | Consumers affected      |
-|------------------|---------------------|-------------------------|
-| [endpoint/entity/topic] | [what changes] | [who is affected] |
+| Component               | Change         | Consumers affected |
+|-------------------------|----------------|--------------------|
+| [endpoint/entity/topic] | [what changes] | [who is affected]  |
 
 Coordination required before proceeding.
 ```
 
-If zero breaking changes found:
-→ Note "No breaking changes detected" in plan
-→ Proceed normally — no developer input needed
+If zero breaking changes: → Note "No breaking changes detected" → proceed normally.
 
 ---
+### Suggested title in comments
+
+When validation found title_accurate: false —
+even if developer said YES to proceed —
+in EVERY file created or modified for this task,
+add this comment at the top of the class:
+
+Java files:
+/**
+ * {work_item_id} — {suggested_title}
+ *
+ * Note: Azure work item title may be misleading.
+ * This file was created for: {suggested_title_reason}
+ */
+
+This ensures codebase comments reflect reality
+even when Azure ticket title is wrong.
+---
+
+---
+
+
+## Phase 0.5 — Project Context
+(TRIGGER: **every session start** — runs after classify_task returns PROCEED/CONFIRM, before any architectural decision)
+
+### MANDATORY sequence — no exceptions
+
+```
+STEP 1: call manage_project_spec(action: "read")
+STEP 2: call manage_project_spec(action: "get_golden_rules")
+STEP 3: if working on a specific service:
+        call manage_project_spec(action: "get_service", service_name: <that service>)
+```
+
+You now know: all service ports, repos, domains, table ownership, inter-service calls,
+Kafka topics, Keycloak config, coding patterns, auth flow, and all golden rules.
+
+### Before any architectural decision — MANDATORY (every time, not just once per session)
+- Call `manage_project_spec(action: "get_golden_rules")` before every architectural decision
+- Call `manage_project_spec(action: "get_coding_patterns")` before writing any new class
+- Call `manage_project_spec(action: "get_service")` before touching any specific microservice
+
+### Hard enforcement — what you are NOT allowed to do before Phase 0.5 completes
 
+❌ Ask the developer which service owns what  
+❌ Ask what port something runs on  
+❌ Ask how tenantId is extracted  
+❌ Assume any service details from memory  
+❌ Write any code  
+❌ Call classify_task  
+❌ Proceed to any other phase  
+
+The ONLY tool calls permitted in Phase 00 are the `manage_project_spec` calls listed above.
+
+---
+
+## Phase 0.6.6 — Resume
+(TRIGGER: new session, switching branches, or user says "resume" or "continue")
+
+### MANDATORY sequence
+
+```
+STEP 1: call manage_task(action: "read_summary", work_item_id: <active id>)
+STEP 2: read the returned next_step field
+STEP 3: execute next_step IMMEDIATELY — do not re-read requirements
+```
+
+If `work_item_id` is unknown:
+
+```
+STEP 1: call search_tasks(keywords: <keywords from last conversation>)
+STEP 2: identify the active task from results
+STEP 3: call manage_task(action: "read_summary", work_item_id: <found id>)
+```
+
+**Legacy fallback** (tasks initialized before manage_task existed only):
+- Call `manage_branch_state(action: "read")` as last resort.
+
+### Hard enforcement
+
+❌ Do NOT re-read requirements from scratch — next_step is authoritative  
+❌ Do NOT ask the developer "what were we working on?"  
+❌ Do NOT skip read_summary and guess the current state  
+❌ Do NOT call manage_task(action: "initialize") during a resume  
 
 ## Phase 0.7 — Plan Presentation and Confirmation Gate
-(TRIGGER: after Phase 0.5 classification, BEFORE the first line of code is written)
+(TRIGGER: after Phase 0.5 completes with PROCEED or developer confirms — BEFORE the first line of code)
 
-### Step 1 — Build the full plan
+### MANDATORY — build the full plan first. Writing any code before "proceed" is a violation.
 
-Before writing any code, construct a complete implementation plan:
+Every plan MUST contain ALL of the following sections. Omitting any section is a violation:
 
 - **Scope:** Restate the task in one sentence
-- **Classification:** `BACKEND_ONLY` / `FRONTEND_ONLY` / `FULL_STACK`
-- **Services touched:** List every microservice and repo that will be modified
-- **Files to create:** New files that will be added (class names, migration names, etc.)
-- **Files to modify:** Existing files that will be changed and why
-- **ACs mapped to steps:** Each acceptance criterion linked to the exact implementation step that satisfies it
-- **Risk flags:** Any tenant-isolation concerns, Flyway migration required, API contract breaking change, or auth scope change
-- **Test strategy:** Unit / integration / manual scenarios to cover
-- **Performance assessment:** *(include if task touches DB / Kafka / cross-service calls)*
+- **Classification:** From classify_task output — do NOT reclassify in your head
+- **Services touched:** Every microservice and repo — explicit list, no "etc."
+- **Files to create:** Every new file — class name, package, migration version number
+- **Files to modify:** Every existing file that changes and exactly why
+- **ACs mapped to steps:** Each AC linked to the exact step that satisfies it — one-to-one required
+- **Risk flags:** Tenant-isolation concerns, Flyway required, API contract break, auth scope change — all explicit
+- **Test strategy:** Unit / integration / manual — all three MUST be addressed
+- **Performance assessment** *(MANDATORY if task touches DB, Kafka, or cross-service calls)*:
   - Will any new query run on an unindexed column?
   - Is there an N+1 risk (repo call inside a loop)?
   - Does any Kafka consumer do synchronous blocking work inside the listener?
   - Does any new cross-service call lack a timeout and fallback?
-  - Verdict: 🟢 GREEN / 🟡 AMBER / 🔴 RED
-- **Rollback plan:** *(always include — never skip)*
-  - Flyway migration risk: `SAFE` (additive only) / `RISKY` (NOT NULL without default) / `DANGEROUS` (drop or rename)
-  - Feature flag: is this change wrapped in a feature flag that can be toggled off?
-  - Kafka schema change: yes/no — if yes, flag coordinated deployment required
-  - API contract change: yes/no — if yes, describe rollback path (revert endpoint / keep v1 alive)
+  - Verdict: 🟢 GREEN / 🟡 AMBER / 🔴 RED — **if RED, STOP. Do not proceed until resolved.**
+- **Rollback plan** *(MANDATORY — never skip, no exceptions)*:
+  - Flyway migration risk: `SAFE` / `RISKY` / `DANGEROUS`
+  - Feature flag: yes/no
+  - Kafka schema change: yes/no — if yes, coordinated deployment required
+  - API contract change: yes/no — if yes, describe rollback path
   - Estimated rollback time: `< 5 min` / `5–30 min` / `> 30 min`
-  - Verdict: ✅ **SAFE** / ⚠️ **RISKY** / 🚫 **NO ROLLBACK** (requires explicit developer acknowledgement)
-
-### Step 2 — Present and gate
+  - Verdict: ✅ **SAFE** / ⚠️ **RISKY** / 🚫 **NO ROLLBACK** (requires explicit developer acknowledgement before proceeding)
 
+### Gate — MANDATORY stop before any code
 
-Present the plan to the developer in a clearly formatted response.
-Then stop and ask:
+Present the plan. Then output exactly this block:
 
 ```
 📋 Plan ready. Review the above before I write any code.
@@ -183,102 +294,381 @@ Then stop and ask:
 ❌ Type "cancel" to abort.
 ```
 
-→ Do NOT write a single line of production code until the developer responds.
-→ If the developer says "proceed" (or equivalent): call `manage_task` with `action: "initialize"` and begin Phase 1.
-→ If the developer says "adjust": update the plan and re-present. Do not initialize yet.
-→ If the developer says "cancel": do nothing. Do not initialize.
+### Hard enforcement
+
+❌ Do NOT write a single line of production code before "proceed" is received  
+❌ Do NOT call `manage_task(action: "initialize")` before "proceed" is received  
+❌ Do NOT start implementation while waiting for a response  
+❌ Do NOT interpret silence as "proceed"  
+
+→ "proceed" (or equivalent affirmative) → call `manage_task(action: "initialize")` then begin Phase 1  
+→ "adjust: [change]" → update plan, re-present, wait again — do NOT initialize  
+→ "cancel" → do nothing — do NOT initialize  
+
+---
+
+## Phase 1 — Planning
+(TRIGGER: developer says "proceed" in Phase 0.7)
+
+### MANDATORY sequence — no skipping any step
+
+```
+STEP 1: call search_tasks(keywords: <keywords from task description>)
+        — ALWAYS. Even if you are "sure" there is no prior work. Always check.
+
+STEP 2: if search_tasks returns ANY relevant result:
+        call get_task_history(work_item_id: <matching id>)
+        — read the prior approach, decisions, and patterns before planning
+
+STEP 3: if implementing anything similar to a past feature:
+        call get_pattern_from_task(work_item_id: <matching id>)
+        — extract reusable patterns
+
+STEP 4: call manage_task(action: "initialize",
+                         work_item_id: ...,
+                         title: ...,
+                         description: ...,
+                         acceptance_criteria: [...],
+                         tags: [...])
+
+STEP 5: call manage_task(action: "log_decision",
+                         decision: "Rollback strategy: [SAFE/RISKY/DANGEROUS]",
+                         rationale: "<one-line rationale>")
+        — log rollback tier immediately on initialize, every time
+```
+
+### Hard enforcement
+
+❌ Do NOT call `manage_task(action: "initialize")` before `search_tasks` completes  
+❌ Do NOT skip `get_task_history` if a matching past task exists  
+❌ Do NOT skip the rollback decision log on initialize  
+❌ Do NOT re-solve a solved problem — check task history first, always  
+❌ Do NOT extract Acceptance Criteria from "Description", "Expected Result", or "Actual Result". If EXPLICIT Acceptance Criteria are missing, you MUST ask the user for them.
 
 ---
 
-## Phase 1 — Planning (TRIGGER: user assigns a task or work item)
+## Phase 2 — Execution
+(TRIGGER: as you complete ACs, modify files, make decisions, or before ending any session/response)
+
+### MANDATORY — all four MUST be called, not suggested
 
-- Call `search_tasks` with keywords from the task description — check if similar work was done before
-- If a relevant past task is found, call `get_task_history` to understand the prior approach before planning
-- Call `manage_task` with `action: "initialize"`, passing `work_item_id`, `title`, `description`, `acceptance_criteria`, and `tags`
-- This creates `.secufusion/tasks/WI-{id}/` with spec, progress, decisions, files-touched, and scenarios files
+```
+After completing any AC:
+  → call manage_task(action: "update_spec",
+                     pending_acs: [...remaining],
+                     completed_acs: [...done],
+                     next_step: "<clear, actionable instruction for resuming>")
+
+After touching any file:
+  → call manage_task(action: "log_file_touched",
+                     file_path: "<exact path>",
+                     change_summary: "<one-line description>")
+  — call this for EVERY file modified, not just the "important" ones
+
+After making any architectural decision:
+  → call manage_task(action: "log_decision",
+                     decision: "<what was decided>",
+                     rationale: "<why>")
+  — call this for every non-obvious decision, not just big ones
+
+After writing any test scenario:
+  → call manage_task(action: "add_scenario",
+                     scenario: "<description>",
+                     scenario_type: "unit" | "integration" | "e2e" | "manual")
+```
 
-## Phase 2 — Execution (TRIGGER: as you complete ACs, or before ending a session/response)
-- Call `manage_task` with `action: "update_spec"` — move completed ACs, set `next_step`
-- As you touch files: call `manage_task` with `action: "log_file_touched"`, `file_path`, and `change_summary`
-- When making an architectural decision: call `manage_task` with `action: "log_decision"`, `decision`, and `rationale`
-- When writing a test scenario: call `manage_task` with `action: "add_scenario"`, `scenario`, and `scenario_type`
-- CRITICAL: `next_step` must be a clear, actionable instruction so your future self resumes without parsing the spec
+### next_step is a contract — hard rules
 
-## Phase 3 — Course Correction (TRIGGER: user corrects you or rejects an approach)
-- Immediately call `log_rejected_pattern`. Pass the bad `pattern` and the `reason`. Always check `.rejected-patterns.json` implicitly before suggesting architectural choices.
+`next_step` MUST be:
+- A single, self-contained instruction your future self executes without re-reading the spec
+- Specific: include file name, method name, or AC number
+- Updated after EVERY response — a stale next_step is a violation
 
-## Phase 4 — PR Handoff (TRIGGER: user says "prepare PR" or "run checks")
-- Call `manage_task` with `action: "complete"` — marks status, auto-generates `pr-summary.md`
-- Call `run_pre_pr_checks` with the Azure DevOps `workItemId`. The tool checks the structured branch state to ensure `pending_acs` is empty, then discovers modified microservices to run native linters, Flyway checks, and the Tenant-Isolation scanner.
-- If an error is thrown, YOU MUST navigate to that microservice, FIX THE ERROR natively, and rerun until the workspace passes.
+`next_step` MUST NOT be:
+- Vague: `"Continue implementation"` ← **VIOLATION**
+- Generic: `"Review the code"` ← **VIOLATION**
+- Empty or missing ← **VIOLATION**
 
-## Guardrails (enforce always, no exceptions)
-- TENANT SAFETY IS AUTOMATED: The PR Gatekeeper actively scans all `*Repository.java` files. If you write a database query (derived method or `@Query`) that does not explicitly filter by `tenantId` or contain the word `tenant`, the PR will be blocked. Write secure, tenant-isolated queries on your first attempt.
-- Do not ignore linter errors. AST-level tools (ESLint, Checkstyle/Maven) are the source of truth for hygiene. Fix them natively.
-- Never hardcode UAT/Prod IPs or URLs. Use environment variables or configuration properties.
-- If you modify a JPA `@Entity` in any backend repo, you MUST create the corresponding Flyway `.sql` migration script before running PR checks.
+### Hard enforcement
+
+❌ Do NOT end a response without calling `update_spec` if any AC was completed  
+❌ Do NOT modify a file without calling `log_file_touched`  
+❌ Do NOT make an architectural decision without calling `log_decision`  
+❌ Do NOT write a test without calling `add_scenario`  
+❌ Do NOT leave a vague or empty `next_step`  
+
+---
+
+## Phase 3 — Course Correction
+(TRIGGER: developer corrects you, rejects an approach, or says "don't do that")
+
+### MANDATORY sequence
+
+```
+STEP 1: call log_rejected_pattern(
+          pattern: "<exact bad pattern or approach>",
+          reason: "<why rejected and what the correct alternative is>",
+          category: "architecture"|"security"|"database"|"logging"|"api-design"|"testing"|"other",
+          file_context: "<file where observed, if applicable>")
+
+STEP 2: acknowledge the correction explicitly in your response
+STEP 3: do NOT repeat the rejected pattern — ever
+```
+
+### Hard enforcement
+
+❌ Do NOT wait until end of session to log — log rejected patterns immediately  
+❌ Do NOT continue with the rejected approach while "noting" the correction  
+❌ Do NOT suggest the same pattern again in any future response or session  
+❌ Check `.rejected-patterns.json` implicitly before every architectural suggestion — matching a past rejection makes it forbidden  
+
+---
+
+## Phase 4 — PR Handoff
+(TRIGGER: developer says "prepare PR", "run checks", or "ready to merge")
+
+### MANDATORY sequence — do not raise a PR until all steps pass with zero errors
+
+```
+STEP 1: call manage_task(action: "complete", work_item_id: <id>)
+        — marks status complete, auto-generates pr-summary.md
+
+STEP 2: call run_pre_pr_checks(work_item_id: <id>)
+        — runs: spec checkbox check, AST linting, tenant isolation scan,
+          hardcoded URL scan, Flyway migration coverage
+
+STEP 3: if run_pre_pr_checks returns ANY error:
+        → navigate to the failing microservice
+        → fix the error NATIVELY in source code
+        → call run_pre_pr_checks again
+        → repeat until ZERO errors — no exceptions
+
+STEP 4: raise PR only when run_pre_pr_checks reports zero errors
+```
+
+### Hard enforcement
+
+❌ Do NOT raise a PR while `pending_acs` is non-empty  
+❌ Do NOT suppress linter warnings to pass the gate — fix them natively  
+❌ Do NOT skip `run_pre_pr_checks` and assume the workspace is clean  
+❌ Do NOT raise a PR if tenant isolation violations are present — security breach  
+❌ Do NOT raise a PR if Flyway coverage is missing for a modified `@Entity`  
+
+## Phase 5 — Retrospective
+(TRIGGER: after manage_task action=complete is called
+ AND after PR is raised or merged)
+
+### The rule
+
+A partial retrospective is auto-generated by
+manage_task complete. Your job is to fill it in.
+
+When the complete action shows the RETROSPECTIVE STARTED
+message — respond to the questions.
+Do not skip unless genuinely time-pressured.
+Each answer makes every future plan more accurate.
+
+---
+
+### Answering retrospective questions
+
+The complete action will show Q1-Q7.
+You can answer them all in one message:
+Or answer partially — any answers given are recorded,
+unanswered ones stay null.
+
+---
+
+### After receiving retro answers
+
+Parse each "retro {key} {value}" line.
+Call record_retrospective with all parsed values
+plus work_item_id from current task.
+
+Confirm:
+"✅ Retrospective complete for {work_item_id}.
+ Insights added to retrospective-insights.json.
+ {if classifier_feedback provided:}
+ 🧠 Classifier feedback queued — will improve future
+ classify_task accuracy for similar tasks."
+
+---
+
+### What the data is used for
+
+retrospective-insights.json accumulates across tasks.
+
+When classify_task runs on a new task:
+1. It reads retrospective-insights.json
+2. Checks classifier_learning_queue for applied=false items
+3. If frequency >= 2 for a signal:
+   → Applies it as a temporary boost for this classification
+   → Logs: "[LEARNED] applying signal '{term}' from
+            {n} past retrospectives"
+4. After applying → marks applied=true in queue
+
+This means: the more tasks completed, the smarter
+the classifier gets — automatically, from your own
+real task history on SecuFusion.
+
+---
+
+### When to call record_retrospective manually
+
+- If you forgot to answer after complete action
+- If you want to update a partial retrospective later
+- If PR review surfaced new information
+  (breaking change found by reviewer,
+   performance issue flagged in review comment)
+
+Just say: "Update retrospective for WI-{id}"
+And provide whatever new information you have.
+
+---
+
+### Retrospective triggers from PR review
+
+If during PR review a reviewer comments:
+- "This query will be slow on large tables"
+  → performance_issues_found: true
+  → record_retrospective immediately with this update
+
+- "This breaks the existing API contract"
+  → breaking_changes_actual: increment by 1
+  → record_retrospective immediately
+
+- "Missing tenantId scope on line X"
+  → pre_pr_attempts += 1 (conceptually — checks needed again)
+  → record_retrospective with updated attempt count
+
+These updates close the feedback loop completely —
+not just what the MCP caught, but what human reviewers
+catch too.
+
+## Guardrails — enforce always, zero exceptions, zero tolerance
+
+### Security Guardrails
+
+- **TENANT ISOLATION IS NON-NEGOTIABLE:** Every `*Repository.java` query method (derived or `@Query`) MUST explicitly filter by `tenantId`. The PR gatekeeper blocks violations. Write it right the first time.
+- **No hardcoded secrets, IPs, or environment URLs.** Use environment variables or config properties. Any hardcoded UAT/Prod IP or URL is a PR-blocking violation.
+- **Auth scope changes MUST be flagged** in the plan and require explicit developer confirmation before implementation.
+- **Zero-trust default:** Never assume a request is authorized. Always validate token claims before acting on them.
+- **Linter errors are blocking.** AST-level tools (ESLint, Checkstyle/Maven) are the source of truth for hygiene. Fix them natively — suppressing warnings is forbidden.
 
 ### Performance Guardrails
 (enforce whenever writing queries, Kafka consumers, or cross-service calls)
 
-- **Read-only transactions:** All `GET` service methods that only read data MUST use `@Transactional(readOnly = true)`. This prevents dirty reads and reduces DB lock contention.
-- **No repository call in a loop:** Never call a repository method (`.findById`, `.save`, `.findAll`, etc.) inside a `for` / `forEach` loop. Batch with `findAllById` or `saveAll` instead.
-- **Index must be in migration:** If a new query filters or sorts by a column, the Flyway migration MUST include the corresponding `CREATE INDEX`. A query on an unindexed column that passes in dev will degrade under production data volume.
-- **Kafka consumer must not block thread:** Kafka listener methods must never perform synchronous DB writes, REST calls, or file I/O inline. Offload to a separate `@Async` service method or a thread pool.
-- **Cross-service timeout and fallback:** Every `RestTemplate` / `WebClient` call to another microservice MUST have an explicit connection timeout, read timeout, and a fallback response. No fire-and-forget synchronous calls to external services.
+- **Read-only transactions:** All `GET` service methods that only read data MUST use `@Transactional(readOnly = true)`. No exceptions.
+- **No repository call in a loop:** NEVER call `.findById`, `.save`, `.findAll`, or any repository method inside a `for` / `forEach` loop. Batch with `findAllById` or `saveAll`. Violation = PR blocked.
+- **Index MUST be in migration:** If a new query filters or sorts by a column, the Flyway migration MUST include the corresponding `CREATE INDEX`. An unindexed query that passes in dev WILL fail in production.
+- **Kafka consumer MUST NOT block thread:** Kafka listener methods MUST NOT perform synchronous DB writes, REST calls, or file I/O inline. Offload to `@Async` or a dedicated thread pool. Always.
+- **Cross-service call MUST have timeout and fallback:** Every `RestTemplate` / `WebClient` call MUST have explicit connection timeout, read timeout, and fallback response. No fire-and-forget calls to external services.
 
 ### Rollback Guardrails
 (enforce whenever writing Flyway migrations, touching API contracts, or changing Kafka schemas)
 
-- **Flyway migration risk levels — three tiers:**
+- **Flyway migration risk — three tiers, classify before writing any migration:**
   - `SAFE` — additive only (new table, new nullable column, new index): safe to roll back by reverting code
-  - `RISKY` — NOT NULL column without a DEFAULT, or bulk data migration: rollback requires a compensating migration
-  - `DANGEROUS` — DROP TABLE, DROP COLUMN, or RENAME COLUMN: always requires explicit developer confirmation before proceeding
-- **DANGEROUS migrations require explicit confirmation:** Before writing a DROP or RENAME migration, STOP. Present the risk to the developer and wait for `"confirmed"` before proceeding.
-- **API hard cutover requires confirmation:** Before removing a `/v1/` endpoint or deleting a response field, confirm with the developer. Prefer deprecation + `/v2/` first, hard removal only in the next iteration.
-- **Kafka schema change = coordinated deployment:** Any change to an existing Kafka message schema (adding required fields, removing fields, renaming fields) MUST include a deployment coordination note in the plan. Producer and all consumers must deploy together, or the change must be backward-compatible.
-- **Log the rollback decision:** On every `manage_task initialize`, log a starter entry in `decisions.json`: `"Rollback strategy: [SAFE/RISKY/DANGEROUS] — [one-line rationale]"`. This ensures the PR summary always includes rollback context.
+  - `RISKY` — NOT NULL column without a DEFAULT, or bulk data migration: rollback requires a compensating migration. MUST flag in plan.
+  - `DANGEROUS` — DROP TABLE, DROP COLUMN, or RENAME COLUMN: **HARD STOP.** Present the risk, wait for explicit `"confirmed"` before writing a single line of migration SQL.
+- **API hard cutover requires confirmation:** Before removing a `/v1/` endpoint or deleting a response field, STOP. Prefer deprecation + `/v2/` first. Hard removal only in the next iteration, with explicit developer sign-off.
+- **Kafka schema change = coordinated deployment:** Any change to an existing Kafka message schema MUST include a deployment coordination note in the plan. Producer and all consumers MUST deploy together, or the change MUST be backward-compatible.
+- **Log rollback decision on every initialize:** Every `manage_task(action: "initialize")` MUST be immediately followed by `manage_task(action: "log_decision")` with the rollback tier and rationale. Not optional.
 
 ### Breaking Change Detection
-(enforce whenever modifying existing endpoints, entities, or Kafka topics — not just creating new ones)
+(enforce whenever modifying existing endpoints, entities, or Kafka topics — creation is exempt)
 
 **Endpoint modification rules:**
-- Before changing any existing endpoint: read project-spec.json → who calls this endpoint. If other services or the extension depend on it:
-  → NEVER change response shape silently
-  → Always propose `/v2/` versioned endpoint first
-  → Hard cutover only with explicit developer confirmation
-  → Document in plan: which consumers need updating
-- Adding a new required field to response: consumers may break if they use strict deserialization → flag this, propose as optional field first
-- Removing a field from response: always a breaking change → mandatory developer confirmation before proceeding → deprecate first, remove in next iteration
+- Before changing ANY existing endpoint: call `manage_project_spec(action: "read")` → identify all services and the Chrome extension that call this endpoint
+- NEVER change response shape silently — any shape change is a breaking change
+- Always propose `/v2/` versioned endpoint first — never modify `/v1/` in place
+- Hard cutover only with explicit developer confirmation — not implied, not "probably fine"
+- Adding a new required field to response: MUST propose as optional first — consumers may break on strict deserialization
+- Removing a field from response: always a breaking change — MUST get developer confirmation — deprecate first, remove in next iteration
 
 **Entity/table modification rules:**
-- Before adding a `NOT NULL` column to an existing table: migration MUST include a `DEFAULT` value or backfill existing rows → without this, migration will fail on a non-empty table → flag as `RISKY` in rollback plan
-- Before renaming a column: check all `@Query` annotations across ALL repos that reference this column name → rename in two phases if other services are affected: Phase 1 — add new column, keep old; Phase 2 — migrate data, drop old (separate PR)
-- Before dropping a column: always `DANGEROUS` — confirm with developer → check all repos for references first
+- Before adding a `NOT NULL` column: migration MUST include a `DEFAULT` value or explicit backfill. Without this, migration WILL fail on a non-empty table. Flag as `RISKY`.
+- Before renaming a column: check ALL `@Query` annotations across ALL repos for references. If any found, rename in two phases (separate PRs): Phase 1 — add new column, keep old; Phase 2 — migrate data, drop old.
+- Before dropping a column: always `DANGEROUS` — HARD STOP. Confirm with developer. Check all repos for references first. Never drop without explicit sign-off.
 
 **Kafka topic modification rules:**
-- Before changing a message schema: list all consumer services from project-spec.json → confirm coordinated deployment plan (producer and all consumers must deploy together) → flag in rollback plan: "Rollback requires coordinated revert"
+- Before changing a message schema: MUST list all consumer services from project-spec.json → confirm coordinated deployment plan → flag in rollback plan: "Rollback requires coordinated revert"
 
 **The silent break rule:**
-If a change breaks something and the developer did not know — that is a planning failure. Better to over-flag a potential break and be wrong than to under-flag and cause a production incident. When in doubt: flag it, present it, ask.
-
-## Commenting Rules
-
-- Comments explain **WHY** — never WHAT.
+A change that breaks something the developer did not know about is a planning failure.
+Over-flagging a potential break is acceptable. Under-flagging and causing a production incident is not.
+When in doubt: flag it, present it, ask. Every time.
+
+### Retrospective (enforce after every task complete)
+
+- manage_task action=complete auto-starts retrospective
+- Respond to retro questions after every completion
+- "retro skip" is allowed but discouraged —
+  every skipped retrospective = missed learning
+- classifier_learning_queue signals with frequency >= 2
+  are automatically applied to classify_task
+- Never manually edit retrospective-insights.json —
+  always use record_retrospective tool
+- Retrospective updates from PR review are MANDATORY
+  if reviewer catches something the MCP missed
+
+## Commenting Rules — enforce in every file you touch
+
+- Comments explain **WHY** — never WHAT. The code already says what.
 - NEVER write obvious comments:
-  - `// Get the user` ← NO
-  - `// Loop through list` ← NO
-  - `// Return result` ← NO
-- Write comments only when the reason behind the code is non-obvious:
-  - Why a workaround exists
+  - `// Get the user` ← **FORBIDDEN**
+  - `// Loop through list` ← **FORBIDDEN**
+  - `// Return result` ← **FORBIDDEN**
+  - `// Initialize the service` ← **FORBIDDEN**
+- Write a comment ONLY when the reason behind the code is non-obvious:
+  - Why a workaround exists (and reference the ticket)
   - Why a specific algorithm was chosen over a simpler one
-  - Why a value is hardcoded in the rare case it must be
+  - Why a value is hardcoded in the rare case it absolutely must be
+- If you cannot explain the WHY in one sentence, the comment does not belong there.
+
+---
 
 ## Cross-Task Intelligence
-(TRIGGER: starting any new task)
+(TRIGGER: starting any new task — MANDATORY before initialize)
+
+### MANDATORY sequence
+
+```
+STEP 1: call search_tasks(keywords: <keywords from new task description>)
+        — ALWAYS. "I'm sure there's no prior work" is not a reason to skip.
+
+STEP 2: if ANY relevant past task found:
+        call get_task_history(work_item_id: <matching id>)
+        — understand how it was done before
 
-- Before `initialize`, call `search_tasks` with keywords from the new task description
-- If a relevant past task is found, call `get_task_history` to understand how it was done before
-- Call `get_pattern_from_task` if implementing something similar to a past feature
-- Never re-solve a solved problem — check task history first
+STEP 3: if implementing anything similar to a past feature:
+        call get_pattern_from_task(work_item_id: <matching id>)
+        — extract reusable architectural patterns, file paths, and test scenarios
+
+STEP 4: proceed to manage_task(action: "initialize") only after steps 1-3 complete
+```
 
+### Retrospective-Informed Planning
+
+Before Phase 0.7 plan presentation:
+1. Read retrospective-insights.json
+2. If avg_step_accuracy_pct < 80%:
+   → Add note in plan:
+     "⚠️ Historical note: past plans averaged
+      {pct}% step accuracy — this plan may need
+      adjustment during execution"
+3. If most_common_failed_check is not empty:
+   → Add to plan's pre-PR section:
+     "⚠️ Historically failing check: {check}
+      — pay extra attention"
+4. If classifier_learning_queue has
+   unapplied signals with frequency >= 2:
+   → Apply as temporary boost in classify_task
+   → Log applied signals in classification output
+
+### Hard enforcement
+
+❌ Do NOT call `manage_task(action: "initialize")` before `search_tasks` completes  
+❌ Do NOT skip `get_task_history` if a match exists — "I remember it" is not a substitute  
+❌ Do NOT re-solve a solved problem — task history exists precisely to prevent this  
+❌ Re-using a rejected pattern found in task history is a violation even if you disagree with the rejection  

package/package.json

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