quiver-cli 1.3.0 → 1.3.1

package/template/.agents/skills/design/impeccable/scripts/context.mjs

@@ -27,6 +27,7 @@
  * shape rather than the markdown block.
  */
 import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -1012,14 +1013,43 @@ async function fetchLatestSkillVersion() {
   }
 }
 
+// Destroy fetch's global undici dispatcher before process.exit(): a live
+// keep-alive socket trips a libuv assertion on Windows/Node 24 after a
+// successful boot (nodejs/node#56645, issue #573).
+async function destroyFetchDispatcher() {
+  const dispatcher = globalThis[Symbol.for('undici.globalDispatcher.1')];
+  if (dispatcher && typeof dispatcher.destroy === 'function') {
+    try { await dispatcher.destroy(); } catch { /* exit regardless */ }
+  }
+}
+
+// Drain the boot payload before process.exit(): a live pipe that has not
+// flushed yet is truncated when Node tears down (issue #573 review). Then
+// close fetch so Windows teardown does not abort on the keep-alive socket.
+async function finishCli(output) {
+  await new Promise((resolve) => {
+    process.stdout.write(output, () => resolve());
+  });
+  await destroyFetchDispatcher();
+  process.exit(0);
+}
+
+// Two instructions used to sit in one directive: ask, and "if they agree, run
+// it". Nothing gated the second on an answer, and the same sentence said to
+// continue without waiting, so a run that could never establish agreement was
+// still spelled out as the next command. The offer stays; the command leaves
+// this turn entirely, because installing over the skill mid-session changes
+// files the session is reading and only takes effect in the next one anyway.
 function buildUpdateDirective(localVersion, latestVersion) {
   return (
     `UPDATE_AVAILABLE: A newer Impeccable skill is available ` +
     `(installed v${localVersion}, latest v${latestVersion}). ` +
-    `Before continuing, ask the user once: "A newer Impeccable (v${latestVersion}) is available. ` +
+    `Mention it once, in this form: "A newer Impeccable (v${latestVersion}) is available. ` +
     `Update now? It runs \`npx impeccable update\`." ` +
-    `If they agree, run \`npx impeccable update\` (the update applies to the next session, not this one). ` +
-    `Either way, continue the current task without waiting, and do not raise this again.`
+    `Do not run \`npx impeccable update\` in this turn, whatever the user answers: it rewrites the skill files ` +
+    `this session is reading, and the update only takes effect in the next session, so there is nothing to gain now. ` +
+    `Run it in a later turn, only after the user has asked for it in their own words. ` +
+    `Continue the current task now without waiting, and do not raise this again.`
   );
 }
 
