fix(#4096): honor --dry-run in todo complete and write completion keys inside the frontmatter fence (#4325)

* fix(#4096): honor --dry-run in todo complete and upsert completion keys inside the frontmatter fence

* review(#4096): tighten todo complete flag rejection to any dash-prefixed token

* chore(#4096): backfill PR number in changeset

---------

Co-authored-by: sim <sim@local>

src/commands.cts

@@ -2906,7 +2906,41 @@ function cmdTodoMatchPhase(cwd: string, phase: string | undefined, raw: boolean)
   output({ phase, matches, todo_count: todos.length }, raw, undefined);
 }
 
-function cmdTodoComplete(cwd: string, filename: string | undefined, raw: boolean): void {
+// #4096: upsert completion keys INSIDE the leading frontmatter block. Never a
+// bare prefix line above the opening `---` (that displaces the fence to line 2
+// and breaks every fence-locating reader). A file with no well-formed block
+// (absent, or an unterminated opening fence) gains a complete block.
+function upsertTodoCompletionFields(content: string, today: string): string {
+  const lines = content.split('\n');
+  const fields = [`completed: ${today}`, 'status: completed'];
+
+  const hasOpeningFence = lines[0] !== undefined && lines[0].trim() === '---';
+  const closeIdx = hasOpeningFence ? lines.findIndex((l, i) => i > 0 && l.trim() === '---') : -1;
+
+  if (!hasOpeningFence || closeIdx === -1) {
+    // No parseable frontmatter: wrap the whole content in a complete block
+    // rather than prefixing bare keys (#4096 fix 2).
+    return `---\n${fields.join('\n')}\n---\n\n${content}`;
+  }
+
+  const block = lines.slice(1, closeIdx);
+  for (const field of fields) {
+    const key = `${field.slice(0, field.indexOf(':'))}:`;
+    const idx = block.findIndex(l => l.startsWith(key));
+    if (idx === -1) {
+      block.push(field);
+    } else {
+      block[idx] = field;
+    }
+  }
+  return [...lines.slice(0, 1), ...block, ...lines.slice(closeIdx)].join('\n');
+}
+
+interface TodoCompleteOptions {
+  dryRun?: boolean;
+}
+
+function cmdTodoComplete(cwd: string, filename: string | undefined, options: TodoCompleteOptions, raw: boolean): void {
   if (!filename) {
     error('filename required for todo complete');
   }
@@ -2919,15 +2953,34 @@ function cmdTodoComplete(cwd: string, filename: string | undefined, raw: boolean
     error(`Todo not found: ${filename as string}`);
   }
 
-  // Ensure completed directory exists
+  const content = fs.readFileSync(sourcePath, 'utf-8');
+  const today = realClock.localToday();
+
+  // #4096: --dry-run mirrors `milestone complete --dry-run` (#2118) — every
+  // existence check above still runs, nothing below mutates, and the payload
+  // is preview-shaped (`dry_run`/`would_*`), never `completed: true`.
+  if (options.dryRun) {
+    output({
+      dry_run: true,
+      would_complete: true,
+      file: filename,
+      date: today,
+      would_move: {
+        source: path.relative(cwd, sourcePath).split(path.sep).join('/'),
+        target: path.relative(cwd, path.join(completedDir, filename as string)).split(path.sep).join('/'),
+      },
+      would_set: { completed: today, status: 'completed' },
+    }, raw);
+    return;
+  }
+
+  // Ensure completed directory exists (only on the real run — a dry run
+  // creates nothing).
   platformEnsureDir(completedDir);
 
-  // Read, add completion timestamp, move
-  let content = fs.readFileSync(sourcePath, 'utf-8');
-  const today = realClock.localToday();
-  content = `completed: ${today}\n` + content;
+  const completedContent = upsertTodoCompletionFields(content, today);
 
-  platformWriteSync(path.join(completedDir, filename as string), content);
+  platformWriteSync(path.join(completedDir, filename as string), completedContent);
   fs.unlinkSync(sourcePath);
 
   output({ completed: true, file: filename, date: today }, raw, 'completed');