akm-cli 0.9.17 → 0.9.19-alpha.1

package/dist/commands/read/knowledge.js

@@ -168,11 +168,11 @@ function parseWriteRefs(rawRefs, flag) {
     }
     return parsedRefs;
 }
-function resolveWriteRefRoots(target) {
+function resolveWriteRefRoots(target, targetFlag) {
     const cfg = loadConfig();
     let writeTarget;
     try {
-        writeTarget = resolveWriteTarget(cfg, target);
+        writeTarget = resolveWriteTarget(cfg, target, { flag: targetFlag });
     }
     catch (error) {
         if (!target)
@@ -297,11 +297,11 @@ export const XREF_SOFT_CAP = 5;
  * {@link XREF_SOFT_CAP} refs emits a stderr warning (soft cap) but still
  * returns them all.
  */
-export function resolveXrefsForWrite(rawXrefs, target) {
+export function resolveXrefsForWrite(rawXrefs, target, targetFlag) {
     const parsedRefs = parseWriteRefs(rawXrefs, "--xref");
     if (parsedRefs.length === 0)
         return [];
-    const { roots } = resolveWriteRefRoots(target);
+    const { roots } = resolveWriteRefRoots(target, targetFlag);
     const unresolved = [];
     const xrefs = [];
     for (const parsed of parsedRefs) {
@@ -386,13 +386,13 @@ function isParseableYamlMapping(frontmatter) {
     }
 }
 /** Resolve any qualified supersedes ref as the mutation target for remember/import. */
-export function resolveSupersedesWriteTarget(rawRefs, target) {
+export function resolveSupersedesWriteTarget(rawRefs, target, targetFlag) {
     const config = loadConfig();
     let effectiveTarget = target;
     for (const parsed of parseWriteRefs(rawRefs, "--supersedes")) {
         if (!parsed.origin)
             continue;
-        const resolved = resolveMutationTarget(config, { type: parsed.type, name: parsed.name, origin: parsed.origin }, effectiveTarget).target;
+        const resolved = resolveMutationTarget(config, { type: parsed.type, name: parsed.name, origin: parsed.origin }, effectiveTarget, { flag: targetFlag }).target;
         effectiveTarget = resolved.selector ?? resolved.source.name;
     }
     return effectiveTarget;
@@ -428,17 +428,17 @@ const SUPERSEDE_REJECTED_TYPES = new Set(["secret", "env", "task", "script"]);
  * constraint (and never dirtying a non-target source outside its boundary
  * commit). A ref that resolves only in another configured source — read-only
  * OR writable-but-not-the-target — is returned with `writable: false` and a
- * reason (naming the `--target` remedy when the source is writable); the
+ * reason (naming the target-flag remedy when the source is writable); the
  * caller writes the correction anyway and reports the demotion as not
  * applied.
  *
  * Returns the deduplicated plan in argv order; empty input returns [].
  */
-export function resolveSupersedesForWrite(rawRefs, target) {
+export function resolveSupersedesForWrite(rawRefs, target, targetFlag) {
     const parsedRefs = parseWriteRefs(rawRefs, "--supersedes");
     if (parsedRefs.length === 0)
         return [];
-    const { roots } = resolveWriteRefRoots(target);
+    const { roots } = resolveWriteRefRoots(target, targetFlag);
     const plan = [];
     const unresolved = [];
     for (const parsed of parsedRefs) {
@@ -491,7 +491,7 @@ export function resolveSupersedesForWrite(rawRefs, target) {
                 : {
                     reason: namedWritableSource
                         ? `resolves outside the write target and the working stash, in writable source "${namedWritableSource}" at ${root}; ` +
-                            `re-run with --target ${namedWritableSource} to demote it there`
+                            `re-run with ${targetFlag ?? "--target"} ${namedWritableSource} to demote it there`
                         : `resolves outside the write target and the working stash, in a read-only source at ${root}; ` +
                             "demotion only applies to assets in the write target or the working stash",
                 }),
@@ -518,7 +518,9 @@ export async function writeMarkdownAsset(options) {
     const subPath = normalizeCreateSubPath(options.path);
     const baseName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
     const normalizedName = combineCreatePath(subPath, baseName);
-    const resolved = resolveMutationTarget(cfg, { type: options.type, name: normalizedName }, options.target);
+    const resolved = resolveMutationTarget(cfg, { type: options.type, name: normalizedName }, options.target, {
+        flag: options.targetFlag,
+    });
     const { target } = resolved;
     const { source, config } = target;
     const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");

package/dist/commands/read/remember-cli.js

@@ -33,6 +33,8 @@ async function fetchSimilarMemories(query, excludeRef, eventSource) {
         return [];
     }
 }
+/** The flag `remember` takes for its destination, as its errors spell it. */
+const TARGET_FLAG = "--bundle";
 /**
  * `--target` was renamed to `--bundle` on `remember` in 0.9 (S8). citty is
  * non-strict, so the retired spelling is silently absorbed rather than
@@ -153,8 +155,8 @@ export const rememberCommand = defineJsonCommand({
         // untouched. Refs resolvable only in a configured extra stash source are
         // accepted (cross-stash provenance).
         const rawSupersedes = parseAllFlagValues("--supersedes");
-        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle);
-        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget);
+        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle, TARGET_FLAG);
+        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget, TARGET_FLAG);
         // Collect and validate --supersedes occurrences (repeatable). Same
         // before-any-write validation contract: an unresolvable ref exits 2 with
         // nothing written AND nothing demoted (no partial correction). The
@@ -162,7 +164,7 @@ export const rememberCommand = defineJsonCommand({
         // (correction provenance per the back-linking conventions); the demotion
         // itself runs inside writeMarkdownAsset, ordered before the git boundary
         // commit.
-        const supersedes = resolveSupersedesForWrite(rawSupersedes, writeTarget);
+        const supersedes = resolveSupersedesForWrite(rawSupersedes, writeTarget, TARGET_FLAG);
         for (const s of supersedes) {
             if (!xrefs.includes(s.ref))
                 xrefs.push(s.ref);
@@ -206,6 +208,7 @@ export const rememberCommand = defineJsonCommand({
                 preferredName: inferAssetName(body, "memory"),
                 force: args.force,
                 target: writeTarget,
+                targetFlag: TARGET_FLAG,
                 path: args.path,
                 supersedes,
             });
@@ -313,6 +316,7 @@ export const rememberCommand = defineJsonCommand({
             preferredName: inferAssetName(body, "memory"),
             force: args.force,
             target: writeTarget,
+            targetFlag: TARGET_FLAG,
             path: args.path,
             supersedes,
         });

package/dist/commands/sources/source-clone.js

@@ -39,7 +39,7 @@ export async function akmClone(options) {
     // are not bundle slugs).
     const parsed = parseQualifiedRefInput(options.sourceRef);
     const config = hasUnmanagedDest ? undefined : loadConfig();
-    const resolvedWriteTarget = config ? resolveWriteTarget(config, options.target) : undefined;
+    const resolvedWriteTarget = config ? resolveWriteTarget(config, options.target, { flag: "--bundle" }) : undefined;
     const writeTarget = resolvedWriteTarget ? prepareWriteTargetForMutation(resolvedWriteTarget) : undefined;
     // An unmanaged --dest does not require any configured write target.
     let allSources;

package/dist/commands/tasks/tasks-cli.js

@@ -212,7 +212,7 @@ const tasksAddCommand = defineJsonCommand({
         },
         command: {
             type: "string",
-            description: 'Exact shell string to run on the schedule (no AI agent), e.g. "akm improve --strategy frequent".',
+            description: 'Exact shell string to run on the schedule (no AI agent), e.g. "akm improve --strategy reflect-distill".',
         },
         engine: { type: "string", description: "Engine to use for prompt targets (default: defaults.engine)" },
         model: { type: "string", description: "Model override for prompt targets" },

package/dist/commands/tasks/tasks.js

@@ -688,7 +688,7 @@ function taskAssetRef(id) {
 /** The bundle `task add` writes into: its write target, config, stash path, and name. */
 function resolveTaskBundle(target) {
     const config = loadConfig();
-    const resolved = prepareWriteTargetForMutation(resolveWriteTarget(config, target, { requireWritable: true }));
+    const resolved = prepareWriteTargetForMutation(resolveWriteTarget(config, target, { requireWritable: true, flag: "--bundle" }));
     return { resolved, config, stashDir: resolved.source.path, bundleName: resolved.source.name };
 }
 function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
@@ -696,7 +696,8 @@ function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
         if (bundle === bundleName) {
             return { file: await resolveAssetPath(bundleRoot, type, name), bundleRoot };
         }
-        const target = resolveWriteTarget(config, bundle, { requireWritable: false });
+        // `bundle` is the qualifier of an asset ref in the task, not a flag.
+        const target = resolveWriteTarget(config, bundle, { requireWritable: false, flag: "The asset ref's bundle" });
         return {
             file: await resolveAssetPath(target.source.path, type, name),
             bundleRoot: target.source.path,
@@ -723,7 +724,13 @@ export function resolveTaskReadBundle(refBundle, flagBundle) {
     else {
         const configured = resolveActiveConfiguredSources(config).some((source) => source.name === selector);
         const implicit = configured ? undefined : resolveImplicitScheduledBundleTarget(config, selector);
-        resolved = implicit ?? resolveWriteTarget(config, selector, { requireWritable: false });
+        resolved =
+            implicit ??
+                resolveWriteTarget(config, selector, {
+                    requireWritable: false,
+                    // The selector is `--bundle` when given, else the task ref's own bundle qualifier.
+                    flag: flagBundle !== undefined ? "--bundle" : "The task ref's bundle",
+                });
     }
     if (refBundle && resolved.source.name !== refBundle) {
         throw new UsageError(`Task ref bundle ${JSON.stringify(refBundle)} does not match the resolved source.`, "INVALID_FLAG_VALUE");

package/dist/core/mutation-target.js

@@ -50,9 +50,14 @@ function resolveExplicitMutationTarget(config, explicitTarget, options) {
         }
     }
 }
-/** Reconcile a qualified mutation ref with `--target`, then resolve the write destination. */
+/**
+ * Reconcile a qualified mutation ref with the explicit target (`--target`, or
+ * the `options.flag` the caller's command spells), then resolve the write
+ * destination.
+ */
 export function resolveMutationTarget(config, ref, explicitTarget, options = {}) {
-    const writeOptions = { requireWritable: options.requireWritable };
+    const flag = options.flag ?? "--target";
+    const writeOptions = { requireWritable: options.requireWritable, flag };
     const qualifiedTarget = ref.origin ? resolveBundleWriteTarget(config, ref.origin, writeOptions) : undefined;
     const explicitResolved = explicitTarget
         ? resolveExplicitMutationTarget(config, explicitTarget, writeOptions)
@@ -60,7 +65,7 @@ export function resolveMutationTarget(config, ref, explicitTarget, options = {})
     if (qualifiedTarget &&
         explicitResolved &&
         path.resolve(qualifiedTarget.source.path) !== path.resolve(explicitResolved.source.path)) {
-        throw new UsageError(`Qualified ref bundle "${ref.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or select the same bundle.`);
+        throw new UsageError(`Qualified ref bundle "${ref.origin}" conflicts with ${flag} "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop ${flag} or select the same bundle.`);
     }
     let target = qualifiedTarget ?? explicitResolved ?? resolveWriteTarget(config, undefined, writeOptions);
     const bundleId = ref.origin ?? canonicalBundleIdForTarget(config, target);

package/dist/core/write-source.js

@@ -59,16 +59,17 @@ export function resolveWriteTarget(akmConfig, explicitTarget, options = {}) {
     const allConfiguredSources = resolveConfiguredSources(akmConfig);
     const configuredSources = resolveActiveConfiguredSources(akmConfig);
     const requireWritable = options.requireWritable !== false;
+    const flag = options.flag ?? "--target";
     if (explicitTarget) {
         const match = configuredSources.find((s) => s.name === explicitTarget);
         if (!match) {
             if (allConfiguredSources.some((source) => source.name === explicitTarget)) {
                 throw new UsageError(`Bundle "${explicitTarget}" is disabled.`, "INVALID_FLAG_VALUE");
             }
-            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
+            throw new UsageError(`${flag} must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
         }
         if (requireWritable && !resolveWritable({ type: match.type, writable: match.writable })) {
-            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
+            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass ${flag} to a different source.`);
         }
         return adaptConfiguredSource(match);
     }

package/dist/indexer/usage/usage-events.js

@@ -85,7 +85,8 @@ export function countFeedbackSignals(db, entryId) {
  * Count usage events of a given `event_type`.
  *
  * Lifted verbatim from `akm improve` (improve.ts) where the show-event count
- * was hand-rolled inline to drive the zero-feedback fallback warning.
+ * was hand-rolled inline to drive the warning that the retrieval scope matches
+ * only search-retrieved assets.
  */
 export function countUsageEventsByType(db, eventType) {
     return db.prepare("SELECT COUNT(*) AS cnt FROM usage_events WHERE event_type = ?").get(eventType)

package/dist/output/shapes/helpers.js

@@ -86,6 +86,7 @@ export function shapeProposalEntry(entry, detail) {
             "confidence",
             "gateDecision",
             "review",
+            "reviewHistory",
             "retirement",
         ]);
     }
@@ -102,6 +103,7 @@ export function shapeProposalEntry(entry, detail) {
         "gateDecision",
         "payload",
         "review",
+        "reviewHistory",
         "retirement",
         "retiredArchive",
         "promotionSource",
@@ -167,6 +169,11 @@ export function shapeProposalDiffOutput(result, detail) {
         isNew: result.isNew,
         unified: result.unified,
         ...(result.targetPath !== undefined ? { targetPath: result.targetPath } : {}),
+        // A retire proposal (#997): the diff alone is a file leaving, so the pair
+        // verdict and the accept/revert note travel with it at every detail level.
+        ...(result.op !== undefined ? { op: result.op } : {}),
+        ...(result.retirement !== undefined ? { retirement: result.retirement } : {}),
+        ...(result.note !== undefined ? { note: result.note } : {}),
     };
     if (detail === "full") {
         return { schemaVersion: result.schemaVersion, ...base };

package/dist/output/shapes/passthrough.js

@@ -53,6 +53,7 @@ const PASSTHROUGH_COMMANDS = [
     "proposal-accept-batch",
     "proposal-drain",
     "proposal-reject-batch",
+    "proposal-reopen-batch",
     "proposal-revert",
     "registry-add",
     "registry-list",

package/dist/output/shapes/proposal/reopen.js

@@ -0,0 +1,14 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+// Output shape registration for `akm proposal reopen` (#997). One reopened
+// proposal is the same envelope `reject` returns (`ok`, `id`, `ref`, an
+// optional `reason` — here the reopen reason — and the shaped proposal), so it
+// shares that shaper; several are the passthrough `proposal-reopen-batch`.
+import { shapeProposalRejectOutput } from "../helpers.js";
+export const proposalReopenShapes = [
+    {
+        command: "proposal-reopen",
+        handler: (result, detail) => shapeProposalRejectOutput(result, detail),
+    },
+];

package/dist/output/shapes.js

@@ -29,6 +29,7 @@ import { proposalDiffShapes } from "./shapes/proposal/diff.js";
 import { proposalListShapes } from "./shapes/proposal/list.js";
 import { proposalProducerShapes } from "./shapes/proposal/producer.js";
 import { proposalRejectShapes } from "./shapes/proposal/reject.js";
+import { proposalReopenShapes } from "./shapes/proposal/reopen.js";
 import { proposalShowShapes } from "./shapes/proposal/show.js";
 import { getOutputShapeHandler, registerOutputShapes } from "./shapes/registry.js";
 import { registrySearchShapes } from "./shapes/registry-search.js";
@@ -51,6 +52,7 @@ const BUILT_IN_OUTPUT_SHAPES = [
     ...proposalShowShapes,
     ...proposalAcceptShapes,
     ...proposalRejectShapes,
+    ...proposalReopenShapes,
     ...proposalDiffShapes,
     ...proposalProducerShapes,
     ...envListShapes,

package/dist/output/text/helpers.js

@@ -18,6 +18,6 @@
 export { formatAddPlain, formatBundleRenamePlain, formatBundleShowPlain, formatClonePlain, formatConfigPlain, formatCuratePlain, formatEnvCreatePlain, formatEnvExportPlain, formatEnvListPlain, formatEnvRemovePlain, formatEventLine, formatEventsPlain, formatFeedbackPlain, formatImportPlain, formatIndexPlain, formatInfoPlain, formatInitPlain, formatListPlain, formatModelsListPlain, formatRegistryAddPlain, formatRegistryListPlain, formatRegistryRemovePlain, formatRegistrySearchPlain, formatRememberPlain, formatRemovePlain, formatSearchPlain, formatSyncPlain, formatUpdatePlain, formatUpgradePlain, } from "./command-format.js";
 export { formatHealthPlain } from "./health-format.js";
 export { formatLintPlain } from "./lint-format.js";
-export { formatGateDecisionSummary, formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalProducerPlain, formatProposalRejectPlain, formatProposalShowPlain, } from "./proposal-format.js";
+export { formatGateDecisionSummary, formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalProducerPlain, formatProposalRejectPlain, formatProposalReopenBatchPlain, formatProposalReopenPlain, formatProposalShowPlain, } from "./proposal-format.js";
 export { formatShowPlain } from "./show-format.js";
 export { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowPlanPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";

package/dist/output/text/proposal/proposal.js

@@ -2,12 +2,14 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 // Output text formatters for `akm proposal *` (#225).
-import { formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalRejectPlain, formatProposalShowPlain, } from "../helpers.js";
+import { formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalRejectPlain, formatProposalReopenBatchPlain, formatProposalReopenPlain, formatProposalShowPlain, } from "../helpers.js";
 export const proposalFormatters = [
     { command: "proposal-list", handler: (r) => formatProposalListPlain(r) },
     { command: "proposal-show", handler: (r) => formatProposalShowPlain(r) },
     { command: "proposal-accept", handler: (r) => formatProposalAcceptPlain(r) },
     { command: "proposal-reject", handler: (r) => formatProposalRejectPlain(r) },
+    { command: "proposal-reopen", handler: (r) => formatProposalReopenPlain(r) },
+    { command: "proposal-reopen-batch", handler: (r) => formatProposalReopenBatchPlain(r) },
     { command: "proposal-diff", handler: (r) => formatProposalDiffPlain(r) },
     { command: "proposal-drain", handler: (r) => formatProposalDrainPlain(r) },
 ];

package/dist/output/text/proposal-format.js

@@ -113,6 +113,47 @@ export function formatProposalListPlain(r) {
     }
     return lines.join("\n").trimEnd();
 }
+/**
+ * A retire proposal's verdict lines — the pair judge's label and reason, and
+ * the continuity check's failing queries — as `proposal show` and `proposal
+ * diff` both print them. `retirement` is the stored block, which `proposal
+ * diff` reports under the same keys.
+ */
+function retireVerdictLines(retirement) {
+    const lines = [
+        `retire.label: ${String(retirement.judgeLabel)} (cosine=${String(retirement.cosine)})`,
+        `retire.reason: ${String(retirement.judgeReason)}`,
+    ];
+    // Item 1 (continuity check): flagged, but still minted — never swept by a
+    // bulk accept, only acceptable by id, so a reviewer must see it.
+    const continuityRisk = retirement.continuityRisk;
+    if (continuityRisk) {
+        const failingQueries = typeof continuityRisk.failingQueries === "number" ? continuityRisk.failingQueries : 0;
+        const unverifiedQueries = typeof continuityRisk.unverifiedQueries === "number" ? continuityRisk.unverifiedQueries : 0;
+        const summary = [];
+        if (failingQueries > 0) {
+            summary.push(`${failingQueries} of the retired asset's own quer${failingQueries === 1 ? "y" : "ies"} would not have found the successor top 10`);
+        }
+        // S2: a query the search call never ran, or that fell back to
+        // keyword-only ranking, is never silently trusted OR silently
+        // dropped — it excludes the proposal from bulk accept on its own.
+        if (unverifiedQueries > 0) {
+            summary.push(`${unverifiedQueries} quer${unverifiedQueries === 1 ? "y" : "ies"} unverified (search failed or used the keyword-only fallback)`);
+        }
+        lines.push(`retire.continuityRisk: ${summary.join("; ")} — excluded from bulk accept`);
+        // N3 / S4: the actual failing query text, not just the count — a
+        // reviewer deciding whether to accept by id needs to see what would
+        // stop resolving, not just how many queries.
+        const ranks = Array.isArray(continuityRisk.ranks) ? continuityRisk.ranks : [];
+        for (const rank of ranks) {
+            const successorRank = rank.successorRank === null || rank.successorRank === undefined
+                ? "absent from top 10"
+                : `#${String(rank.successorRank)}`;
+            lines.push(`  - "${String(rank.query)}": retired #${String(rank.retiredRank)}, successor ${successorRank}`);
+        }
+    }
+    return lines;
+}
 export function formatProposalShowPlain(r) {
     const p = r.proposal;
     const lines = [];
@@ -150,42 +191,24 @@ export function formatProposalShowPlain(r) {
         if (review.decidedAt)
             lines.push(`review.decidedAt: ${String(review.decidedAt)}`);
     }
+    // `akm proposal reopen` (#997): the rejection each reopen undid, so a
+    // pending proposal that was once rejected says so.
+    const history = Array.isArray(p.reviewHistory) ? p.reviewHistory : [];
+    for (const entry of history) {
+        const undone = entry.review;
+        const was = undone
+            ? `${String(undone.outcome ?? "?")}${undone.reason ? `: ${String(undone.reason)}` : ""} (${String(undone.decidedAt ?? "?")})`
+            : "an unrecorded review";
+        const why = entry.reopenReason ? ` (${String(entry.reopenReason)})` : "";
+        lines.push(`reopened: ${String(entry.reopenedAt)}${why}, undoing ${was}`);
+    }
     // alpha.9: a consolidate retire proposal writes no content (`payload.content`
     // is empty by design) — this is the reason a reviewer needs instead. `diff`
     // shows the body being retired.
     const retirement = p.retirement;
     if (retirement) {
         lines.push(`retire: ${String(retirement.retiredRef)} -> ${String(retirement.successorRef)}`);
-        lines.push(`retire.label: ${String(retirement.judgeLabel)} (cosine=${String(retirement.cosine)})`);
-        lines.push(`retire.reason: ${String(retirement.judgeReason)}`);
-        // Item 1 (continuity check): flagged, but still minted — never swept by a
-        // bulk accept, only acceptable by id, so a reviewer must see it here.
-        const continuityRisk = retirement.continuityRisk;
-        if (continuityRisk) {
-            const failingQueries = typeof continuityRisk.failingQueries === "number" ? continuityRisk.failingQueries : 0;
-            const unverifiedQueries = typeof continuityRisk.unverifiedQueries === "number" ? continuityRisk.unverifiedQueries : 0;
-            const summary = [];
-            if (failingQueries > 0) {
-                summary.push(`${failingQueries} of the retired asset's own quer${failingQueries === 1 ? "y" : "ies"} would not have found the successor top 10`);
-            }
-            // S2: a query the search call never ran, or that fell back to
-            // keyword-only ranking, is never silently trusted OR silently
-            // dropped — it excludes the proposal from bulk accept on its own.
-            if (unverifiedQueries > 0) {
-                summary.push(`${unverifiedQueries} quer${unverifiedQueries === 1 ? "y" : "ies"} unverified (search failed or used the keyword-only fallback)`);
-            }
-            lines.push(`retire.continuityRisk: ${summary.join("; ")} — excluded from bulk accept`);
-            // N3 / S4: the actual failing query text, not just the count — a
-            // reviewer deciding whether to accept by id needs to see what would
-            // stop resolving, not just how many queries.
-            const ranks = Array.isArray(continuityRisk.ranks) ? continuityRisk.ranks : [];
-            for (const rank of ranks) {
-                const successorRank = rank.successorRank === null || rank.successorRank === undefined
-                    ? "absent from top 10"
-                    : `#${String(rank.successorRank)}`;
-                lines.push(`  - "${String(rank.query)}": retired #${String(rank.retiredRank)}, successor ${successorRank}`);
-            }
-        }
+        lines.push(...retireVerdictLines(retirement));
     }
     const validation = r.validation;
     if (validation) {
@@ -215,7 +238,10 @@ export function formatProposalShowPlain(r) {
         }
     }
     const payload = p.payload;
-    if (payload && typeof payload.content === "string") {
+    // A retire proposal's payload is empty by design (it archives a file, it
+    // writes none): a bare `payload:` heading reads as "replaced by nothing" —
+    // the misreading #997 is about — so the retirement lines above stand alone.
+    if (!retirement && payload && typeof payload.content === "string") {
         lines.push("");
         lines.push("payload:");
         lines.push(payload.content);
@@ -229,6 +255,18 @@ export function formatProposalRejectPlain(r) {
     const reason = r.reason ? ` (${String(r.reason)})` : "";
     return `Rejected proposal ${String(r.id)} (${String(r.ref)})${reason}`;
 }
+export function formatProposalReopenPlain(r) {
+    const reason = r.reason ? ` (${String(r.reason)})` : "";
+    return `Reopened proposal ${String(r.id)} (${String(r.ref)}) [pending]${reason}`;
+}
+export function formatProposalReopenBatchPlain(r) {
+    const results = Array.isArray(r.results) ? r.results : [];
+    const reason = results[0]?.reason ? ` (${String(results[0].reason)})` : "";
+    return [
+        `Reopened ${results.length} proposal(s) [pending]${reason}`,
+        ...results.map((result) => `  ${String(result.id)}  ${String(result.ref)}`),
+    ].join("\n");
+}
 export function formatProposalDrainPlain(r) {
     const applyMode = String(r.applyMode ?? "queue");
     const promoted = Array.isArray(r.promoted) ? r.promoted : [];
@@ -257,10 +295,27 @@ export function formatProposalDrainPlain(r) {
     return lines.join("\n").trimEnd();
 }
 export function formatProposalDiffPlain(r) {
+    const unified = typeof r.unified === "string" ? r.unified : "";
+    if (r.op === "delete") {
+        // #997: a retire proposal archives its target — it does not "update" it —
+        // so the header says so, and the pair verdict and the accept/revert note
+        // sit above the file that is leaving.
+        const retirement = r.retirement;
+        const subject = retirement
+            ? `${String(retirement.retiredRef)} -> ${String(retirement.successorRef)}`
+            : String(r.ref);
+        const lines = [`# proposal ${String(r.id)} (retire: ${subject})`];
+        if (retirement)
+            lines.push(...retireVerdictLines(retirement));
+        if (typeof r.note === "string")
+            lines.push(`note: ${r.note}`);
+        if (unified)
+            lines.push(unified);
+        return lines.join("\n");
+    }
     const header = r.isNew
         ? `# proposal ${String(r.id)} (new asset: ${String(r.ref)})`
         : `# proposal ${String(r.id)} (update: ${String(r.ref)})`;
-    const unified = typeof r.unified === "string" ? r.unified : "";
     if (!unified)
         return `${header}\n(no changes)`;
     return `${header}\n${unified}`;