open-wiki-spec 0.2.4 → 0.3.0

package/dist/core/workflow/apply/apply.js

@@ -21,6 +21,79 @@ function defaultExclusiveCreateFile(filePath, content) {
         fs.closeSync(fd);
     }
 }
+/**
+ * Recover from a prior crash: restore .ows-backup-* files and remove .ows-tmp-* files.
+ * Called before acquiring lock to ensure clean state.
+ *
+ * Returns a list of per-file recovery failures so the caller can decide
+ * whether to abort. Previously these were swallowed silently, which could
+ * leave the vault in a partially-recovered state where some Feature files
+ * were successfully restored from backup but others were not — the next
+ * apply would then operate on mixed pre-/post-crash content without the
+ * user ever seeing a warning.
+ */
+function recoverFromCrash(vaultRoot, deps) {
+    const failures = [];
+    const wikiDir = join(vaultRoot, 'wiki');
+    try {
+        const allFiles = fs.readdirSync(wikiDir, { recursive: true });
+        // Step 0: Check for a commit marker. If present, ALL renames
+        // succeeded in a prior run but the process crashed before cleanup.
+        // Forward-recover: delete backups + commit marker, keep new files.
+        // If absent AND backups exist, the renames were partial — rollback
+        // by restoring all backups.
+        const commitMarker = allFiles.find((f) => String(f).includes('.ows-commit-'));
+        if (commitMarker) {
+            // Forward recovery: all renames completed → delete backups + marker
+            for (const relFile of allFiles) {
+                const file = String(relFile);
+                const absPath = join(wikiDir, file);
+                if (file.includes('.ows-backup-') || file.includes('.ows-tmp-') || file.includes('.ows-commit-')) {
+                    try {
+                        if (deps.deleteFile)
+                            deps.deleteFile(absPath);
+                    }
+                    catch (err) {
+                        failures.push(`forward-recovery cleanup failed for ${file}: ${err.message}`);
+                    }
+                }
+            }
+            return failures;
+        }
+        // No commit marker → rollback any partial renames
+        for (const relFile of allFiles) {
+            const file = String(relFile);
+            const absPath = join(wikiDir, file);
+            if (file.includes('.ows-tmp-')) {
+                try {
+                    if (deps.deleteFile)
+                        deps.deleteFile(absPath);
+                }
+                catch (err) {
+                    failures.push(`failed to remove stale tmp file ${file}: ${err.message}`);
+                }
+            }
+            else if (file.includes('.ows-backup-')) {
+                // Rollback: ALWAYS restore backup regardless of whether the
+                // original path exists. If the original was overwritten by a
+                // partial rename, the backup is the authoritative pre-apply
+                // version. This prevents the mixed-state bug where some files
+                // have post-apply content and others have pre-apply content.
+                const originalPath = absPath.replace(/\.ows-backup-\d+/, '');
+                try {
+                    fs.renameSync(absPath, originalPath);
+                }
+                catch (err) {
+                    failures.push(`failed to restore backup ${file}: ${err.message}`);
+                }
+            }
+        }
+    }
+    catch {
+        // wiki dir might not exist yet — ignore
+    }
+    return failures;
+}
 function acquireLock(vaultRoot, deps) {
     const lockPath = join(vaultRoot, 'wiki', LOCK_FILENAME);
     const lockContent = JSON.stringify({ pid: process.pid, timestamp: new Date().toISOString() });
@@ -128,7 +201,13 @@ export function applyChange(options, index, deps) {
         throw new Error(`Cannot apply change with status "${changeRecord.status}". ` +
             'Expected "in_progress". Use \'continue\' to advance through the status lifecycle first.');
     }
-    // Check all tasks complete
+    // Check all tasks complete. Reject changes with zero tasks — a change with
+    // no tasks is an incomplete spec (Tasks is a hard prerequisite per the
+    // planned transition), and allowing it would let users apply a Change that
+    // was never actually implemented.
+    if (parsed.tasks.length === 0) {
+        throw new Error('Cannot apply: change has no tasks defined. Add implementation tasks to the ## Tasks section before applying.');
+    }
     const uncheckedTasks = parsed.tasks.filter((t) => !t.done);
     if (uncheckedTasks.length > 0) {
         throw new Error(`Cannot apply: ${uncheckedTasks.length} unchecked task(s) remaining. ` +
@@ -136,11 +215,18 @@ export function applyChange(options, index, deps) {
     }
     // 2. Parse Delta Summary
     const resolveWikilink = (target) => {
-        // Simple lookup by title
+        // Lookup by id first (highest priority), then title, then alias
         for (const record of index.records.values()) {
-            if (record.title === target || record.id === target) {
+            if (record.id === target)
+                return record.id;
+        }
+        for (const record of index.records.values()) {
+            if (record.title === target)
+                return record.id;
+        }
+        for (const record of index.records.values()) {
+            if (record.aliases.some((a) => a === target))
                 return record.id;
-            }
         }
         return undefined;
     };
@@ -153,6 +239,57 @@ export function applyChange(options, index, deps) {
             warnings,
         });
     }
+    // Hard-fail on any Unparseable line. These warnings are only emitted when
+    // a delta line STARTS with ADDED/MODIFIED/REMOVED/RENAMED but fails the
+    // full regex (e.g., missing quotes around the requirement name, or the
+    // target was written as plain text instead of a `[[wikilink]]`). Such
+    // lines are unambiguously intended as delta entries — silently applying
+    // only the parseable siblings produces a partial change that is
+    // impossible to audit after the fact. Block the whole apply so the user
+    // fixes the syntax explicitly.
+    const unparseable = deltaPlan.warnings.filter((w) => w.startsWith('Unparseable Delta Summary entry'));
+    if (unparseable.length > 0) {
+        return makeResult(options, changeRecord, {
+            success: false,
+            errors: [
+                `Delta Summary has ${unparseable.length} unparseable line(s). ` +
+                    `Fix the syntax — requirement names must be quoted ` +
+                    `(e.g., \`ADDED requirement "FooBar" to [[Feature: Auth]]\`) ` +
+                    `and target Features must be wikilinks, not plain text:`,
+                ...unparseable.map((u) => `  ${u}`),
+            ],
+            warnings,
+        });
+    }
+    // Validate that every Delta Summary entry targets a Feature declared in the
+    // change's frontmatter (`feature` or `features`). This prevents a Change that
+    // claims `features: [A, B]` from accidentally modifying Feature C.
+    const declaredFeatureIds = new Set();
+    if (changeRecord.feature)
+        declaredFeatureIds.add(changeRecord.feature);
+    if (changeRecord.features) {
+        for (const f of changeRecord.features)
+            declaredFeatureIds.add(f);
+    }
+    if (declaredFeatureIds.size > 0) {
+        const undeclaredTargets = [];
+        for (const [noteKey] of deltaPlan.byTargetNote) {
+            if (!declaredFeatureIds.has(noteKey)) {
+                undeclaredTargets.push(noteKey);
+            }
+        }
+        if (undeclaredTargets.length > 0) {
+            return makeResult(options, changeRecord, {
+                success: false,
+                errors: [
+                    `Delta Summary targets Feature(s) not declared in the change's frontmatter: ${undeclaredTargets.join(', ')}. ` +
+                        `Declared features: ${Array.from(declaredFeatureIds).join(', ')}. ` +
+                        `Either add the undeclared targets to the change's "features" field, or fix the Delta Summary to point at the declared Features.`,
+                ],
+                warnings,
+            });
+        }
+    }
     // Validate delta conflicts
     const conflictErrors = validateDeltaConflicts(deltaPlan);
     if (conflictErrors.length > 0) {
@@ -163,10 +300,22 @@ export function applyChange(options, index, deps) {
     for (const [noteKey] of deltaPlan.byTargetNote) {
         const noteRecord = index.records.get(noteKey);
         if (!noteRecord) {
-            errors.push(`Target note "${noteKey}" not found in index`);
+            errors.push(`Target note "${noteKey}" referenced in Delta Summary does not exist in the vault. ` +
+                `Either the Feature was deleted, renamed, or the Change's Delta Summary points to the wrong target. ` +
+                `Fix the Delta Summary wikilink or restore the missing note.`);
+            continue;
+        }
+        // Resolve path: absolute paths stay as-is, relative paths resolve against vault root
+        const resolvedNotePath = resolve(options.vaultRoot, noteRecord.path);
+        let noteParsed;
+        try {
+            noteParsed = deps.parseNote(resolvedNotePath);
+        }
+        catch (parseErr) {
+            errors.push(`Failed to read target note "${noteKey}" at ${noteRecord.path}: ${parseErr.message}. ` +
+                `The file may have been deleted or become unreadable since the index was built.`);
             continue;
         }
-        const noteParsed = deps.parseNote(resolve(options.vaultRoot, noteRecord.path));
         const reqMap = new Map();
         for (const req of noteParsed.requirements) {
             reqMap.set(req.name, req);
@@ -190,6 +339,19 @@ export function applyChange(options, index, deps) {
             errors: staleReport.staleEntries.map((s) => `STALE: ${s.entry.op} "${s.entry.targetName}" - ${s.reason}`),
         });
     }
+    // 5b. If --force-stale was used and there actually was a stale report,
+    // record a prominent warning per entry so the audit trail isn't silent.
+    // Without this, a forced apply looks identical to a clean apply in the
+    // resulting ApplyResult — making it impossible for reviewers to tell
+    // after the fact that the stale guard was bypassed on purpose.
+    if (staleReport.blocked && options.forceStale && staleReport.staleEntries.length > 0) {
+        warnings.push(`--force-stale: bypassed ${staleReport.staleEntries.length} stale base check(s). ` +
+            'Applied requirement deltas against a base that has already been modified ' +
+            'by another change. Review the result carefully and re-verify the Feature.');
+        for (const s of staleReport.staleEntries) {
+            warnings.push(`  force-stale: ${s.entry.op} "${s.entry.targetName}" - ${s.reason}`);
+        }
+    }
     // === PHASE 1: Validate and compute ===
     const featureResults = [];
     const allPostValidations = [];
@@ -231,10 +393,40 @@ export function applyChange(options, index, deps) {
         const agentEntries = reqEntries.filter((e) => AGENT_DRIVEN_OPS.has(e.op));
         const allReqEntries = [...mechEntries, ...agentEntries];
         const resolvedNotePath = resolve(options.vaultRoot, noteRecord.path);
-        // Read Feature file content for programmatic editing
-        const featureContent = deps.readFile(resolvedNotePath);
+        // Read Feature file content for programmatic editing. The file may
+        // have been deleted or replaced between parseNote (earlier in this
+        // function) and this read — for example, an Obsidian user moving
+        // files while `ows apply` runs. Turn a raw exception into a
+        // structured `errors` entry so the caller gets a clean failure
+        // report instead of the process aborting mid-apply.
+        let featureContent;
+        try {
+            featureContent = deps.readFile(resolvedNotePath);
+        }
+        catch (err) {
+            const code = err.code;
+            const reason = code === 'ENOENT'
+                ? 'file no longer exists (was it moved or deleted mid-apply?)'
+                : code === 'EACCES'
+                    ? 'permission denied while reading'
+                    : err.message;
+            errors.push(`Failed to re-read Feature "${noteKey}" at ${noteRecord.path}: ${reason}. ` +
+                'Aborting apply before any writes.');
+            continue;
+        }
         const result = applyDeltaToFeature(noteKey, resolvedNotePath, reqMap, allReqEntries, featureContent, options.changeId);
         featureResults.push(result);
+        // Hard-fail on any semantic operation failure within a Feature.
+        // Without this, a multi-Feature change (features: [A, B]) could
+        // see Feature A succeed and Feature B fail at the operation level
+        // (e.g., "## Requirements section not found"), yet Phase 2 would
+        // still write A and skip B — producing a partial apply. Promoting
+        // operation-level failures to the global errors array ensures the
+        // entire apply aborts before any writes.
+        const failedOps = result.operations.filter((op) => !op.success);
+        for (const op of failedOps) {
+            errors.push(`Feature "${noteKey}": ${op.entry.op} "${op.entry.targetName}" failed: ${op.error ?? 'unknown error'}`);
+        }
         // Collect agent-driven ops (MODIFIED/ADDED need agent to fill content)
         for (const entry of agentEntries) {
             pendingAgentOps.push({
@@ -307,10 +499,43 @@ export function applyChange(options, index, deps) {
     // Uses atomic temp-file pattern: write to .ows-tmp first, then rename all at once.
     let statusTransitioned = false;
     const modifiedFiles = [];
-    // When noAutoTransition is set and there are pending agent ops, skip auto-transition.
-    // The agent must fill markers first, then run apply again (or verifyApply).
-    const skipTransition = options.noAutoTransition && pendingAgentOps.length > 0;
+    // Always skip auto-transition when agent-driven ops remain — even if
+    // `noAutoTransition` is false. Previously the default behavior was
+    // to still flip the Change to `applied` while leaving `MODIFIED/ADDED`
+    // markers unfilled in the Feature, which verify later caught via
+    // `UNFILLED_APPLY_MARKER`. That verdict was correct but came AFTER
+    // the status transition, leaving the Change in a lying state. Skip
+    // the transition up front so the Change stays `in_progress` until
+    // the agent actually fills the markers and runs apply again.
+    const skipTransition = pendingAgentOps.length > 0;
+    if (skipTransition && !options.noAutoTransition) {
+        warnings.push(`Auto-transition to "applied" blocked: ${pendingAgentOps.length} agent-driven op(s) still need marker fill. ` +
+            'Fill the MODIFIED/ADDED markers in the Feature note, then re-run `ows apply`.');
+    }
     if (!options.dryRun) {
+        // Recover from prior crash (restore backups, clean temp files).
+        // Failures here are not fatal for tmp-file leftovers, but unrestored
+        // backups mean the vault is in a half-restored state — surface them
+        // as errors so the user can intervene before we clobber more files.
+        const recoveryFailures = recoverFromCrash(options.vaultRoot, deps);
+        for (const fail of recoveryFailures) {
+            if (fail.startsWith('failed to restore backup')) {
+                errors.push(`Pre-apply crash recovery could not restore a backup: ${fail}. ` +
+                    'Manually inspect wiki/ for .ows-backup-* files, restore them, then retry.');
+            }
+            else {
+                warnings.push(`Pre-apply crash recovery warning: ${fail}`);
+            }
+        }
+        if (errors.length > 0) {
+            return makeResult(options, changeRecord, {
+                success: false,
+                staleReport,
+                featureResults,
+                errors,
+                warnings,
+            });
+        }
         // Acquire vault-level lock
         if (!acquireLock(options.vaultRoot, deps)) {
             errors.push('Cannot apply: another apply operation is in progress (wiki/.ows-lock exists)');
@@ -335,7 +560,12 @@ export function applyChange(options, index, deps) {
             const pendingWrites = [];
             for (const featureResult of featureResults) {
                 if (featureResult.requiresWrite && featureResult.updatedContent) {
-                    pendingWrites.push({ path: featureResult.featurePath, content: featureResult.updatedContent });
+                    // Only append Change Log when actually transitioning to applied
+                    // (skip when --no-auto-transition with pending agent ops)
+                    const content = skipTransition
+                        ? featureResult.updatedContent
+                        : appendChangeLogEntry(featureResult.updatedContent, changeRecord, deltaPlan.byTargetNote.get(featureResult.featureId) ?? []);
+                    pendingWrites.push({ path: featureResult.featurePath, content });
                 }
             }
             // Status transition content — skip if noAutoTransition with pending ops
@@ -346,7 +576,10 @@ export function applyChange(options, index, deps) {
             pendingWrites.push({ path: resolvedChangePath, content: updatedChangeContent });
             // Use unique temp suffix to avoid collisions
             const tmpSuffix = `.ows-tmp-${Date.now()}`;
-            // Phase 2a: Write all to temp files
+            // Phase 2a: Write all to temp files, preserving the original file
+            // mode so permissions survive the write (a 0444 read-only vault
+            // stays 0444, preserving the user's intent). When copyFileMode is
+            // not injected, we fall through to whatever umask produces.
             const tmpPaths = [];
             let writeFailed = false;
             for (const { path, content } of pendingWrites) {
@@ -355,6 +588,16 @@ export function applyChange(options, index, deps) {
                 try {
                     deps.writeFile(tmpPath, content);
                     tmpPaths.push(tmpPath);
+                    if (deps.copyFileMode) {
+                        try {
+                            deps.copyFileMode(path, tmpPath);
+                        }
+                        catch {
+                            // Mode preservation is best-effort — on platforms where
+                            // chmod is a no-op (Windows without admin) or the source
+                            // file was already replaced, just use default permissions.
+                        }
+                    }
                 }
                 catch (err) {
                     errors.push(`Failed to write temp file ${tmpPath}: ${err.message}`);
@@ -387,13 +630,15 @@ export function applyChange(options, index, deps) {
                     }
                 }
                 if (backupFailed) {
-                    // Restore any backups already made
+                    // Restore any backups already made. Surface any restore failure
+                    // so the user knows a backup file is orphaned and the original missing.
                     for (const { original, backup } of backedUpPaths) {
                         try {
                             deps.moveFile(backup, original);
                         }
-                        catch {
-                            // Best-effort restore — swallow errors
+                        catch (restoreErr) {
+                            errors.push(`CRITICAL: Failed to restore backup "${backup}" -> "${original}": ${restoreErr.message}. ` +
+                                `Manual recovery required: move the backup file back to the original path.`);
                         }
                     }
                     // Cleanup temp files
@@ -429,13 +674,14 @@ export function applyChange(options, index, deps) {
                                 // Best-effort — swallow errors
                             }
                         }
-                        // Restore all backups
+                        // Restore all backups. Surface restore failures so users can recover manually.
                         for (const { original, backup } of backedUpPaths) {
                             try {
                                 deps.moveFile(backup, original);
                             }
-                            catch {
-                                // Best-effort restore — swallow errors
+                            catch (restoreErr) {
+                                errors.push(`CRITICAL: Failed to restore backup "${backup}" -> "${original}": ${restoreErr.message}. ` +
+                                    `Manual recovery required.`);
                             }
                         }
                         // Cleanup remaining temp files (the ones not yet renamed)
@@ -445,17 +691,40 @@ export function applyChange(options, index, deps) {
                         cleanupTempFiles(remainingTmps, deps);
                     }
                     else {
-                        // All writes succeeded — delete backups
+                        // All renames succeeded. Write a commit marker so that
+                        // crash recovery knows this is a complete apply — forward
+                        // recovery (delete backups) instead of rollback (restore
+                        // backups). The marker is deleted after backup cleanup.
+                        const commitMarkerPath = join(options.vaultRoot, 'wiki', `.ows-commit-${Date.now()}`);
+                        try {
+                            deps.writeFile(commitMarkerPath, `${options.changeId}|${Date.now()}`);
+                        }
+                        catch {
+                            // Commit marker write failure is non-fatal — without it,
+                            // a crash here would trigger rollback recovery on next run,
+                            // which is safe (just means the apply would be re-run).
+                        }
+                        // All writes succeeded — delete backups. Surface any
+                        // cleanup failure as a warning.
                         for (const { backup } of backedUpPaths) {
                             try {
                                 if (deps.deleteFile) {
                                     deps.deleteFile(backup);
                                 }
                             }
-                            catch {
-                                // Best-effort cleanup — swallow errors
+                            catch (err) {
+                                warnings.push(`Orphan backup: apply succeeded but could not delete ${backup} (${err.message}). ` +
+                                    'Remove the file manually or check wiki/ permissions.');
                             }
                         }
+                        // Remove commit marker now that backups are cleaned up
+                        try {
+                            if (deps.deleteFile)
+                                deps.deleteFile(commitMarkerPath);
+                        }
+                        catch {
+                            // Non-fatal — marker will be cleaned up on next apply.
+                        }
                         for (const { path } of pendingWrites) {
                             if (path !== resolvedChangePath) {
                                 modifiedFiles.push(path);
@@ -470,6 +739,17 @@ export function applyChange(options, index, deps) {
             releaseLock(options.vaultRoot, deps);
         }
     }
+    // Dry-run warning: when dry-run reports success but pendingAgentOps
+    // remain, the caller must still fill markers and run a real apply
+    // later. Without this note, a CI that runs `--dry-run` then trusts
+    // `success: true` would skip the real apply and leave the change
+    // stuck in in_progress. Surface it explicitly in warnings so both
+    // JSON and human consumers see it.
+    if (options.dryRun && pendingAgentOps.length > 0 && errors.length === 0) {
+        warnings.push(`Dry-run success is PROVISIONAL: ${pendingAgentOps.length} agent-driven operation(s) ` +
+            `still need human/LLM authoring (MODIFIED/ADDED requirement markers). ` +
+            'Real apply cannot skip this step — fill the markers then run `ows apply` without --dry-run.');
+    }
     return {
         changeId: options.changeId,
         changeName: changeRecord.title,
@@ -531,9 +811,9 @@ export function archiveChange(options, index, deps) {
 function preValidateEntry(entry, requirements) {
     switch (entry.op) {
         case 'ADDED':
-            return requirements.has(entry.targetName)
-                ? `Requirement "${entry.targetName}" already exists (ADDED requires non-existence)`
-                : null;
+            // If requirement already exists (e.g., from a prior --no-auto-transition run),
+            // treat as no-op rather than error — the skeleton was already placed.
+            return null;
         case 'MODIFIED':
             return !requirements.has(entry.targetName)
                 ? `Requirement "${entry.targetName}" not found (MODIFIED requires existence)`
@@ -566,6 +846,130 @@ function cleanupTempFiles(tmpPaths, deps) {
         }
     }
 }
+/**
+ * Maximum number of rows kept in a Feature note's Change Log table.
+ * Older entries are dropped (still preserved in archived Change notes).
+ */
+const CHANGE_LOG_MAX_ROWS = 50;
+/**
+ * Trim a Change Log section so only the most recent CHANGE_LOG_MAX_ROWS remain.
+ * If rows were dropped, adds a comment marker indicating the trim.
+ */
+function trimChangeLogSection(featureContent) {
+    const changeLogMatch = featureContent.match(/^## Change Log\s*$/m);
+    if (!changeLogMatch)
+        return featureContent;
+    const sectionStart = changeLogMatch.index + changeLogMatch[0].length;
+    const nextHeadingMatch = featureContent.slice(sectionStart).match(/^## /m);
+    const sectionEnd = nextHeadingMatch
+        ? sectionStart + nextHeadingMatch.index
+        : featureContent.length;
+    const sectionContent = featureContent.slice(sectionStart, sectionEnd);
+    // Find table rows (lines starting with `| ` that are not header/separator)
+    const lines = sectionContent.split('\n');
+    const rowLines = [];
+    let headerDone = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.match(/^\|[-\s|]+\|\s*$/)) {
+            headerDone = true;
+            continue;
+        }
+        if (headerDone && line.startsWith('| ') && line.trim().endsWith('|')) {
+            rowLines.push({ line, index: i });
+        }
+    }
+    if (rowLines.length <= CHANGE_LOG_MAX_ROWS)
+        return featureContent;
+    // Keep the first CHANGE_LOG_MAX_ROWS rows (newest, since we prepend)
+    const keepRows = rowLines.slice(0, CHANGE_LOG_MAX_ROWS);
+    const dropCount = rowLines.length - CHANGE_LOG_MAX_ROWS;
+    const lastKeptIdx = keepRows[keepRows.length - 1].index;
+    // Build the trimmed section: up to last kept row + marker + empty line
+    const keptSectionLines = lines.slice(0, lastKeptIdx + 1);
+    keptSectionLines.push('');
+    keptSectionLines.push(`<!-- ${dropCount} older entries trimmed; see wiki/99-archive/ for full history -->`);
+    keptSectionLines.push('');
+    const newSectionContent = keptSectionLines.join('\n');
+    return featureContent.slice(0, sectionStart) + newSectionContent + featureContent.slice(sectionEnd);
+}
+/**
+ * Append a Change Log entry row to a Feature note's ## Change Log section.
+ * If the section or table header doesn't exist, creates them.
+ * Trims older entries when the table grows beyond CHANGE_LOG_MAX_ROWS.
+ */
+function appendChangeLogEntry(featureContent, changeRecord, deltaEntries) {
+    const date = new Date().toLocaleDateString('en-CA'); // YYYY-MM-DD
+    const changeLink = `[[${changeRecord.title}]]`;
+    const summary = deltaEntries
+        .map((e) => {
+        if (e.op === 'RENAMED' && e.newName) {
+            return `${e.op} [${e.targetType}] ${e.targetName} → ${e.newName}`;
+        }
+        return `${e.op} [${e.targetType}] ${e.targetName}`;
+    })
+        .join(', ');
+    const newRow = `| ${date} | ${changeLink} | ${summary} |`;
+    // Idempotency: if ANY row containing this change's wikilink already
+    // exists in the Change Log section, skip the append. Previously the
+    // check required both date AND change link to match — which meant a
+    // revert on day 1 followed by re-apply on day 2 would insert a
+    // duplicate entry. Matching on the change link alone is safe because
+    // each Change has a unique title/id, and a single apply should
+    // produce at most one log row per Feature.
+    const existingChangeLogMatch = featureContent.match(/^## Change Log\s*$/m);
+    if (existingChangeLogMatch) {
+        const exStart = existingChangeLogMatch.index + existingChangeLogMatch[0].length;
+        const exNextHeading = featureContent.slice(exStart).match(/^## /m);
+        const exEnd = exNextHeading ? exStart + exNextHeading.index : featureContent.length;
+        const exSection = featureContent.slice(exStart, exEnd);
+        // Escape the change link for use in a literal regex test
+        const escapedLink = changeLink.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+        const dupRegex = new RegExp(`${escapedLink}`, 'm');
+        if (dupRegex.test(exSection)) {
+            return featureContent; // Change already logged — skip append.
+        }
+    }
+    let updated;
+    // Check if ## Change Log section exists
+    const changeLogMatch = featureContent.match(/^## Change Log\s*$/m);
+    if (changeLogMatch) {
+        // Extract the Change Log section content (bounded by next ## heading or EOF)
+        const sectionStart = changeLogMatch.index + changeLogMatch[0].length;
+        const nextHeadingMatch = featureContent.slice(sectionStart).match(/^## /m);
+        const sectionEnd = nextHeadingMatch
+            ? sectionStart + nextHeadingMatch.index
+            : featureContent.length;
+        const sectionContent = featureContent.slice(sectionStart, sectionEnd);
+        // Look for table separator ONLY within this section (handle EOF without trailing newline)
+        const sepMatch = sectionContent.match(/(\|[-\s|]+\|)\s*(?:\n|$)/);
+        if (sepMatch) {
+            // Insert after the separator row within the section
+            const sepAbsPos = sectionStart + sepMatch.index + sepMatch[0].length;
+            updated = featureContent.slice(0, sepAbsPos) + newRow + '\n' + featureContent.slice(sepAbsPos);
+        }
+        else {
+            // Section exists but no table — insert table + row after heading
+            const tableBlock = `\n\n| Date | Change | Summary |\n|------|--------|---------|\n${newRow}\n`;
+            updated = featureContent.slice(0, sectionStart) + tableBlock + featureContent.slice(sectionStart);
+        }
+    }
+    else {
+        // No Change Log section — insert before ## Related Notes (or at end)
+        const relatedMatch = featureContent.match(/^## Related Notes\s*$/m);
+        const section = `## Change Log\n\n| Date | Change | Summary |\n|------|--------|---------|\n${newRow}\n\n`;
+        if (relatedMatch) {
+            updated = featureContent.slice(0, relatedMatch.index) + section + featureContent.slice(relatedMatch.index);
+        }
+        else {
+            // Ensure trailing newline before appending
+            const base = featureContent.endsWith('\n') ? featureContent : featureContent + '\n';
+            updated = base + '\n' + section;
+        }
+    }
+    // Trim older entries to keep the table bounded
+    return trimChangeLogSection(updated);
+}
 function makeResult(options, changeRecord, overrides) {
     return {
         changeId: options.changeId,