@appchy/jarvis 0.1.95 → 0.1.97

package/dist/data/backends.mjs

@@ -11,14 +11,72 @@ import {
 } from "./chunk-YWSWQEJN.mjs";
 
 // ../../packages/data/src/backends/graphify.ts
+import { execFile as execFile2 } from "child_process";
+import { access, readFile as readFile3, rename, rm, stat, utimes, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, resolve as resolve3 } from "path";
+import { promisify as promisify2 } from "util";
+
+// ../../packages/data/src/backends/changes.ts
 import { execFile } from "child_process";
-import { access, readFile as readFile2, rename, rm, stat, utimes, writeFile } from "fs/promises";
-import { dirname, resolve as resolve2 } from "path";
+import { readFile, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
 import { promisify } from "util";
+var run = promisify(execFile);
+var STAMP = "extracted-at";
+async function git(root, argv) {
+  try {
+    const { stdout } = await run("git", argv, {
+      cwd: root,
+      timeout: 5e3,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    });
+    return stdout.trim();
+  } catch {
+    return void 0;
+  }
+}
+function stampPath(graphPath) {
+  return resolve(dirname(graphPath), STAMP);
+}
+async function saveExtractedCommit(root, graphPath) {
+  const head = await git(root, ["rev-parse", "HEAD"]);
+  if (!head) return;
+  try {
+    await writeFile(stampPath(graphPath), `${head}
+`, "utf8");
+  } catch {
+  }
+}
+async function loadExtractedCommit(graphPath) {
+  try {
+    const sha = (await readFile(stampPath(graphPath), "utf8")).trim();
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function changedSince(root, since) {
+  const committed = await git(root, ["diff", "--name-only", since, "HEAD"]);
+  if (committed === void 0) return void 0;
+  const working = await git(root, ["status", "--porcelain"]);
+  if (working === void 0) return void 0;
+  const staged = working.split("\n").filter((line) => line.trim().length > 0).flatMap((line) => line.slice(3).split(" -> "));
+  return [...committed.split("\n"), ...staged].map((path) => path.trim()).filter(Boolean);
+}
+async function indexedCodeChanged(root, graphPath, globs) {
+  if (!globs.include || globs.include.length === 0) return true;
+  const since = await loadExtractedCommit(graphPath);
+  if (!since) return true;
+  const changed = await changedSince(root, since);
+  if (changed === void 0) return true;
+  const included = matcher(globs.include);
+  const ignored = globs.ignore && globs.ignore.length > 0 ? matcher(globs.ignore) : () => false;
+  return changed.some((path) => included(path) && !ignored(path));
+}
 
 // ../../packages/data/src/backends/imports.ts
-import { readFile } from "fs/promises";
-import { posix, resolve } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { posix, resolve as resolve2 } from "path";
 var IMPORT_RELATION_SET = new Set(IMPORT_RELATIONS);
 var asStr = (v) => typeof v === "string" ? v : void 0;
 var toPosix = (p) => p.replace(/\\/g, "/");
@@ -50,7 +108,7 @@ async function packageNameOf(cache, root, file) {
       return hit === NO_PACKAGE ? void 0 : hit;
     }
     pending.push(dir);
-    const name = await readFile(resolve(root, dir, "package.json"), "utf8").then((text) => asStr(JSON.parse(text).name)).catch(() => void 0);
+    const name = await readFile2(resolve2(root, dir, "package.json"), "utf8").then((text) => asStr(JSON.parse(text).name)).catch(() => void 0);
     if (name !== void 0) {
       for (const d of pending) cache.set(d, name);
       return name;
@@ -65,7 +123,7 @@ async function packageNameOf(cache, root, file) {
 async function readLines(cache, absPath) {
   const hit = cache.get(absPath);
   if (hit !== void 0) return hit;
-  const lines = await readFile(absPath, "utf8").then((text) => text.split(/\r?\n/)).catch(() => null);
+  const lines = await readFile2(absPath, "utf8").then((text) => text.split(/\r?\n/)).catch(() => null);
   cache.set(absPath, lines);
   return lines;
 }
@@ -83,7 +141,7 @@ async function resolveImportCollisions(raw, root) {
   const specsInFile = async (file) => {
     const hit = fileSpecCache.get(file);
     if (hit !== void 0 || fileSpecCache.has(file)) return hit;
-    const lines = await readLines(lineCache, resolve(root, file));
+    const lines = await readLines(lineCache, resolve2(root, file));
     const specs = lines?.flatMap((l) => specifiersOf(l));
     fileSpecCache.set(file, specs);
     return specs;
@@ -125,7 +183,7 @@ async function resolveImportCollisions(raw, root) {
     const importer = toPosix(asStr(links[0]?.source_file) ?? "");
     const lineNo = lineNumberOf(asStr(links[0]?.source_location));
     if (!importer || lineNo === void 0) continue;
-    const lines = await readLines(lineCache, resolve(root, importer));
+    const lines = await readLines(lineCache, resolve2(root, importer));
     const line = lines?.[lineNo - 1];
     if (!line) continue;
     const allSpecs = specifiersOf(line);
@@ -185,7 +243,7 @@ function communityLabelPrompt(communities) {
 }
 
 // ../../packages/data/src/backends/graphify.ts
-var run = promisify(execFile);
+var run2 = promisify2(execFile2);
 var LABEL_TOP_K = 8;
 var LABEL_MAX_LEN = 80;
 var PLACEHOLDER_COMMUNITY = /^Community \d+$/;
@@ -200,8 +258,8 @@ function graphify(options = {}) {
     // saying so at the moment it is produced.
     ...options.staleness ? { staleness: options.staleness } : {},
     load: async (ctx) => {
-      const root = resolve2(ctx.config.repoRoot, options.root ?? ".");
-      const graphPath = resolve2(ctx.config.repoRoot, graphRel);
+      const root = resolve3(ctx.config.repoRoot, options.root ?? ".");
+      const graphPath = resolve3(ctx.config.repoRoot, graphRel);
       const bin = options.bin ?? "graphify";
       const forceExtract = process.env.JARVIS_DATA_REBUILD === "1";
       const refresh = process.env.JARVIS_DATA_REFRESH === "1" && options.extract !== false;
@@ -209,15 +267,27 @@ function graphify(options = {}) {
       const mode = forceExtract ? true : options.extract ?? "auto";
       const present = await exists(graphPath);
       const missing = options.missing !== void 0 ? { missing: options.missing } : {};
-      const extracted = forceExtract && present ? await rebuildFresh(graphPath, () => extract(bin, root, ctx, graphRel, { ...missing })) : refresh ? await extract(bin, root, ctx, graphRel, { force: true, ...missing }) : mode === true || mode === "auto" && !present ? await extract(bin, root, ctx, graphRel, { ...missing }) : false;
-      if (extracted) await stampFresh(graphPath);
+      const unmoved = refresh && present && !await indexedCodeChanged(root, graphPath, {
+        ...options.include ? { include: options.include } : {},
+        ...options.ignore ? { ignore: options.ignore } : {}
+      });
+      const extracted = forceExtract && present ? await rebuildFresh(graphPath, () => extract(bin, root, ctx, graphRel, { ...missing })) : unmoved ? false : refresh ? await extract(bin, root, ctx, graphRel, { force: true, ...missing }) : mode === true || mode === "auto" && !present ? await extract(bin, root, ctx, graphRel, { ...missing }) : false;
+      if (extracted) {
+        await stampFresh(graphPath);
+        await saveExtractedCommit(root, graphPath);
+      } else if (unmoved) {
+        ctx.logger.info(
+          "graphify: nothing it indexes changed \u2014 keeping the graph, skipping extract"
+        );
+        await stampFresh(graphPath);
+      }
       if (!await exists(graphPath)) {
         ctx.panic(
           `graphify graph not found at ${graphRel}. Run \`jarvis build graph\`, or set { extract: true } in the backend options.`
         );
       }
       if (options.staleness) await reportIfStale(ctx, graphPath, graphRel, options.staleness);
-      const raw = JSON.parse(await readFile2(graphPath, "utf8"));
+      const raw = JSON.parse(await readFile3(graphPath, "utf8"));
       if (options.labeler && (forceLabel || extracted && !refresh)) {
         await labelCommunities(ctx, options.labeler, raw, graphPath, extracted);
       }
@@ -231,7 +301,7 @@ async function loadCommunityLabels(graphPath) {
   const labels = /* @__PURE__ */ new Map();
   const labelPath = communityLabelsPath(graphPath);
   try {
-    const raw = JSON.parse(await readFile2(labelPath, "utf8"));
+    const raw = JSON.parse(await readFile3(labelPath, "utf8"));
     if (!raw || typeof raw !== "object") return labels;
     for (const [rawId, rawName] of Object.entries(raw)) {
       const name = asString(rawName);
@@ -289,7 +359,7 @@ function communityOf(n, labels) {
   return key ? `Community ${key}` : void 0;
 }
 function graphifyOptions(ctx, graphRel) {
-  return { cwd: ctx.config.repoRoot, env: { ...process.env, GRAPHIFY_OUT: dirname(graphRel) } };
+  return { cwd: ctx.config.repoRoot, env: { ...process.env, GRAPHIFY_OUT: dirname2(graphRel) } };
 }
 async function extract(bin, root, ctx, graphRel, options = {}) {
   try {
@@ -297,7 +367,7 @@ async function extract(bin, root, ctx, graphRel, options = {}) {
       `graphify: extracting ${root}${options.force ? " (incremental \u2014 prune deletions)" : ""}`
     );
     const args = options.force ? ["update", "--force", root] : ["update", root];
-    await run(bin, args, graphifyOptions(ctx, graphRel));
+    await run2(bin, args, graphifyOptions(ctx, graphRel));
     return true;
   } catch (err) {
     const code = err.code;
@@ -337,7 +407,7 @@ async function rebuildFresh(graphPath, extract2) {
 }
 async function parseable(path) {
   try {
-    JSON.parse(await readFile2(path, "utf8"));
+    JSON.parse(await readFile3(path, "utf8"));
     return true;
   } catch {
     return false;
@@ -411,12 +481,12 @@ function sampleCommunities(raw) {
   return communities;
 }
 function communityLabelsPath(graphPath) {
-  return resolve2(dirname(graphPath), "community-labels.json");
+  return resolve3(dirname2(graphPath), "community-labels.json");
 }
 async function readCommunityLabels(graphPath) {
   const out = /* @__PURE__ */ new Map();
   try {
-    const existing = JSON.parse(await readFile2(communityLabelsPath(graphPath), "utf8"));
+    const existing = JSON.parse(await readFile3(communityLabelsPath(graphPath), "utf8"));
     for (const [id, value] of Object.entries(existing)) {
       const name = asString(value);
       if (name && !PLACEHOLDER_COMMUNITY.test(name)) out.set(id, name);
@@ -429,7 +499,7 @@ async function writeCommunityLabels(graphPath, named) {
   const merged = {};
   for (const [id, name] of await readCommunityLabels(graphPath)) merged[id] = name;
   for (const [id, name] of named) merged[id] = name;
-  await writeFile(communityLabelsPath(graphPath), `${JSON.stringify(merged, null, 2)}
+  await writeFile2(communityLabelsPath(graphPath), `${JSON.stringify(merged, null, 2)}
 `, "utf8");
 }
 async function reportIfStale(ctx, graphPath, graphRel, severity) {
@@ -441,7 +511,7 @@ async function reportIfStale(ctx, graphPath, graphRel, severity) {
   }
   let headMs;
   try {
-    const { stdout } = await run("git", ["show", "-s", "--format=%ct", "HEAD"], {
+    const { stdout } = await run2("git", ["show", "-s", "--format=%ct", "HEAD"], {
       cwd: ctx.config.repoRoot
     });
     const seconds = Number(stdout.trim());

package/dist/data/mcp.mjs

@@ -215,6 +215,14 @@ async function freshness(ctx) {
   const builtMs = Date.parse(ctx.builtAt);
   let behindHead;
   if (head && mtimeMs) behindHead = mtimeMs < head.committedMs;
+  let behindHeadBy;
+  let behindHeadForMs;
+  if (behindHead && head && mtimeMs) {
+    behindHeadForMs = head.committedMs - mtimeMs;
+    const since = new Date(mtimeMs).toISOString();
+    const count = Number(await git(root, ["rev-list", "--count", `--since=${since}`, "HEAD"]));
+    if (Number.isFinite(count)) behindHeadBy = count;
+  }
   const replacedMs = Math.max(mtimeMs ?? 0, await snapshotMtimeMs(ctx) ?? 0);
   const rebuiltOnDisk = Boolean(
     replacedMs && Number.isFinite(builtMs) && replacedMs > builtMs + 1e3
@@ -223,27 +231,47 @@ async function freshness(ctx) {
   const behindOrigin = Boolean(origin?.reachable && (origin.behindBy ?? 0) > 0);
   const originUnknown = Boolean(origin && !origin.reachable);
   let reason;
-  if (behindOrigin)
+  let verdict;
+  if (behindOrigin) {
+    verdict = "stale";
     reason = `this checkout is ${origin?.behindBy} commit(s) behind ${origin?.ref} \u2014 the map and the board both describe an older world than the origin's. Pull, then \`jarvis build graph\`.`;
-  else if (originUnknown)
-    reason = `cannot reach ${origin?.ref}, so I cannot tell whether this is current${origin?.lastSyncedIso ? ` \u2014 last synced at ${origin.lastSyncedIso}` : " and this clone has never fetched"}.`;
-  else if (behindHead)
-    reason = `${graphRel} is older than HEAD \u2014 the code graph is stale; run \`jarvis build graph\` (the incremental update \u2014 it re-extracts in place), then traces and impact are trustworthy again. \`--rebuild\` re-extracts from scratch and relabels; it is for a graph still wrong after a plain build, not for ordinary drift.`;
-  else if (rebuiltOnDisk)
+  } else if (originUnknown) {
+    verdict = "unknown";
+    reason = `cannot reach ${origin?.ref}, so whether this is current is UNKNOWN rather than bad \u2014 rebuilding cannot answer it${origin?.lastSyncedIso ? `. Last heard from a remote at ${origin.lastSyncedIso}` : ", and this clone has never fetched"}.`;
+  } else if (behindHead) {
+    verdict = "stale";
+    reason = `${graphRel} is ${describeBehind(behindHeadBy, behindHeadForMs)} \u2014 run \`jarvis build graph\` (the incremental update \u2014 it re-extracts in place), then traces and impact are trustworthy again. \`--rebuild\` re-extracts from scratch and relabels; it is for a graph still wrong after a plain build, not for ordinary drift.`;
+  } else if (rebuiltOnDisk) {
+    verdict = "stale";
     reason = `${graphRel} was rebuilt after this MCP server loaded it \u2014 reloading automatically.`;
+  }
   return {
     graphPath: graphRel,
     ...mtimeIso ? { mtimeIso } : {},
     ...head ? { head: { commit: head.commit, dirty: head.dirty } } : {},
     ...behindHead !== void 0 ? { behindHead } : {},
+    ...behindHeadBy !== void 0 ? { behindHeadBy } : {},
+    ...behindHeadForMs !== void 0 ? { behindHeadForMs } : {},
     ...rebuiltOnDisk ? { rebuiltOnDisk } : {},
     ...origin ? { origin } : {},
     ...behindOrigin ? { behindOrigin } : {},
     ...originUnknown ? { originUnknown } : {},
     stale: Boolean(behindHead) || rebuiltOnDisk || behindOrigin || originUnknown,
+    ...verdict ? { verdict } : {},
     ...reason ? { reason } : {}
   };
 }
+function describeBehind(commits, forMs) {
+  const age = forMs !== void 0 && forMs >= 60 * 60 * 1e3 ? describeAge(forMs) : void 0;
+  if (commits === void 0) return `older than HEAD${age ? ` by ${age}` : ""}`;
+  const plural = commits === 1 ? "commit" : "commits";
+  return `${commits} ${plural} behind HEAD${age ? `, built ${age} ago` : ""}`;
+}
+function describeAge(ms) {
+  const hours = Math.round(ms / (60 * 60 * 1e3));
+  if (hours < 48) return `${hours} hour(s)`;
+  return `${Math.round(hours / 24)} day(s)`;
+}
 async function snapshotMtimeMs(ctx) {
   const path = ctx.config.persistence?.locate?.({ repoRoot: ctx.config.repoRoot }, "snapshot");
   if (!path) return void 0;
@@ -874,11 +902,13 @@ async function brief(ctx, req) {
   const areas = [...communityCounts.entries()].map(([name, size]) => ({ name, size })).sort((a, b) => b.size - a.size).slice(0, listCap);
   const inProgressCount = byCategory["in-progress"] ?? 0;
   return {
-    summary: `${leaves.length} work item(s) \u2014 ${inProgressCount} in flight, ${byCategory["open"] ?? 0} open, ${byCategory["done"] ?? 0} done. ${artifacts} knowledge artifact(s); health: ${health.counts.error} error(s), ${health.counts.warn} warning(s)${f.stale ? " \u2014 GRAPH IS STALE, run `jarvis build graph` (incremental) before trusting details" : ""}${staleOrigins.length ? ` \u2014 ${staleOrigins.map((o) => o.origin).join(", ")} behind their own HEAD (re-run \`jarvis build graph\` there, then re-merge)` : ""}.`,
+    summary: `${leaves.length} work item(s) \u2014 ${inProgressCount} in flight, ${byCategory["open"] ?? 0} open, ${byCategory["done"] ?? 0} done. ${artifacts} knowledge artifact(s); health: ${health.counts.error} error(s), ${health.counts.warn} warning(s)${f.stale ? ` \u2014 ${describeFreshness(f)}` : ""}${staleOrigins.length ? ` \u2014 ${staleOrigins.map((o) => o.origin).join(", ")} behind their own HEAD (re-run \`jarvis build graph\` there, then re-merge)` : ""}.`,
     freshness: {
       builtAt: ctx.builtAt,
       ...f.head ? { head: { commit: f.head.commit, dirty: f.head.dirty } } : {},
       ...f.stale !== void 0 ? { stale: f.stale } : {},
+      ...f.verdict ? { verdict: f.verdict } : {},
+      ...f.behindHeadBy !== void 0 ? { behindHeadBy: f.behindHeadBy } : {},
       ...originsFresh.length ? { federated: originsFresh } : {}
     },
     graph: { nodes: ctx.graph.nodes().length, artifacts, edges: ctx.graph.edges().length },
@@ -920,6 +950,15 @@ function renderWorkItem(ctx, item, home) {
     ...home !== void 0 ? { belongsTo: home } : {}
   };
 }
+function describeFreshness(f) {
+  if (f.verdict === "unknown")
+    return "FRESHNESS UNKNOWN \u2014 cannot reach the origin, so nothing below is confirmed current; rebuilding cannot answer it";
+  if (f.behindOrigin)
+    return `THIS CHECKOUT IS BEHIND ITS ORIGIN by ${f.origin?.behindBy} commit(s) \u2014 pull, then run \`jarvis build graph\``;
+  if (f.behindHead)
+    return `GRAPH IS STALE by ${f.behindHeadBy ?? "an unknown number of"} commit(s), run \`jarvis build graph\` (incremental) before trusting details`;
+  return "GRAPH IS STALE, run `jarvis build graph` (incremental) before trusting details";
+}
 
 // ../../packages/data/src/resolve.ts
 function resolveTarget(ctx, input) {
@@ -2562,15 +2601,11 @@ function createServer(ctx, hosted = [], prompts = []) {
     );
   }
   for (const p of prompts) {
-    server.registerPrompt(
-      p.name,
-      { title: p.title, description: p.description },
-      async () => ({
-        messages: [
-          { role: "user", content: { type: "text", text: await p.read() } }
-        ]
-      })
-    );
+    server.registerPrompt(p.name, { title: p.title, description: p.description }, async () => ({
+      messages: [
+        { role: "user", content: { type: "text", text: await p.read() } }
+      ]
+    }));
   }
   return server;
 }
@@ -2601,14 +2636,23 @@ function buildInstructions(req = {}) {
 }
 async function result(ctx, structured) {
   const f = await freshness(ctx);
-  const summary = f.stale && !/stale/i.test(structured.summary) ? `${STALE_PREFIX}${structured.summary}` : structured.summary;
+  const summary = f.stale && !/stale/i.test(structured.summary) ? `${f.verdict === "unknown" ? UNKNOWN_PREFIX : STALE_PREFIX}${structured.summary}` : structured.summary;
   return {
     content: [{ type: "text", text: summary }],
     structuredContent: { ...structured, summary },
-    ...f.stale ? { _meta: { data: { stale: true, ...f.reason ? { reason: f.reason } : {} } } } : {}
+    ...f.stale ? {
+      _meta: {
+        data: {
+          stale: true,
+          ...f.verdict ? { verdict: f.verdict } : {},
+          ...f.reason ? { reason: f.reason } : {}
+        }
+      }
+    } : {}
   };
 }
 var STALE_PREFIX = "\u26A0 STALE GRAPH \u2014 results may be wrong; run `jarvis build graph` (the incremental update \u2014 not --rebuild). ";
+var UNKNOWN_PREFIX = "\u26A0 FRESHNESS UNKNOWN \u2014 this clone cannot reach its origin, so it cannot tell whether these results are current. ";
 
 // ../../packages/data/src/mcp/snapshot.ts
 async function loadSnapshot(config) {

package/harness/harness/epic.py

@@ -212,13 +212,81 @@ def cmd_epic_move(args) -> int:
           f"with {len(moved)} task(s)")
     _sync(root)
     return 0
+#: Headings whose content is a STATEMENT ABOUT THE WORLD rather than a plan for one
+#: piece of work — the parts of an epic that can outlive it, and therefore the parts
+#: worth naming before they are deleted. Slice ordering, as-found and running logs are
+#: deliberately absent: those are supposed to die with the epic.
+_DURABLE_SECTIONS = ("## Governance this implies", "## Non-goals", "### Settled",
+                     "### Forward-compat")
+
+
+def _cost_of_removing(version, root) -> list:
+    """What this release is about to delete, as lines a person can act on.
+
+    **Said BEFORE the unlink, because the advice that follows a release is useless
+    after it.** `release` has always printed _"promote still-load-bearing decisions
+    to the domain that owns them"_ — and printed it after the files holding those
+    decisions had already left the tree. Measured 2026-09-11 on `01-one-board`: twelve
+    plans, 450,405 bytes, about a hundred durable statements with no owner file, and
+    the recovery commit had to be worked out by hand afterwards from `git log
+    --diff-filter=D`.
+
+    So this names the size, the sections that can outlive the plan, and the commit
+    where the text still lives. It does not judge whether a statement is durable —
+    that is the judgement a lint cannot make, and claiming it would be worse than
+    saying nothing.
+    """
+    plans = [e for e in version.epics if e.planned]
+    if not plans:
+        return []
+    out, total = [], 0
+    for e in plans:
+        try:
+            text = e.md.read_text()
+        except OSError:                               # pragma: no cover — defensive
+            continue
+        total += len(text.encode())
+        held = [h.split("## ")[-1].split("### ")[-1]
+                for h in _DURABLE_SECTIONS if h in text]
+        note = f" — holds §{', §'.join(held)}" if held else ""
+        out.append(f"          {e.name}  {len(text.encode()):,} bytes{note}")
+    head = _still_holds(root)
+    return ([f"\n        DELETING {len(plans)} epic plan(s), {total:,} bytes. Anything "
+             f"durable in them must already be in the file that owns it — after this "
+             f"they are in git only, and nobody reads git for a decision:"]
+            + out
+            + ([f"          the text stays recoverable at {head}"] if head else [])
+            + ["          `git show <commit>:<path>` — and `jarvis work align` reports "
+               "what cites a file that is gone"])
+
+
+def _still_holds(root) -> str:
+    """The commit whose tree still contains these plans, or empty when git cannot say.
+
+    HEAD is the right answer, and it is worth being precise about why: the unlink has
+    not happened yet and the board write commits after it, so at the moment this
+    prints, the newest commit in the history is one that still holds every file about
+    to go. Through the same seam every other git question goes through — a second way
+    of asking would eventually give a second answer.
+    """
+    from . import git
+    code, out, _ = git._git(root.parent, "rev-parse", "--short", "HEAD")
+    return out.strip() if code == 0 else ""
+
+
 def cmd_epic_release(root, version) -> int:
     """Remove every `epic.md` in a released version, and report it.
 
     An epic is TEMPORARY by definition: it is the plan-it-together doc, and how
     the work was planned stops being true the moment it ships. The folder stays
     as the grouping of what shipped — that record is worth keeping — and git
-    holds the plan. Called from `cmd_release`, never on its own."""
+    holds the plan. Called from `cmd_release`, never on its own.
+
+    It says what it is deleting FIRST. The cost of a release is not the stamp, it is
+    the plans that go with it, and a person deciding needs that in front of them
+    while the files still exist."""
+    for line in _cost_of_removing(version, root):
+        print(line)
     removed = []
     for e in version.epics:
         # An epic with no plan doc is already in the shape this produces — a folder

package/harness/harness/version.py

@@ -198,7 +198,12 @@ def cmd_release(args) -> int:
     # how the work was planned stops being true once it ships.
     cmd_epic_release(root, version)
     print("\nDistill before archiving:")
-    print("  1. Promote still-load-bearing decisions to the domain or system that owns them")
+    # Points at the commit the deletion just named, because this instruction used to
+    # send a reader to files the same command had already removed — and the one time
+    # it mattered, the recovery commit had to be reconstructed afterwards with
+    # `git log --diff-filter=D`.
+    print("  1. Promote still-load-bearing decisions to the domain or system that owns "
+          "them — read them from the commit named above; they are no longer in the tree")
     print(f"  2. Repoint any inbound deep-links to those {ids.LEDGER}-nn entries")
     print(f"  3. {cli()} archive {name}   (strips each task to task.md, and "
           f"files a RELEASED cut under versions/complete/)")

package/harness/test_work.py

@@ -7288,6 +7288,81 @@ def test_the_stop_hook_being_switched_off_silences_the_standing_too():
 
 
 
+def test_a_release_says_what_it_is_deleting_before_it_deletes_it():
+    # `release` has always printed "promote still-load-bearing decisions to the
+    # domain that owns them" — AFTER unlinking the files holding those decisions.
+    # Measured on 01-one-board: twelve plans, 450,405 bytes, about a hundred durable
+    # statements with no owner file, and the recovery commit reconstructed afterwards
+    # by hand with `git log --diff-filter=D`. The cost of a release is the plans that
+    # go with it, so it is named while they still exist.
+    with tempfile.TemporaryDirectory() as tmp:
+        try:
+            repo = _git_repo(tmp, push=False)
+            v = repo / "work" / "versions" / "09-a-cut"
+            (v / "an-epic" / "complete" / "only-task").mkdir(parents=True)
+            (v / "version.md").write_text(
+                "---\ncreated: 2026-09-01\norder: 9\noutcome: a user can do it\n"
+                "---\n\n# A cut\n")
+            (v / "an-epic" / "epic.md").write_text(
+                "---\ntype: epic\nowner: quality\n---\n\n# An epic\n\n## Plan\n\n"
+                "Slice ordering, which is supposed to die with this file.\n\n"
+                "## Governance this implies\n\n- quality/README.md — a rule is owed\n")
+            (v / "an-epic" / "complete" / "only-task" / "task.md").write_text(
+                "---\npriority: P0\ncompleted: 2026-09-02\n---\n\n# Only task\n\n"
+                "## Acceptance criteria\n\n- [x] it works\n")
+            _git(repo, "add", "-A")
+            _git(repo, "commit", "-qm", "the board")
+            head = _git(repo, "rev-parse", "--short", "HEAD").stdout.strip()
+
+            with _work_dir(str(repo / "work")):
+                said = _capture_stdout(lambda: version.cmd_release({"name": "09-a-cut"}))
+
+            # The cost, in front of the person, in units they can weigh.
+            assert "DELETING 1 epic plan(s)" in said, said
+            assert "bytes" in said
+            # WHICH sections can outlive the plan — and not the ones that cannot.
+            assert "§Governance this implies" in said, said
+            assert "§Plan" not in said, "slice ordering is supposed to die with the epic"
+            # Where it went, named at the moment it goes rather than reconstructed later.
+            assert head and head in said, f"expected the recovery commit {head}: {said}"
+
+            # And the claim is true: the plan is out of the tree and in that commit.
+            assert not (v / "an-epic" / "epic.md").exists()
+            kept = _git(repo, "show", f"{head}:work/versions/09-a-cut/an-epic/epic.md")
+            assert "a rule is owed" in kept.stdout, kept.stderr
+
+            # The instruction that follows no longer sends a reader to a deleted file.
+            assert "no longer in the tree" in said, said
+        finally:
+            events._PENDING.clear()
+            config.apply(config.DEFAULTS)
+
+
+def test_a_release_with_no_plans_left_says_nothing_about_deleting_any():
+    # Silence where there is no cost. An epic with no plan doc is already in the
+    # shape release produces, and announcing a deletion of nothing would train the
+    # reader to skip the announcement that matters.
+    with tempfile.TemporaryDirectory() as tmp:
+        try:
+            repo = _git_repo(tmp, push=False)
+            v = repo / "work" / "versions" / "09-a-cut"
+            (v / "an-epic" / "complete" / "only-task").mkdir(parents=True)
+            (v / "version.md").write_text(
+                "---\ncreated: 2026-09-01\norder: 9\noutcome: a user can do it\n"
+                "---\n\n# A cut\n")
+            (v / "an-epic" / "complete" / "only-task" / "task.md").write_text(
+                "---\npriority: P0\ncompleted: 2026-09-02\n---\n\n# Only task\n\n"
+                "## Acceptance criteria\n\n- [x] it works\n")
+            _git(repo, "add", "-A")
+            _git(repo, "commit", "-qm", "the board")
+            with _work_dir(str(repo / "work")):
+                said = _capture_stdout(lambda: version.cmd_release({"name": "09-a-cut"}))
+            assert "DELETING" not in said, said
+        finally:
+            events._PENDING.clear()
+            config.apply(config.DEFAULTS)
+
+
 if __name__ == "__main__":
     tests = [v for k, v in sorted(globals().items())
              if k.startswith("test_") and callable(v)]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -56,12 +56,12 @@
     "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "vitest": "^2.1.0",
-    "@jarvis/agents": "1.0.0",
     "@jarvis/anthropic": "1.0.0",
     "@jarvis/board": "0.1.0",
+    "@jarvis/agents": "1.0.0",
     "@jarvis/data": "0.1.0",
-    "@jarvis/errors": "1.0.0",
     "@jarvis/logger": "1.0.0",
+    "@jarvis/errors": "1.0.0",
     "@jarvis/rpc": "1.0.0",
     "@jarvis/types": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",