@natjswenson/devlog 0.10.0 → 0.11.0

package/SKILL.md

@@ -16,7 +16,7 @@ actual work, backed by cited reputable sources, and including **gotchas earned f
 experience**. The release is the springboard; the teaching is the point.
 
 The deterministic work (release discovery, post linting, manifest updates, config edits)
-is done by the `@natjswenson/devlog` CLI — invoke it as `npx -y @natjswenson/devlog <cmd>`.
+is done by the `@natjswenson/devlog` CLI — invoke it as `npx -y @natjswenson/devlog@latest <cmd>`.
 Every agent-facing command prints JSON.
 
 ## Decide which mode you're in
@@ -38,10 +38,10 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 
 | Intent | Command |
 |---|---|
-| Show config | `npx -y @natjswenson/devlog config --json` |
-| Add a project | `npx -y @natjswenson/devlog add-project --yes --path <abs-path> [--key K] [--remote O/R] [--label L] [--tag-prefix P] [--path-filter F] [--private]` |
-| Remove a project | `npx -y @natjswenson/devlog remove-project <key> --yes` |
-| Change a setting | `npx -y @natjswenson/devlog set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| Show config | `npx -y @natjswenson/devlog@latest config --json` |
+| Add a project | `npx -y @natjswenson/devlog@latest add-project --yes --path <abs-path> [--key K] [--remote O/R] [--label L] [--tag-prefix P] [--path-filter F] [--private]` |
+| Remove a project | `npx -y @natjswenson/devlog@latest remove-project <key> --yes` |
+| Change a setting | `npx -y @natjswenson/devlog@latest set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
 
 `targetDir` is the subdirectory of `targetRepo` that holds the devlog content tree
 (e.g. `content/devlog` when the target is the site repo itself); unset/empty means the
@@ -71,26 +71,32 @@ fix the named field via `set`.
 
 ## Status mode
 
-Run `npx -y @natjswenson/devlog scan --json` and render a compact table: project, new
-releases (version + date + commit count), and skipped tags worth mentioning (reason
-`prerelease`, `empty-range`, etc. — omit `entry-exists` noise unless asked). Note
-`tagFetch: "failed"` ("using local tags only") and `existenceCheck: "failed"` ("couldn't
-confirm which entries exist; publish will still refuse overwrites"). Write nothing.
+Run `npx -y @natjswenson/devlog@latest scan --json --summary` and render a compact table:
+project, new releases (version + date + `commitCount`), and skipped-tag counts worth
+mentioning (`prerelease`, `empty-range`, `entry-tombstoned`, etc. — omit `entry-exists`
+noise unless asked). Note `tagFetch: "failed"` ("using local tags only") and
+`existenceCheck: "failed"` ("couldn't confirm which entries exist; publish will still
+refuse overwrites"). Write nothing.
 
 ## Generate mode
 
 ### Step 1: Scan for new releases
 
 ```bash
-npx -y @natjswenson/devlog scan --json            # all projects
-npx -y @natjswenson/devlog scan --json --project '<key>'   # one project
+npx -y @natjswenson/devlog@latest scan --json --summary            # the plan table
+npx -y @natjswenson/devlog@latest scan --json --project '<key>'    # full detail, one project
 ```
 
-The JSON plan contains everything discovery used to require: per project, the
-`newReleases` array (`tag`, `version`, `date`, `prevTag`, `commits[{hash, subject, date,
-public}]`, `diffstat`) plus `skippedTags` with reasons, and the resolved `deepDive`
-settings (`minSources`, `topicDomains`). Handle the edges:
+Start with `--summary`: per project it gives `newReleases` (`tag`, `version`, `date`,
+`commitCount`), per-reason `skippedTags` counts, `publishedEntries` (every live entry's
+`version`/`title`/`tags` — the topic-dedup input for 3b), and the resolved `deepDive`
+settings (`minSources`, `topicDomains`). When you start writing a project's posts, run
+the full per-project scan for its `commits[{hash, subject, date, public}]` and
+`diffstat`. Handle the edges:
 
+- The output echoes `cliVersion` — the version npx actually ran. npx caches aggressively;
+  if it's older than the version this SKILL.md shipped with, say so and re-run (the
+  `@latest` pin usually prevents this).
 - `error: "unknown-project"` → list `availableKeys` and stop.
 - `totalNewReleases: 0` → tell the user nothing new was tagged (mention notable skipped
   tags) and stop. Do not create empty entries.
@@ -150,14 +156,28 @@ trivia or niche internals. If the obvious topic is repo-specific, step up one le
 the general pattern behind it — the test is "could a reader finish this how-to and have
 something working of their own?" When a release spans two candidate topics (or two
 releases in one run share one), don't write the same guide twice: give each post the
-most usable topic the run hasn't already covered. In a monorepo, one commit can appear
-in several projects' ranges — it belongs to the post whose release story it is; other
-posts leave it out of their narrative and `## Changelog` (check what sibling entries
-already cover, across all projects).
+most usable topic the run hasn't already covered. **The same rule applies against the
+whole catalog**: before settling on a topic, check every project's `publishedEntries`
+(titles + tags, in the scan output) — if an existing entry already teaches this topic,
+find the angle this release genuinely adds, or step to the next-most-usable topic.
+Never publish a near-duplicate of a guide the catalog already has. Vary the surface
+too: don't reuse the catalog's title shapes ("How to …" again and again) or repeat the
+same section-heading skeleton post after post.
+
+In a monorepo, one commit can appear in several projects' ranges — it belongs to the
+post whose release story it is; other posts leave it out of their narrative and
+`## Changelog` (`publish-entry` refuses a draft whose Changelog repeats a commit an
+existing entry already lists). **Never force a second angle the history doesn't
+support**: if the twin release has no story of its own beyond the shared commits, give
+it a proportionally small post — or fold it into the sibling's `## Shipped` — rather
+than inventing a premise to differentiate it.
 
 **3c. Research before writing.** Use web search/fetch to gather at least
 `deepDive.minSources` **distinct** reputable sources: official docs and release notes,
