@imenam/mcp-feature-analyzer 1.0.3 → 1.0.5

package/dist/src/core/refresh.d.ts

@@ -14,9 +14,13 @@ export interface RefreshStats {
     findingsOutdated: number;
     /** Constats `outdated` revenus à `open`. */
     findingsRestored: number;
+    /** Explications `current` passées à `outdated`. */
+    explanationsOutdated: number;
+    /** Explications `outdated` revenues à `current`. */
+    explanationsRestored: number;
 }
 export interface RefreshResult {
-    fields: Pick<Analysis, "baseCommit" | "headCommit" | "snapshotAt" | "files" | "findings">;
+    fields: Pick<Analysis, "baseCommit" | "headCommit" | "snapshotAt" | "files" | "findings" | "explanations">;
     stats: RefreshStats;
 }
 /**
@@ -25,6 +29,8 @@ export interface RefreshResult {
  * - un constat `open` dont les lignes ne correspondent plus à `anchorText`, ou dont le
  *   fichier a quitté le diff, passe à `outdated` ;
  * - un constat `outdated` dont les lignes correspondent de nouveau revient à `open` ;
- * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas.
+ * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas ;
+ * - une explication dont les lignes ne correspondent plus à `anchorText` passe à
+ *   `outdated`, et revient à `current` quand elles correspondent de nouveau.
  */
 export declare function applyRefresh(analysis: Analysis, oldSnapshot: DiffSnapshot, next: ComputedSnapshot): RefreshResult;

package/dist/src/core/refresh.js

@@ -1,5 +1,6 @@
 import { splitLines } from "../../shared/text.js";
 import { AnalysisError } from "./errors.js";