@@ -1141,15 +1171,17 @@ async function cli() {
     parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
+    appendBuildPathDirective(parts, ctx);
+    await appendCompRoundOpenDirective(parts, ctx);
     appendAutonomyCounterDirective(parts);
     appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
+    appendImageToolsDirective(parts);
     appendStalenessDirective(parts, ctx, cliOptions);
     if (updateDirective) parts.push(updateDirective);
-    process.stdout.write(parts.join('\n\n---\n\n') + '\n');
-    process.exit(0);
+    await finishCli(parts.join('\n\n---\n\n') + '\n');
   }
   const parts = [`# PRODUCT.md\n\n${ctx.product.trim()}`];
   if (ctx.hasDesign) {
@@ -1159,6 +1191,8 @@ async function cli() {
   parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
+  appendBuildPathDirective(parts, ctx);
+  await appendCompRoundOpenDirective(parts, ctx);
   appendAutonomyCounterDirective(parts);
   appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
@@ -1180,6 +1214,7 @@ async function cli() {
       `# NATIVE PLATFORM REFERENCE: ${reference.name.toUpperCase()} (reference/${reference.name}.md)\n\n${reference.content.trim()}`,
     );
   }
+  appendImageToolsDirective(parts);
   appendStalenessDirective(parts, ctx, cliOptions);
   if (!ctx.platform) {
     // A `## Platform` section that names something we don't recognize (a
@@ -1193,7 +1228,7 @@ async function cli() {
     }
   }
   if (updateDirective) parts.push(updateDirective);
-  process.stdout.write(parts.join('\n\n---\n\n') + '\n');
+  await finishCli(parts.join('\n\n---\n\n') + '\n');
 }
 
 function parseCliOptions(args) {
@@ -1266,6 +1301,72 @@ function automaticHookMode(ctx) {
 }
 
 
+// Build-path preference: a workflow setting (comp-led vs code-led), read here
+// so every session starts knowing it without a file hunt. It rides the unified
+// config beside the hook and detector settings, and the gitignored local file
+// wins, because whether a machine has an image tool is a property of that
+// machine, not of the team's committed default. Absence stays silent;
+// new-work's own default applies, and the decision page toggle can flip the
+// value for a single session.
+function readBuildPathAt(root) {
+  let value = null;
+  let source = null;
+  for (const name of ['config.json', 'config.local.json']) {
+    const raw = readJson(path.join(root, '.impeccable', name));
+    if (raw?.buildPath === 'comp' || raw?.buildPath === 'code') {
+      value = raw.buildPath;
+      source = `.impeccable/${name}`;
+    }
+  }
+  return value ? { value, source } : null;
+}
+
+// Roots in precedence order, nearest first: the resolved project decides, and
+// the repo root is the fallback a monorepo commits once for every app in it.
+// `checkBuildPathUnset` reads exactly these two, and the pair has to match:
+// when they disagree the finding goes silent because a value exists while the
+// directive never names it, which is the one combination nobody can debug.
+//
+// The invoking directory is deliberately not in the chain. With `--target`
+// selecting another workspace, cwd is the caller's app, not the target's, and
+// letting it rank above the repo root hands one workspace another's workflow.
+// It stands in only when no project resolved at all.
+// A direction was dealt for a comp-led build and the phase machine never
+// started, or stopped short of the hero gate: the comp round is open. Said
+// here because every model in the corpus ran context.mjs unprompted, and
+// the run that skipped the round did so between the roll and the first
+// write; a boot that names the open round is a boot the write cannot claim
+// it never saw. Reads build-phase's own helper so the two agree.
+async function appendCompRoundOpenDirective(parts, ctx) {
+  try {
+    const { compRoundOpen } = await import('./build-phase.mjs');
+    const roots = [...new Set([ctx?.projectRoot || process.cwd(), ctx?.repoRoot].filter(Boolean).map((r) => path.resolve(r)))];
+    for (const root of roots) {
+      const open = compRoundOpen(root);
+      if (!open) continue;
+      parts.push(`COMP_ROUND_OPEN: ${open.reason}. On a comp-led build no page code is written before build-phase.mjs closes the comps, spec, plates, and hero gates; run \`node ${path.dirname(fileURLToPath(import.meta.url))}/build-phase.mjs status\` and follow its NEXT line. A page written past an open round is what the finish reviewer sends back.`);
+      return;
+    }
+  } catch { /* build-phase absent: nothing to say */ }
+}
+
+function appendBuildPathDirective(parts, ctx) {
+  const roots = [...new Set(
+    [ctx?.projectRoot || process.cwd(), ctx?.repoRoot].filter(Boolean).map((root) => path.resolve(root)),
+  )];
+  for (const root of roots) {
+    const found = readBuildPathAt(root);
+    if (!found) continue;
+    // "Never written back" is scoped by the fact that this directive exists at
+    // all: it is emitted only where a value is already recorded, which is the
+    // case where a flip really is session-only. Saying so inline because the
+    // bare absolute reads as a rule that overrides new-work's one-time offer,
+    // which is exactly how the same wording misfired in serve-question.
+    parts.push(`BUILD_PATH_DEFAULT: ${found.value} (from ${found.source}). Author direction and surface rounds with this as buildPath.value and toggle: true; a flip on the page binds that session only and is never written back, because a default is already recorded here. New-work's one-time offer to record a flipped value applies only where no default exists, which is why you are not seeing this line on those projects.`);
+    return;
+  }
+}
+
 // Image generation availability: harness-native tools always win, but when the
 // environment carries an OpenAI key the API fallback works everywhere. The
 // flag only reports capability, positively: absence stays silent, because a
@@ -1275,9 +1376,10 @@ function appendImageGenDirective(parts) {
   if (!process.env.OPENAI_API_KEY) return;
   const scriptsPath = path.dirname(fileURLToPath(import.meta.url));
   parts.push([
-    'IMAGE_GEN_AVAILABLE: An OpenAI key is present, so image generation works even without a harness-native image tool:',
-    `\`node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file>\` (gpt-image-2, billed to the user's key; say so before the first render).`,
-    'Prefer the harness-native image tool when one exists. Visualizing a direction before building it measurably strengthens the result.',
+    'IMAGE_GEN_AVAILABLE: your harness-native image tool is always the first choice for generation; use it whenever one exists.',
+    'This environment also carries an OpenAI key as the fallback for harnesses with no native tool:',
+    `\`node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file>\` (gpt-image-2, billed to the user's key; say so before the first render, and never reach for it when a native tool exists).`,
+    'Visualizing a direction before building it measurably strengthens the result.',
   ].join(' '));
 }
 
@@ -1332,6 +1434,19 @@ function appendDetectorFallback(parts, ctx) {
 // markdown already in memory, a bounded set of stats, or one of the small JSON
 // files the boot reads regardless. The deep pass (git drift, token divergence,
 // cross-workspace sweep) belongs to the doctor command, not to every session.
+// One boot-time probe replaces every session re-deriving its image toolchain:
+// harnesses and OSes differ (cwebp, sips on macOS, magick, ffmpeg), and the
+// agent should read this line instead of running command -v per image.
+function appendImageToolsDirective(parts) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const found = ['cwebp', 'sips', 'magick', 'ffmpeg'].filter((tool) => {
+    try { return spawnSync(probe, [tool], { stdio: 'ignore' }).status === 0; } catch { return false; }
+  });
+  parts.push(found.length
+    ? `IMAGE_TOOLS: available image converters on this machine: ${found.join(', ')}. Use the first suitable one; never probe again this session.`
+    : 'IMAGE_TOOLS: no image converter found (cwebp, sips, magick, ffmpeg). Ship PNG output unconverted rather than probing per image.');
+}
+
 function appendStalenessDirective(parts, ctx, options) {
   const projectRoot = ctx.projectRoot || process.cwd();
   if (stalenessCheckDisabled([projectRoot, ctx.repoRoot])) return;

package/template/.agents/skills/design/impeccable/scripts/critique-storage.mjs

@@ -16,8 +16,9 @@
  * CLI entry points (called from skill instructions):
  *   node critique-storage.mjs slug <resolved-target>
  *   node critique-storage.mjs write <slug> <snapshot-body-file>
- *   node critique-storage.mjs latest <slug>
+ *   node critique-storage.mjs latest <slug> [--json]
  *   node critique-storage.mjs trend <slug> [limit]
+ *   node critique-storage.mjs close <resolved-target> <snapshot-file>
  *
  * Note: there is intentionally no `ignore` subcommand. ignore.md is a plain
  * markdown file; the model reads it directly with its file-read tool. This
@@ -27,6 +28,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 import { slugFromTarget } from './lib/target-slug.mjs';
@@ -50,6 +52,45 @@ export function nowFilenameStamp(date = new Date()) {
   return iso.replace(/[:.]/g, '-').replace(/-\d+Z$/, 'Z');
 }
 
+/**
+ * Return an exact content fingerprint for a local file target. URLs and
+ * non-files return null because their content is not available here.
+ *
+ * The fingerprint deliberately describes bytes, not Git state or mtimes:
+ * critique often assesses an uncommitted file, and a later polish run should
+ * inherit that backlog when the bytes are unchanged regardless of staging.
+ */
+function resolveLocalTargetPath(target, { cwd = process.cwd() } = {}) {
+  if (!target || /^https?:\/\//i.test(target)) return null;
+  return path.isAbsolute(target) ? path.resolve(target) : path.resolve(cwd, target);
+}
+
+function resolveTargetIdentity(target, { cwd = process.cwd() } = {}) {
+  if (!target || typeof target !== 'string') return null;
+  if (/^https?:\/\//i.test(target)) {
+    try {
+      const url = new URL(target);
+      const pathname = url.pathname.replace(/\/+$/, '') || '/';
+      return `url:${url.origin}${pathname}`;
+    } catch {
+      return null;
+    }
+  }
+  const filePath = resolveLocalTargetPath(target, { cwd });
+  return filePath ? `file:${filePath}` : null;
+}
+
+export function fingerprintTarget(target, { cwd = process.cwd() } = {}) {
+  const filePath = resolveLocalTargetPath(target, { cwd });
+  if (!filePath) return null;
+  try {
+    if (!fs.statSync(filePath).isFile()) return null;
+    return `sha256:${createHash('sha256').update(fs.readFileSync(filePath)).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Write a snapshot for `slug`. `meta` carries the small structured frontmatter
  * keys read back by readTrend(). `body` is the human-readable critique
@@ -62,14 +103,27 @@ export function writeSnapshot({ slug, meta, body, cwd = process.cwd(), now = new
   const dir = getCritiqueDir(cwd);
   fs.mkdirSync(dir, { recursive: true });
   const timestamp = nowFilenameStamp(now);
-  const filePath = path.join(dir, `${timestamp}__${slug}.md`);
   // Spread `meta` first so internally computed `timestamp` and `slug`
   // always win. Otherwise a caller-supplied meta blob (parsed from the
   // IMPECCABLE_CRITIQUE_META env var) could clobber them, leaving the
   // filename in disagreement with its frontmatter and corrupting trends.
   const front = serializeFrontmatter({ ...meta, timestamp, slug });
-  fs.writeFileSync(filePath, `${front}\n${body.trim()}\n`, 'utf-8');
-  return filePath;
+  const contents = `${front}\n${body.trim()}\n`;
+
+  // A second critique can finish in the same UTC second. Use exclusive
+  // creation and a fixed-width suffix so concurrent writers cannot replace
+  // history and lexical ordering still keeps collision entries newest.
+  for (let collision = 0; collision <= 9999; collision += 1) {
+    const suffix = collision === 0 ? '' : `~${String(collision).padStart(4, '0')}`;
+    const filePath = path.join(dir, `${timestamp}${suffix}__${slug}.md`);
+    try {
+      fs.writeFileSync(filePath, contents, { encoding: 'utf-8', flag: 'wx' });
+      return filePath;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+  }
+  throw new Error(`Too many critique snapshots for ${slug} at ${timestamp}`);
 }
 
 function serializeFrontmatter(obj) {
@@ -98,6 +152,8 @@ function parseFrontmatter(text) {
       try { value = JSON.parse(value); } catch { /* leave as-is */ }
     } else if (/^-?\d+$/.test(value)) {
       value = Number(value);
+    } else if (value === 'true' || value === 'false') {
+      value = value === 'true';
     }
     out[key] = value;
   }
@@ -105,28 +161,118 @@ function parseFrontmatter(text) {
 }
 
 /**
- * Return all snapshot files for `slug`, sorted oldest → newest.
+ * Return snapshot files matching `suffix`, sorted oldest → newest.
  */
-function listSnapshotsForSlug(slug, cwd) {
+const SNAPSHOT_FILENAME = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z(?:~\d{4})?__.+\.md$/;
+
+function listSnapshots(suffix, cwd) {
   const dir = getCritiqueDir(cwd);
   if (!fs.existsSync(dir)) return [];
-  const suffix = `__${slug}.md`;
   return fs.readdirSync(dir)
-    .filter((f) => f.endsWith(suffix))
+    .filter((f) => SNAPSHOT_FILENAME.test(f) && f.endsWith(suffix))
     .sort()
     .map((f) => path.join(dir, f));
 }
 
+function readSnapshot(filePath) {
+  if (!filePath) return null;
+  const body = fs.readFileSync(filePath, 'utf-8');
+  return { path: filePath, body, meta: parseFrontmatter(body) };
+}
+
+function snapshotTargetIdentity(snapshot) {
+  const targetPath = snapshot?.meta.target_path;
+  return snapshot?.meta.target_identity
+    || (targetPath ? `file:${targetPath}` : null);
+}
+
+function readNewestSnapshot(slug, { cwd = process.cwd() } = {}) {
+  return readSnapshot(listSnapshots(`__${slug}.md`, cwd).at(-1));
+}
+
+function readNewestSnapshotForIdentity(
+  slug,
+  targetIdentity,
+  { cwd = process.cwd() } = {},
+) {
+  const matches = listSnapshots(`__${slug}.md`, cwd)
+    .map(readSnapshot)
+    .filter((snapshot) => snapshotTargetIdentity(snapshot) === targetIdentity);
+  return matches.at(-1) || null;
+}
+
 /**
  * Return the most recent snapshot for `slug`, or null. Polish reads this
  * to find its fix backlog when the slug matches.
  */
 export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
-  const all = listSnapshotsForSlug(slug, cwd);
-  if (!all.length) return null;
-  const latest = all[all.length - 1];
-  const body = fs.readFileSync(latest, 'utf-8');
-  return { path: latest, body, meta: parseFrontmatter(body) };
+  const latest = readNewestSnapshot(slug, { cwd });
+  return latest?.meta.closed === true ? null : latest;
+}
+
+/**
+ * Mark one exact snapshot closed without deleting the score history consumed
+ * by `trend`. Exact identity matters: a newer critique may land after polish
+ * reads its backlog, and that newer snapshot must remain live. `snapshotFile`
+ * may be the absolute path returned by readLatestSnapshot() or the basename
+ * emitted by `latest --json`. Returns the path marked closed, or null.
+ */
+export function closeSnapshot(snapshotFile, { cwd = process.cwd() } = {}) {
+  if (!snapshotFile || typeof snapshotFile !== 'string') return null;
+  const dir = path.resolve(getCritiqueDir(cwd));
+  const snapshotPath = path.isAbsolute(snapshotFile)
+    ? path.resolve(snapshotFile)
+    : path.resolve(dir, snapshotFile);
+  const filename = path.basename(snapshotPath);
+  if (
+    path.dirname(snapshotPath) !== dir
+    || !SNAPSHOT_FILENAME.test(filename)
+  ) return null;
+
+  let snapshot;
+  try {
+    if (!fs.lstatSync(snapshotPath).isFile()) return null;
+    snapshot = readSnapshot(snapshotPath);
+  } catch {
+    return null;
+  }
+  if (!snapshot || snapshot.meta.closed === true) return null;
+  const closedBody = snapshot.body.replace(
+    /^(---\r?\n[\s\S]*?)(\r?\n---)/,
+    '$1\nclosed: true$2',
+  );
+  if (closedBody === snapshot.body) {
+    throw new Error(`Cannot close snapshot without frontmatter: ${snapshot.path}`);
+  }
+  fs.writeFileSync(snapshot.path, closedBody, 'utf-8');
+  return snapshot.path;
+}
+
+/** Return the most recent snapshot across all targets, or null. */
+export function readLatestSnapshotAcrossTargets({ cwd = process.cwd() } = {}) {
+  const snapshots = listSnapshots('.md', cwd).map(readSnapshot);
+  const identifiedSlugs = new Set(
+    snapshots
+      .filter((snapshot) => snapshotTargetIdentity(snapshot))
+      .map((snapshot) => snapshot.meta.slug),
+  );
+  const latestByTarget = new Map();
+  for (const snapshot of snapshots) {
+    if (!snapshot?.meta.slug) continue;
+    // Slugs are lossy: distinct targets such as foo/bar and foo-bar can share
+    // one. Keep each known identity's latest open/closed state independent so
+    // closing one target cannot hide another target's live backlog. Once a
+    // slug has any identity-aware snapshot, its older legacy records are no
+    // longer independently routable and must not resurface as zombie work.
+    const targetIdentity = snapshotTargetIdentity(snapshot);
+    if (!targetIdentity && identifiedSlugs.has(snapshot.meta.slug)) continue;
+    const streamKey = targetIdentity || `slug:${snapshot.meta.slug}`;
+    latestByTarget.set(streamKey, snapshot);
+  }
+  return [...latestByTarget.values()]
+    .filter((snapshot) => snapshot.meta.closed !== true)
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .at(-1) || null;
 }
 
 /**
@@ -134,7 +280,7 @@ export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
  * Critique appends a one-line trend to its output using this.
  */
 export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
-  const all = listSnapshotsForSlug(slug, cwd);
+  const all = listSnapshots(`__${slug}.md`, cwd);
   const slice = all.slice(-limit);
   return slice.map((file) => parseFrontmatter(fs.readFileSync(file, 'utf-8')));
 }
@@ -144,9 +290,13 @@ export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
 // Accept either a ready slug or a concrete target (path/URL) everywhere, so
 // callers never have to run the slug step separately. Anything containing a
 // path or URL marker is resolved through slugFromTarget.
+function isReadySlug(value) {
+  return /^[a-z0-9-]+$/.test(value || '') && !value.includes('/');
+}
+
 function coerceSlug(value) {
   if (!value) return null;
-  if (/^[a-z0-9-]+$/.test(value) && !value.includes('/')) return value;
+  if (isReadySlug(value)) return value;
   return slugFromTarget(value);
 }
 
@@ -172,14 +322,124 @@ function main(argv) {
       if (metaArg) {
         try { meta = JSON.parse(metaArg); } catch { /* ignore */ }
       }
+      // The helper, not caller-provided metadata, owns the target fingerprint.
+      // This makes the snapshot describe the exact file bytes critique saw.
+      delete meta.target_fingerprint;
+      delete meta.target_path;
+      delete meta.target_identity;
+      const targetIdentity = resolveTargetIdentity(slugArg);
+      if (targetIdentity) meta.target_identity = targetIdentity;
+      const targetFingerprint = fingerprintTarget(slugArg);
+      if (targetFingerprint) {
+        meta.target_fingerprint = targetFingerprint;
+        meta.target_path = resolveLocalTargetPath(slugArg);
+      }
       const out = writeSnapshot({ slug, meta, body: raw });
       process.stdout.write(`${out}\n`);
       return;
     }
     case 'latest': {
-      const latest = readLatestSnapshot(coerceSlug(args[0]));
-      if (!latest) { process.exit(2); }
-      process.stdout.write(latest.body);
+      const target = args[0];
+      const format = args[1];
+      const slug = coerceSlug(target);
+      if (!slug || (format && format !== '--json')) {
+        process.stderr.write('usage: latest <slug-or-target> [--json]\n');
+        process.exit(1);
+      }
+      const targetFingerprint = fingerprintTarget(target);
+      const targetPath = resolveLocalTargetPath(target);
+      const targetIdentity = resolveTargetIdentity(target);
+      const readySlug = isReadySlug(target);
+      const newestForSlug = readNewestSnapshot(slug);
+      if (!newestForSlug) { process.exit(2); }
+
+      // Concrete targets select the newest snapshot for their exact identity,
+      // not merely the newest filename for a lossy slug. This keeps distinct
+      // targets such as foo/bar and foo-bar from hiding each other's backlog.
+      const exactSnapshot = readNewestSnapshotForIdentity(slug, targetIdentity);
+      let latest = exactSnapshot;
+      if (!latest && !readySlug) {
+        // Legacy snapshots have no identity. Preserve their old explicit
+        // path/URL behavior only when no known target identity was selected.
+        latest = readNewestSnapshotForIdentity(slug, null);
+      }
+      if (!latest) latest = newestForSlug;
+      if (latest.meta.closed === true) { process.exit(2); }
+
+      const recordedTargetPath = latest.meta.target_path;
+      const recordedTargetIdentity = snapshotTargetIdentity(latest);
+      const matchingIdentity = recordedTargetIdentity === targetIdentity;
+
+      // Bare slugs remain a supported lookup mode, including for URL
+      // snapshots. But when a same-named local file exists, the request is
+      // ambiguous unless that exact file owns the snapshot identity.
+      if (readySlug && !recordedTargetIdentity) {
+        process.stderr.write(
+          'ambiguous legacy snapshot target; use an explicit ./path or full URL\n',
+        );
+        process.exit(2);
+      }
+      if (readySlug && targetPath && fs.existsSync(targetPath) && !matchingIdentity) {
+        process.stderr.write(
+          'ambiguous snapshot slug; use an explicit ./path or remove the local name collision\n',
+        );
+        process.exit(2);
+      }
+
+      const concreteTarget = !readySlug || matchingIdentity;
+      if (concreteTarget && recordedTargetIdentity && !matchingIdentity) {
+        process.exit(2);
+      }
+      const concreteLocalTarget = concreteTarget && targetPath;
+      if (concreteLocalTarget && latest.meta.target_fingerprint !== targetFingerprint) {
+        closeSnapshot(latest.path);
+        process.exit(2);
+      }
+      if (format === '--json') {
+        process.stdout.write(JSON.stringify({
+          snapshot_file: path.basename(latest.path),
+          body: latest.body,
+        }, null, 2) + '\n');
+      } else {
+        process.stdout.write(latest.body);
+      }
+      return;
+    }
+    case 'close': {
+      const [slugArg, snapshotFile, ...extra] = args;
+      const slug = coerceSlug(slugArg);
+      if (!slug || !snapshotFile || extra.length > 0) {
+        process.stderr.write('usage: close <resolved-target> <snapshot-file>\n');
+        process.exit(1);
+      }
+      if (
+        path.basename(snapshotFile) !== snapshotFile
+        || !SNAPSHOT_FILENAME.test(snapshotFile)
+        || !snapshotFile.endsWith(`__${slug}.md`)
+      ) process.exit(2);
+
+      // A slug and filename are not enough to prove ownership because two
+      // distinct targets can normalize to the same slug. Modern snapshots
+      // carry a canonical identity, so require the supplied resolved target
+      // to match it before allowing the exact snapshot to be closed. Legacy
+      // snapshots without identity retain their historical close behavior.
+      const snapshotPath = path.join(getCritiqueDir(process.cwd()), snapshotFile);
+      let snapshot;
+      try {
+        if (!fs.lstatSync(snapshotPath).isFile()) process.exit(2);
+        snapshot = readSnapshot(snapshotPath);
+      } catch {
+        process.exit(2);
+      }
+      const recordedTargetIdentity = snapshotTargetIdentity(snapshot);
+      if (
+        recordedTargetIdentity
+        && recordedTargetIdentity !== resolveTargetIdentity(slugArg)
+      ) process.exit(2);
+
+      const closed = closeSnapshot(snapshotFile);
+      if (!closed) { process.exit(2); }
+      process.stdout.write(`${closed}\n`);
       return;
     }
     case 'trend': {
@@ -188,7 +448,7 @@ function main(argv) {
       return;
     }
     default:
-      process.stderr.write('usage: critique-storage.mjs <slug|write|latest|trend> [args]\n');
+      process.stderr.write('usage: critique-storage.mjs <slug|write|latest|trend|close> [args]\n');
       process.exit(1);
   }
 }