@planu/cli 5.3.3 → 5.3.5

package/dist/tools/reconcile-spec.js

@@ -1,3 +1,5 @@
+import { SECTIONS_WITHOUT_LITERAL_BODY_TEXT, } from '../types/index.js';
+import { createHash } from 'node:crypto';
 import { elicitOrFallback, buildEnumSchema } from '../engine/elicitation/elicit-helper.js';
 import { ti, t } from '../i18n/index.js';
 import { formatSuccess, addNextSteps } from './response-helpers.js';
@@ -10,101 +12,153 @@ import { extractSectionBody } from '../engine/spec-format/read-technical-section
 import { stripFrontmatter } from '../engine/frontmatter-parser.js';
 import { analyzeLivingSpec } from '../engine/living-spec-analyzer.js';
 import { notifyStoreChange } from '../engine/doc-generator/portal/regen-hook.js';
-// SPEC-1011 Bug D: Post-write verification + apply text changes
 import { applyChangesToSpec } from '../engine/reconcile/apply-changes.js';
 import { verifyWriteSucceeded } from '../engine/reconcile/verify-write.js';
-/**
- * Auto-detect changes by comparing spec metadata with current state.
- */
-async function autoDetectChanges(spec, _knowledge) {
-    const changes = [];
-    // Check if estimation was significantly off (only if actuals exist)
-    if (spec.actuals) {
-        const estimatedTotal = spec.estimation.devHours + spec.estimation.reviewHours;
-        const actualTotal = spec.actuals.devHours + spec.actuals.reviewHours;
-        const ratio = actualTotal / estimatedTotal;
-        if (ratio > 1.3 || ratio < 0.7) {
-            changes.push({
-                section: 'estimation',
-                originalValue: `${estimatedTotal}h estimated`,
-                newValue: `${actualTotal}h actual (${Math.round(ratio * 100)}% of estimate)`,
-                reason: ratio > 1.3
-                    ? 'Implementation took significantly longer than estimated'
-                    : 'Implementation was completed faster than estimated',
-                approved: true,
-            });
-        }
-        // Cost discrepancy
-        if (Math.abs(spec.estimation.totalCostUsd - spec.actuals.totalCostUsd) > 10) {
-            changes.push({
-                section: 'cost',
-                originalValue: `$${spec.estimation.totalCostUsd}`,
-                newValue: `$${spec.actuals.totalCostUsd}`,
-                reason: 'Actual cost differs from estimate',
-                approved: true,
-            });
-        }
+function detectEstimationDrift(spec) {
+    if (!spec.actuals) {
+        return null;
     }
-    // Check if status should be updated
-    if (spec.actuals && spec.status !== 'done') {
-        changes.push({
-            section: 'status',
-            originalValue: spec.status,
-            newValue: 'done',
-            reason: 'Actuals are recorded but status is not done',
-            approved: false,
-        });
+    const estimatedTotal = spec.estimation.devHours + spec.estimation.reviewHours;
+    const actualTotal = spec.actuals.devHours + spec.actuals.reviewHours;
+    const ratio = actualTotal / estimatedTotal;
+    if (ratio <= 1.3 && ratio >= 0.7) {
+        return null;
+    }
+    return {
+        section: 'estimation',
+        originalValue: `${estimatedTotal}h estimated`,
+        newValue: `${actualTotal}h actual (${Math.round(ratio * 100)}% of estimate)`,
+        reason: ratio > 1.3
+            ? 'Implementation took significantly longer than estimated'
+            : 'Implementation was completed faster than estimated',
+        approved: true,
+    };
+}
+function detectCostDiscrepancy(spec) {
+    if (!spec.actuals) {
+        return null;
+    }
+    if (Math.abs(spec.estimation.totalCostUsd - spec.actuals.totalCostUsd) <= 10) {
+        return null;
+    }
+    return {
+        section: 'cost',
+        originalValue: `$${spec.estimation.totalCostUsd}`,
+        newValue: `$${spec.actuals.totalCostUsd}`,
+        reason: 'Actual cost differs from estimate',
+        approved: true,
+    };
+}
+function detectStatusNeedsUpdate(spec) {
+    if (!spec.actuals || spec.status === 'done') {
+        return null;
     }
-    // Detect if spec files have been manually modified
+    return {
+        section: 'status',
+        originalValue: spec.status,
+        newValue: 'done',
+        reason: 'Actuals are recorded but status is not done',
+        approved: false,
+    };
+}
+async function detectManualSpecEdits(spec) {
     if (!spec.specPath) {
-        return changes;
+        return null;
     }
     try {
         const rawHuContent = await readFile(spec.specPath, 'utf-8');
         const huContent = stripFrontmatter(rawHuContent);
-        if (huContent.includes('MODIFIED') || huContent.includes('UPDATED')) {
-            changes.push({
-                section: 'hu-manual-edits',
-                originalValue: 'Original spec content',
-                newValue: 'Manual edits detected in spec.md',
-                reason: 'spec.md appears to have been manually modified after creation',
-                approved: true,
-            });
+        if (!huContent.includes('MODIFIED') && !huContent.includes('UPDATED')) {
+            return null;
         }
+        return {
+            section: 'hu-manual-edits',
+            originalValue: 'Original spec content',
+            newValue: 'Manual edits detected in spec.md',
+            reason: 'spec.md appears to have been manually modified after creation',
+            approved: true,
+        };
     }
     catch {
-        changes.push({
+        return {
             section: 'hu-file',
             originalValue: spec.specPath,
             newValue: 'File not found',
             reason: 'spec.md file is missing or was moved',
             approved: false,
-        });
+        };
     }
+}
+async function detectMissingTechnicalSection(spec) {
     try {
         await readFile(spec.technicalPath, 'utf-8');
+        return null;
     }
     catch {
-        changes.push({
+        return {
             section: 'ficha-file',
             originalValue: spec.technicalPath,
             newValue: 'File not found',
             reason: 'spec.md inline Technical/Files section is missing or incomplete',
             approved: false,
-        });
+        };
+    }
+}
+async function autoDetectChanges(spec, _knowledge) {
+    const changes = [];
+    const estimationDrift = detectEstimationDrift(spec);
+    if (estimationDrift) {
+        changes.push(estimationDrift);
+    }
+    const costDiscrepancy = detectCostDiscrepancy(spec);
+    if (costDiscrepancy) {
+        changes.push(costDiscrepancy);
+    }
+    const statusNeedsUpdate = detectStatusNeedsUpdate(spec);
+    if (statusNeedsUpdate) {
+        changes.push(statusNeedsUpdate);
+    }
+    if (!spec.specPath) {
+        return changes;
+    }
+    const manualEditsChange = await detectManualSpecEdits(spec);
+    if (manualEditsChange) {
+        changes.push(manualEditsChange);
+    }
+    const missingTechnicalChange = await detectMissingTechnicalSection(spec);
+    if (missingTechnicalChange) {
+        changes.push(missingTechnicalChange);
     }
     return changes;
 }
-/**
- * Apply approved changes to the spec files.
- */
-async function applyChangesToSpecFiles(spec, changes) {
-    const approvedChanges = changes.filter((c) => c.approved);
-    if (approvedChanges.length === 0) {
-        return;
+const MAX_AUDIT_CELL_LENGTH = 120;
+function escapeAuditCell(value) {
+    const backslashesEscaped = value.replace(/\\/g, '\\\\');
+    // U+2028/U+2029 are ECMAScript LineTerminators, so `^`/`$` with the `m` flag match after them like \n.
+    const lineBreaksEscaped = backslashesEscaped.replace(/\r\n|\r|\n|\u2028|\u2029/g, '\\n');
+    const pipesEscaped = lineBreaksEscaped.replace(/\|/g, '\\|');
+    const escaped = pipesEscaped.replace(/`/g, '\\`');
+    if (escaped.length <= MAX_AUDIT_CELL_LENGTH) {
+        return escaped;
+    }
+    const hash = createHash('sha256').update(value).digest('hex').slice(0, 8);
+    const suffix = `-${hash}`;
+    return `${escaped.slice(0, MAX_AUDIT_CELL_LENGTH - suffix.length)}${suffix}`;
+}
+function insertReconciliationLogEntry(existingTechnical, reconcileSection) {
+    if (existingTechnical.includes('### Reconciliation Log')) {
+        return existingTechnical.replace(/(### Reconciliation Log[\s\S]*?)(\n### |\n## |\n$|$)/, `$1\n${reconcileSection}\n$2`);
     }
-    // Build reconciliation log entry
-    const reconcileRows = approvedChanges.map((c) => `| ${c.section} | ${c.originalValue} | ${c.newValue} | ${c.reason} |`);
+    return existingTechnical.length > 0
+        ? `${existingTechnical}\n\n### Reconciliation Log\n\n${reconcileSection}`
+        : `### Reconciliation Log\n\n${reconcileSection}`;
+}
+async function writeAuditLogForAppliedChanges(spec, changes) {
+    const appliedChanges = changes.filter((c) => c.approved);
+    if (appliedChanges.length === 0) {
+        return { auditWritten: false };
+    }
+    const reconcileRows = appliedChanges.map((c) => `| ${escapeAuditCell(c.section)} | ${escapeAuditCell(c.originalValue)} | ${escapeAuditCell(c.newValue)} | ${escapeAuditCell(c.reason)} |`);
     const reconcileSection = [
         `> Reconciled at: ${new Date().toISOString()}`,
         '',
@@ -112,33 +166,19 @@ async function applyChangesToSpecFiles(spec, changes) {
         '|---------|----------|---------|--------|',
         ...reconcileRows,
     ].join('\n');
-    // Write reconciliation log into the ## Technical section of spec.md
+    let auditWritten = false;
     if (spec.specPath) {
         try {
-            // Read current Technical section body and append reconciliation log to it
             const specContent = await readFile(spec.specPath, 'utf-8');
             const existingTechnical = extractSectionBody(specContent, 'Technical');
-            let updatedTechnical;
-            if (existingTechnical.includes('### Reconciliation Log')) {
-                // Append inside existing Reconciliation Log subsection. The Log uses
-                // h3 (### ) so it nests inside ## Technical without the body parser
-                // truncating the parent section. Terminate the inner block at the
-                // next h3, h2, hr, or EOF. (SPEC-1010 PR-C dual-Opus review.)
-                updatedTechnical = existingTechnical.replace(/(### Reconciliation Log[\s\S]*?)(\n### |\n## |\n$|$)/, `$1\n${reconcileSection}\n$2`);
-            }
-            else {
-                updatedTechnical =
-                    existingTechnical.length > 0
-                        ? `${existingTechnical}\n\n### Reconciliation Log\n\n${reconcileSection}`
-                        : `### Reconciliation Log\n\n${reconcileSection}`;
-            }
+            const updatedTechnical = insertReconciliationLogEntry(existingTechnical, reconcileSection);
             await replaceSectionInSpec(spec.specPath, 'Technical', updatedTechnical);
+            auditWritten = true;
         }
-        catch {
-            // spec.md unreadable — skip
+        catch (err) {
+            void err;
         }
     }
-    // Update post-implementation actuals inside the ## Technical section
     if (spec.actuals && spec.specPath) {
         try {
             const specContent = await readFile(spec.specPath, 'utf-8');
@@ -149,14 +189,84 @@ async function applyChangesToSpecFiles(spec, changes) {
             fichaContent = fichaContent.replace(/(\| Total Cost \| [^|]+ \|) — \|/, `$1 $${spec.actuals.totalCostUsd} |`);
             await replaceSectionInSpec(spec.specPath, 'Technical', fichaContent);
         }
-        catch {
-            // spec.md unreadable — skip
+        catch (err) {
+            void err;
         }
     }
+    return { auditWritten };
+}
+function partitionAppliedTextChanges(approvedTextChanges, skipped) {
+    const skippedKey = (s) => `${s.section}::${s.originalValue}`;
+    const totalKeyCounts = new Map();
+    for (const c of approvedTextChanges) {
+        const key = skippedKey(c);
+        totalKeyCounts.set(key, (totalKeyCounts.get(key) ?? 0) + 1);
+    }
+    const skippedKeyCounts = new Map();
+    for (const s of skipped) {
+        const key = skippedKey(s);
+        skippedKeyCounts.set(key, (skippedKeyCounts.get(key) ?? 0) + 1);
+    }
+    const appliedRemaining = new Map();
+    for (const [key, total] of totalKeyCounts) {
+        appliedRemaining.set(key, total - (skippedKeyCounts.get(key) ?? 0));
+    }
+    return approvedTextChanges.filter((c) => {
+        const key = skippedKey(c);
+        const remaining = appliedRemaining.get(key) ?? 0;
+        if (remaining > 0) {
+            appliedRemaining.set(key, remaining - 1);
+            return true;
+        }
+        return false;
+    });
+}
+async function restoreAfterVerificationFailure(specPath, preWriteSpecContent) {
+    if (preWriteSpecContent === null) {
+        return { restoreFailed: false, note: '' };
+    }
+    try {
+        await atomicWriteFile(specPath, preWriteSpecContent);
+        return { restoreFailed: false, note: ' (spec.md has been restored to its pre-write snapshot)' };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            restoreFailed: true,
+            note: ` (restore to pre-write snapshot ALSO failed: ${reason} — spec.md may be left in a corrupted, partially-written state)`,
+        };
+    }
+}
+async function verifyWriteOrBuildFailureResult(specPath, appliedTextChanges, approvedChanges, preWriteSpecContent, preWriteVersion) {
+    const verification = await verifyWriteSucceeded(specPath, appliedTextChanges);
+    if (verification.verified) {
+        return null;
+    }
+    const { restoreFailed, note: restoreNote } = await restoreAfterVerificationFailure(specPath, preWriteSpecContent);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `reconcile_spec post-write verification failed: ${verification.missingChanges.map((m) => `[${m.section}] ${m.reason}`).join('; ')}${restoreNote}`,
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            specUpdated: false,
+            versionCreated: null,
+            postWriteVerificationFailed: true,
+            missingChanges: verification.missingChanges,
+            appliedChanges: [],
+            skippedChanges: approvedChanges.map((c) => ({
+                section: c.section,
+                originalValue: c.originalValue,
+                reason: 'verification-failed',
+            })),
+            versionRolledBack: !restoreFailed,
+            preWriteVersion,
+        },
+    };
 }
-/**
- * Append a reconciliation note to PLAN.md when changes are applied.
- */
 async function appendPlanReconcileNote(planPath, changes) {
     try {
         const existing = await readFile(planPath, 'utf-8');
@@ -173,14 +283,48 @@ async function appendPlanReconcileNote(planPath, changes) {
         ].join('\n');
         await atomicWriteFile(planPath, existing + note);
     }
-    catch {
-        // Non-fatal: if PLAN.md can't be updated, reconcile still succeeds
+    catch (err) {
+        void err;
+    }
+}
+function buildConflictResolutionQuestion(pendingChanges) {
+    const { field, property } = buildEnumSchema('resolution', ['keep-mine', 'use-spec', 'merge-interactive', 'cancel'], [
+        'Keep mine — discard spec suggestions',
+        'Use spec — apply all suggested changes',
+        'Merge interactively — review each change',
+        'Cancel — do not apply anything',
+    ], `${String(pendingChanges.length)} conflict(s) detected. How to resolve?`, 'keep-mine');
+    const schema = { type: 'object', properties: { [field]: property } };
+    const fallback = {
+        header: 'Conflict Resolution',
+        question: `${String(pendingChanges.length)} pending change(s) detected. How do you want to resolve conflicts?`,
+        multiSelect: false,
+        options: [
+            {
+                label: 'keep-mine',
+                description: 'Keep current state — discard spec suggestions (safe default)',
+            },
+            { label: 'use-spec', description: 'Apply all suggested changes from spec' },
+            { label: 'merge-interactive', description: 'Review each change interactively' },
+            { label: 'cancel', description: 'Cancel — do not apply anything' },
+        ],
+    };
+    return { schema, fallback };
+}
+function applyConflictResolution(resolution, allChanges, pendingChanges) {
+    if (resolution === 'keep-mine') {
+        allChanges.splice(0, allChanges.length, ...allChanges.filter((c) => c.approved));
+        return;
+    }
+    if (resolution === 'use-spec') {
+        for (const change of pendingChanges) {
+            change.approved = true;
+        }
     }
 }
 export async function handleReconcileSpec(params, server) {
     const { specId, projectId, autoDetect = true, livingSpec = false, changes: manualChanges, } = params;
     try {
-        // Get the spec
         const spec = await specStore.getSpec(projectId, specId);
         if (!spec) {
             return {
@@ -188,43 +332,18 @@ export async function handleReconcileSpec(params, server) {
                 isError: true,
             };
         }
-        // Load project knowledge
         const knowledge = await knowledgeStore.getKnowledge(projectId);
-        // Collect all changes
         const allChanges = [];
-        // Auto-detect changes
         if (autoDetect) {
             const autoChanges = await autoDetectChanges(spec, knowledge);
             allChanges.push(...autoChanges);
         }
-        // Add manual changes
         if (manualChanges && manualChanges.length > 0) {
             allChanges.push(...manualChanges);
         }
-        // SPEC-595: Elicit conflict resolution strategy when there are pending (non-approved) changes
         const pendingChanges = allChanges.filter((c) => !c.approved);
         if (server !== undefined && pendingChanges.length > 0) {
-            const { field, property } = buildEnumSchema('resolution', ['keep-mine', 'use-spec', 'merge-interactive', 'cancel'], [
-                'Keep mine — discard spec suggestions',
-                'Use spec — apply all suggested changes',
-                'Merge interactively — review each change',
-                'Cancel — do not apply anything',
-            ], `${String(pendingChanges.length)} conflict(s) detected. How to resolve?`, 'keep-mine');
-            const schema = { type: 'object', properties: { [field]: property } };
-            const fallback = {
-                header: 'Conflict Resolution',
-                question: `${String(pendingChanges.length)} pending change(s) detected. How do you want to resolve conflicts?`,
-                multiSelect: false,
-                options: [
-                    {
-                        label: 'keep-mine',
-                        description: 'Keep current state — discard spec suggestions (safe default)',
-                    },
-                    { label: 'use-spec', description: 'Apply all suggested changes from spec' },
-                    { label: 'merge-interactive', description: 'Review each change interactively' },
-                    { label: 'cancel', description: 'Cancel — do not apply anything' },
-                ],
-            };
+            const { schema, fallback } = buildConflictResolutionQuestion(pendingChanges);
             const outcome = await elicitOrFallback(server, `${String(pendingChanges.length)} conflict(s) detected. How to resolve?`, schema, [fallback]);
             if (outcome.mode === 'fallback') {
                 return {
@@ -247,105 +366,100 @@ export async function handleReconcileSpec(params, server) {
             if (resolution === 'cancel') {
                 return { content: [{ type: 'text', text: `Reconcile ${specId} cancelled.` }] };
             }
-            if (resolution === 'keep-mine') {
-                // Remove pending changes — only keep already-approved ones
-                allChanges.splice(0, allChanges.length, ...allChanges.filter((c) => c.approved));
-            }
-            else if (resolution === 'use-spec') {
-                // Approve all pending changes
-                for (const change of pendingChanges) {
-                    change.approved = true;
-                }
-            }
-            // 'merge-interactive': proceed with whatever is currently approved (LLM handles the rest)
+            applyConflictResolution(resolution, allChanges, pendingChanges);
         }
-        // Apply approved changes to spec files
-        await applyChangesToSpecFiles(spec, allChanges);
-        // SPEC-1011 Bug D: Apply text changes to spec.md body and run post-write verification.
-        // This is the actual write path for manual changes with section content updates.
         const approvedChanges = allChanges.filter((c) => c.approved);
+        const metadataChanges = approvedChanges.filter((c) => SECTIONS_WITHOUT_LITERAL_BODY_TEXT.has(c.section));
+        const approvedTextChanges = approvedChanges.filter((c) => !SECTIONS_WITHOUT_LITERAL_BODY_TEXT.has(c.section));
         const preWriteVersion = approvedChanges.length > 0 ? await specStore.getLatestVersion(projectId, specId) : null;
         let specBodyWritten = false;
         let bodySkippedChanges = [];
+        let appliedTextChanges = [];
         if (spec.specPath && approvedChanges.length > 0) {
-            const applyResult = await applyChangesToSpec(spec.specPath, approvedChanges);
-            specBodyWritten = applyResult.fileWritten;
-            bodySkippedChanges = applyResult.skipped;
-            if (applyResult.fileWritten) {
-                // SPEC-1011 Bug D — Post-write integrity check: re-read and verify each newValue
-                // is present. If verification fails, the file was written but the content does not
-                // reflect the requested changes (e.g., atomic-write race or replace silently no-oped).
-                // In that case we surface a hard error and do NOT create a version, since reporting
-                // specUpdated:true with versionCreated:N would lie about disk state — exactly the bug.
-                //
-                // Verify only changes that applyChangesToSpec actually applied. Skipped changes
-                // (originalValue not found in section, ambiguous, etc.) are documented as
-                // non-fatal further down — including them here would falsely fail verification on
-                // legitimate conceptual/metadata-only changes. (SPEC-1010 PR-C dual-Opus review.)
-                const skippedKey = (s) => `${s.section}::${s.originalValue}`;
-                const skippedKeys = new Set(applyResult.skipped.map(skippedKey));
-                const appliedChanges = approvedChanges.filter((c) => !skippedKeys.has(skippedKey(c)));
-                const verification = await verifyWriteSucceeded(spec.specPath, appliedChanges);
-                if (!verification.verified) {
+            const needsPreWriteSnapshot = approvedTextChanges.length > 0;
+            let preWriteSpecContent = null;
+            if (needsPreWriteSnapshot) {
+                try {
+                    preWriteSpecContent = await readFile(spec.specPath, 'utf-8');
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `reconcile_spec post-write verification failed: ${verification.missingChanges.map((m) => `[${m.section}] ${m.reason}`).join('; ')}`,
+                                text: `reconcile_spec refused to apply changes: could not read spec.md to take a pre-write snapshot (${reason})`,
                             },
                         ],
                         isError: true,
                         structuredContent: {
                             specUpdated: false,
-                            postWriteVerificationFailed: true,
-                            missingChanges: verification.missingChanges,
-                            // The file was already written before verification ran; "version-rolled-back"
-                            // means we refused to record a SpecVersion entry, not that disk was reverted.
-                            versionRolledBack: true,
+                            versionCreated: null,
+                            postWriteVerificationFailed: false,
+                            missingChanges: [],
+                            appliedChanges: [],
+                            skippedChanges: approvedChanges.map((c) => ({
+                                section: c.section,
+                                originalValue: c.originalValue,
+                                reason: 'pre-write-snapshot-failed',
+                            })),
+                            versionRolledBack: false,
                             preWriteVersion,
                         },
                     };
                 }
             }
-            // applyResult.skipped (originalValue not found in spec.md body) is non-fatal:
-            // many manual changes are conceptual (e.g., scope expansion notes) and only update
-            // metadata/version, not the spec body. Surfaced via structuredContent below.
+            const applyResult = await applyChangesToSpec(spec.specPath, approvedChanges);
+            specBodyWritten = applyResult.fileWritten;
+            bodySkippedChanges = applyResult.skipped;
+            appliedTextChanges = partitionAppliedTextChanges(approvedTextChanges, applyResult.skipped);
+            if (applyResult.fileWritten) {
+                const verificationFailure = await verifyWriteOrBuildFailureResult(spec.specPath, appliedTextChanges, approvedChanges, preWriteSpecContent, preWriteVersion);
+                if (verificationFailure) {
+                    return verificationFailure;
+                }
+            }
+        }
+        else if (!spec.specPath && approvedTextChanges.length > 0) {
+            bodySkippedChanges = approvedTextChanges.map((c) => ({
+                section: c.section,
+                originalValue: c.originalValue,
+                reason: 'spec.md path is missing — cannot apply text change',
+                reasonCategory: 'skipped',
+            }));
+        }
+        const appliedChanges = [...metadataChanges, ...appliedTextChanges];
+        const anyApplied = appliedChanges.length > 0;
+        let auditWriteResult = { auditWritten: false };
+        if (anyApplied) {
+            auditWriteResult = await writeAuditLogForAppliedChanges(spec, appliedChanges);
         }
-        // Update spec metadata if needed
-        const hasStatusChange = approvedChanges.find((c) => c.section === 'status');
+        const hasStatusChange = metadataChanges.find((c) => c.section === 'status');
         if (hasStatusChange) {
-            // SPEC-720: Use __internalSetStatus for reconcile (tool-layer maintenance write,
-            // not a user-initiated transition — no gates needed here as this is driven by an
-            // approved reconcile review with explicit change approval).
             await specStore.__internalSetStatus(projectId, specId, hasStatusChange.newValue);
         }
-        // Update PLAN.md if spec has one and there were approved changes
-        if (spec.planPath && approvedChanges.length > 0) {
-            await appendPlanReconcileNote(spec.planPath, approvedChanges);
+        if (spec.planPath && anyApplied) {
+            await appendPlanReconcileNote(spec.planPath, appliedChanges);
         }
-        // Create a new SpecVersion only when there were approved changes that actually mutated state.
-        // (specBodyWritten OR metadata-only changes that are still valid)
         let createdVersion = null;
-        if (approvedChanges.length > 0) {
+        if (anyApplied) {
             const currentVersion = await specStore.getLatestVersion(projectId, specId);
-            const version = createVersion(specId, currentVersion, approvedChanges, `Reconcile: ${approvedChanges.length} change(s) applied`);
+            const version = createVersion(specId, currentVersion, appliedChanges, `Reconcile: ${appliedChanges.length} change(s) applied`);
             await specStore.saveVersion(projectId, specId, version);
             createdVersion = version.version;
         }
-        // Mark spec as reconciled by updating the timestamp
         await specStore.updateSpec(projectId, specId, {
             updatedAt: new Date().toISOString(),
         });
         const report = {
             specId,
             changes: allChanges,
-            specUpdated: approvedChanges.length > 0,
-            reason: approvedChanges.length > 0
-                ? `Applied ${approvedChanges.length} change(s) to spec`
+            specUpdated: anyApplied,
+            reason: anyApplied
+                ? `Applied ${appliedChanges.length} change(s) to spec`
                 : 'No changes to apply',
             reconciledAt: new Date().toISOString(),
         };
-        // Living spec analysis: compare criteria against codebase
         let livingSpecReport = null;
         if (livingSpec) {
             const projectKnowledge = await knowledgeStore.getKnowledge(projectId);
@@ -353,10 +467,22 @@ export async function handleReconcileSpec(params, server) {
                 livingSpecReport = await analyzeLivingSpec(spec, projectKnowledge.projectPath);
             }
         }
+        const appliedChangesReport = appliedChanges.map((c) => ({
+            section: c.section,
+            newValue: c.newValue,
+        }));
+        const skippedChangesReport = bodySkippedChanges.map((s) => ({
+            section: s.section,
+            originalValue: s.originalValue,
+            reason: s.reasonCategory,
+        }));
         const result = {
             ...report,
             versionCreated: createdVersion,
             specBodyWritten,
+            auditWritten: auditWriteResult.auditWritten,
+            appliedChanges: appliedChangesReport,
+            skippedChanges: skippedChangesReport,
             ...(bodySkippedChanges.length > 0 ? { skippedTextChanges: bodySkippedChanges } : {}),
             ...(livingSpecReport ? { livingSpec: livingSpecReport } : {}),
             summary: {
@@ -373,7 +499,6 @@ export async function handleReconcileSpec(params, server) {
                 count: String(allChanges.length),
             }),
         };
-        // Notify portal regeneration (fire-and-forget)
         if (knowledge?.projectPath) {
             notifyStoreChange(knowledge.projectPath, 'specs');
         }

package/dist/tools/update-status/dod-gates.js

@@ -285,7 +285,7 @@ function validationReceiptGateError(specId, reason) {
         },
     };
 }
-function doneReviewDigestError(specId, code, message) {
+function doneReviewDigestError(specId, code, message, digests) {
     const artifactPath = `external Planu project data: handoffs/${specId}/validation-report.json`;
     const fixHint = 'Run validate, then recompute the sha256 digest from the exact report bytes.';
     return {
@@ -294,7 +294,7 @@ function doneReviewDigestError(specId, code, message) {
         structuredContent: {
             error: code,
             code: 422,
-            context: { specId, artifactPath },
+            context: { specId, artifactPath, ...digests },
             fixHint,
         },
     };
@@ -430,7 +430,7 @@ async function checkDoneReviewDigest(specId, projectId, implementationReviewDige
     }
     const observed = `sha256:${createHash('sha256').update(reportResult).digest('hex')}`;
     if (observed !== implementationReviewDigest) {
-        return doneReviewDigestError(specId, 'DONE_REVIEW_DIGEST_MISMATCH', 'The implementation review digest does not match the persisted validation report.');
+        return doneReviewDigestError(specId, 'DONE_REVIEW_DIGEST_MISMATCH', 'The implementation review digest does not match the persisted validation report.', { received: implementationReviewDigest, expected: observed });
     }
     let decoded;
     try {