@prowi/deskcheck 0.2.0 → 0.4.0

package/build/services/review/ReviewPlanBuilderService.js

@@ -1,17 +1,24 @@
 import { findMatchingModules } from "../criteria/glob-matcher.js";
+import { PartitionerError } from "./ReviewPartitionerService.js";
 /**
- * Build a complete review plan: create the plan, match files to modules,
- * generate tasks, and finalize.
+ * Build a complete review plan: create the plan, glob-match files to
+ * criteria, run one partitioner agent per matched criterion to produce
+ * subtasks, write everything to storage, and finalize.
  *
- * This is the single authoritative implementation of plan+task creation,
- * shared by both the planner agent's in-process MCP tool and any other
- * entry point that needs to create a plan from a file list.
+ * Partitioners run concurrently with `Promise.all`. ALL partitioners must
+ * complete before any tasks are added — this is a deliberate barrier so
+ * that downstream reviewers see a fully-partitioned plan and so that the
+ * partitioning step can be inspected as a unit (e.g. via `--dry-run`).
+ *
+ * If any partitioner throws, the error propagates and the plan is left in
+ * its pre-finalized state. Per design, partitioner failures fail the run.
  */
-export function buildPlanWithTasks(storage, name, source, files, modules) {
-    // Create the plan shell
-    const plan = storage.createPlan(name, source);
-    // Match files against criteria
+export async function buildPlanWithTasks(storage, partitioner, name, scope, invocation, files, modules, events) {
+    // Create the plan shell — already at step "matching" by default.
+    const plan = storage.createPlan(name, scope, invocation);
+    // Match files against criteria (programmatic, no LLM)
     const matches = findMatchingModules(files, modules);
+    events?.onMatchingComplete?.(matches.length, new Set(matches.flatMap((m) => m.matchedFiles)).size);
     // Track coverage
     const matchedFileSet = new Set();
     for (const match of matches) {
@@ -28,39 +35,90 @@ export function buildPlanWithTasks(storage, name, source, files, modules) {
         moduleSummaries[match.module.id] = {
             review_id: match.module.id,
             description: match.module.description,
-            severity: match.module.severity,
             model: match.module.model,
+            partition: match.module.partition,
             task_count: 0,
             matched_files: match.matchedFiles,
         };
     }
     storage.setModules(plan.plan_id, moduleSummaries);
-    // Create tasks based on module mode
-    for (const match of matches) {
-        const isGrouped = match.module.mode.toLowerCase().includes("grouped") ||
-            match.module.mode.toLowerCase().includes("all files");
-        if (isGrouped) {
+    // ---------------------------------------------------------------------------
+    // Partition step — one fresh agent per matched criterion, all in parallel.
+    // Must complete entirely before any tasks are added. If anything throws,
+    // we stamp the failure on the plan so the UI can render it before
+    // re-raising for the CLI to surface.
+    // ---------------------------------------------------------------------------
+    storage.setStep(plan.plan_id, "partitioning");
+    let decisions;
+    try {
+        decisions = await Promise.all(matches.map(async (match) => {
+            events?.onPartitionStarted?.(match.module.id, match.matchedFiles.length);
+            const result = await partitioner.partition(match.module, match.matchedFiles, scope);
+            // Persist the partitioner's full SDK transcript as a side-file.
+            try {
+                storage.writePartitionerLog(plan.plan_id, match.module.id, result.messages);
+            }
+            catch (logErr) {
+                console.error(`[deskcheck] Warning: failed to write partitioner log for ${match.module.id}: ${logErr instanceof Error ? logErr.message : String(logErr)}`);
+            }
+            const decision = {
+                review_id: match.module.id,
+                matched_files: match.matchedFiles,
+                reasoning: result.reasoning,
+                subtasks: result.subtasks,
+                completed_at: new Date().toISOString(),
+                model: result.model,
+                usage: result.usage,
+            };
+            storage.setPartitionDecision(plan.plan_id, decision);
+            events?.onPartitionCompleted?.(decision);
+            return decision;
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const reviewId = err instanceof PartitionerError ? err.reviewId : null;
+        storage.setFailure(plan.plan_id, {
+            step: "partitioning",
+            review_id: reviewId,
+            message,
+        });
+        throw err;
+    }
+    // ---------------------------------------------------------------------------
+    // Materialize partitioner output as ReviewTasks. We do this after all
+    // partitioners finish so storage writes are batched and the plan is never
+    // half-partitioned on disk.
+    // ---------------------------------------------------------------------------
+    for (let i = 0; i < matches.length; i++) {
+        const match = matches[i];
+        const decision = decisions[i];
+        for (const subtask of decision.subtasks) {
             storage.addTask(plan.plan_id, {
                 review_id: match.module.id,
                 review_file: match.module.file,
-                files: match.matchedFiles,
-                hint: null,
+                files: subtask.files,
+                focus: subtask.focus,
+                hint: subtask.hint,
                 model: match.module.model,
+                tools: match.module.tools,
+                prompt: match.module.prompt,
             });
         }
-        else {
-            for (const file of match.matchedFiles) {
-                storage.addTask(plan.plan_id, {
-                    review_id: match.module.id,
-                    review_file: match.module.file,
-                    files: [file],
-                    hint: null,
-                    model: match.module.model,
-                });
-            }
-        }
     }
-    // Finalize the plan (sets status to "ready", recounts tasks per module)
-    return storage.finalizePlan(plan.plan_id);
+    // Finalize the plan (sets status to "ready", recounts tasks per module).
+    // After finalize, the orchestrator takes over — it flips step to "complete"
+    // when all tasks reach a terminal state. We set "reviewing" here as the
+    // intermediate so the UI sees the transition immediately on plan load.
+    const finalized = storage.finalizePlan(plan.plan_id);
+    if (Object.keys(finalized.tasks).length > 0) {
+        storage.setStep(plan.plan_id, "reviewing");
+    }
+    else {
+        // No tasks (no criteria matched, or all partitioners produced empty
+        // sets — though the validator forbids the latter). Mark complete.
+        storage.setStep(plan.plan_id, "complete");
+    }
+    return storage.getPlan(plan.plan_id);
 }
 //# sourceMappingURL=ReviewPlanBuilderService.js.map

package/build/services/review/ReviewPlanBuilderService.js.map

@@ -1 +1 @@
-{"version":3,"file":"ReviewPlanBuilderService.js","sourceRoot":"","sources":["../../../src/services/review/ReviewPlanBuilderService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ReviewPlanBuilderService.js","sourceRoot":"","sources":["../../../src/services/review/ReviewPlanBuilderService.ts"],"names":[],"mappings":"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"}

package/build/services/review/ReviewStorageService.d.ts

@@ -1,4 +1,4 @@
-import type { ContextType, Finding, ModuleSummary, ReviewPlan, ReviewResults, ReviewSource, ReviewTask, TaskUsage } from "../../types/review.js";
+import type { Issue, ModuleSummary, PartitionDecision, PipelineStep, PlanFailure, PlanInvocation, ReviewPlan, ReviewResults, ReviewTask, Scope, TaskUsage } from "../../types/review.js";
 /**
  * Manages the two-file storage format (plan.json + results.json) for deskcheck runs.
  *
@@ -29,7 +29,7 @@ export declare class ReviewStorageService {
      * Creates the timestamped directory and writes an initial plan.json with
      * status "planning" and empty collections.
      */
-    createPlan(name: string, source: ReviewSource): ReviewPlan;
+    createPlan(name: string, scope: Scope, invocation: PlanInvocation): ReviewPlan;
     /** Read the plan.json for a given plan ID. */
     getPlan(planId: string): ReviewPlan;
     /**
@@ -56,18 +56,42 @@ export declare class ReviewStorageService {
      * appending a zero-padded incrementing suffix (e.g., "-001", "-002").
      * The task is created with status "pending" and null context fields.
      */
-    addTask(planId: string, task: Omit<ReviewTask, "task_id" | "status" | "created_at" | "started_at" | "completed_at" | "context" | "context_type" | "symbol" | "prompt">): ReviewTask;
+    addTask(planId: string, task: Omit<ReviewTask, "task_id" | "status" | "created_at" | "started_at" | "completed_at" | "scope" | "focus" | "tools" | "error" | "prompt"> & {
+        focus?: string | null;
+        tools?: string[];
+        prompt?: string | null;
+    }): ReviewTask;
+    /** Record a partitioner decision for one criterion. */
+    setPartitionDecision(planId: string, decision: PartitionDecision): void;
+    /**
+     * Update the pipeline step the plan is currently in. When transitioning
+     * to a terminal step (`complete`/`failed`), also promotes `status` to the
+     * matching terminal value and stamps `completed_at` if not already set —
+     * this keeps the invariant `step terminal ⟺ status terminal`.
+     */
+    setStep(planId: string, step: PipelineStep): void;
+    /**
+     * Mark the plan as failed at a specific step. Sets `status = "failed"`,
+     * `step = "failed"`, and stamps the failure details. Idempotent — if the
+     * plan is already failed, the new failure overwrites the old.
+     */
+    setFailure(planId: string, failure: PlanFailure): void;
+    /** Persist the full SDK message stream from one reviewer's run. */
+    writeTaskLog(planId: string, taskId: string, messages: unknown[]): void;
+    /** Read a previously persisted reviewer transcript. */
+    getTaskLog(planId: string, taskId: string): unknown[];
+    /** Persist the full SDK message stream from one partitioner's run. */
+    writePartitionerLog(planId: string, reviewId: string, messages: unknown[]): void;
+    /** Read a previously persisted partitioner transcript. */
+    getPartitionerLog(planId: string, reviewId: string): unknown[];
     /**
      * Claim a pending task for execution.
      *
-     * Sets the task status to "in_progress", fills in the context fields
-     * (context type, content, symbol, prompt), and records the start time.
+     * Sets the task status to "in_progress", records the start time, and
+     * optionally stores the criterion prompt for later inspection.
      */
-    claimTask(planId: string, taskId: string, context: {
-        contextType: ContextType;
-        content: string;
-        symbol?: string;
-        prompt: string;
+    claimTask(planId: string, taskId: string, options?: {
+        prompt?: string;
     }): ReviewTask;
     /**
      * Return tasks eligible for execution: those with status "pending" or
@@ -81,7 +105,7 @@ export declare class ReviewStorageService {
      * results.json, and recomputes all aggregations (by_file, by_module,
      * summary, completion).
      */
-    completeTask(planId: string, taskId: string, findings: Finding[], usage?: TaskUsage | null): void;
+    completeTask(planId: string, taskId: string, issues: Issue[], usage?: TaskUsage | null): void;
     /**
      * Mark a task as errored.
      *

package/build/services/review/ReviewStorageService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReviewStorageService.d.ts","sourceRoot":"","sources":["../../../src/services/review/ReviewStorageService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EAGP,aAAa,EACb,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EAEV,SAAS,EAEV,MAAM,uBAAuB,CAAC;AAsC/B;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,+EAA+E;IAC/E,OAAO,CAAC,MAAM,CAAC,WAAW,CAAqB;gBAanC,UAAU,EAAE,MAAM;IAI9B;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ;IAoDhB,yCAAyC;IACzC,OAAO,CAAC,OAAO;IAQf;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,UAAU;IA0B1D,8CAA8C;IAC9C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IAMnC;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI;IAsBhC,0CAA0C;IAC1C,SAAS,IAAI,KAAK,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAqCF;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IAsBxC;;;;;;OAMG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,CACR,UAAU,EACR,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,YAAY,GACZ,cAAc,GACd,SAAS,GACT,cAAc,GACd,QAAQ,GACR,QAAQ,CACX,GACA,UAAU;IAkCb;;;;;OAKG;IACH,SAAS,CACP,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QACP,WAAW,EAAE,WAAW,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,GACA,UAAU;IA6Bb;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE;IAkB7C;;;;;;OAMG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,GACvB,IAAI;IAiDP;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IA8C/F,iDAAiD;IACjD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAgBzC,4DAA4D;IAC5D,eAAe,CACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EAAE,GAClB,IAAI;IASP,gDAAgD;IAChD,UAAU,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GACrC,IAAI;IAYP,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;CAkH9B"}
+{"version":3,"file":"ReviewStorageService.d.ts","sourceRoot":"","sources":["../../../src/services/review/ReviewStorageService.ts"],"names":[],"mappings":"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"}

package/build/services/review/ReviewStorageService.js

@@ -130,7 +130,7 @@ export class ReviewStorageService {
      * Creates the timestamped directory and writes an initial plan.json with
      * status "planning" and empty collections.
      */
-    createPlan(name, source) {
+    createPlan(name, scope, invocation) {
         const now = new Date();
         const planId = formatTimestamp(now);
         const planDir = path.join(this.storageDir, planId);
@@ -138,8 +138,11 @@ export class ReviewStorageService {
         const plan = {
             plan_id: planId,
             name,
-            source,
+            invocation,
+            scope,
             status: "planning",
+            step: "matching",
+            failure: null,
             created_at: now.toISOString(),
             finalized_at: null,
             started_at: null,
@@ -148,6 +151,7 @@ export class ReviewStorageService {
             unmatched_files: [],
             tasks: {},
             modules: {},
+            partition_decisions: {},
         };
         this.writePlan(planId, plan);
         return plan;
@@ -240,29 +244,110 @@ export class ReviewStorageService {
                 review_id: task.review_id,
                 review_file: task.review_file,
                 files: task.files,
+                scope: plan.scope,
+                focus: task.focus ?? null,
                 hint: task.hint,
                 model: task.model,
+                tools: task.tools ?? [],
                 status: "pending",
                 created_at: new Date().toISOString(),
                 started_at: null,
                 completed_at: null,
-                context_type: plan.source.type,
-                context: null,
-                symbol: null,
-                prompt: null,
+                error: null,
+                prompt: task.prompt ?? null,
             };
             plan.tasks[taskId] = newTask;
             this.writePlan(planId, plan);
             return newTask;
         });
     }
+    /** Record a partitioner decision for one criterion. */
+    setPartitionDecision(planId, decision) {
+        this.withLock(planId, () => {
+            const plan = this.getPlan(planId);
+            plan.partition_decisions[decision.review_id] = decision;
+            this.writePlan(planId, plan);
+        });
+    }
+    /**
+     * Update the pipeline step the plan is currently in. When transitioning
+     * to a terminal step (`complete`/`failed`), also promotes `status` to the
+     * matching terminal value and stamps `completed_at` if not already set —
+     * this keeps the invariant `step terminal ⟺ status terminal`.
+     */
+    setStep(planId, step) {
+        this.withLock(planId, () => {
+            const plan = this.getPlan(planId);
+            plan.step = step;
+            if (step === "complete" && plan.status !== "complete") {
+                plan.status = "complete";
+                plan.completed_at = plan.completed_at ?? new Date().toISOString();
+            }
+            else if (step === "failed" && plan.status !== "failed") {
+                plan.status = "failed";
+                plan.completed_at = plan.completed_at ?? new Date().toISOString();
+            }
+            this.writePlan(planId, plan);
+        });
+    }
+    /**
+     * Mark the plan as failed at a specific step. Sets `status = "failed"`,
+     * `step = "failed"`, and stamps the failure details. Idempotent — if the
+     * plan is already failed, the new failure overwrites the old.
+     */
+    setFailure(planId, failure) {
+        this.withLock(planId, () => {
+            const plan = this.getPlan(planId);
+            plan.status = "failed";
+            plan.step = "failed";
+            plan.failure = failure;
+            plan.completed_at = plan.completed_at ?? new Date().toISOString();
+            this.writePlan(planId, plan);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Agent transcripts
+    //
+    // Each agent run (executor for a task, partitioner for a criterion) writes
+    // its full SDK message stream to a side-file in the plan directory. Kept
+    // out of plan.json/results.json so those stay small enough to load
+    // routinely. The CLI/server only loads transcripts on demand.
+    // ---------------------------------------------------------------------------
+    /** Persist the full SDK message stream from one reviewer's run. */
+    writeTaskLog(planId, taskId, messages) {
+        const target = path.join(this.planDir(planId), `task_${taskId}.log.json`);
+        const tmp = target + ".tmp";
+        fs.writeFileSync(tmp, JSON.stringify(messages, null, 2) + "\n");
+        fs.renameSync(tmp, target);
+    }
+    /** Read a previously persisted reviewer transcript. */
+    getTaskLog(planId, taskId) {
+        const target = path.join(this.planDir(planId), `task_${taskId}.log.json`);
+        if (!fs.existsSync(target))
+            return [];
+        return JSON.parse(fs.readFileSync(target, "utf-8"));
+    }
+    /** Persist the full SDK message stream from one partitioner's run. */
+    writePartitionerLog(planId, reviewId, messages) {
+        const target = path.join(this.planDir(planId), `partitioner_${flattenReviewId(reviewId)}.log.json`);
+        const tmp = target + ".tmp";
+        fs.writeFileSync(tmp, JSON.stringify(messages, null, 2) + "\n");
+        fs.renameSync(tmp, target);
+    }
+    /** Read a previously persisted partitioner transcript. */
+    getPartitionerLog(planId, reviewId) {
+        const target = path.join(this.planDir(planId), `partitioner_${flattenReviewId(reviewId)}.log.json`);
+        if (!fs.existsSync(target))
+            return [];
+        return JSON.parse(fs.readFileSync(target, "utf-8"));
+    }
     /**
      * Claim a pending task for execution.
      *
-     * Sets the task status to "in_progress", fills in the context fields
-     * (context type, content, symbol, prompt), and records the start time.
+     * Sets the task status to "in_progress", records the start time, and
+     * optionally stores the criterion prompt for later inspection.
      */
-    claimTask(planId, taskId, context) {
+    claimTask(planId, taskId, options) {
         return this.withLock(planId, () => {
             const plan = this.getPlan(planId);
             const task = plan.tasks[taskId];
@@ -271,10 +356,9 @@ export class ReviewStorageService {
             }
             task.status = "in_progress";
             task.started_at = new Date().toISOString();
-            task.context_type = context.contextType;
-            task.context = context.content;
-            task.symbol = context.symbol ?? null;
-            task.prompt = context.prompt;
+            if (options?.prompt !== undefined) {
+                task.prompt = options.prompt;
+            }
             // Set plan to executing if it was ready
             if (plan.status === "ready") {
                 plan.started_at = task.started_at;
@@ -311,7 +395,7 @@ export class ReviewStorageService {
      * results.json, and recomputes all aggregations (by_file, by_module,
      * summary, completion).
      */
-    completeTask(planId, taskId, findings, usage) {
+    completeTask(planId, taskId, issues, usage) {
         this.withLock(planId, () => {
             const now = new Date().toISOString();
             // Update plan.json task status
@@ -326,6 +410,7 @@ export class ReviewStorageService {
             const allDone = Object.values(plan.tasks).every((t) => t.status === "complete" || t.status === "error");
             if (allDone) {
                 plan.status = "complete";
+                plan.step = "complete";
                 plan.completed_at = now;
             }
             this.writePlan(planId, plan);
@@ -335,7 +420,7 @@ export class ReviewStorageService {
                 review_id: task.review_id,
                 files: task.files,
                 completed_at: now,
-                findings,
+                issues,
                 usage: usage ?? null,
             };
             const results = this.loadOrCreateResults(planId);
@@ -362,10 +447,12 @@ export class ReviewStorageService {
             }
             task.status = "error";
             task.completed_at = now;
+            task.error = errorMessage;
             // Check if all tasks have reached a terminal status
             const allDone = Object.values(plan.tasks).every((t) => t.status === "complete" || t.status === "error");
             if (allDone) {
                 plan.status = "complete";
+                plan.step = "complete";
                 plan.completed_at = now;
             }
             this.writePlan(planId, plan);
@@ -377,7 +464,7 @@ export class ReviewStorageService {
                     review_id: task.review_id,
                     files: task.files,
                     completed_at: now,
-                    findings: [],
+                    issues: [],
                     usage: usage ?? null,
                 };
                 results.task_results[taskId] = taskResult;
@@ -502,32 +589,47 @@ export class ReviewStorageService {
             in_progress: tasks.filter((t) => t.status === "in_progress").length,
             errored: tasks.filter((t) => t.status === "error").length,
         };
-        // ---- Summary (aggregate finding counts) ----
+        // ---- Stamp issue_id on all issues ----
+        for (const taskResult of Object.values(results.task_results)) {
+            for (let i = 0; i < taskResult.issues.length; i++) {
+                taskResult.issues[i].issue_id = `${taskResult.task_id}:${i}`;
+            }
+        }
+        // ---- Summary (aggregate issue counts) ----
         const summary = { total: 0, critical: 0, warning: 0, info: 0 };
         for (const taskResult of Object.values(results.task_results)) {
-            for (const finding of taskResult.findings) {
+            for (const issue of taskResult.issues) {
                 summary.total++;
-                summary[finding.severity]++;
+                summary[issue.severity]++;
             }
         }
         results.summary = summary;
-        // ---- by_file (group all findings by file path) ----
+        // ---- by_file (group issues by reference file paths) ----
+        // An issue can appear under multiple files if it has multiple references.
         const byFile = {};
         for (const taskResult of Object.values(results.task_results)) {
-            for (const finding of taskResult.findings) {
-                const fileFinding = {
-                    ...finding,
+            for (const issue of taskResult.issues) {
+                const fileIssue = {
+                    ...issue,
+                    issue_id: issue.issue_id,
                     review_id: taskResult.review_id,
                     task_id: taskResult.task_id,
                 };
-                if (!byFile[finding.file]) {
-                    byFile[finding.file] = [];
+                // Index under each referenced file path
+                const seenFiles = new Set();
+                for (const ref of issue.references) {
+                    if (ref.file && !seenFiles.has(ref.file)) {
+                        seenFiles.add(ref.file);
+                        if (!byFile[ref.file]) {
+                            byFile[ref.file] = [];
+                        }
+                        byFile[ref.file].push(fileIssue);
+                    }
                 }
-                byFile[finding.file].push(fileFinding);
             }
         }
         results.by_file = byFile;
-        // ---- by_module (group findings by criterion) ----
+        // ---- by_module (group issues by criterion) ----
         const byModule = {};
         for (const taskResult of Object.values(results.task_results)) {
             const reviewId = taskResult.review_id;
@@ -537,19 +639,18 @@ export class ReviewStorageService {
                 byModule[reviewId] = {
                     review_id: reviewId,
                     description: moduleSummary?.description ?? "",
-                    severity: moduleSummary?.severity ?? "medium",
                     task_count: moduleSummary?.task_count ?? 0,
                     completed: 0,
                     counts: { critical: 0, warning: 0, info: 0, total: 0 },
-                    findings: [],
+                    issues: [],
                 };
             }
-            const moduleFindings = byModule[reviewId];
-            moduleFindings.completed++;
-            for (const finding of taskResult.findings) {
-                moduleFindings.counts.total++;
-                moduleFindings.counts[finding.severity]++;
-                moduleFindings.findings.push(finding);
+            const moduleIssues = byModule[reviewId];
+            moduleIssues.completed++;
+            for (const issue of taskResult.issues) {
+                moduleIssues.counts.total++;
+                moduleIssues.counts[issue.severity]++;
+                moduleIssues.issues.push(issue);
             }
         }
         results.by_module = byModule;