+import { explanationText } from "./locations.js";
 function hunksEqual(a, b) {
     if (a.length !== b.length)
         return false;
@@ -48,7 +49,9 @@ function currentText(finding, diffs) {
  * - un constat `open` dont les lignes ne correspondent plus à `anchorText`, ou dont le
  *   fichier a quitté le diff, passe à `outdated` ;
  * - un constat `outdated` dont les lignes correspondent de nouveau revient à `open` ;
- * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas.
+ * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas ;
+ * - une explication dont les lignes ne correspondent plus à `anchorText` passe à
+ *   `outdated`, et revient à `current` quand elles correspondent de nouveau.
  */
 export function applyRefresh(analysis, oldSnapshot, next) {
     if (next.repoPath !== analysis.repoPath || next.mode !== analysis.mode || next.base !== analysis.base || next.head !== analysis.head) {
@@ -65,6 +68,8 @@ export function applyRefresh(analysis, oldSnapshot, next) {
         reviewedReset: 0,
         findingsOutdated: 0,
         findingsRestored: 0,
+        explanationsOutdated: 0,
+        explanationsRestored: 0,
     };
     const files = next.files.map((entry) => {
         const previous = oldEntries.get(entry.path);
@@ -100,6 +105,18 @@ export function applyRefresh(analysis, oldSnapshot, next) {
         }
         return finding;
     });
+    const explanations = analysis.explanations.map((explanation) => {
+        const matches = explanationText(newDiffs.get(explanation.location.path), explanation.location) === explanation.anchorText;
+        if (explanation.status === "current" && !matches) {
+            stats.explanationsOutdated++;
+            return { ...explanation, status: "outdated" };
+        }
+        if (explanation.status === "outdated" && matches) {
+            stats.explanationsRestored++;
+            return { ...explanation, status: "current" };
+        }
+        return explanation;
+    });
     return {
         fields: {
             baseCommit: next.baseCommit,
@@ -107,6 +124,7 @@ export function applyRefresh(analysis, oldSnapshot, next) {
             snapshotAt: next.snapshotAt,
             files,
             findings,
+            explanations,
         },
         stats,
     };

package/dist/src/core/review-actions.d.ts

@@ -1,5 +1,5 @@
 import type { Analysis } from "../../shared/schemas/analysis.schema.js";
-import type { AddNoteBody, DeleteNoteBody, SetFileReviewedBody, SetFindingStatusBody, SubmitReviewBody } from "../../shared/schemas/api.schema.js";
+import type { AddNoteBody, DeleteNoteBody, SetFileReviewedBody, SetFindingStatusBody, SubmitReviewBody, UpdateNoteBody } from "../../shared/schemas/api.schema.js";
 import type { AnalysisStore } from "./analysis-store.js";
 /**
  * Modifications faites par le relecteur depuis la GUI. Chacune passe par
@@ -15,6 +15,11 @@ export declare function setFileReviewed(store: AnalysisStore, analysisId: string
 export declare function setFindingStatus(store: AnalysisStore, analysisId: string, findingId: string, body: SetFindingStatusBody): Analysis;
 /** Ajoute une remarque du relecteur sur une ligne du côté « nouveau » ou sur un fichier entier. */
 export declare function addNote(store: AnalysisStore, analysisId: string, body: AddNoteBody): Analysis;
+/**
+ * Remplace le texte d'une remarque. Quand elle fait partie d'une revue soumise,
+ * le prompt enregistré est recalculé avec le nouveau texte.
+ */
+export declare function updateNote(store: AnalysisStore, analysisId: string, noteId: string, body: UpdateNoteBody): Analysis;
 /**
  * Supprime une remarque. Quand elle fait partie d'une revue soumise, elle est
  * retirée de la sélection et le prompt enregistré est recalculé sans elle.

package/dist/src/core/review-actions.js

@@ -47,6 +47,26 @@ export function addNote(store, analysisId, body) {
         });
     }, { baseRevision: body.baseRevision });
 }
+/**
+ * Remplace le texte d'une remarque. Quand elle fait partie d'une revue soumise,
+ * le prompt enregistré est recalculé avec le nouveau texte.
+ */
+export function updateNote(store, analysisId, noteId, body) {
+    return store.mutate(analysisId, "user", (draft) => {
+        const note = draft.notes.find((entry) => entry.id === noteId);
+        if (!note)
+            throw new NotFoundError(`Note "${noteId}" not found in analysis "${analysisId}".`);
+        note.text = body.text;
+        const review = draft.review;
+        if (review.state === "submitted" && review.selectedNoteIds.includes(noteId)) {
+            review.prompt = buildAgentPrompt(draft, {
+                findingIds: review.selectedFindingIds,
+                noteIds: review.selectedNoteIds,
+                decision: review.decision,
+            });
+        }
+    }, { baseRevision: body.baseRevision });
+}
 /**
  * Supprime une remarque. Quand elle fait partie d'une revue soumise, elle est
  * retirée de la sélection et le prompt enregistré est recalculé sans elle.

package/dist/src/gui-worker.js

@@ -7,7 +7,7 @@ import path from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
 import { IPCMessageSchema, PUSHED_EVENT_TYPES } from "../shared/schemas/ipc.schema.js";
-import { AddNoteBodySchema, DeleteNoteBodySchema, SetFileReviewedBodySchema, SetFindingStatusBodySchema, SubmitReviewBodySchema, } from "../shared/schemas/api.schema.js";
+import { AddNoteBodySchema, DeleteNoteBodySchema, SetFileReviewedBodySchema, SetFindingStatusBodySchema, SubmitReviewBodySchema, UpdateNoteBodySchema, } from "../shared/schemas/api.schema.js";
 import { resolveLogDir } from "./core/log-dir.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function findProjectRoot(startDir) {
@@ -256,6 +256,12 @@ app.post("/api/analyses/:id/notes", async (c) => {
         return read.response;
     return forward(c, "ADD_NOTE", { analysisId: c.req.param("id"), body: read.body });
 });
+app.patch("/api/analyses/:id/notes/:noteId", async (c) => {
+    const read = await readBody(c, UpdateNoteBodySchema);
+    if ("response" in read)
+        return read.response;
+    return forward(c, "UPDATE_NOTE", { analysisId: c.req.param("id"), noteId: c.req.param("noteId"), body: read.body });
+});
 app.delete("/api/analyses/:id/notes/:noteId", async (c) => {
     const read = await readBody(c, DeleteNoteBodySchema);
     if ("response" in read)

package/dist/src/index.js

@@ -16,10 +16,10 @@ import { DEFAULT_HEAD_REF, localRepo } from "./core/git.js";
 import { agentRepo } from "./core/agent-repo.js";
 import { EXEC_ARG, handleAgentExec } from "./core/gateway-exec.js";
 import { resolveRole } from "./core/role.js";
-import { addNote, deleteNote, setFileReviewed, setFindingStatus, submitReview } from "./core/review-actions.js";
+import { addNote, deleteNote, setFileReviewed, setFindingStatus, submitReview, updateNote } from "./core/review-actions.js";
 import { GUI_REQUEST_TYPES, IPCMessageSchema } from "../shared/schemas/ipc.schema.js";
-import { AddNoteRequestSchema, AnalysisRequestSchema, DeleteNoteRequestSchema, SetFileReviewedRequestSchema, SetFindingStatusRequestSchema, SubmitReviewRequestSchema, } from "../shared/schemas/api.schema.js";
-import { ANALYSIS_MODES, DIAGRAM_KINDS, FINDING_KINDS, NODE_SHAPES, NODE_STATUSES, SEVERITIES, } from "../shared/schemas/analysis.schema.js";
+import { AddNoteRequestSchema, AnalysisRequestSchema, DeleteNoteRequestSchema, SetFileReviewedRequestSchema, SetFindingStatusRequestSchema, SubmitReviewRequestSchema, UpdateNoteRequestSchema, } from "../shared/schemas/api.schema.js";
+import { ANALYSIS_MODES, DIAGRAM_KINDS, EXPLANATION_SIDES, FINDING_KINDS, NODE_SHAPES, NODE_STATUSES, SEVERITIES, } from "../shared/schemas/analysis.schema.js";
 import { errorResult, textResult } from "./tools/types.js";
 import { createAnalysis } from "./tools/create-analysis.js";
 import { listAnalyses } from "./tools/list-analyses.js";
@@ -30,6 +30,9 @@ import { updateAnalysis } from "./tools/update-analysis.js";
 import { addFindings } from "./tools/add-findings.js";
 import { updateFinding } from "./tools/update-finding.js";
 import { deleteFindings } from "./tools/delete-findings.js";
+import { addExplanations } from "./tools/add-explanations.js";
+import { updateExplanation } from "./tools/update-explanation.js";
+import { deleteExplanations } from "./tools/delete-explanations.js";
 import { DEFAULT_NODE_SHAPE, DEFAULT_NODE_STATUS, setDiagram } from "./tools/set-diagram.js";
 import { deleteDiagram } from "./tools/delete-diagram.js";
 import { getReviewFeedback } from "./tools/get-review-feedback.js";
@@ -88,6 +91,7 @@ Concepts:
 - A **project** groups the analyses of one product or feature; the GUI files analyses by project.
 - The **overview** is your global analysis of the feature: its objective (what it lets users do), its approach (architecture choices, main flow) and the attention points the reviewer should check first. The **summary** lists the functional changes of the feature, one bullet per change, not one bullet per file.
 - A **finding** is a point for the reviewer: an issue anchored on changed lines, or a requirement_gap for requested behaviour that is missing (location optional). Severity: ${SEVERITIES.join(", ")}.
+- An **explanation** describes what a block of added or removed code does and how it works, so that the reviewer understands it before judging it. It is not a finding: it judges nothing and asks for nothing. It is anchored on new-side lines (added code) or old-side lines (removed code), and shown in the diff above the lines it describes.
 - A **diagram** is a flow, layers or mindmap picture of the feature. You give nodes and links only; the GUI lays them out.
 - The **review** belongs to the reviewer: files marked reviewed, findings ignored, notes, and a submitted decision with a prompt for you.
 
@@ -95,11 +99,19 @@ Workflow:
 1. list_analyses (with project) to find an analysis of the same feature: reuse it with update_analysis and refresh_analysis instead of creating a duplicate. Otherwise create_analysis with its project once the feature is developed.
 2. get_diff to read the frozen diff.
 3. update_analysis with the overview (objective, approach, attention_points) and the summary (the functional changes).
-4. add_findings for every problem, including requirement_gap findings for requested behaviour that is missing.
-5. set_diagram when a picture helps (impacted layers, process flow, concept tree).
-6. Tell the user to review the analysis in the GUI (the link is in the tool results).
-7. get_review_feedback to read the decision, the selected points and the prompt.
-8. Fix the code, then refresh_analysis to recompute the diff for a new review round.
+4. add_explanations for the long or complex blocks of added or removed code (see Explanation rules).
+5. add_findings for every problem, including requirement_gap findings for requested behaviour that is missing.
+6. set_diagram when a picture helps (impacted layers, process flow, concept tree).
+7. Tell the user to review the analysis in the GUI (the link is in the tool results).
+8. get_review_feedback to read the decision, the selected points and the prompt.
+9. Fix the code, then refresh_analysis to recompute the diff for a new review round; re-anchor or rewrite the outdated findings and explanations.
+
+Explanation rules:
+- Write one for every added or removed block that is long (a function or a block of about 30 lines or more) or complex (non-trivial algorithm, state machine, concurrency, recursion, tricky regular expression or data transformation). A 100-line function always gets one.
+- Cover the whole block, from its first to its last line. Title: the name of the block and its role, e.g. "parseUnifiedDiff: diff text to hunks".
+- Body: what the block does (inputs, outputs, effects), then how it works, step by step, in the order of the code; name the key variables and the edge cases it handles. For removed code, say what it did and what replaces it, if anything.
+- Describe, never judge: problems go in findings.
+- Skip trivial code (imports, getters, simple wiring): an explanation there only adds noise.
 
 Diagram rules:
 - One subject per diagram, 5 to 12 nodes; split a bigger picture into several diagrams.
@@ -108,7 +120,7 @@ Diagram rules:
 - flow for a process with steps and decisions; layers for the impact perimeter across architecture layers; mindmap for a tree of concepts (one root, one parent per node).
 
 Rules:
-- Line numbers are always NEW-side numbers, as shown by get_diff.
+- Line numbers are NEW-side numbers, as shown by get_diff, except for explanations of removed code, which use OLD-side numbers (side "old").
 - Nothing is ever written to the repository: suggestions are displayed to the reviewer only.
 - The reviewer alone decides which findings are ignored and when the review is submitted; you cannot change either.`;
 const server = new Server({ name: "mcp-feature-analyzer", version: APP_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
@@ -192,6 +204,12 @@ function handleGuiRequest(msg) {
             afterUserMutation(analysis.id);
             return { analysis };
         }
+        case "UPDATE_NOTE": {
+            const request = parseRequest(UpdateNoteRequestSchema, msg.data);
+            const analysis = updateNote(store, request.analysisId, request.noteId, request.body);
+            afterUserMutation(analysis.id);
+            return { analysis };
+        }
         case "DELETE_NOTE": {
             const request = parseRequest(DeleteNoteRequestSchema, msg.data);
             const analysis = deleteNote(store, request.analysisId, request.noteId, request.body);
@@ -305,6 +323,18 @@ const LOCATION_PROPERTIES = {
     start_line: { type: "integer", minimum: 1, description: `First targeted line. ${LINE_NUMBERS_DOC}` },
     end_line: { type: "integer", minimum: 1, description: "Last targeted line, inclusive (default: start_line)." },
 };
+const EXPLANATION_LOCATION_PROPERTIES = {
+    path: LOCATION_PROPERTIES.path,
+    side: {
+        type: "string",
+        enum: [...EXPLANATION_SIDES],
+        description: 'Side of the diff the lines belong to (default "new"): "new" for added or kept code, with NEW-side numbers (second column of get_diff); ' +
+            '"old" for removed code, with OLD-side numbers (first column of get_diff), all shown in the diff and at least one removed.',
+    },
+    start_line: { type: "integer", minimum: 1, description: "First described line, on the side given by side." },
+    end_line: { type: "integer", minimum: 1, description: "Last described line, inclusive (default: start_line)." },
+};
+const EXPLANATION_BODY_DOC = "What the code does (inputs, outputs, effects), then how it works, step by step in the order of the code. Describe, never judge. Plain text; line breaks are kept.";
 const SEVERITY_DOC = `Severity: ${SEVERITIES.join(", ")} (from most to least serious).`;
 const FINDING_KIND_DOC = `Kind (default "issue"): "issue" is a problem in the changed code and needs a location; ` +
     `"requirement_gap" is requested behaviour that is missing and may have no location.`;
@@ -503,6 +533,61 @@ const TOOLS = [
             required: ["analysis_id", "finding_ids"],
         },
     },
+    {
+        name: "add_explanations",
+        description: "Explain blocks of added or removed code to the reviewer, as a batch: what each block does and how it works. " +
+            "Write one for every long (about 30 lines or more) or complex block; skip trivial code. An explanation judges nothing: problems go in findings. " +
+            "Each location is checked against the frozen diff and its lines are copied; if any explanation is invalid, nothing is added and every problem is reported.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                analysis_id: { type: "string", description: ANALYSIS_ID_DOC },
+                explanations: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string", description: "Optional id (letters, digits, '_' or '-'); generated when omitted." },
+                            title: { type: "string", description: 'Name of the block and its role, e.g. "parseUnifiedDiff: diff text to hunks".' },
+                            body: { type: "string", description: EXPLANATION_BODY_DOC },
+                            ...EXPLANATION_LOCATION_PROPERTIES,
+                        },
+                        required: ["title", "body", "path", "start_line"],
+                    },
+                },
+            },
+            required: ["analysis_id", "explanations"],
+        },
+    },
+    {
+        name: "update_explanation",
+        description: "Change one explanation: title, body or location. A new location (path and start_line, with side for removed code) is checked against the diff " +
+            "and makes an outdated explanation current again; rewrite the body too when the code changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                analysis_id: { type: "string", description: ANALYSIS_ID_DOC },
+                explanation_id: { type: "string", description: "Id of the explanation, as shown by get_analysis." },
+                title: { type: "string", description: "New title." },
+                body: { type: "string", description: EXPLANATION_BODY_DOC },
+                ...EXPLANATION_LOCATION_PROPERTIES,
+            },
+            required: ["analysis_id", "explanation_id"],
+        },
+    },
+    {
+        name: "delete_explanations",
+        description: "Delete explanations by id, e.g. when the code they describe is gone. If any id is unknown, nothing is deleted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                analysis_id: { type: "string", description: ANALYSIS_ID_DOC },
+                explanation_ids: { type: "array", minItems: 1, items: { type: "string" }, description: "Ids of the explanations to delete." },
+            },
+            required: ["analysis_id", "explanation_ids"],
+        },
+    },
     {
         name: "set_diagram",
         description: "Create a diagram, or fully replace the one with diagram_id, when a picture helps the reviewer (impact perimeter, process flow, concept map). " +
@@ -647,6 +732,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return afterMutation(updateFinding(store, params));
             case "delete_findings":
                 return afterMutation(deleteFindings(store, params));
+            case "add_explanations":
+                return afterMutation(addExplanations(store, params));
+            case "update_explanation":
+                return afterMutation(updateExplanation(store, params));
+            case "delete_explanations":
+                return afterMutation(deleteExplanations(store, params));
             case "set_diagram":
                 return afterMutation(setDiagram(store, params));
             case "delete_diagram":

package/dist/src/tools/add-explanations.d.ts

@@ -0,0 +1,9 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+export declare const EXPLANATION_INPUT_FIELDS: readonly ["id", "title", "body", "path", "side", "start_line", "end_line"];
+/**
+ * Ajoute un lot d'explications. Tout le lot est validé (champs, identifiants,
+ * emplacements résolus sur le snapshot) avant l'écriture : une seule explication
+ * invalide et rien n'est ajouté.
+ */
+export declare function addExplanations(store: AnalysisStore, args: Args): MutationResult;

package/dist/src/tools/add-explanations.js

@@ -0,0 +1,73 @@
+import { AnalysisError } from "../core/errors.js";
+import { itemId } from "../core/ids.js";
+import { resolveExplanationLocation } from "../core/locations.js";
+import { explanationLine } from "./format.js";
+import { readExplanationLocation, readItemId } from "./inputs.js";
+import { rejectUnknownFields, requireArray, requireObject, requireString, requireText, textResult, } from "./types.js";
+export const EXPLANATION_INPUT_FIELDS = ["id", "title", "body", "path", "side", "start_line", "end_line"];
+/**
+ * Ajoute un lot d'explications. Tout le lot est validé (champs, identifiants,
+ * emplacements résolus sur le snapshot) avant l'écriture : une seule explication
+ * invalide et rien n'est ajouté.
+ */
+export function addExplanations(store, args) {
+    rejectUnknownFields(args, ["analysis_id", "explanations"]);
+    const id = requireString(args, "analysis_id");
+    const items = requireArray(args, "explanations", 1);
+    const analysis = store.get(id);
+    const snapshot = store.getSnapshot(id);
+    const taken = new Set(analysis.explanations.map((explanation) => explanation.id));
+    const batchIds = new Set();
+    const prepared = [];
+    const errors = [];
+    items.forEach((raw, index) => {
+        try {
+            const item = requireObject(raw, `explanations[${index}]`);
+            rejectUnknownFields(item, EXPLANATION_INPUT_FIELDS);
+            const explanationId = readItemId(item, "id");
+            if (explanationId !== undefined) {
+                if (taken.has(explanationId))
+                    throw new Error(`id "${explanationId}" is already used by another explanation of this analysis.`);
+                if (batchIds.has(explanationId))
+                    throw new Error(`id "${explanationId}" appears twice in this batch.`);
+                batchIds.add(explanationId);
+            }
+            const title = requireString(item, "title");
+            const body = requireText(item, "body");
+            const location = readExplanationLocation(item);
+            if (location === undefined) {
+                throw new Error(`an explanation describes lines of code: give "path" and "start_line" (and "side": "old" for removed code).`);
+            }
+            const { anchorText, ...resolved } = resolveExplanationLocation(snapshot, analysis.files, location);
+            prepared.push({ id: explanationId, title, body, location: resolved, anchorText });
+        }
+        catch (err) {
+            errors.push(`- explanations[${index}]: ${err.message}`);
+        }
+    });
+    if (errors.length > 0) {
+        throw new AnalysisError(`No explanation was added: ${errors.length} of ${items.length} explanation(s) are invalid. Fix them and send the whole batch again.\n` +
+            errors.join("\n"));
+    }
+    const added = [];
+    const updated = store.mutate(id, "agent", (draft) => {
+        if (draft.snapshotAt !== analysis.snapshotAt) {
+            throw new AnalysisError(`The diff of analysis "${id}" was recomputed while the explanations were validated. Send the batch again.`);
+        }
+        const ids = new Set([...draft.explanations.map((explanation) => explanation.id), ...batchIds]);
+        const now = new Date().toISOString();
+        for (const explanation of prepared) {
+            const newId = explanation.id ?? itemId("explanation", ids);
+            ids.add(newId);
+            const created = { ...explanation, id: newId, status: "current", createdAt: now };
+            added.push(created);
+            draft.explanations.push(created);
+        }
+    });
+    const lines = [
+        `Added ${added.length} explanation(s) to "${updated.title}" (${updated.id}):`,
+        ...added.map((explanation) => `  ${explanationLine(explanation)}`),
+        `The analysis has ${updated.explanations.length} explanation(s). The reviewer reads them in the diff, above the lines they describe.`,
+    ];
+    return { result: textResult(lines.join("\n")), analysisId: updated.id };
+}

package/dist/src/tools/create-analysis.js

@@ -31,6 +31,6 @@ export async function createAnalysis(store, args, repoFor = localRepo) {
     else {
         lines.push(`Changed files (${fileTotals(analysis.files)}):`, ...analysis.files.map((file) => `  ${fileLine(file)}`));
     }
-    lines.push("", "Next steps:", `1. Read the frozen diff with get_diff (analysis_id "${analysis.id}"); anchor findings on its new-side line numbers.`, "2. Write the overview (objective, approach, attention_points) and the summary (the functional changes of the feature) with update_analysis.", "3. Record problems with add_findings, including requirement_gap findings for requested behaviour that is missing.", "4. Add diagrams with set_diagram when a picture helps the reviewer: one subject each, 5 to 12 nodes, no crossing.", "5. Ask the user to review the analysis in the GUI, then read the outcome with get_review_feedback.");
+    lines.push("", "Next steps:", `1. Read the frozen diff with get_diff (analysis_id "${analysis.id}"); anchor findings on its new-side line numbers.`, "2. Write the overview (objective, approach, attention_points) and the summary (the functional changes of the feature) with update_analysis.", "3. Explain every long (about 30 lines or more) or complex block of added or removed code with add_explanations: what it does and how it works.", "4. Record problems with add_findings, including requirement_gap findings for requested behaviour that is missing.", "5. Add diagrams with set_diagram when a picture helps the reviewer: one subject each, 5 to 12 nodes, no crossing.", "6. Ask the user to review the analysis in the GUI, then read the outcome with get_review_feedback.");
     return { result: textResult(lines.join("\n")), analysisId: analysis.id };
 }

package/dist/src/tools/delete-explanations.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+/** Supprime des explications par identifiant. Un identifiant inconnu fait échouer l'appel sans rien supprimer. */
+export declare function deleteExplanations(store: AnalysisStore, args: Args): MutationResult;

package/dist/src/tools/delete-explanations.js

@@ -0,0 +1,23 @@
+import { AnalysisError } from "../core/errors.js";
+import { rejectUnknownFields, requireString, requireStringArray, textResult } from "./types.js";
+/** Supprime des explications par identifiant. Un identifiant inconnu fait échouer l'appel sans rien supprimer. */
+export function deleteExplanations(store, args) {
+    rejectUnknownFields(args, ["analysis_id", "explanation_ids"]);
+    const id = requireString(args, "analysis_id");
+    const ids = [...new Set(requireStringArray(args, "explanation_ids", 1))];
+    const updated = store.mutate(id, "agent", (draft) => {
+        const known = new Set(draft.explanations.map((explanation) => explanation.id));
+        const unknown = ids.filter((explanationId) => !known.has(explanationId));
+        if (unknown.length > 0) {
+            const existing = draft.explanations.map((explanation) => explanation.id).join(", ") || "none";
+            throw new AnalysisError(`No explanation was deleted: unknown explanation id(s) ${unknown.join(", ")} in analysis "${id}". Existing explanations: ${existing}.`);
+        }
+        const removed = new Set(ids);
+        draft.explanations = draft.explanations.filter((explanation) => !removed.has(explanation.id));
+    });
+    return {
+        result: textResult(`Deleted ${ids.length} explanation(s) from "${updated.title}" (${updated.id}): ${ids.join(", ")}. ` +
+            `${updated.explanations.length} explanation(s) remain.`),
+        analysisId: updated.id,
+    };
+}

package/dist/src/tools/format.d.ts

@@ -1,4 +1,4 @@
-import { type Analysis, type FileEntry, type Finding, type Note, type Overview, type ReviewProgress, type ReviewProgressState, type Severity } from "../../shared/schemas/analysis.schema.js";
+import { type Analysis, type Explanation, type FileEntry, type Finding, type Note, type Overview, type ReviewProgress, type ReviewProgressState, type Severity } from "../../shared/schemas/analysis.schema.js";
 /** Sha abrégé à 7 caractères. */
 export declare function shortSha(sha: string | null): string;
 /** Refs d'une analyse : `branch master...HEAD` ou `working_tree (changes against HEAD)`. */
@@ -15,6 +15,8 @@ export declare function locationLabel(finding: Pick<Finding, "location">): strin
 export declare function noteLocationLabel(note: Pick<Note, "location">): string;
 /** Ligne d'un constat : id, gravité, nature, statut, emplacement, titre. */
 export declare function findingLine(finding: Finding): string;
+/** Ligne d'une explication : id, statut, emplacement avec son côté, titre. */
+export declare function explanationLine(explanation: Explanation): string;
 /** `1 critical, 2 major` ; `none` quand tous les compteurs sont à zéro. */
 export declare function severityCountsLabel(counts: Record<Severity, number>): string;
 /** Préfixe chaque ligne non vide de `indent`. */

package/dist/src/tools/format.js

@@ -52,6 +52,11 @@ export function noteLocationLabel(note) {
 export function findingLine(finding) {
     return `${finding.id} [${finding.severity}] ${finding.kind}, ${finding.status} — ${locationLabel(finding)} — ${finding.title}`;
 }
+/** Ligne d'une explication : id, statut, emplacement avec son côté, titre. */
+export function explanationLine(explanation) {
+    const { path, side, startLine, endLine } = explanation.location;
+    return `${explanation.id} ${explanation.status} — ${path}:${lineRange(startLine, endLine)} (${side} side) — ${explanation.title}`;
+}
 /** `1 critical, 2 major` ; `none` quand tous les compteurs sont à zéro. */
 export function severityCountsLabel(counts) {
     const parts = SEVERITIES.filter((severity) => counts[severity] > 0).map((severity) => `${counts[severity]} ${severity}`);

package/dist/src/tools/get-analysis.js

@@ -2,7 +2,7 @@ import { summarize } from "../core/analysis-store.js";
 import { diagramQuality } from "../../shared/diagram-quality.js";
 import { reviewProgress } from "../../shared/review-state.js";
 import { sortBySeverity } from "../../shared/severity.js";
-import { fileLine, fileTotals, findingLine, noteLocationLabel, overviewLines, progressLabel, severityCountsLabel, snapshotLabel, } from "./format.js";
+import { fileLine, explanationLine, fileTotals, findingLine, noteLocationLabel, overviewLines, progressLabel, severityCountsLabel, snapshotLabel, } from "./format.js";
 import { rejectUnknownFields, requireString, textResult } from "./types.js";
 function noteLine(note) {
     return `${note.id} — ${noteLocationLabel(note)} — ${note.text.replace(/\n/g, " / ")}`;
@@ -74,6 +74,11 @@ export function getAnalysis(store, args) {
     if (analysis.findings.length === 0)
         lines.push("  none (record them with add_findings)");
     lines.push(...sortBySeverity(analysis.findings).map((finding) => `  ${findingLine(finding)}`), "");
+    const outdatedExplanations = analysis.explanations.filter((explanation) => explanation.status === "outdated").length;
+    lines.push(`Explanations (${analysis.explanations.length}: ${outdatedExplanations} outdated):`);
+    if (analysis.explanations.length === 0)
+        lines.push("  none (explain long or complex blocks with add_explanations)");
+    lines.push(...analysis.explanations.map((explanation) => `  ${explanationLine(explanation)}`), "");
     lines.push(`Reviewer notes (${analysis.notes.length}):`);
     if (analysis.notes.length === 0)
         lines.push("  none");

package/dist/src/tools/get-diff.js

@@ -52,7 +52,8 @@ export function getDiff(store, args) {
     const lines = [
         `Frozen diff of "${analysis.title}" (${analysis.id}): ${snapshotLabel(analysis)}.`,
         "Columns: old line | new line, then + (added), - (removed) or a space (context). " +
-            "Anchor findings on the NEW-side numbers (second column).",
+            "Anchor findings and explanations of added code on the NEW-side numbers (second column); " +
+            'explanations of removed code use the OLD-side numbers (first column) with "side": "old".',
     ];
     if (entries.length === 0)
         lines.push("", "The analysis has no changed files.");

package/dist/src/tools/inputs.d.ts

@@ -1,3 +1,4 @@
+import { type ExplanationSide } from "../../shared/schemas/analysis.schema.js";
 import { type Args } from "./types.js";
 /** Emplacement demandé par l'agent : `null` pour retirer l'emplacement, `undefined` s'il n'en donne pas. */
 export type LocationInput = {
@@ -10,5 +11,18 @@ export type LocationInput = {
  * `end_line` vaut `start_line` quand il est omis. `path: null` retire l'emplacement.
  */
 export declare function readLocation(args: Args, prefix?: string): LocationInput;
+/** Emplacement d'une explication demandé par l'agent ; `undefined` s'il n'en donne pas. */
+export type ExplanationLocationInput = {
+    path: string;
+    side: ExplanationSide;
+    startLine: number;
+    endLine: number | undefined;
+} | undefined;
+/**
+ * Lit `path`, `side`, `start_line` et `end_line` d'une explication. `path` et
+ * `start_line` vont ensemble ; `side` vaut `new` quand il est omis ; `end_line`
+ * vaut `start_line` quand il est omis. Une explication a toujours un emplacement.
+ */
+export declare function readExplanationLocation(args: Args, prefix?: string): ExplanationLocationInput;
 /** Lit un identifiant d'élément facultatif fourni par l'agent. */
 export declare function readItemId(args: Args, field: string, prefix?: string): string | undefined;

package/dist/src/tools/inputs.js

@@ -1,5 +1,5 @@
-import { ITEM_ID_PATTERN } from "../../shared/schemas/analysis.schema.js";
-import { has, nullableString, optionalPositiveInt } from "./types.js";
+import { EXPLANATION_SIDES, ITEM_ID_PATTERN } from "../../shared/schemas/analysis.schema.js";
+import { has, nullableString, optionalEnum, optionalPositiveInt } from "./types.js";
 /**
  * Lit `path`, `start_line` et `end_line`. `path` et `start_line` vont ensemble ;
  * `end_line` vaut `start_line` quand il est omis. `path: null` retire l'emplacement.
@@ -28,6 +28,24 @@ export function readLocation(args, prefix = "") {
     }
     return { path, startLine, endLine };
 }
+/**
+ * Lit `path`, `side`, `start_line` et `end_line` d'une explication. `path` et
+ * `start_line` vont ensemble ; `side` vaut `new` quand il est omis ; `end_line`
+ * vaut `start_line` quand il est omis. Une explication a toujours un emplacement.
+ */
+export function readExplanationLocation(args, prefix = "") {
+    const side = optionalEnum(args, "side", EXPLANATION_SIDES, prefix);
+    const location = readLocation(args, prefix);
+    if (location === null) {
+        throw new Error(`"${prefix}path" cannot be null: an explanation always describes lines of a changed file.`);
+    }
+    if (location === undefined) {
+        if (side !== undefined)
+            throw new Error(`"${prefix}side" needs "${prefix}path" and "${prefix}start_line": give the lines it refers to.`);
+        return undefined;
+    }
+    return { ...location, side: side ?? "new" };
+}
 /** Lit un identifiant d'élément facultatif fourni par l'agent. */
 export function readItemId(args, field, prefix = "") {
     if (!has(args, field))

package/dist/src/tools/refresh-analysis.js

@@ -1,5 +1,5 @@
 import { computeSnapshot, localRepo } from "../core/git.js";
-import { snapshotLabel } from "./format.js";
+import { explanationLine, snapshotLabel } from "./format.js";
 import { rejectUnknownFields, requireString, textResult } from "./types.js";
 /**
  * Recalcule le snapshot avec le dépôt, le mode et les refs de l'analyse, lus par
@@ -19,6 +19,8 @@ export async function refreshAnalysis(store, args, repoFor = localRepo) {
         `Reviewed files: ${stats.reviewedKept} kept (diff unchanged), ${stats.reviewedReset} reset to unreviewed (diff changed).`,
         `Findings: ${stats.findingsOutdated} became outdated (their lines changed or left the diff), ` +
             `${stats.findingsRestored} back to open (their lines match again); ${outdated.length} outdated in total.`,
+        `Explanations: ${stats.explanationsOutdated} became outdated (the code they describe changed or left the diff), ` +
+            `${stats.explanationsRestored} current again.`,
     ];
     if (previousReview.state === "submitted") {
         lines.push(`Review: the previous feedback (decision ${previousReview.decision}, submitted at ${previousReview.submittedAt}) was discarded; the review is pending again.`);
@@ -26,9 +28,13 @@ export async function refreshAnalysis(store, args, repoFor = localRepo) {
     else {
         lines.push("Review: pending; the previous feedback, decision and selection in progress were discarded.");
     }
-    lines.push("", "Next steps:", "- Re-read the changed files with get_diff.", "- For each outdated finding: re-anchor it with update_finding (a new location reopens it), or remove it with delete_findings if it is solved.", "- Ask the user to review the analysis again in the GUI.");
+    lines.push("", "Next steps:", "- Re-read the changed files with get_diff.", "- For each outdated finding: re-anchor it with update_finding (a new location reopens it), or remove it with delete_findings if it is solved.", "- For each outdated explanation: re-anchor it and rewrite its body with update_explanation, or remove it with delete_explanations.", "- Explain the new long or complex blocks with add_explanations.", "- Ask the user to review the analysis again in the GUI.");
     if (outdated.length > 0) {
         lines.push("", "Outdated findings:", ...outdated.map((finding) => `  ${finding.id} [${finding.severity}] ${finding.title}`));
     }
+    const outdatedExplanations = analysis.explanations.filter((explanation) => explanation.status === "outdated");
+    if (outdatedExplanations.length > 0) {
+        lines.push("", "Outdated explanations:", ...outdatedExplanations.map((explanation) => `  ${explanationLine(explanation)}`));
+    }
     return { result: textResult(lines.join("\n")), analysisId: analysis.id };
 }

package/dist/src/tools/update-explanation.d.ts

@@ -0,0 +1,7 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+/**
+ * Modifie une explication. Un nouvel emplacement est résolu sur le snapshot et
+ * remet une explication `outdated` à `current`.
+ */
+export declare function updateExplanation(store: AnalysisStore, args: Args): MutationResult;