-standards bodies, primary research, well-regarded engineering writing. Avoid SEO farms.
+standards bodies, primary research, well-regarded engineering writing. A content farm
+or SEO-mill page never counts toward `minSources` — when a concept has a primary source
+(the original paper, the official docs, the pattern's canonical text), cite that, not a
+summary site that ranks for the keyword.
 Every specific external claim (a version, a behavior, a study, a definition) must be
 backed by a source you actually verified — if you can't source it, don't claim it. Don't
 lean on one URL for most claims. Keep a working `(claim, url)` list. Fetch tools can
@@ -277,16 +297,28 @@ Write each draft with the **Write tool** (never a bash heredoc) to a temp dir
 (`mktemp -d` once, reuse the absolute path — shell variables don't persist across bash
 calls). Name it `<version>.md`. Then:
 
-1. **Lint:** `npx -y @natjswenson/devlog lint-post '<abs-draft-path>'` — fix every
-   finding (missing sections, thin gotchas, too few distinct sources, sources listed
-   but never cited inline, untagged fences).
-2. **Assemble-and-run check:** when the post's code is runnable without external
-   services, copy its code blocks in order into a scratch dir and execute them exactly
-   as a reader would. Anything undefined, out of order, or missing an entrypoint fails
-   the stranger test mechanically — fix the post, not just the scratch copy.
-3. **Self-review against the how-to contract**, honestly, as a skeptical reader: walk
+1. **Ground-truth gate.** List every claim the draft makes about the user's own repo —
+   a tag exists or doesn't, a count ("seven tests went red"), a timeline, an outcome —
+   and verify each one with a git command run NOW, in this session (`git tag -l`,
+   `git show`, `git log`), the same way 3c keeps a `(claim, url)` list for external
+   claims. A claim you can't verify gets removed, not softened. A specific number is
+   publishable only if it appears in a commit, a diff, or a fetched source — otherwise
+   drop the precision ("several", not "seven"). And never label output as real ("that's
+   the real output", "from my actual run") unless the command that produced it ran in
+   this session — unrun output is always framed as expectation ("you should see…").
+2. **Lint:** `npx -y @natjswenson/devlog@latest lint-post '<abs-draft-path>' --voice` —
+   fix every finding (missing sections, thin gotchas, too few distinct sources, sources
+   listed but never cited inline, untagged fences, voice violations).
+3. **Assemble-and-run check:**
+   `npx -y @natjswenson/devlog@latest assemble-post '<abs-draft-path>' --out '<scratch>/assemble/<version>'`
+   extracts the draft's code blocks in order as numbered files (`text` fences are
+   expected output, listed but not written). When the code is runnable without external
+   services, execute the blocks exactly as a reader would. Anything undefined, out of
+   order, or missing an entrypoint (or an install step the post never shows) fails the
+   stranger test mechanically — fix the post, not just the scratch copy.
+4. **Self-review against the how-to contract**, honestly, as a skeptical reader: walk
    points 1-8 above plus voice adherence. Revise the draft for any point that fails.
-4. At most **two** revision passes; then proceed with the best version and carry any
+5. At most **two** revision passes; then proceed with the best version and carry any
    residual weakness into the final summary (e.g. "v0.5.0: only 2 gotchas had commit
    evidence").
 
@@ -312,57 +344,66 @@ mktemp -d    # → record the absolute path, e.g. /var/folders/.../tmp.abc
 git -C '<abs-tmp>' clone --depth=1 'https://github.com/<targetRepo>.git'
 # <content-root> = '<abs-tmp>/<repo-name>/<targetDir>' if targetDir is set,
 #                  '<abs-tmp>/<repo-name>' otherwise.
+```
 
-# Per release (refuses to overwrite an existing entry — on {"error": ...,
-# "message": "... immutable ..."} skip that release and note it):
-
-# 1. Style guide + up to 3 reference images of recently published covers.
-npx -y @natjswenson/devlog cover-context '<key>' '<version>' \
-  --clone '<content-root>'
-# On {"error": "style-guide-missing", ...}: skip cover composition for this release
-# entirely — proceed straight to publish-entry with no --cover flag. Never block
-# publish on a missing style guide.
-
-# 2. Compose the cover using ONLY this release's title/tags/summary/`## Shipped` text
-#    (never the raw draft file, never `## Changelog`) plus the returned style guide,
-#    icon catalog, and reference images. A cover that just re-renders the title in large text is a failure —
-#    find the one concrete mechanism this release is actually about
-#    (not the project name, not "a bug fix") and draw ONE custom inline-SVG illustration
-#    of it, sized as the dominant visual element of the canvas; title/kicker stay
-#    secondary. Two different releases should never produce visually similar covers.
-#
-#    Draw the illustration inside a `#hero-zone` container at exactly
-#    `x:150 y:425 width:1300 height:400` (render-cover mechanically checks this box and
-#    refuses to render otherwise) — pick ONE of two composition slots per post: single
-#    centered hero (one freehand mechanism, nothing else), or two-node before/after (a
-#    left node, a right node, a connecting line, all freehand). Snap interior key points
-#    to a 25px coordinate grid. Catalog icons (image-style/icons.md) are never placed
-#    inside `#hero-zone` — they may only appear as an optional small accent glyph near
-#    the kicker/title area, entirely outside the hero zone, its bottom edge no lower than
-#    y:400. See the style guide's hero-zone grid contract section before composing.
-#    Write the result with the Write tool to '<abs-scratch>/<key>/<version>.html' — a
-#    full document starting with `<!DOCTYPE html>`, sized
-#    `html, body { margin:0; width:1600px; height:900px; }`, referencing the bundled
-#    font only as `font-family: 'DevlogCoverFont', sans-serif`.
-
-# 3. Rasterize it. On failure (render timeout / Chromium not installed / font missing /
-#    a #hero-zone problem — missing, duplicate, wrong position/size, or a catalog icon
-#    overlapping it),
-#    the .html is left in place for debugging — retry composing once with the error text
-#    fed back, or give up and proceed with no --cover flag.
-npx -y @natjswenson/devlog render-cover '<abs-scratch>/<key>/<version>.html' \
-  --project '<key>' --slug '<version>' --out '<abs-scratch>'
-# Show the rendered <abs-scratch>/<key>/<version>.png in this session before continuing —
-# this interactive review IS the quality gate for the cover, the same way Step 4 is for
-# the prose.
-
-npx -y @natjswenson/devlog publish-entry \
-  --clone '<content-root>' --project '<key>' \
-  --version '<version>' --entry '<abs-draft-path>' \
-  --cover '<abs-scratch>/<key>/<version>.png'
-# Omit --cover entirely if no cover was produced for this release (missing style guide,
-# a render failure not worth a second attempt) — publish still proceeds normally.
+Right after the clone, **Write `<abs-tmp>/run-state.json`**: the clone path, the planned
+releases, and a per-release status you update as each one drafts/lints/publishes. If the
+session is compacted or interrupted mid-run, re-read it instead of re-deriving paths
+from `/var/folders` archaeology.
+
+Per release:
+
+1. **Cover context.**
+   `npx -y @natjswenson/devlog@latest cover-context '<key>' '<version>' --clone '<content-root>'`
+   returns the style guide, icon catalog, and up to 3 reference cover paths. **Read
+   only the single most recent reference image** (image reads are the expensive part;
+   open another only if you're genuinely unsure the new cover is distinct). On
+   `{"error": "style-guide-missing"}`: skip cover composition for this release entirely
+   and proceed straight to publish-entry with no `--cover` flag.
+   Never block publish on a missing style guide.
+2. **Compose** using ONLY this release's title/tags/summary/`## Shipped` text
+   (never the raw draft file, never `## Changelog`) plus the style guide and icon catalog. A
+   cover that just re-renders the title in large text is a failure — find the one
+   concrete mechanism this release is actually about (not the project name, not "a bug
+   fix") and draw ONE custom inline-SVG illustration of it as the dominant visual
+   element; title/kicker stay secondary; two releases should never produce visually
+   similar covers. Follow the style guide's hero-zone grid contract: the illustration
+   lives in a `#hero-zone` container at exactly `x:150 y:425 width:1300 height:400`
+   (render-cover mechanically enforces this), one of two slots (single centered hero,
+   or two-node before/after), interior points snapped to a 25px grid; catalog icons
+   never go inside `#hero-zone` (optional small accent glyph near the kicker only,
+   bottom edge above y:400). Write the document with the Write tool to
+   `'<abs-scratch>/<key>/<version>.html'` — full `<!DOCTYPE html>` document, sized
+   `html, body { margin:0; width:1600px; height:900px; }`, font referenced only as
+   `font-family: 'DevlogCoverFont', sans-serif`.
+3. **Rasterize.**
+   `npx -y @natjswenson/devlog@latest render-cover '<abs-scratch>/<key>/<version>.html' --project '<key>' --slug '<version>' --out '<abs-scratch>'`
+   The HTML is the source of truth and **survives the render**: to fix a visual
+   problem, edit (or re-Write — if an Edit fails, re-Write the whole file) the same
+   .html and re-run render-cover; it re-renders whenever the HTML is present,
+   overwriting the old PNG. On `render-failed` (timeout / Chromium missing / font
+   missing / a `#hero-zone` geometry violation), retry composing once with the error
+   text fed back, or give up and proceed with no `--cover` flag. **Show the rendered
+   `<abs-scratch>/<key>/<version>.png` in this session before continuing —
+   this interactive review IS the quality gate for the cover**, the same way Step 4
+   is for the prose.
+4. **Publish.**
+   ```bash
+   npx -y @natjswenson/devlog@latest publish-entry \
+     --clone '<content-root>' --project '<key>' \
+     --version '<version>' --entry '<abs-draft-path>' \
+     --cover '<abs-scratch>/<key>/<version>.png'
+   ```
+   Omit `--cover` entirely if no cover was produced (missing style guide, a render
+   failure not worth a second attempt) — publish still proceeds normally. publish-entry
+   refuses three things; none is retried by workaround: an existing entry (`immutable`
+   — skip the release, note it), a tombstoned version (`tombstoned` — skip; that
+   identity was editorially retired), and a Changelog commit another entry already
+   lists (drop the commit from this draft's `## Changelog` and re-publish).
+
+Then, once, after all releases:
 
+```bash
 git -C '<abs-tmp>/<repo-name>' add .
 git -C '<abs-tmp>/<repo-name>' commit -m 'devlog: add release entries'
 git -C '<abs-tmp>/<repo-name>' push --no-tags origin '<branch>'
@@ -415,5 +456,17 @@ rules:
   not an error.
 - **Entry already exists** (skipped as `entry-exists`, or `publish-entry` refuses): a cut
   release is immutable; never overwrite, never delete.
+- **`entry-tombstoned`:** the release's entry was editorially retired (moved,
+  consolidated, or deleted on purpose) — skip it silently, never regenerate it.
+- **The user moved/consolidated/deleted a published entry by hand:** tombstone the
+  identity it left behind so no later run resurrects it:
+  `npx -y @natjswenson/devlog@latest tombstone --clone '<content-root>' --project '<key>'
+  --version '<vX.Y.Z>' --reason '<where it went>'` (commit + push like a publish).
+- **The user edited a published entry's prose/frontmatter:** resync its manifest row
+  (title/summary/date/tags — what the site index and RSS read) with
+  `npx -y @natjswenson/devlog@latest sync-entry --clone '<content-root>' --project '<key>'
+  --slug '<version>'`. If the result reports `coverStale: true` and the title/topic
+  changed, offer to recompose the cover (Step 5 flow, `--cover` via publish is not
+  needed — use the backfill commands or recompose+`render-cover`+commit).
 - **Unknown project argument:** list the available keys from the scan error.
 - **Config missing/invalid:** point at `npx @natjswenson/devlog init` / `set` and stop.

package/bin/devlog.js

@@ -2,7 +2,7 @@
 import { spawn, spawnSync, execSync } from 'node:child_process';
 import {
   existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, realpathSync,
-  readdirSync, statSync, unlinkSync, rmSync, mkdtempSync,
+  readdirSync, statSync, rmSync, mkdtempSync,
 } from 'node:fs';
 import { dirname, join, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,9 +32,10 @@ import {
   validateConfig,
   resolveDeepDive,
 } from '../lib/core.mjs';
-import { scanAll } from '../lib/scan.mjs';
+import { scanAll, summarizeScan } from '../lib/scan.mjs';
 import { lintPost, parseFrontmatter, splitSections } from '../lib/lint_post.mjs';
-import { publishEntry, addCoverToExistingEntry } from '../lib/publish_entry.mjs';
+import { publishEntry, addCoverToExistingEntry, tombstoneEntry, syncEntryFromFrontmatter } from '../lib/publish_entry.mjs';
+import { writeAssembledBlocks } from '../lib/assemble_post.mjs';
 import { addProject, removeProject, setField, SETTABLE_FIELDS } from '../lib/config_ops.mjs';
 import { loadStyleGuide, getRecentCovers, mergeManifestEntries } from '../lib/cover_gen.mjs';
 import { renderCoverImage } from '../lib/render_cover.mjs';
@@ -110,6 +111,18 @@ function emitJSON(obj, exitCode = 0) {
   process.exit(exitCode);
 }
 
+// parseArgs is strict by default, so an unknown flag (`render-cover --force`)
+// used to die with a raw ERR_PARSE_ARGS_UNKNOWN_OPTION stack trace instead of
+// the JSON error shape every agent-facing command promises. Same contract as
+// commit-covers' hand-rolled parser: unknown/malformed flags → bad-flag JSON.
+function safeParseArgs(spec) {
+  try {
+    return parseArgs(spec);
+  } catch (e) {
+    emitJSON({ error: 'bad-flag', message: e.message }, 2);
+  }
+}
+
 function readValidConfigOrExit({ json = false } = {}) {
   if (!existsSync(CONFIG_PATH)) {
     if (json) emitJSON({ error: 'config-missing', path: CONFIG_PATH, hint: 'Run `npx @natjswenson/devlog init` first.' }, 1);
@@ -462,7 +475,7 @@ async function cmdInit() {
 
 // ─── add-project ─────────────────────────────────────────────────────────────
 async function cmdAddProject(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: {
       path: { type: 'string' },
@@ -541,7 +554,7 @@ async function cmdAddProject(rest) {
 
 // ─── remove-project ──────────────────────────────────────────────────────────
 async function cmdRemoveProject(rest) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = safeParseArgs({
     args: rest,
     options: { yes: { type: 'boolean', default: false } },
     allowPositionals: true,
@@ -571,7 +584,7 @@ async function cmdRemoveProject(rest) {
 
 // ─── set ─────────────────────────────────────────────────────────────────────
 function cmdSet(rest) {
-  const { positionals } = parseArgs({ args: rest, options: {}, allowPositionals: true });
+  const { positionals } = safeParseArgs({ args: rest, options: {}, allowPositionals: true });
   const [field, value] = positionals;
   const config = readValidConfigOrExit({ json: true });
   if (!field || value === undefined) {
@@ -588,11 +601,14 @@ function cmdSet(rest) {
 
 // ─── scan ────────────────────────────────────────────────────────────────────
 function cmdScan(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: {
       project: { type: 'string' },
       'no-fetch': { type: 'boolean', default: false },
+      // Plan-table view: per release, commitCount instead of the commit list
+      // and diffstat; skippedTags collapsed to per-reason counts.
+      summary: { type: 'boolean', default: false },
       // scan always emits JSON; the flag is accepted so `scan --json` (as
       // SKILL.md spells it) is never a crash.
       json: { type: 'boolean', default: true },
@@ -600,19 +616,29 @@ function cmdScan(rest) {
     allowPositionals: false,
   });
   const config = readValidConfigOrExit({ json: true });
-  const result = scanAll(config, { projectKey: values.project || null, fetch: !values['no-fetch'] });
+  let result = scanAll(config, { projectKey: values.project || null, fetch: !values['no-fetch'] });
+  if (values.summary) result = summarizeScan(result);
+  // Which CLI actually ran: npx caches aggressively, and a stale install has
+  // silently missed shipped fixes before — the skill compares this against the
+  // version its own instructions shipped with.
+  if (!result.error) result.cliVersion = readPackageVersion();
   emitJSON(result, result.error ? 1 : 0);
 }
 
 // ─── lint-post ───────────────────────────────────────────────────────────────
 function cmdLintPost(rest) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = safeParseArgs({
     args: rest,
-    options: { 'min-sources': { type: 'string' } },
+    options: {
+      'min-sources': { type: 'string' },
+      // Deterministic voice-contract rules (em dashes, banned phrases) —
+      // opt-in so non-voice callers and the eval harness keep their behavior.
+      voice: { type: 'boolean', default: false },
+    },
     allowPositionals: true,
   });
   const file = positionals[0];
-  if (!file) emitJSON({ error: 'missing-arg', message: 'Usage: devlog lint-post <file> [--min-sources N]' }, 2);
+  if (!file) emitJSON({ error: 'missing-arg', message: 'Usage: devlog lint-post <file> [--min-sources N] [--voice]' }, 2);
 
   let minSources;
   if (values['min-sources'] !== undefined) {
@@ -633,13 +659,13 @@ function cmdLintPost(rest) {
   } catch (e) {
     emitJSON({ error: 'unreadable', message: e.message }, 2);
   }
-  const result = lintPost(content, { minSources, filename: file });
+  const result = lintPost(content, { minSources, filename: file, voice: values.voice });
   emitJSON({ ...result, minSources }, result.ok ? 0 : 1);
 }
 
 // ─── publish-entry ───────────────────────────────────────────────────────────
 function cmdPublishEntry(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: {
       clone: { type: 'string' },
@@ -677,6 +703,92 @@ function cmdPublishEntry(rest) {
   }
 }
 
+// ─── tombstone ───────────────────────────────────────────────────────────────
+// Editorially retire a (project, version) identity after its entry was moved,
+// consolidated, or deleted by hand — scan then reports `entry-tombstoned` and
+// publish-entry refuses it forever.
+function cmdTombstone(rest) {
+  const { values } = safeParseArgs({
+    args: rest,
+    options: {
+      clone: { type: 'string' },
+      project: { type: 'string' },
+      version: { type: 'string' },
+      reason: { type: 'string' },
+    },
+    allowPositionals: false,
+  });
+  for (const flag of ['clone', 'project', 'version', 'reason']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `tombstone requires --${flag}` }, 1);
+  }
+  try {
+    const result = tombstoneEntry({
+      cloneDir: expandHome(values.clone),
+      project: values.project,
+      version: values.version,
+      reason: values.reason,
+    });
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: 'tombstone-failed', message: e.message }, 1);
+  }
+}
+
+// ─── sync-entry ──────────────────────────────────────────────────────────────
+// Resync a published entry's manifest row (title/summary/date/tags) from its
+// .md frontmatter after a deliberate post-publish edit.
+function cmdSyncEntry(rest) {
+  const { values } = safeParseArgs({
+    args: rest,
+    options: {
+      clone: { type: 'string' },
+      project: { type: 'string' },
+      slug: { type: 'string' },
+    },
+    allowPositionals: false,
+  });
+  for (const flag of ['clone', 'project', 'slug']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `sync-entry requires --${flag}` }, 1);
+  }
+  try {
+    const result = syncEntryFromFrontmatter({
+      cloneDir: expandHome(values.clone),
+      project: values.project,
+      slug: values.slug,
+    });
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: 'sync-failed', message: e.message }, 1);
+  }
+}
+
+// ─── assemble-post ───────────────────────────────────────────────────────────
+// Extract a draft's fenced code blocks, in order, into numbered files so the
+// Step 4 assemble-and-run check is mechanical instead of hand-copied.
+function cmdAssemblePost(rest) {
+  const { values, positionals } = safeParseArgs({
+    args: rest,
+    options: { out: { type: 'string' } },
+    allowPositionals: true,
+  });
+  const file = positionals[0];
+  if (!file) emitJSON({ error: 'missing-arg', message: 'Usage: devlog assemble-post <draft> --out <dir>' }, 2);
+  if (!values.out) emitJSON({ error: 'missing-flag', message: 'assemble-post requires --out' }, 1);
+
+  let content;
+  try {
+    content = readFileSync(expandHome(file), 'utf8');
+  } catch (e) {
+    emitJSON({ error: 'unreadable', message: e.message }, 2);
+  }
+  try {
+    const result = writeAssembledBlocks(content, expandHome(values.out));
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: 'assemble-failed', message: e.message }, 1);
+  }
+}
+
 // ─── backfill-covers list ─────────────────────────────────────────────────────
 function cmdBackfillCovers(rest) {
   const sub = rest[0];
@@ -684,7 +796,7 @@ function cmdBackfillCovers(rest) {
     emitJSON({ error: 'unknown-subcommand', message: 'Usage: devlog backfill-covers list --clone <cloneDir> [--project <key>] [--out <staging-dir>] [--all]' }, 2);
     return;
   }
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest.slice(1),
     options: {
       clone: { type: 'string' },
@@ -761,7 +873,7 @@ function cmdBackfillCovers(rest) {
 
 // ─── cover-context ─────────────────────────────────────────────────────────────
 function cmdCoverContext(rest) {
-  const { positionals, values } = parseArgs({
+  const { positionals, values } = safeParseArgs({
     args: rest,
     options: {
       clone: { type: 'string' },
@@ -826,7 +938,7 @@ function regenerateContactSheet(outDir) {
 }
 
 async function cmdRenderCover(rest) {
-  const { positionals, values } = parseArgs({
+  const { positionals, values } = safeParseArgs({
     args: rest,
     options: {
       project: { type: 'string' },
@@ -852,17 +964,21 @@ async function cmdRenderCover(rest) {
   mkdirSync(projectDir, { recursive: true });
   const pngPath = join(projectDir, `${values.slug}.png`);
 
-  // Idempotent re-run: an existing, valid PNG is left untouched — no re-render.
-  if (existsSync(pngPath) && isValidPngFile(pngPath)) {
-    regenerateContactSheet(outDir);
-    emitJSON({ ok: true, written: pngPath, rendered: false });
-    return;
-  }
-
+  // The HTML file is the source of truth: whenever it's present, render it —
+  // overwriting any stale PNG from a previous attempt. (The old
+  // PNG-exists short-circuit silently ignored freshly edited HTML, which cost
+  // every real retry loop an ls/mtime/md5 debugging dance and a guessed-at
+  // `--force` flag that didn't exist.) Only when the HTML is gone does an
+  // existing valid PNG mean "already rendered, nothing to do".
   let html;
   try {
     html = readFileSync(expandHome(htmlFile), 'utf8');
   } catch (e) {
+    if (existsSync(pngPath) && isValidPngFile(pngPath)) {
+      regenerateContactSheet(outDir);
+      emitJSON({ ok: true, written: pngPath, rendered: false });
+      return;
+    }
     emitJSON({ error: 'html-unreadable', message: e.message }, 1);
     return;
   }
@@ -878,9 +994,10 @@ async function cmdRenderCover(rest) {
   }
   writeFileSync(pngPath, png);
 
-  // Transient source document — deleted immediately after a successful render only.
-  try { unlinkSync(expandHome(htmlFile)); } catch { /* best-effort cleanup */ }
-
+  // The HTML source deliberately stays on disk (it lives in the run's scratch
+  // dir and dies with it): keeping it is what makes "tweak the HTML, re-run
+  // render-cover" work at all — deleting it on success broke every
+  // post-render Edit attempt in real runs.
   regenerateContactSheet(outDir);
   emitJSON({ ok: true, written: pngPath, rendered: true });
 }
@@ -1018,7 +1135,7 @@ async function cmdCommitCovers(rest) {
 
 // ─── config (view) ───────────────────────────────────────────────────────────
 async function cmdConfig(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: { json: { type: 'boolean', default: false } },
     allowPositionals: false,
@@ -1137,12 +1254,17 @@ Setup & config:
   ${kleur.cyan('npx @natjswenson/devlog config [--json]')}          Show current config (with validation)
 
 Used by the /devlog skill:
-  ${kleur.cyan('npx @natjswenson/devlog scan [--project <key>]')}   JSON plan of new releases needing entries
-  ${kleur.cyan('npx @natjswenson/devlog lint-post <file>')}         Deterministic post-contract check
+  ${kleur.cyan('npx @natjswenson/devlog scan [--project <key>] [--summary]')}   JSON plan of new releases needing entries
+  ${kleur.cyan('npx @natjswenson/devlog lint-post <file> [--voice]')}  Deterministic post-contract check (+ voice rules)
+  ${kleur.cyan('npx @natjswenson/devlog assemble-post <draft> --out <dir>')}  Extract the draft's code blocks for the run-it check
   ${kleur.cyan('npx @natjswenson/devlog publish-entry ...')}        Copy a drafted entry into the clone + update manifest (never overwrites)
   ${kleur.cyan('npx @natjswenson/devlog cover-context <project> <slug> --clone <dir>')}  Style guide + reference-image paths for cover composition
   ${kleur.cyan('npx @natjswenson/devlog render-cover <html> --project <key> --slug <s> --out <dir>')}  Rasterize a composed cover to PNG
 
+Editorial maintenance:
+  ${kleur.cyan('npx @natjswenson/devlog tombstone --clone <dir> --project <key> --version <v> --reason <why>')}  Retire a moved/consolidated entry's identity
+  ${kleur.cyan('npx @natjswenson/devlog sync-entry --clone <dir> --project <key> --slug <v>')}  Resync a manifest row from an edited entry's frontmatter
+
 Backfilling covers onto existing posts:
   ${kleur.cyan('npx @natjswenson/devlog backfill-covers list --clone <dir> [--out <staging-dir>]')}  List posts missing a cover
   ${kleur.cyan('npx @natjswenson/devlog commit-covers <staging-dir> [--force [slug]]')}  Publish staged covers to already-published entries
@@ -1196,6 +1318,15 @@ if (isMain) {
     case 'publish-entry':
       cmdPublishEntry(rest);
       break;
+    case 'tombstone':
+      cmdTombstone(rest);
+      break;
+    case 'sync-entry':
+      cmdSyncEntry(rest);
+      break;
+    case 'assemble-post':
+      cmdAssemblePost(rest);
+      break;
     case 'backfill-covers':
       cmdBackfillCovers(rest);
       break;

package/examples/react/useDevLogEntries.js

@@ -34,6 +34,8 @@ function validateManifest(data) {
   const entries = [];
   for (const e of data.entries) {
     if (!e || typeof e !== 'object') continue;
+    // Tombstoned rows (removed: true) are editorial retirements, not entries.
+    if (e.removed) continue;
     const { date, file, title, summary, version } = e;
     if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
     if (typeof file !== 'string' || !/^[a-zA-Z0-9._-]+\.md$/.test(file)) continue;

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/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/publish_entry.mjs

@@ -5,7 +5,7 @@
 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,81 @@ 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
@@ -104,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);
 
@@ -128,15 +220,6 @@ 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.
@@ -159,7 +242,7 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
       no,
       ...(coverFile ? { cover: { file: coverFile, bytes: coverImageBuffer.length } } : {}),
     });
-    manifest.entries = sortEntries(manifest.entries);
+    manifest.entries = sortManifestEntries(manifest.entries);
     atomicWriteJSON(manifestPath, manifest);
     manifestUpdated = true;
   }
@@ -167,6 +250,120 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
   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.
 // Never writes/reads <slug>.md, never pushes a new manifest row — its only mutation is the
 // `cover` field of an already-existing entry, keyed by that entry's version/file stem.

package/lib/scan.mjs

@@ -66,10 +66,11 @@ function git(projectPath, args) {
   return execArgs('git', ['-C', projectPath, ...args]);
 }
 
-// Scan one project's local clone. Pure git — the caller supplies the set of
-// entry filenames that already exist in the target repo (existingFiles), so
-// this function stays testable against throwaway fixture repos.
-export function scanProject(project, { branch = 'main', fetch = true, existingFiles = new Set() } = {}) {
+// Scan one project's local clone. Pure git — the caller supplies what already
+// exists in the target repo (`existing`: entry filenames, live manifest
+// versions, and tombstoned versions), so this function stays testable against
+// throwaway fixture repos.
+export function scanProject(project, { branch = 'main', fetch = true, existing = emptyExisting() } = {}) {
   const out = {
     key: project.key,
     label: project.label || project.key,
@@ -119,7 +120,14 @@ export function scanProject(project, { branch = 'main', fetch = true, existingFi
 
   for (let i = 0; i < releases.length; i++) {
     const { tag, version } = releases[i];
-    if (existingFiles.has(`${version}.md`)) {
+    // Tombstone check comes first: a tombstoned row also carries a `file`
+    // field, so the entry-exists check below would otherwise mask the more
+    // specific reason.
+    if (existing.removedVersions.has(version)) {
+      out.skippedTags.push({ tag, reason: 'entry-tombstoned' });
+      continue;
+    }
+    if (existing.versions.has(version) || existing.files.has(`${version}.md`)) {
       out.skippedTags.push({ tag, reason: 'entry-exists' });
       continue;
     }
@@ -185,22 +193,65 @@ function splitLogLine(line) {
   return [hash, subject, date];
 }
 
-// Which entry files already exist in the target repo for one project — a
-// single `gh api` directory listing (vs. the old one-probe-per-tag pattern).
-// Returns { files: Set, status: 'ok' | 'empty' | 'failed' }: a 404 means the
-// project has no entries yet; any other failure is surfaced so the caller
-// knows the entry-exists filter may be incomplete (publish-entry still refuses
-// overwrites against the fresh clone, so a stale scan cannot clobber anything).
+export function emptyExisting() {
+  return { files: new Set(), versions: new Set(), removedVersions: new Set(), entries: [] };
+}
+
+// What already exists in the target repo for one project. Entry identity is
+// project+version in the MANIFEST, not a filename: manifest rows survive
+// editorial file moves/consolidations, and a tombstoned row (`removed: true`)
+// keeps suppressing generation even after its .md is gone — the failure class
+// that re-armed three deleted entries in the first six runs. Fetches the
+// project's manifest.json (one `gh api` call); falls back to a directory
+// listing for legacy dirs with entries but no manifest yet.
+// Returns { files: Set, versions: Set, removedVersions: Set,
+//           entries: [{version, title, tags}] (live rows only),
+//           status: 'ok' | 'empty' | 'failed' }: 'empty' means the project has
+// no entries yet; 'failed' is surfaced so the caller knows the entry-exists
+// filter may be incomplete (publish-entry still refuses overwrites against the
+// fresh clone, so a stale scan cannot clobber anything).
 export function fetchExistingEntries(targetRepo, branch, projectKey, targetDir = '') {
   const contentPath = targetDir ? `${targetDir}/${projectKey}` : projectKey;
+  const m = spawnArgs('gh', ['api', `repos/${targetRepo}/contents/${contentPath}/manifest.json?ref=${branch}`, '--jq', '.content']);
+  if (m.status === 0) {
+    let manifest = null;
+    try {
+      manifest = JSON.parse(Buffer.from(m.stdout.replace(/\s/g, ''), 'base64').toString('utf8'));
+    } catch {
+      // Malformed manifest content — fall through to the directory listing.
+    }
+    if (manifest && Array.isArray(manifest.entries)) {
+      const out = { ...emptyExisting(), status: 'ok' };
+      for (const e of manifest.entries) {
+        if (!e) continue;
+        if (typeof e.file === 'string') out.files.add(e.file);
+        if (typeof e.version !== 'string' || e.version === '') continue;
+        if (e.removed) {
+          out.removedVersions.add(e.version);
+        } else {
+          out.versions.add(e.version);
+          out.entries.push({
+            version: e.version,
+            title: typeof e.title === 'string' ? e.title : null,
+            tags: Array.isArray(e.tags) ? e.tags : [],
+          });
+        }
+      }
+      return out;
+    }
+  } else if (!/HTTP 404|Not Found/i.test(m.stderr)) {
+    return { ...emptyExisting(), status: 'failed' };
+  }
+
+  // No manifest (or unparseable): legacy directory listing.
   const r = spawnArgs('gh', ['api', `repos/${targetRepo}/contents/${contentPath}?ref=${branch}`, '--jq', '.[].name']);
   if (r.status === 0) {
-    return { files: new Set(r.stdout.split('\n').filter(Boolean)), status: 'ok' };
+    return { ...emptyExisting(), files: new Set(r.stdout.split('\n').filter(Boolean)), status: 'ok' };
   }
   if (/HTTP 404|Not Found/i.test(r.stderr)) {
-    return { files: new Set(), status: 'empty' };
+    return { ...emptyExisting(), status: 'empty' };
   }
-  return { files: new Set(), status: 'failed' };
+  return { ...emptyExisting(), status: 'failed' };
 }
 
 // Full scan across the configured projects. `getExisting` is injectable for
@@ -219,9 +270,15 @@ export function scanAll(config, { projectKey = null, fetch = true, getExisting =
   }
 
   const results = projects.map((project) => {
-    const existing = getExisting(config.targetRepo, branch, project.key, config.targetDir || '');
-    const scanned = scanProject(project, { branch, fetch, existingFiles: existing.files });
+    // Normalized so an injected getExisting returning a partial shape (e.g. a
+    // legacy { files, status } double) can't crash the tombstone checks.
+    const existing = { ...emptyExisting(), status: 'ok', ...getExisting(config.targetRepo, branch, project.key, config.targetDir || '') };
+    const scanned = scanProject(project, { branch, fetch, existing });
     scanned.existenceCheck = existing.status;
+    // Live catalog rows for this project — the skill's topic-dedup input
+    // ("don't re-teach a guide the catalog already covers"), free with the
+    // manifest fetch above.
+    scanned.publishedEntries = existing.entries;
     return scanned;
   });
 
@@ -237,3 +294,25 @@ export function scanAll(config, { projectKey = null, fetch = true, getExisting =
     totalNewReleases: results.reduce((n, p) => n + p.newReleases.length, 0),
   };
 }
+
+// Compact plan-table view of a scanAll result: per release, drop the commit
+// list and diffstat (the bulky parts) for a commitCount; collapse skippedTags
+// to per-reason counts. publishedEntries stays — it's small and the skill's
+// topic-dedup input. Full detail remains one `scan --project <key>` away.
+export function summarizeScan(result) {
+  if (result.error) return result;
+  return {
+    ...result,
+    projects: result.projects.map((p) => ({
+      ...p,
+      newReleases: p.newReleases.map(({ commits, diffstat, ...release }) => ({
+        ...release,
+        commitCount: commits.length,
+      })),
+      skippedTags: p.skippedTags.reduce((acc, { reason }) => {
+        acc[reason] = (acc[reason] || 0) + 1;
+        return acc;
+      }, {}),
+    })),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Release dev log generator \u2014 Claude Code skill + preview app for publishing version-release dev logs, written in your voice, to your site",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json

@@ -81,6 +81,26 @@
       "pattern": "this interactive review IS the quality gate for the cover",
       "rationale": "The rendered cover must be shown to the user before push, the same way Step 4 gates the prose — losing this line reopens publishing an unreviewed cover."
     },
+    {
+      "id": "ground-truth-gate",
+      "pattern": "verify each one with a git command run NOW",
+      "rationale": "The 6-run audit found a post that published a provably false premise about the author's own repo (resume/v1.0.1: 'two of four packages never got tags' — all four existed). Every repo-fact claim must be re-verified against git in-session before publish; losing this line reopens the fabricated-premise path."
+    },
+    {
+      "id": "no-unrun-output",
+      "pattern": "never label output as real[\\s\\S]{0,120}unless the command that produced it ran in\\s+this session",
+      "rationale": "Two audited posts claimed 'real output' over commands that never ran (v0.6.0's phantom fixtures, v0.10.0's internally-impossible scan table). Output honesty must be a hard rule, not a stylistic preference."
+    },
+    {
+      "id": "tombstone-never-republish",
+      "pattern": "editorially retired[\\s\\S]{0,80}skip it silently, never regenerate",
+      "rationale": "Deleted/moved entries re-armed generation three times in the first six runs (ghostwriter v0.8.1 twice, market-research v0.1.0). The tombstoned state must always mean 'never regenerate'."
+    },
+    {
+      "id": "one-commit-one-changelog",
+      "pattern": "refuses a draft whose Changelog repeats a commit",
+      "rationale": "Monorepo twin releases shipped identical Changelogs (resume v1.0.1 + ghostwriter v0.8.1); a commit belongs to exactly one post's Changelog and publish-entry enforces it."
+    },
     {
       "id": "cover-custom-illustration",
       "pattern": "cover that just re-renders the title in large text is a failure",
@@ -95,5 +115,5 @@
       "rationale": "The catalog-icon/hero-zone overlap check must stay wired into renderCoverImage() — losing it silently reopens the gap where a catalog icon (or two, connected by a line) can stand in for the required bespoke hero illustration."
     }
   ],
-  "cli_commands_referenced": ["scan", "lint-post", "publish-entry", "add-project", "remove-project", "set", "config", "init", "cover-context", "render-cover"]
+  "cli_commands_referenced": ["scan", "lint-post", "publish-entry", "add-project", "remove-project", "set", "config", "init", "cover-context", "render-cover", "tombstone", "sync-entry", "assemble-post"]
 }