akm-cli 0.9.31 → 0.10.26101002-alpha

package/dist/commands/observability-cli.js

@@ -17,15 +17,14 @@
  * ranking's `lessonStrength` contributor is untouched, only the CLI read
  * surface for it goes away.
  *
- * The embedded agent-guide surfaces (`akm hints` and `akm help agents`) live
- * in src/cli.ts, so their loading code is intentionally outside this module.
+ * The embedded agent guide (`akm hints`) lives in src/cli.ts, so its
+ * loading code is intentionally outside this module.
  *
  * The leaf handler's body is a plain `runWithJsonErrors(...) + output(...)`,
  * migrated onto `defineJsonCommand`, which emits the same JSON envelope
  * (stdout/stderr/exit-code) as the inline form.
  */
 import { parsePositiveIntFlag } from "../cli/parse-args.js";
-import { retiredCommandHint } from "../cli/retired-commands.js";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
 import { UsageError } from "../core/errors.js";
 import { akmEventsList } from "./log.js";
@@ -42,12 +41,7 @@ function rejectExtraLogPositionals(positionals) {
     const extra = Array.isArray(positionals) ? positionals.map(String) : [];
     if (extra.length === 0)
         return;
-    // A retired subcommand spelling gets its replacement hint (same table the
-    // unknown-command path uses), so `akm log tail` teaches the durable-cursor
-    // polling pattern instead of a bare "takes no positional arguments".
-    const retired = extra[0] === undefined ? undefined : retiredCommandHint(["log"], extra[0]);
-    throw new UsageError(`akm log takes no positional arguments, but got ${extra.map((token) => `"${token}"`).join(" ")}. ` +
-        '"log list"/"log tail" were removed in 0.9.0 — `akm log` alone is today\'s `log list` surface.', "INVALID_FLAG_VALUE", retired);
+    throw new UsageError(`akm log takes no positional arguments, but got ${extra.map((token) => `"${token}"`).join(" ")}.`, "INVALID_FLAG_VALUE");
 }
 // ── `akm log` ────────────────────────────────────────────────────────────────
 // Append-only events stream surface (#204). Reads state.db events with

package/dist/commands/proposal/drain.js

@@ -9,9 +9,18 @@
  *     gate decision carrying its content hash) is accepted, unless its target
  *     changed since mint — then it is auto-rejected as `stale-target`, never
  *     overwritten;
