akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -4,21 +4,19 @@
 import path from "node:path";
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { getStringArg, parseAutoAcceptFlag, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { isFullRefInput, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
+import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getCacheDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
-import { withStateDb } from "../../core/state-db.js";
-import { clearLogFile, setLogFile } from "../../core/warn.js";
+import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
-import { getActiveCanaries, queryRecentCycleMetrics } from "../../storage/repositories/canaries-repository.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
-import { refreshCanarySet } from "./collapse-detector.js";
 import { akmImprove } from "./improve.js";
-import { buildImproveRunId, improveRunLocator, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
+import { buildImproveRunId, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
 import { resolveImprovePlan } from "./improve-strategies.js";
 let akmImproveForRun = akmImprove;
@@ -26,89 +24,79 @@ let akmImproveForRun = akmImprove;
 export function _setAkmImproveForTests(fake) {
     akmImproveForRun = fake ?? akmImprove;
 }
-// R5 — collapse-detector canary set inspection / explicit refresh. The
-// detector NEVER auto-refreshes the canary set (silent re-baselining is how a
-// slow collapse hides); this verb is the only refresh path.
-//
-// Dispatched from the parent improve run() on `scope === "canary"` — NOT a
-// citty subCommand: registering subCommands makes citty treat EVERY first
-// positional as a subcommand name, breaking `akm improve <type|ref>` outright
-// (citty throws "Unknown command memory"), and citty also re-runs the parent
-// run() after a matched subcommand.
-async function runCanaryInspection(refresh) {
-    const config = loadConfig();
-    const cfg = config.improve?.collapseDetector ?? {};
-    const result = withStateDb((stateDb) => {
-        let refreshOutcome;
-        if (refresh) {
-            const indexDb = openExistingDatabase();
-            try {
-                // Mint-first, deactivate-after (refreshCanarySet): an empty/unreadable
-                // index keeps the old baseline instead of destroying it.
-                refreshOutcome = refreshCanarySet(stateDb, indexDb, cfg) === null ? "kept-old-set" : "refreshed";
-            }
-            finally {
-                closeDatabase(indexDb);
-            }
-        }
-        const canaries = getActiveCanaries(stateDb);
-        const canarySetId = canaries[0]?.canary_set_id;
-        const recentCycles = canarySetId ? queryRecentCycleMetrics(stateDb, canarySetId, cfg.windowCycles ?? 5) : [];
-        return {
-            schemaVersion: 1,
-            ok: true,
-            refreshed: refreshOutcome === "refreshed",
-            ...(refreshOutcome === "kept-old-set"
-                ? { warning: "refresh skipped: no mintable learning entries in the index — existing canary set kept" }
-                : {}),
-            canarySetId: canarySetId ?? null,
-            canaries: canaries.map((c) => ({ id: c.id, anchorRef: c.anchor_ref, query: c.query })),
-            recentCycles: recentCycles.map((r) => ({
-                ts: r.ts,
-                pass: r.pass,
-                meanRecall: r.mean_recall,
-                meanNdcg: r.mean_ndcg,
-                distinctContentRatio: r.distinct_content_ratio,
-                acceptedActions: r.accepted_actions,
-                mergeFloorViolations: r.merge_floor_violations,
-                alerts: JSON.parse(r.alerts_json),
-            })),
-        };
-    });
-    output("improve-canary", result);
+/**
+ * Handle the `--auto-accept` flag retired in 0.9.0, returning the scope the run
+ * should actually use.
+ *
+ * citty is non-strict, so the removed flag is silently absorbed rather than
+ * rejected — which is the dangerous case. The SPACE-separated spelling
+ * (`--auto-accept 90`) leaves `90` sitting in the positional slot, where it is
+ * read as the asset-type scope: the run then matches nothing and exits 0, so a
+ * 0.8-era crontab goes dark with no error at all. Warn about the flag, and drop
+ * the poisoned positional so the run behaves as an unscoped improve instead.
+ */
+function resolveScopeAfterRetiredAutoAccept(scopeArg) {
+    const invocation = getParsedInvocation();
+    const autoAcceptRaw = invocation.getFlagValue("--auto-accept");
+    if (autoAcceptRaw === undefined && !invocation.hasFlag("--auto-accept"))
+        return scopeArg;
+    warn("[improve] --auto-accept was removed in 0.9 and is ignored; proposals always queue for review. " +
+        "Replacement: `akm improve && akm proposal drain --promote --yes`, or a `triage` block with " +
+        'applyMode: "promote" in your strategy. It becomes a hard error in 0.10.');
+    if (scopeArg !== undefined && scopeArg === autoAcceptRaw) {
+        warn(`[improve] ignoring "${scopeArg}" as a scope — it is the removed --auto-accept flag's value.`);
+        return undefined;
+    }
+    return scopeArg;
+}
+/**
+ * `akm improve canary` was removed in 0.9 (moved to
+ * `scripts/refresh-canary-set.ts`). Without this check "canary" falls through
+ * to the generic scope positional, where resolveImproveScope treats any bare
+ * word as a type filter that matches zero entries — so an unmigrated caller
+ * silently acquires the improve lock and exits 0 having done nothing, instead
+ * of getting an error.
+ */
+function rejectRetiredCanaryScope(scopeArg) {
+    if (scopeArg !== "canary")
+        return;
+    throw new UsageError('"akm improve canary" was removed in 0.9. Use `bun scripts/refresh-canary-set.ts [--refresh]` instead.', "INVALID_FLAG_VALUE");
+}
+/**
+ * `--target` was renamed to `--bundle` on `improve` in 0.9 (S8). citty is
+ * non-strict, so the retired spelling is silently absorbed rather than
+ * rejected — accepted proposals then write into the default bundle instead
+ * of the one the caller named, with exit 0 and no error. Reject it
+ * explicitly instead.
+ */
+function rejectRetiredImproveTargetFlag() {
+    if (!getParsedInvocation().hasFlag("--target"))
+        return;
+    throw new UsageError("`akm improve --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
 }
 export const improveCommand = defineCommand({
     meta: {
         name: "improve",
-        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when the selected strategy enables consolidate. `akm improve canary [--refresh]` inspects the collapse-detector canary set.",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when the selected strategy enables consolidate.",
     },
+    // Raw defineCommand, so the global output flags are declared here explicitly.
+    // Without them citty treats `--format` as a boolean and its space-separated
+    // value falls through to the `scope` positional.
     args: {
+        ...GLOBAL_OUTPUT_ARGS,
         scope: {
             type: "positional",
             description: "Optional asset type or asset ref to improve",
             required: false,
         },
         task: { type: "string", description: "Add extra guidance for this improvement pass" },
-        refresh: {
-            type: "boolean",
-            description: "(canary scope only) Mint a new collapse-detector canary set and deactivate the old one; old rows and their cycle history are retained",
-            default: false,
-        },
         "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
-        target: { type: "string", description: "Override the write target for accepted proposals" },
-        "auto-accept": {
-            type: "string",
-            description: "DEPRECATED and ignored (the 0.9.0 confidence gate was removed; proposals queue for review via `akm proposal` / the drain engine). Accepted for one minor so existing crontabs keep working; removed in 0.10.",
-        },
+        bundle: { type: "string", description: "Override the write target for accepted proposals" },
         limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
         "timeout-ms": {
             type: "string",
             description: "Wall-clock budget for the entire run in milliseconds (default: 7200000 = 2 hours)",
         },
-        "consolidate-recovery": {
-            type: "string",
-            description: "How to handle stale/incomplete consolidation journals: abort (default) or clean (remove stale journal artifacts)",
-        },
         "require-feedback-signal": {
             type: "boolean",
             description: "Only process assets with recent feedback signals (disables the proactive/high-salience fallback lanes)",
@@ -116,7 +104,7 @@ export const improveCommand = defineCommand({
         },
         "json-to-stdout": {
             type: "boolean",
-            description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
+            description: "Also emit the full persisted run result on stdout as JSON.",
             default: false,
         },
         "skip-if-locked": {
@@ -126,11 +114,11 @@ export const improveCommand = defineCommand({
         },
         strategy: {
             type: "string",
-            description: "Named improve strategy from improve.strategies or built-in strategies (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, frequent, graph-refresh, memory-focus, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
         },
         sync: {
             type: "boolean",
-            description: "Commit (and optionally push) the git-backed primary stash when the run finishes. Use --no-sync to disable. Default: on for git-backed stashes (per profile config).",
+            description: "Commit (and optionally push) the git-backed primary bundle when the run finishes. Use --no-sync to disable. Default: on for git-backed bundles (per profile config).",
         },
         push: {
             type: "boolean",
@@ -138,39 +126,32 @@ export const improveCommand = defineCommand({
         },
     },
     async run({ args }) {
-        // "canary" is a reserved scope word (never a valid asset type, and refs
-        // contain ":"): dispatch to the detector inspection verb instead of an
-        // improve run.
-        if (args.scope === "canary") {
-            await runWithJsonErrors(() => runCanaryInspection(args.refresh));
-            return;
-        }
         await runWithJsonErrors(async () => {
-            const formatFlagValue = getParsedInvocation().getFlagValue("--format");
-            if (formatFlagValue !== undefined) {
-                throw new UsageError(`akm improve does not accept --format. That flag controls output formatting for other commands (search, show, etc.).\n` +
-                    `Did you mean: akm improve (no --format flag)?`, "INVALID_FLAG_VALUE");
-            }
+            rejectRetiredImproveTargetFlag();
+            // D7 — `--format` used to be rejected here outright. It is a global flag on
+            // a command that does emit an envelope through `output()` (always on
+            // `--dry-run`, otherwise with `--json-to-stdout`), so rejecting it made
+            // improve a fourth inconsistent format behaviour rather than a documented
+            // exemption. It now applies to that envelope; progress output stays on
+            // stderr regardless.
             const jsonToStdout = args["json-to-stdout"];
-            // Deprecated (0.9.0): warns when present, has no effect. Removed in 0.10.
-            parseAutoAcceptFlag(args["auto-accept"]);
-            const targetArg = getStringArg(args, "target");
+            const targetArg = getStringArg(args, "bundle");
             const taskArg = getStringArg(args, "task");
             const dryRun = args["dry-run"];
             const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
-            const consolidateRecoveryRaw = args["consolidate-recovery"];
-            const consolidateRecovery = consolidateRecoveryRaw === undefined
-                ? undefined
-                : consolidateRecoveryRaw.trim().toLowerCase();
-            if (consolidateRecovery !== undefined && consolidateRecovery !== "abort" && consolidateRecovery !== "clean") {
-                throw new UsageError(`Invalid --consolidate-recovery value: "${consolidateRecoveryRaw}". Must be one of: abort, clean.`, "INVALID_FLAG_VALUE");
-            }
             const requireFeedbackSignal = args["require-feedback-signal"];
             const skipIfLocked = args["skip-if-locked"];
             const strategyArg = getStringArg(args, "strategy");
             const effectiveConfig = loadConfig();
-            const writeTarget = resolveWriteTarget(effectiveConfig, targetArg, { requireWritable: !dryRun });
+            const scopeArg = resolveScopeAfterRetiredAutoAccept(getStringArg(args, "scope"));
+            rejectRetiredCanaryScope(scopeArg);
+            const scopeRef = scopeArg && isFullRefInput(scopeArg) ? parseRefInput(scopeArg) : undefined;
+            const writeTarget = dryRun
+                ? undefined
+                : scopeRef
+                    ? resolveMutationTarget(effectiveConfig, scopeRef, targetArg).target
+                    : resolveWriteTarget(effectiveConfig, targetArg);
             // Resolve every enabled model-backed process before logging, signal
             // lifecycle setup, or any filesystem/database side effect.
             const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig);
@@ -197,9 +178,8 @@ export const improveCommand = defineCommand({
             // was minted at end-of-run, so SIGTERM'd runs (cron timeout) left no
             // row in improve_runs and effectively disappeared from `akm health`.
             const runId = buildImproveRunId();
-            const primaryStashDir = writeTarget.source.path;
-            const scopeArg = getStringArg(args, "scope");
-            const inferredScopeMode = (scopeArg ?? "").includes(":") ? "ref" : scopeArg ? "type" : "all";
+            const primaryStashDir = writeTarget?.source.path;
+            const inferredScopeMode = scopeRef ? "ref" : scopeArg ? "type" : "all";
             // Signal handler + exception path both flow through this helper so
             // every abnormal termination produces a row with ok:false and a
             // reason in metadata.terminated.
@@ -243,7 +223,7 @@ export const improveCommand = defineCommand({
                         dryRun,
                         resolvedPlan,
                         target: targetArg,
-                        writeTarget,
+                        ...(writeTarget ? { writeTarget } : {}),
                         ...(runId !== undefined ? { runId } : {}),
                         ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
                         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
@@ -255,7 +235,6 @@ export const improveCommand = defineCommand({
                             target: targetArg,
                             dryRun,
                             task: taskArg,
-                            ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
                         },
                     }),
                 }, {
@@ -278,12 +257,15 @@ export const improveCommand = defineCommand({
             finally {
                 clearLogFile();
             }
-            const durationMs = Date.now() - startedAtMs;
-            if (dryRun || jsonToStdout) {
+            if (dryRun) {
                 // A dry-run never persists its result, so stdout is its only result
-                // channel. --json-to-stdout remains the live-run escape hatch.
+                // channel. F4: was `process.exit(0)`, which terminates synchronously
+                // and skips pending cleanup (e.g. the `finally { clearLogFile(); }`
+                // above already ran, but any citty/runWithJsonErrors-level cleanup
+                // on the way out would not). Exit code is 0 either way — `return`
+                // alone is sufficient since success is the default `process.exitCode`.
                 output("improve", improveResult);
-                process.exit(0);
+                return;
             }
             // Default mode (0.8.0+): persist the full result as a row in the
             // `improve_runs` table of state.db (migration 003) and emit NOTHING
@@ -299,7 +281,6 @@ export const improveCommand = defineCommand({
             //      ORDER BY started_at DESC LIMIT 10"
             // runId + primaryStashDir minted up-top so signal handlers can record
             // partial runs; reuse them here for the success path.
-            const resultRef = improveRunLocator(runId);
             runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
             if (primaryStashDir) {
                 try {
@@ -308,15 +289,18 @@ export const improveCommand = defineCommand({
                 catch (err) {
                     // Stderr warning on the failure path is preferable to crashing
                     // the run after all the work has completed.
-                    process.stderr.write(`warning: failed to record improve run ${resultRef}: ${err instanceof Error ? err.message : String(err)}\n`);
+                    process.stderr.write(`warning: failed to record improve run ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
             }
             else {
-                process.stderr.write(`warning: no writable stash directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
+                process.stderr.write(`warning: no writable bundle directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
             }
-            // durationMs reserved for future use (no console emission today).
-            void durationMs;
-            process.exit(0);
+            if (jsonToStdout)
+                output("improve", improveResult);
+            // F4: was `process.exit(0)` — the run has already been fully recorded
+            // above (recordImproveRunResult / the warning path), so nothing here
+            // depends on an immediate synchronous exit. This is the last statement
+            // in the handler, so a plain fall-through is equivalent.
         });
     },
 });

package/dist/commands/improve/improve-result-file.js

@@ -9,8 +9,7 @@
  *     `improve_runs` table of `state.db` (migration 003). Stdout is empty.
  *     The existing `[improve] ...` progress log lines on stderr remain the
  *     canonical console UX.
- *   - `--json-to-stdout` restores the prior behaviour: full JSON to stdout,
- *     nothing written to state.db.
+ *   - `--json-to-stdout` additionally emits the persisted result as JSON.
  *
  * v0.8.0 storage change (this module): the previous on-disk artifact at
  * `<stash>/.akm/runs/<runId>/improve-result.json` is no longer written. The
@@ -26,7 +25,6 @@
  * single-slot artefact. We mint a fresh timestamped id for each improve run.
  */
 import crypto from "node:crypto";
-import path from "node:path";
 import { decodeImproveResult } from "../../core/improve-result.js";
 import { redactSensitiveValue } from "../../core/redaction.js";
 import { withStateDb } from "../../core/state-db.js";
@@ -45,32 +43,9 @@ export function buildImproveRunId(now = new Date()) {
     const rand = crypto.randomBytes(4).toString("hex");
     return `${iso}-${rand}`;
 }
-/**
- * Return a stable, human-recognisable reference for a given improve run.
- *
- * Historical compatibility shim: callers used to receive a stash-relative
- * file path like `.akm/runs/<runId>/improve-result.json`. With the state.db
- * migration, no such file exists, but several callers still log "wrote to
- * <path>" style messages. Returning a `state.db//improve_runs/<runId>`
- * locator preserves the "the result is at <thing>" signature so existing
- * log lines and error messages continue to make sense without rewriting
- * every call site.
- */
-export function improveRunLocator(runId) {
-    return path.join("state.db", "improve_runs", runId);
-}
 /**
  * Persist the full improve result into the `improve_runs` table of state.db.
  *
- * Backwards-compatible signature: the argument list and return type match the
- * pre-0.8.0 file-writing helper (the 0.9.0 rename from `writeImproveResultFile`
- * corrects the name, which had lied about writing a file). The returned
- * string is the `state.db//improve_runs/<runId>` locator (see
- * {@link improveRunLocator}), which is intended for log messages
- * only — no caller should treat it as a filesystem path. Zero current
- * readers existed for the previous file path, so this is a pure storage
- * swap.
- *
  * The state.db row carries the scope and dry-run flag from `result.scope`
  * and `result.dryRun`, plus the full result JSON for full fidelity. The
  * dry-run column is indexed so productivity audits can filter cleanly
@@ -94,7 +69,6 @@ export function recordImproveRunResult(stashDir, runId, result, startedAt, sensi
             completedAt,
             stashDir,
             dryRun: Boolean(result.dryRun),
-            legacyProfile: redactSensitiveValue(decoded.legacyProfile, sensitiveValues),
             strategy: redactSensitiveValue(decoded.strategy, sensitiveValues),
             scopeMode: result.scope?.mode ?? "all",
             scopeValue: persistedResult.scope?.value ?? null,
@@ -103,7 +77,6 @@ export function recordImproveRunResult(stashDir, runId, result, startedAt, sensi
             result: persistedResult,
         });
     });
-    return improveRunLocator(runId);
 }
 /**
  * Persist an improve_runs row for a run that did NOT complete normally.

package/dist/commands/improve/improve-strategies.js

@@ -16,6 +16,7 @@ import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES, } from "../../core/config/engine-semantics.js";
 import { ConfigError } from "../../core/errors.js";
 import { resolveImproveProcessRunner, resolveTriageJudgmentRunner, } from "../../integrations/agent/runner.js";
+import { applyAutonomyGate } from "./autonomy-gate.js";
 export const DEFAULT_ALLOWED_TYPES = {
     reflect: ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"],
     distill: ["memory"],
@@ -66,9 +67,6 @@ export function resolveImproveStrategy(name, config) {
     const resolved = deepMergeConfig(baseStrategy, (userStrategies[selectedName] ?? {}));
     return { name: selectedName, config: resolved };
 }
-export function resolveStrategyProcessEnabled(strategy, processName) {
-    return resolveProcessEnabled(processName, strategy.config);
-}
 function cloneAndFreeze(value) {
     const clone = structuredClone(value);
     const freeze = (item) => {
@@ -83,8 +81,13 @@ function cloneAndFreeze(value) {
 }
 /** Resolve every enabled process structurally before improve emits signals or performs I/O. */
 export function resolveImprovePlan(name, config, options = {}) {
-    const strategy = resolveImproveStrategy(name, config);
-    return buildImprovePlan(strategy, config, options);
+    const selected = resolveImproveStrategy(name, config);
+    // D8 — gate autonomy BEFORE the plan is built, so every downstream consumer
+    // (process enablement, LLM preflight, triage judgment) sees one already-safe
+    // strategy rather than each having to re-ask whether autonomy is allowed.
+    const { config: gatedStrategyConfig, gated } = applyAutonomyGate(selected.config, config);
+    const strategy = { name: selected.name, config: gatedStrategyConfig };
+    return { ...buildImprovePlan(strategy, config, options), autonomyGated: gated };
 }
 function buildImprovePlan(strategy, config, options) {
     const processes = {};