@natjswenson/devlog 0.9.0 → 0.11.0

package/lib/assemble_post.mjs

@@ -0,0 +1,71 @@
+// Mechanical extraction of a post's fenced code blocks, in order, so the
+// SKILL.md Step 4 assemble-and-run check is a command instead of an honor
+// system: the audit of the first six runs found "copy the blocks into a
+// scratch dir and run them" was skipped whenever it was inconvenient, and two
+// posts shipped claiming "real output" over code that could not run.
+// `text` fences are expected OUTPUT, not code — they're listed but not written
+// as runnable files.
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFrontmatter } from './lint_post.mjs';
+
+// Languages a post realistically fences; anything unknown falls back to .txt
+// so the block is still on disk for the agent to run by hand.
+const LANG_EXT = {
+  javascript: 'js', js: 'js', mjs: 'mjs', typescript: 'ts', ts: 'ts', jsx: 'jsx', tsx: 'tsx',
+  python: 'py', py: 'py',
+  bash: 'sh', sh: 'sh', shell: 'sh', zsh: 'sh',
+  json: 'json', yaml: 'yml', yml: 'yml', toml: 'toml',
+  html: 'html', css: 'css', svg: 'svg', xml: 'xml',
+  sql: 'sql', ruby: 'rb', go: 'go', rust: 'rs', java: 'java', c: 'c', cpp: 'cpp',
+  markdown: 'md', md: 'md', diff: 'diff', ini: 'ini', dockerfile: 'dockerfile', makefile: 'mk',
+};
+
+const OUTPUT_LANGS = new Set(['text', 'txt', 'console', 'output']);
+
+// Ordered fenced blocks of a post body (frontmatter excluded):
+// [{ index, lang, code, runnable }] — `runnable` is false for output-shaped
+// fences (`text` and friends), which readers compare against, not execute.
+export function assemblePost(content) {
+  const { body } = parseFrontmatter(content);
+  const blocks = [];
+  let current = null;
+  for (const line of body.split('\n')) {
+    const m = /^```(.*)$/.exec(line);
+    if (m && !current) {
+      current = { lang: m[1].trim().toLowerCase() || 'txt', lines: [] };
+    } else if (m && current) {
+      const lang = current.lang;
+      blocks.push({
+        index: blocks.length + 1,
+        lang,
+        code: current.lines.join('\n'),
+        runnable: !OUTPUT_LANGS.has(lang),
+      });
+      current = null;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  return blocks;
+}
+
+// Write the runnable blocks to outDir as NN.<ext> and return a manifest of
+// everything (including the skipped output blocks) for the agent to execute
+// in order.
+export function writeAssembledBlocks(content, outDir) {
+  const blocks = assemblePost(content);
+  mkdirSync(outDir, { recursive: true });
+  const written = blocks.map((b) => {
+    if (!b.runnable) return { ...b, file: null };
+    const ext = LANG_EXT[b.lang] || 'txt';
+    const file = join(outDir, `${String(b.index).padStart(2, '0')}.${ext}`);
+    writeFileSync(file, b.code.endsWith('\n') || b.code === '' ? b.code : `${b.code}\n`);
+    return { index: b.index, lang: b.lang, runnable: true, file };
+  });
+  return {
+    blocks: written.map(({ code, ...rest }) => rest),
+    runnableCount: written.filter((b) => b.runnable).length,
+    outputBlockCount: written.filter((b) => !b.runnable).length,
+  };
+}

package/lib/config_ops.mjs

@@ -31,6 +31,7 @@ export function removeProject(config, key) {
 const SETTERS = {
   targetRepo: (c, v) => ({ ...c, targetRepo: v }),
   branch: (c, v) => ({ ...c, branch: v }),
+  targetDir: (c, v) => (v === '' ? omit(c, 'targetDir') : { ...c, targetDir: v }),
   gitAuthor: (c, v) => ({ ...c, gitAuthor: v }),
   githubUser: (c, v) => ({ ...c, githubUser: v }),
   voicePath: (c, v) => (v === '' ? omit(c, 'voicePath') : { ...c, voicePath: expandHome(v) }),

package/lib/core.mjs

@@ -113,6 +113,18 @@ export function validateConfig(config) {
       throw new Error(`branch must be a valid git branch name (no leading dash, no '..'): got ${JSON.stringify(config.branch)}`);
     }
   }
+  if ('targetDir' in config) {
+    // Optional: subdirectory of targetRepo holding the devlog content tree — e.g.
+    // `content/devlog` when the target is a site repo that renders the entries
+    // itself. Relative, slash-separated, no traversal, no leading/trailing slash.
+    // Interpolated into shell commands (the publish clone path) and the gh api
+    // contents path, so the charset is deliberately tight.
+    if (typeof config.targetDir !== 'string'
+      || !/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(config.targetDir)
+      || config.targetDir.split('/').some((s) => s === '.' || s === '..')) {
+      throw new Error(`targetDir must be a relative path like "content/devlog" (no leading/trailing slash, no '..'): got ${JSON.stringify(config.targetDir)}`);
+    }
+  }
   if ('voicePath' in config) {
     // Optional: directory holding the voice profile used to write entries. Read by
     // the skill with the Read tool only — never shell-interpolated — so the only

package/lib/cover_gen.mjs

@@ -77,7 +77,12 @@ export function mergeManifestEntries(cloneDir, config) {
   for (const p of (config.projects || [])) {
     const { entries, status, reason } = readProjectManifest(cloneDir, p.key);
     if (status === 'failed') throw new Error(reason);
-    for (const e of entries) merged.push({ ...e, project: p.key });
+    for (const e of entries) {
+      // Tombstoned rows (removed: true) are editorial retirements, not entries —
+      // they must never surface as backfill candidates or reference covers.
+      if (e && e.removed) continue;
+      merged.push({ ...e, project: p.key });
+    }
   }
   return merged;
 }

package/lib/lint_post.mjs

@@ -110,8 +110,42 @@ export function extractSourceUrls(sectionContent) {
   return urls;
 }
 
+// Voice-contract bans that are safe to check deterministically (the fuller
+// contract — hedge words, staccato rhythm, closers — stays with the judge,
+// where context can tell a false positive from a violation). Phrases are the
+// user's own explicit bans from voice-notes.md.
+export const VOICE_BANNED_PHRASES = [
+  /\bhonestly,/i,
+  /\bI keep seeing\b/i,
+  /isn't a bug, it's/i,
+  /not a bug, a feature/i,
+  /\bthe problem isn't\b/i,
+  /here's what stuck with me/i,
+];
+
+// Sections whose text is template punctuation or verbatim quoted data, exempt
+// from voice rules per SKILL.md (the `## Sources` em dash is fixed template
+// punctuation; `## Changelog` quotes commit subjects as-is).
+const VOICE_EXEMPT_SECTIONS = new Set(['Sources', 'Changelog']);
+
+// Prose lines of the non-exempt sections: fenced code excluded.
+function voiceCheckableLines(sections) {
+  const out = [];
+  for (const s of sections) {
+    if (VOICE_EXEMPT_SECTIONS.has(s.heading)) continue;
+    let inFence = false;
+    for (const line of s.content.split('\n')) {
+      if (/^```/.test(line)) { inFence = !inFence; continue; }
+      if (!inFence) out.push({ heading: s.heading, line });
+    }
+  }
+  return out;
+}
+
 // Lint a post. Returns { ok, findings: [{ rule, message }] }.
-export function lintPost(content, { minSources = 3, filename = null } = {}) {
+// `voice: true` adds the deterministic voice-contract rules — opt-in so the
+// eval harness and non-voice callers keep their existing behavior.
+export function lintPost(content, { minSources = 3, filename = null, voice = false } = {}) {
   const findings = [];
   const add = (rule, message) => findings.push({ rule, message });
 
@@ -194,5 +228,17 @@ export function lintPost(content, { minSources = 3, filename = null } = {}) {
     add('fence-untagged', `Code fence at body line ${line} has no language tag.`);
   }
 
+  if (voice) {
+    for (const { heading, line } of voiceCheckableLines(sections)) {
+      if (line.includes('—')) {
+        add('voice-em-dash', `Em dash in \`## ${heading}\` prose ("${line.trim().slice(0, 60)}…") — the voice contract bans them; use a comma, semicolon, or split the sentence.`);
+      }
+      for (const re of VOICE_BANNED_PHRASES) {
+        const m = re.exec(line);
+        if (m) add('voice-banned-phrase', `Banned phrase "${m[0]}" in \`## ${heading}\` — rewrite per voice-notes.md.`);
+      }
+    }
+  }
+
   return { ok: findings.length === 0, findings };
 }

package/lib/migrate_entry_numbers.mjs

@@ -0,0 +1,116 @@
+// One-time (but idempotent, safely re-runnable) migration that backfills the
+// frozen `no` field onto every pre-existing manifest row that lacks one. Run
+// once against the published corpus after `publishEntry` started emitting
+// `no` for new entries (see publish_entry.mjs) — everything published before
+// that point needs a number assigned retroactively.
+//
+// `no` is a single global sequence across ALL projects (issue numbers of one
+// publication), so this walks every project directory under corpusDir
+// together rather than numbering each project's manifest independently.
+//
+// Tiebreak for entries sharing a date (common in this corpus — multiple
+// projects, and multiple releases of one project, often ship the same day):
+// date ascending, then project name ascending, then filename ascending. Both
+// of those are stable fields already on the row, so the order is
+// deterministic and reproducible from the data alone, with no external
+// input (e.g. "whichever I published first today") required to redo it.
+//
+// Mutates ONLY the `no` field. Never touches `.md` files. Never touches
+// `cover`. Preserves every other field's value and the manifest's existing
+// key order — `no` is inserted immediately before `cover` (matching where
+// publishEntry places it on a fresh row) or appended at the end when the row
+// has no cover, so old and newly-migrated rows end up shaped the same way.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJSON } from './core.mjs';
+
+function compareRows(a, b) {
+  return String(a.date).localeCompare(String(b.date))
+    || a.project.localeCompare(b.project)
+    || String(a.file).localeCompare(String(b.file));
+}
+
+function insertNo(entry, no) {
+  const out = {};
+  let inserted = false;
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === 'cover' && !inserted) {
+      out.no = no;
+      inserted = true;
+    }
+    out[key] = value;
+  }
+  if (!inserted) out.no = no;
+  return out;
+}
+
+// dryRun: compute and return the assignment without writing anything —
+// useful to preview before committing to a run.
+export function migrateEntryNumbers(corpusDir, { dryRun = false } = {}) {
+  if (!existsSync(corpusDir)) throw new Error(`Corpus directory not found: ${corpusDir}`);
+
+  const projects = readdirSync(corpusDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+
+  const manifestsByProject = new Map();
+  let maxNo = 0;
+  const unnumbered = [];
+
+  for (const project of projects) {
+    const manifestPath = join(corpusDir, project, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!manifest || !Array.isArray(manifest.entries)) {
+      throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
+    }
+    manifestsByProject.set(project, manifest);
+
+    manifest.entries.forEach((entry, index) => {
+      if (!entry) return;
+      if (Number.isInteger(entry.no)) {
+        if (entry.no > maxNo) maxNo = entry.no;
+      } else {
+        unnumbered.push({ project, index, date: String(entry.date), file: String(entry.file) });
+      }
+    });
+  }
+
+  unnumbered.sort(compareRows);
+
+  const assigned = [];
+  let next = maxNo + 1;
+  for (const row of unnumbered) {
+    const manifest = manifestsByProject.get(row.project);
+    manifest.entries[row.index] = insertNo(manifest.entries[row.index], next);
+    assigned.push({ project: row.project, file: row.file, date: row.date, no: next });
+    next += 1;
+  }
+
+  const touchedProjects = [...new Set(unnumbered.map((r) => r.project))].sort();
+  if (!dryRun) {
+    for (const project of touchedProjects) {
+      atomicWriteJSON(join(corpusDir, project, 'manifest.json'), manifestsByProject.get(project));
+    }
+  }
+
+  return { assigned, touchedProjects, startingNo: maxNo + 1, endingNo: next - 1 };
+}
+
+// CLI entry point: `node migrate_entry_numbers.mjs <corpusDir> [--dry-run]`
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const corpusDir = process.argv[2];
+  const dryRun = process.argv.includes('--dry-run');
+  if (!corpusDir) {
+    console.error('Usage: node migrate_entry_numbers.mjs <corpusDir> [--dry-run]');
+    process.exit(2);
+  }
+  const result = migrateEntryNumbers(corpusDir, { dryRun });
+  console.log(JSON.stringify(result, null, 2));
+  if (result.assigned.length === 0) {
+    console.error('Nothing to do — every entry already has `no`.');
+  } else {
+    console.error(`${dryRun ? '[dry run] would assign' : 'Assigned'} ${result.assigned.length} numbers (${result.startingNo}..${result.endingNo}).`);
+  }
+}