+ *   - a proposal planned by the proactive lane (`eligibilitySource: "proactive"`,
+ *     no feedback behind it) is never accepted, by a gate or by the judgment tier,
+ *     and a staged accept does not carry it: it is left for a person with reason
+ *     `proactive-needs-review` (#1147);
  *   - everything else needs a judge: the judgment tier decides it when a runner
  *     is configured, and whatever stays undecided is left for review
  *     (`review_needed` in the improve ledger).
+ * The judgment tier may accept only a consolidate promotion (a memory proposed
+ * as a new knowledge note). Judged over every kind, it accepted unsafe
+ * retirements, applied exact fixes unreviewed and changed notes no one had
+ * touched (6 to 14 harmed items a night on two models, #1132); a promotion it
+ * judges well. Any other kind it would accept is left for a person.
  * `maxAccepts` caps promotions across both tiers; `applyMode: "queue"` never
  * promotes; `excludeIds` keeps this run's fresh proposals out; a proposal that
  * a generating stage routed to a person is left for that person.
@@ -35,6 +44,10 @@ import { isRetireProposal, PAIR_PASS_GATE, STALE_TARGET_GATE_REASON } from "./pr
 import { listProposals, listProposalsReadOnly, preflightProposalPromotion, proposalContent, proposalContentHash, readFreshProposalTarget, recordGateDecision, } from "./repository.js";
 /** The gate label on every decision the drain records. */
 const DRAIN_GATE = "triage";
+/** A consolidate promotion: a memory proposed as a new knowledge note. The only kind the judgment tier may accept. */
+export function isPromotionProposal(proposal) {
+    return proposal.source === "consolidate" && proposal.promotionSource !== undefined;
+}
 /** An empty diff: no non-blank body line outside the frontmatter. */
 export function isEmptyDiff(proposal) {
     const content = proposalContent(proposal);
@@ -246,7 +259,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
     const cappedBefore = result.skippedByCap.length;
     for (const item of result.deferred) {
         const proposal = byId.get(item.id);
-        if (!proposal) {
+        if (!proposal || item.reason === "proactive-needs-review") {
             stillDeferred.push(item);
             continue;
         }
@@ -288,6 +301,15 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
             }
             continue;
         }
+        // Only a promotion may be accepted on a judgment (#1132): anything else waits for a person.
+        if (!isPromotionProposal(proposal)) {
+            deferNotes.set(item.id, {
+                reason: "judgment-not-promotion",
+                ...(verdict.reason ? { judgeReason: verdict.reason } : {}),
+            });
+            stillDeferred.push(item);
+            continue;
+        }
         // Queue mode never writes the asset: the verdict is staged for a later promote run.
         if (opts.applyMode !== "promote") {
             if (opts.dryRun) {
@@ -317,8 +339,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
         const outcome = await acceptProposal(opts, proposal, item.id, "judgment-accept", promoteFn, rejectFn, verdict.reason);
         if (outcome === "promoted") {
             result.promoted.push(item.id);
-            if (proposal.source === "consolidate" && proposal.promotionSource !== undefined)
-                acceptedPromotions.push(proposal);
+            acceptedPromotions.push(proposal);
             acceptBudget -= 1;
         }
         else if (outcome === "rejected") {
@@ -339,7 +360,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
 }
 /** The knowledge notes nearest to a consolidate promotion's source memory; none for any other proposal. */
 function promotionNeighbours(stashDir, proposal, acceptedPromotions) {
-    if (proposal.source !== "consolidate" || proposal.promotionSource === undefined)
+    if (!isPromotionProposal(proposal) || proposal.promotionSource === undefined)
         return [];
     try {
         const parsed = parseRefInput(proposal.promotionSource);
@@ -424,14 +445,24 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         if (isEmptyDiff(proposal)) {
             empties.push(proposal.id);
         }
+        else if (proposal.eligibilitySource === "proactive") {
+            // Planned by the proactive lane (no feedback behind it): never accepted
+            // here, whatever a judge or an earlier drain staged. A person decides (#1147).
+            result.deferred.push({ id: proposal.id, reason: "proactive-needs-review" });
+        }
         else if (decision?.outcome === "staged" && decision.contentHash === proposalContentHash(proposal)) {
+            // A judgment accept staged by an earlier drain obeys the same rule: only a promotion.
+            if (decision.gate === DRAIN_GATE && !isPromotionProposal(proposal)) {
+                result.deferred.push({ id: proposal.id, reason: "needs-judgment" });
+                continue;
+            }
             accepts.push({ id: proposal.id, reason: decision.gate === "quality-gate" ? "judge-passed" : "judgment-accept" });
         }
         else {
             result.deferred.push({ id: proposal.id, reason: "needs-judgment" });
         }
     }
-    if (opts.judgment && result.deferred.length > 0) {
+    if (opts.judgment && result.deferred.some((d) => d.reason === "needs-judgment")) {
         // Symbolic credentials, and the runner's model-work tool policy, are checked before any gate, reject or promote.
         const prepared = resolveExecution({
             content: "Validate the selected proposal judgment runner before mutation.",
@@ -488,7 +519,9 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     if (!opts.dryRun) {
         for (const item of result.deferred) {
             const note = deferNotes.get(item.id);
-            const reviewReason = note?.reason ?? (opts.judgment ? "judgment-deferred" : "no-judge-configured");
+            const reviewReason = item.reason === "proactive-needs-review"
+                ? item.reason
+                : (note?.reason ?? (opts.judgment ? "judgment-deferred" : "no-judge-configured"));
             try {
                 recordGateDecision(opts.stashDir, item.id, {
                     outcome: "deferred",

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

@@ -13,7 +13,6 @@
  * commands are absorbed here as `extract` and `new` — no top-level
  * registration remains for either spelling.
  */
-import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
 import { resolveStashDir } from "../../core/common.js";
@@ -36,20 +35,6 @@ export function mergeProposalDrainNotices(resolutionNotices, dispatchNotices) {
         byKey.set(JSON.stringify(notice), notice);
     return byKey.size > 0 ? Object.freeze([...byKey.values()]) : undefined;
 }
-/**
- * `--source` was renamed to `--generator` on `proposal accept`/`proposal
- * reject` in 0.9 (WS3/S8 — "Removed in 0.9.0"). citty is non-strict, so the
- * retired spelling is silently absorbed rather than rejected — a bulk
- * accept/reject invoked with `--source <name>` then has neither `--generator`
- * nor a positional id, and falls through to the single-proposal path, which
- * throws MISSING_REQUIRED_ARGUMENT instead of running the bulk action the
- * caller asked for. Reject it explicitly instead.
- */
-function rejectRetiredProposalSourceFlag(subcommand) {
-    if (!getParsedInvocation().hasFlag("--source"))
-        return;
-    throw new UsageError(`\`akm proposal ${subcommand} --source\` was renamed to \`--generator\` in 0.9. Use \`--generator <name>\` instead.`, "INVALID_FLAG_VALUE");
-}
 /**
  * Parse + validate the shared bulk-adjudication filter flags
  * (`--max-diff-lines`, `--older-than`). Extracted from the two verbatim
@@ -117,7 +102,7 @@ const proposalAcceptCommand = defineJsonCommand({
             required: false,
         },
         queue: { type: "string", description: "Select the proposal queue by source name" },
-        target: { type: "string", description: "Write destination; must match the proposal's recorded target" },
+        bundle: { type: "string", description: "Write destination; must match the proposal's recorded target" },
         // F-6 / #393: Batch accept by generator, diff size, or age.
         generator: {
             type: "string",
@@ -144,7 +129,6 @@ const proposalAcceptCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        rejectRetiredProposalSourceFlag("accept");
         const generator = args.generator;
         // F-6 / #393: Bulk-accept when --generator is provided without a positional id.
         if (generator && !args.id) {
@@ -162,7 +146,7 @@ const proposalAcceptCommand = defineJsonCommand({
                 olderThanMs,
                 dryRun: args["dry-run"],
                 queue: args.queue,
-                target: args.target,
+                target: args.bundle,
             });
             output("proposal-accept-batch", {
                 accepted: count,
@@ -182,7 +166,7 @@ const proposalAcceptCommand = defineJsonCommand({
         const result = await akmProposalAccept({
             id: args.id,
             queue: args.queue,
-            target: args.target,
+            target: args.bundle,
         });
         output("proposal-accept", result);
     },
@@ -223,7 +207,6 @@ const proposalRejectCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        rejectRetiredProposalSourceFlag("reject");
         const generator = args.generator;
         if (!args.reason || !String(args.reason).trim()) {
             throw new UsageError("Usage: akm proposal reject <id> --reason '<reason>'  OR  akm proposal reject --generator <generator> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
@@ -312,10 +295,10 @@ const proposalDiffCommand = defineJsonCommand({
             required: true,
         },
         queue: { type: "string", description: "Select the proposal queue by source name" },
-        target: { type: "string", description: "Diff destination; must match the proposal's recorded target" },
+        bundle: { type: "string", description: "Diff destination; must match the proposal's recorded target" },
     },
     run({ args }) {
-        const result = akmProposalDiff({ id: args.id, queue: args.queue, target: args.target });
+        const result = akmProposalDiff({ id: args.id, queue: args.queue, target: args.bundle });
         output("proposal-diff", result);
     },
 });
@@ -342,13 +325,13 @@ const proposalRevertCommand = defineJsonCommand({
             required: true,
         },
         queue: { type: "string", description: "Select the proposal queue by source name" },
-        target: { type: "string", description: "Write destination; must match the proposal's recorded target" },
+        bundle: { type: "string", description: "Write destination; must match the proposal's recorded target" },
     },
     async run({ args }) {
         const result = await akmProposalRevert({
             id: args.id,
             queue: args.queue,
-            target: args.target,
+            target: args.bundle,
         });
         output("proposal-revert", result);
     },
@@ -372,7 +355,7 @@ const proposalShowCommand = defineJsonCommand({
 const proposalDrainCommand = defineJsonCommand({
     meta: {
         name: "drain",
-        description: "Drain the pending proposal backlog: accept what a quality judge passed, reject empty diffs, leave the rest for judgment or review",
+        description: "Drain the pending proposal backlog: accept what a quality judge passed, reject empty diffs, leave the rest for judgment or review. The judgment tier accepts only consolidate promotions; it accepted unsafe retirements and unreviewed fixes in testing (#1132), so every other kind waits for a person",
     },
     args: {
         "dry-run": {
@@ -401,7 +384,7 @@ const proposalDrainCommand = defineJsonCommand({
         },
         judgment: {
             type: "boolean",
-            description: "Enable the judgment tier for this drain (overrides judgment.enabled=false; agent/sdk per config). No-op with a logged triage_deferred summary when no runner is configured.",
+            description: "Enable the judgment tier for this drain (overrides judgment.enabled=false; agent/sdk per config). It accepts only consolidate promotions; every other kind it would accept is left for review. No-op with a logged triage_deferred summary when no runner is configured.",
             default: false,
         },
         strategy: {
@@ -409,10 +392,7 @@ const proposalDrainCommand = defineJsonCommand({
             description: "Read the triage block (applyMode, ceilings, judgment) from this improve strategy; enabled judgment runs the judge.",
         },
     },
-    async run({ args, rawArgs }) {
-        if (rawArgs.some((arg) => arg === "--profile" || arg.startsWith("--profile="))) {
-            throw new UsageError("proposal drain: --profile is retired; use --strategy.", "INVALID_FLAG_VALUE");
-        }
+    async run({ args }) {
         const stashDir = resolveStashDir();
         const cfg = loadConfig();
         // Phase 2: read the triage block from the named improve strategy. CLI flags
@@ -423,7 +403,7 @@ const proposalDrainCommand = defineJsonCommand({
         const applyMode = args.promote === true ? "promote" : (triageConfig?.applyMode ?? "queue");
         const maxAccepts = parsePositiveIntFlag(args["max-accepts"], "--max-accepts") ??
             triageConfig?.maxAcceptsPerRun ??
-            25;
+            200;
         const rawOlderThan = parsePositiveIntFlag(args["older-than"], "--older-than");
         const olderThanMs = rawOlderThan !== undefined ? rawOlderThan * 86_400_000 : undefined;
         // Promotion in promote mode is destructive (commits to git, no batch revert).

package/dist/commands/proposal/repository.js

@@ -824,7 +824,7 @@ function resolveRecordedProposalTarget(config, proposalId, binding, explicitTarg
     const targetBundleId = canonicalBundleIdForTarget(config, target);
     if (targetBundleId !== binding.source || path.resolve(target.source.path) !== path.resolve(binding.root)) {
         throw new UsageError(`Proposal ${proposalId} is bound to target "${binding.source}" at ${binding.root}; ` +
-            `--target "${explicitTarget}" resolves to "${targetBundleId}" at ${target.source.path}.`, "INVALID_FLAG_VALUE");
+            `--bundle "${explicitTarget}" resolves to "${targetBundleId}" at ${target.source.path}.`, "INVALID_FLAG_VALUE");
     }
     return { ...target, source: { ...target.source, name: targetBundleId } };
 }
@@ -841,7 +841,7 @@ function resolveProposalWriteTarget(config, proposal, explicitTarget, queueTarge
             const target = named(resolveBundleWriteTarget(config, identity.bundle));
             if (explicitTarget !== undefined &&
                 canonicalBundleIdForTarget(config, resolveWriteTarget(config, explicitTarget)) !== identity.bundle) {
-                throw new UsageError(`Proposal ${proposal.id} ref is bound to bundle "${identity.bundle}", which conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE");
+                throw new UsageError(`Proposal ${proposal.id} ref is bound to bundle "${identity.bundle}", which conflicts with --bundle "${explicitTarget}".`, "INVALID_FLAG_VALUE");
             }
             if (queueTarget && canonicalBundleIdForTarget(config, queueTarget) !== identity.bundle) {
                 throw new UsageError(`Proposal ${proposal.id} is bound to a different queue target.`, "INVALID_FLAG_VALUE");
@@ -850,7 +850,7 @@ function resolveProposalWriteTarget(config, proposal, explicitTarget, queueTarge
         }
         const target = explicitTarget ? resolveWriteTarget(config, explicitTarget) : queueTarget;
         if (!target) {
-            throw new UsageError(`Unbound short proposal ${proposal.id} requires an explicit --target or authenticated --queue context.`, "INVALID_PROPOSAL");
+            throw new UsageError(`Unbound short proposal ${proposal.id} requires an explicit --bundle or authenticated --queue context.`, "INVALID_PROPOSAL");
         }
         return named(target);
     }

package/dist/commands/read/knowledge.js

@@ -491,7 +491,7 @@ export function resolveSupersedesForWrite(rawRefs, target, targetFlag) {
                 : {
                     reason: namedWritableSource
                         ? `resolves outside the write target and the working stash, in writable source "${namedWritableSource}" at ${root}; ` +
-                            `re-run with ${targetFlag ?? "--target"} ${namedWritableSource} to demote it there`
+                            `re-run with ${targetFlag ?? "--bundle"} ${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",
                 }),
@@ -506,7 +506,7 @@ export function resolveSupersedesForWrite(rawRefs, target, targetFlag) {
 /**
  * Write a markdown asset (knowledge or memory) to the resolved write target.
  *
- * Resolves the write target via the v1 precedence chain (`--target` →
+ * Resolves the write target via the v1 precedence chain (`--bundle` →
  * `defaultWriteTarget` → working stash), validates the path is within the
  * type root, enforces `--force` semantics, and delegates the actual write
  * to `writeAssetToSource`.
@@ -613,7 +613,7 @@ export async function writeMarkdownAsset(options) {
     // Write-path indexing: the asset is searchable immediately. Fail-open; reads
     // no longer trigger reindexes, so keeping the index current is the writer's
     // job. Demoted files reindex under their own containing root (usually the
-    // write target itself; the working stash when writing to a --target) so
+    // write target itself; the working stash when writing to a --bundle) so
     // `--belief current` filtering takes effect without waiting for the next
     // full index. (alpha.4 removed belief weights from ranking; `--belief` is
     // the only reader of `beliefState` today.)

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

@@ -1,7 +1,6 @@
 // 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/.
-import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
@@ -35,17 +34,6 @@ async function fetchSimilarMemories(query, excludeRef, eventSource) {
 }
 /** 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
- * rejected — the memory then lands in the default bundle instead of the one
- * the caller named, with exit 0 and no error. Reject it explicitly instead.
- */
-function rejectRetiredTargetFlag() {
-    if (!getParsedInvocation().hasFlag("--target"))
-        return;
-    throw new UsageError("`akm remember --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
-}
 // ── Command definition ────────────────────────────────────────────────────────
 export const rememberCommand = defineJsonCommand({
     meta: {
@@ -140,7 +128,6 @@ export const rememberCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        rejectRetiredTargetFlag();
         const body = readMemoryContent(args.content);
         const eventSource = resolveUsageEventSource();
         // `--name` is a flat name; subdirectory placement is `--path`'s job.

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

@@ -24,24 +24,6 @@ import { deliverRendered } from "../../output/html-render.js";
 import { akmCurate, packCuratedHits } from "./curate.js";
 import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
-/**
- * `--source` was renamed to `--from` on `search`/`curate` in 0.9 (S8). citty
- * is non-strict, so the retired spelling is silently absorbed rather than
- * rejected — the command then runs against the DEFAULT `--from` value
- * (local) instead of the source the caller named, with exit 0 and no error.
- * Reject it explicitly instead.
- *
- * Exported so `akm task list` (`../tasks/tasks-cli.ts`, #951) — a pure
- * delegating alias for `akm search --type task` — applies the identical
- * guard rather than a second copy of it; a task-list-scoped `--source` must
- * fail exactly like `search`'s does, not fall through to citty's silent
- * unknown-flag absorption.
- */
-export function rejectRetiredSourceFlag() {
-    if (!getParsedInvocation().hasFlag("--source"))
-        return;
-    throw new UsageError("`--source` was renamed to `--from` in 0.9. Use `--from local|registry|all` instead.", "INVALID_FLAG_VALUE");
-}
 export const searchCommand = defineJsonCommand({
     meta: { name: "search", description: "Search the bundle" },
     args: {
@@ -83,7 +65,6 @@ export const searchCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        rejectRetiredSourceFlag();
         const query = (args.query ?? "").trim();
         const type = args.type;
         const limit = parsePositiveIntFlag(args.limit ?? undefined);
@@ -140,24 +121,9 @@ export const curateCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        rejectRetiredSourceFlag();
-        if (!args.query || !String(args.query).trim()) {
-            throw new UsageError('A curate query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Describe the task you want assets for, e.g. `akm curate "deploy to prod"`.');
-        }
-        const type = args.type;
-        const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
-        const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
-        const source = parseSearchSource(args.from ?? "local");
-        const outputMode = getOutputMode();
         const packBudget = parsePositiveIntFlag(args.pack ?? undefined, "--pack");
-        const curated = await akmCurate({
-            query: args.query,
-            type,
-            limit,
-            source,
-            eventSource: resolveUsageEventSource(),
-            attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
-        });
+        const outputMode = getOutputMode();
+        const curated = await runCurate({ query: args.query, type: args.type, limit: args.limit, from: args.from }, outputMode);
         if (packBudget !== undefined) {
             const packed = await packCuratedHits(curated, packBudget);
             deliverRendered(outputMode.format === "text" ? formatCuratePackText(packed) : JSON.stringify(packed.items, null, 2), outputMode.outputPath);
@@ -166,6 +132,27 @@ export const curateCommand = defineJsonCommand({
         output("curate", curated);
     },
 });
+/**
+ * Validate the curate arguments and run the curation. The one path both
+ * `akm curate` and the in-process `curate()` of `src/api.ts` go through, so
+ * argument errors and ranking cannot drift between them. Takes the output
+ * mode explicitly (it only picks the attribution projection) instead of
+ * reading the process-level singleton.
+ */
+export async function runCurate(args, outputMode) {
+    if (!args.query || !String(args.query).trim()) {
+        throw new UsageError('A curate query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Describe the task you want assets for, e.g. `akm curate "deploy to prod"`.');
+    }
+    const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
+    return akmCurate({
+        query: args.query,
+        type: args.type,
+        limit: limitParsed && limitParsed > 0 ? limitParsed : 4,
+        source: parseSearchSource(args.from ?? "local"),
+        eventSource: resolveUsageEventSource(),
+        attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
+    });
+}
 /** Human-readable rendering for `akm curate --pack`: concatenated content per hit under a `## <ref>` header. */
 function formatCuratePackText(packed) {
     if (packed.items.length === 0) {
@@ -174,62 +161,16 @@ function formatCuratePackText(packed) {
     return packed.items.map((item) => `## ${item.ref}\n\n${item.content}`).join("\n\n");
 }
 /**
- * Reject `--scope` (either spelling) on `akm show` (E-3). `--scope` was
- * removed in favor of `--filter` (R-047, guardrail 6 — no alias, must keep
- * failing loudly, not silently). It is deliberately NOT a declared flag on
- * this command, which means citty's default behavior for an undeclared flag
- * kicks in — and that default is silent acceptance:
- *
- *   - `--scope=user=nobody` (equals form): citty consumes it as an unknown
- *     flag's own inline value. It never reaches `args._`, so nothing downstream
- *     ever notices — the command runs to completion and exits 0, having
- *     silently ignored the caller's (unsatisfied) scope request. This is the
- *     dangerous case: the caller believes a read was scoped when it was not,
- *     and it directly violates guardrail 6's "removed spelling must fail
- *     loudly, not silently".
- *   - `--scope user=nobody` (space form): citty treats `--scope` as boolean
- *     and pushes `user=nobody` into `args._` as a stray positional, which
- *     incidentally trips `rejectExtraShowPositionals`'s arity check below —
- *     but with the wrong diagnosis (it blames the unrelated retired
- *     `toc|section|lines|frontmatter|full` view-mode grammar).
- *
- * This check runs FIRST, before the positional check, so both spellings are
- * caught by one explicit, correctly-worded error — it does NOT make `--scope`
- * work, it only makes the failure loud and the diagnosis accurate.
- *
- * NOTE (general issue, out of scope here): citty silently accepts ANY
- * undeclared flag on ANY command (e.g. `akm info --totallybogus` exits 0) —
- * this same silent-ignore failure mode applies repo-wide, not just to
- * `--scope` on `show`. Fixing that generally is a separate, wide-blast-radius
- * owner decision (same family as E-2, `akm list --type skill`); this function
- * only closes the `--scope`/`show` instance of it.
- */
-function rejectRemovedScopeFlag(ref) {
-    const usedScopeFlag = getParsedInvocation().userArgs.some((token) => token === "--scope" || token.startsWith("--scope="));
-    if (!usedScopeFlag)
-        return;
-    throw new UsageError("akm show has no --scope flag — it was removed in 0.9.0. Use --filter instead: " +
-        "--filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>.", "INVALID_FLAG_VALUE", `\`akm show ${ref} --filter user=<id>\` narrows resolution to assets whose frontmatter scope matches.`);
-}
-/**
- * Reject any positional after the ref. The
- * `akm show <ref> toc|section "H"|lines A B|frontmatter|full` view grammar was
- * removed in 0.9.0; its keywords used to be rewritten into hidden flags before
- * citty saw argv, so without this guard a stale invocation would silently
- * render the whole item instead of the view the caller asked for.
- *
- * `--scope` is handled separately, and earlier, by {@link rejectRemovedScopeFlag}
- * — by the time this runs, a `--scope`-caused stray positional has already
- * been intercepted with the correct diagnosis, so this function's generic
- * message is reached only by genuine leftover view-grammar tokens.
+ * Reject any positional after the ref: `akm show` takes one ref, and a stray
+ * token would otherwise silently render the whole item instead of what the
+ * caller asked for.
  */
 function rejectExtraShowPositionals(positionals, ref) {
     const extra = (Array.isArray(positionals) ? positionals.map(String) : []).slice(1);
     if (extra.length === 0)
         return;
     throw new UsageError(`akm show takes a single ref, but got ${extra.map((token) => `"${token}"`).join(" ")} after "${ref}". ` +
-        "The view-mode grammar (toc|section|lines|frontmatter|full) was removed in 0.9.0 — use " +
-        `\`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", "An unmatched #fragment lists the available slugs.");
+        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", "An unmatched #fragment lists the available slugs.");
 }
 export const showCommand = defineJsonCommand({
     meta: {
@@ -265,10 +206,8 @@ export const showCommand = defineJsonCommand({
         // direct-read it. (the ref parser would reject the non-type `meta`.)
         if (!parseMetaRef(args.ref))
             parseBundleRef(args.ref);
-        rejectRemovedScopeFlag(args.ref);
         rejectExtraShowPositionals(args._, args.ref);
         const invocation = getParsedInvocation();
-        const cliShape = getOutputMode().shape;
         // F6/R-021 — `show` deliberately does NOT inherit `output.detail` from
         // config the way `search`/`curate` do via `getOutputMode().detail`
         // (which merges an explicit `--detail` flag with the config default,
@@ -282,15 +221,8 @@ export const showCommand = defineJsonCommand({
         // `--detail full` (explicit or, since it's also the implicit default,
         // omitted) and any other value fall through to the full response.
         const explicitDetail = invocation.getFlagValue("--detail");
-        // `--shape summary` selects the compact metadata projection for show.
-        // `--detail brief` forces the brief response regardless of shape.
-        const showDetail = explicitDetail === "brief"
-            ? "brief"
-            : explicitDetail === "full"
-                ? "full"
-                : cliShape === "summary"
-                    ? "summary"
-                    : undefined;
+        // `--detail brief` forces the brief response regardless of projection.
+        const showDetail = explicitDetail === "brief" ? "brief" : explicitDetail === "full" ? "full" : undefined;
         // `--filter` is repeatable — citty only exposes the last value, so read
         // every occurrence directly from argv (same helper as `akm search`; the two
         // commands share one spelling for the scope-narrowing axis).

package/dist/commands/read/search.js

@@ -366,17 +366,6 @@ export function parseSearchSource(source) {
         return source;
     if (typeof source === "undefined")
         return "local";
-    // 0.9.0 (S8): `--source stash`/`--source both` renamed to `--from
-    // local`/`--from all`. Reject the retired values explicitly — otherwise
-    // they fall through to the named-source lookup below and surface as a
-    // misleading "no source named stash/both" error instead of naming the
-    // rename.
-    if (source === "stash") {
-        throw new UsageError('"stash" was renamed to "local" in 0.9. Use `--from local` instead.', "INVALID_FLAG_VALUE");
-    }
-    if (source === "both") {
-        throw new UsageError('"both" was renamed to "all" in 0.9. Use `--from all` instead.', "INVALID_FLAG_VALUE");
-    }
     // Pass through unknown strings — they may be valid named sources.
     // `akmSearch` will validate against config.sources and throw a UsageError
     // with a helpful message if the name isn't found.

package/dist/commands/read/show.js

@@ -67,11 +67,6 @@ export async function akmShowUnified(input) {
         if (metaRef)
             return showStashMeta(metaRef);
     }
-    const legacyReplacement = legacyColonRefReplacement(ref);
-    if (legacyReplacement) {
-        throw new NotFoundError(`The legacy colon ref "${ref}" was removed in 0.9.0. Use the slash form instead: ` +
-            `akm show ${legacyReplacement}`);
-    }
     // Env/secret bodies have no safe fragment surface, and a fragment cannot
     // widen what the env/secret renderers expose: both always omit the body
     // (env — key names only; secret — never rendered), fragment or not. Warn
@@ -107,20 +102,6 @@ export async function akmShowUnified(input) {
     }
     return result;
 }
-/** Actionable migration guidance for the retired `[bundle//]type:name` spelling. */
-function legacyColonRefReplacement(ref) {
-    const match = /^(?:(?<bundle>[^/#]+)\/\/)?(?<type>[a-z][a-z0-9-]*):(?<name>[^#]+)(?<fragment>#.*)?$/i.exec(ref);
-    const type = match?.groups?.type?.toLowerCase();
-    const name = match?.groups?.name;
-    if (!type || !name)
-        return undefined;
-    const stashDir = stashDirFor(type);
-    if (!stashDir)
-        return undefined;
-    const bundle = match?.groups?.bundle;
-    const fragment = match?.groups?.fragment ?? "";
-    return `${bundle ? `${bundle}//` : ""}${stashDir}/${name}${fragment}`;
-}
 /**
  * Resolve a stash `.meta/` doc and return it as a lightweight ShowResponse.
  *