package/lib/publish_entry.mjs

@@ -2,10 +2,10 @@
 // manifest. This is the code-enforced immutability guard: a cut release's
 // entry is never overwritten, and manifest mutation is no longer done by
 // hand-editing JSON in the agent loop.
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, openSync, readSync, closeSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { RE_PROJECT_KEY, RE_FINAL_RELEASE, atomicWriteJSON } from './core.mjs';
-import { parseFrontmatter } from './lint_post.mjs';
+import { parseFrontmatter, splitSections } from './lint_post.mjs';
 
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
@@ -55,6 +55,118 @@ function sortEntries(entries) {
     String(b.date).localeCompare(String(a.date)) || compareVersionsDesc(a, b));
 }
 
+// Tombstoned rows have no date, so they'd sort arbitrarily among the live
+// feed rows — keep the live entries date-sorted and park tombstones at the end.
+function sortManifestEntries(entries) {
+  const live = entries.filter((e) => !(e && e.removed));
+  const removed = entries.filter((e) => e && e.removed);
+  return [...sortEntries(live), ...removed];
+}
+
+function readManifestIfExists(manifestPath) {
+  if (!existsSync(manifestPath)) return { entries: [] };
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (!manifest || !Array.isArray(manifest.entries)) {
+    throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
+  }
+  return manifest;
+}
+
+// Commit hashes referenced by a post's `## Changelog` section, normalized to
+// their 7-char short form so a short link text matches its full-hash URL.
+// Only hash-shaped tokens in link syntax count — `[abc1234](...)` texts and
+// `/commit/<hash>` URLs — never bare hex words in prose.
+export function extractChangelogHashes(body) {
+  const section = splitSections(body).find((s) => s.heading === 'Changelog');
+  const hashes = new Set();
+  if (!section) return hashes;
+  for (const m of section.content.matchAll(/\[([0-9a-f]{7,40})\]/g)) hashes.add(m[1].slice(0, 7));
+  for (const m of section.content.matchAll(/\/commit\/([0-9a-f]{7,40})\b/g)) hashes.add(m[1].slice(0, 7));
+  return hashes;
+}
+
+// A commit belongs to exactly one post's Changelog (SKILL.md 3b) — in a
+// monorepo, one commit range can feed several projects' releases, and letting
+// both posts list it produced twin entries with identical Changelogs. Walks
+// every live published entry in the clone and throws on the first collision.
+function assertNoChangelogCollision(cloneDir, project, version, draftBody) {
+  const draftHashes = extractChangelogHashes(draftBody);
+  if (draftHashes.size === 0) return;
+
+  let dirents;
+  try {
+    dirents = readdirSync(cloneDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const dirent of dirents) {
+    if (!dirent.isDirectory()) continue;
+    let manifest;
+    try {
+      manifest = readManifestIfExists(join(cloneDir, dirent.name, 'manifest.json'));
+    } catch {
+      continue; // a sibling project's broken manifest must not block this publish
+    }
+    for (const entry of manifest.entries) {
+      if (!entry || entry.removed || !entry.file) continue;
+      if (dirent.name === project && entry.version === version) continue; // self (idempotent republish)
+      const entryPath = join(cloneDir, dirent.name, entry.file);
+      if (!existsSync(entryPath)) continue;
+      let published;
+      try {
+        published = parseFrontmatter(readFileSync(entryPath, 'utf8'));
+      } catch {
+        continue;
+      }
+      for (const hash of extractChangelogHashes(published.body)) {
+        if (draftHashes.has(hash)) {
+          throw new Error(
+            `Commit ${hash} already appears in ${dirent.name}/${entry.file}'s Changelog — ` +
+            `a commit belongs to exactly one post's Changelog (SKILL.md 3b); drop it from this draft's Changelog.`
+          );
+        }
+      }
+    }
+  }
+}
+
+// `no` is a single sequence across ALL projects (issue numbers of one
+// publication, not per-project counters), but manifests are stored one per
+// project — so "next" means "scan every project's manifest under cloneDir and
+// take the highest `no` seen, plus one." Pre-migration rows with no `no` field
+// are simply skipped, not treated as 0; a manifest a sibling agent is mid-write
+// on is skipped rather than thrown on, since a transient parse failure on
+// ANOTHER project must never block publishing to THIS one.
+// NOT safe against two publishEntry calls racing in separate processes at the
+// same instant (read-then-write with no lock) — acceptable for this single-
+// operator CLI; a real lock is not worth the complexity until that changes.
+function nextEntryNumber(cloneDir) {
+  let dirents;
+  try {
+    dirents = readdirSync(cloneDir, { withFileTypes: true });
+  } catch {
+    return 1;
+  }
+
+  let max = 0;
+  for (const dirent of dirents) {
+    if (!dirent.isDirectory()) continue;
+    const manifestPath = join(cloneDir, dirent.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!manifest || !Array.isArray(manifest.entries)) continue;
+    for (const entry of manifest.entries) {
+      if (entry && Number.isInteger(entry.no) && entry.no > max) max = entry.no;
+    }
+  }
+  return max + 1;
+}
+
 export function publishEntry({ cloneDir, project, version, entryPath, coverImageBuffer }) {
   if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
     throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
@@ -67,16 +179,33 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
 
   const projectDir = join(cloneDir, project);
   const destPath = join(projectDir, `${version}.md`);
+  const manifestPath = join(projectDir, 'manifest.json');
+  const manifest = readManifestIfExists(manifestPath);
+
+  // Tombstone refusal comes before the file check: a tombstoned release's .md
+  // is gone by definition, and re-generating it is exactly the failure this
+  // state exists to prevent (an editorially moved/consolidated entry must
+  // never come back on a later run).
+  const tombstoned = manifest.entries.find((e) => e && e.removed && e.version === version);
+  if (tombstoned) {
+    throw new Error(
+      `Entry ${project}/${version} is tombstoned` +
+      (tombstoned.reason ? ` (${tombstoned.reason})` : '') +
+      ' — this release was editorially retired, refusing to republish.'
+    );
+  }
   if (existsSync(destPath)) {
     throw new Error(`Entry ${project}/${version}.md already exists — a cut release is immutable, refusing to overwrite.`);
   }
 
   const content = readFileSync(entryPath, 'utf8');
-  const { data } = parseFrontmatter(content);
+  const { data, body } = parseFrontmatter(content);
   if (!data || !data.title || !data.date || !data.summary) {
     throw new Error('Entry frontmatter must include title, date, and summary (run lint-post first).');
   }
 
+  assertNoChangelogCollision(cloneDir, project, version, body);
+
   mkdirSync(projectDir, { recursive: true });
   copyFileSync(entryPath, destPath);
 
@@ -91,21 +220,18 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
     writeFileSync(join(projectDir, coverFile), coverImageBuffer);
   }
 
-  const manifestPath = join(projectDir, 'manifest.json');
-  let manifest = { entries: [] };
-  if (existsSync(manifestPath)) {
-    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    if (!manifest || !Array.isArray(manifest.entries)) {
-      throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
-    }
-  }
-
   const file = `${version}.md`;
   // Idempotent: legacy manifests may already reference this file/version even
   // when the .md was missing — never duplicate an index row.
   const already = manifest.entries.some((e) => e && (e.file === file || e.version === version));
   let manifestUpdated = false;
+  // Frozen at publish, never recomputed: a backdated entry published later must
+  // never shift a number already baked into a live published social image.
+  // Computed only on the write path — a repeat/idempotent call that hits
+  // `already` above must not burn a number on a publish that's a no-op.
+  let no = null;
   if (!already) {
+    no = nextEntryNumber(cloneDir);
     manifest.entries.push({
       date: String(data.date),
       file,
@@ -113,14 +239,129 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
       summary: String(data.summary),
       version,
       tags: Array.isArray(data.tags) ? data.tags : [],
+      no,
       ...(coverFile ? { cover: { file: coverFile, bytes: coverImageBuffer.length } } : {}),
     });
-    manifest.entries = sortEntries(manifest.entries);
+    manifest.entries = sortManifestEntries(manifest.entries);
     atomicWriteJSON(manifestPath, manifest);
     manifestUpdated = true;
   }
 
-  return { written: destPath, manifestUpdated, coverWritten: !!coverFile };
+  return { written: destPath, manifestUpdated, coverWritten: !!coverFile, no };
+}
+
+// Editorially retire a release: after an entry is manually moved, consolidated,
+// or deleted in the target repo, its (project, version) identity must keep
+// suppressing generation forever — scan reports it as `entry-tombstoned` and
+// publish-entry refuses it. Creates the project manifest if the whole directory
+// was removed (the market-research case). Refuses to tombstone a LIVE entry
+// (its .md still on disk): move or delete the entry first, deliberately, then
+// tombstone the identity it left behind.
+export function tombstoneEntry({ cloneDir, project, version, reason }) {
+  if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
+    throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
+  }
+  if (!RE_FINAL_RELEASE.test(version)) {
+    throw new Error(`Invalid version label (must be v<digits.digits...>): ${JSON.stringify(version)}`);
+  }
+  if (typeof reason !== 'string' || reason.trim() === '' || /[\x00-\x1f]/.test(reason)) {
+    throw new Error('A tombstone requires a non-empty --reason (where did the entry go, and why?).');
+  }
+  if (!existsSync(cloneDir)) throw new Error(`Clone directory not found: ${cloneDir}`);
+
+  const projectDir = join(cloneDir, project);
+  const manifestPath = join(projectDir, 'manifest.json');
+  const manifest = readManifestIfExists(manifestPath);
+
+  const idx = manifest.entries.findIndex((e) => e && e.version === version);
+  if (idx !== -1 && manifest.entries[idx].removed) {
+    return { tombstoned: false, already: true, project, version };
+  }
+
+  const file = `${version}.md`;
+  if (idx !== -1 && existsSync(join(projectDir, manifest.entries[idx].file || file))) {
+    throw new Error(
+      `${project}/${version} is a live published entry — tombstone marks an identity whose ` +
+      'file was editorially moved or deleted; remove/move the entry file first, then tombstone.'
+    );
+  }
+
+  const prior = idx !== -1 ? manifest.entries[idx] : null;
+  const row = {
+    version,
+    file: prior?.file || file,
+    removed: true,
+    reason: reason.trim(),
+    // A dead row that already held a frozen `no` keeps it — numbers are never
+    // reused, and dropping the max would let the next publish re-issue it.
+    ...(prior && Number.isInteger(prior.no) ? { no: prior.no } : {}),
+  };
+  if (idx !== -1) manifest.entries[idx] = row;
+  else manifest.entries.push(row);
+
+  mkdirSync(projectDir, { recursive: true });
+  manifest.entries = sortManifestEntries(manifest.entries);
+  atomicWriteJSON(manifestPath, manifest);
+  return { tombstoned: true, project, version, manifest: manifestPath };
+}
+
+// Post-publish metadata resync: entry prose edits are the user's call, but the
+// manifest's title/summary/date/tags (what the site index, RSS, and covers
+// read) previously had no legitimate way to follow — a hand-edited post left
+// them stale for hours while "rebuilds" chased phantom caches. Reads the
+// PUBLISHED .md in the clone and replaces exactly those four fields on its
+// manifest row. Never touches `no`, `version`, `file`, or `cover`; reports
+// `coverStale` so the caller knows a cover derived from the old title may need
+// regenerating.
+export function syncEntryFromFrontmatter({ cloneDir, project, slug }) {
+  if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
+    throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
+  }
+  assertSafeSlug(slug);
+  if (!existsSync(cloneDir)) throw new Error(`Clone directory not found: ${cloneDir}`);
+
+  const projectDir = join(cloneDir, project);
+  const manifestPath = join(projectDir, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    throw new Error(`No manifest found for project "${project}" at ${manifestPath}`);
+  }
+  const manifest = readManifestIfExists(manifestPath);
+
+  const idx = manifest.entries.findIndex(
+    (e) => e && (e.version === slug || (e.file && e.file.replace(/\.md$/, '') === slug))
+  );
+  if (idx === -1) {
+    throw new Error(`No manifest row for ${project}/${slug} — nothing to sync.`);
+  }
+  const entry = manifest.entries[idx];
+  if (entry.removed) {
+    throw new Error(`${project}/${slug} is tombstoned — there is no entry to sync.`);
+  }
+
+  const entryFilePath = join(projectDir, entry.file);
+  if (!existsSync(entryFilePath)) {
+    throw new Error(`Published entry file not found at ${entryFilePath} — sync reads the clone's .md, not a draft.`);
+  }
+  const { data } = parseFrontmatter(readFileSync(entryFilePath, 'utf8'));
+  if (!data || !data.title || !data.date || !data.summary) {
+    throw new Error('Published entry frontmatter must include title, date, and summary (run lint-post on it first).');
+  }
+
+  const next = {
+    ...entry,
+    date: String(data.date),
+    title: String(data.title),
+    summary: String(data.summary),
+    tags: Array.isArray(data.tags) ? data.tags : [],
+  };
+  const changedFields = ['date', 'title', 'summary', 'tags'].filter(
+    (k) => JSON.stringify(entry[k]) !== JSON.stringify(next[k])
+  );
+  manifest.entries[idx] = next;
+  manifest.entries = sortManifestEntries(manifest.entries);
+  atomicWriteJSON(manifestPath, manifest);
+
+  return { synced: true, project, slug, changedFields, coverStale: !!entry.cover };
 }
 
 // Backfill path only: add a cover to an entry that was already published without one.