akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/improve/run-context.js

@@ -42,7 +42,6 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../../core/common.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
-import { chatCompletion } from "../../llm/client.js";
 /**
  * Build a `RunContext` over the given carriers with the supplied memo (or `null`
  * for the non-memoizing base context). Kept private so the only way to obtain a
@@ -56,7 +55,7 @@ function buildRunContext(carriers, memo) {
         eventsCtx: carriers.eventsCtx,
         proposalsCtx: carriers.proposalsCtx,
         chat: carriers.chat,
-        getLlmConfig: carriers.getLlmConfig,
+        getLlmRunner: carriers.getLlmRunner,
         sourceRun: carriers.sourceRun,
         dryRun: carriers.dryRun,
         signal: carriers.signal,
@@ -99,8 +98,8 @@ export function createRunContext(init) {
         config: init.config,
         eventsCtx: init.eventsCtx,
         proposalsCtx: init.proposalsCtx,
-        chat: init.chat ?? chatCompletion,
-        getLlmConfig: init.getLlmConfig,
+        chat: init.chat,
+        getLlmRunner: init.getLlmRunner ?? (() => null),
         sourceRun: init.sourceRun,
         dryRun: init.dryRun,
         signal: init.signal,

package/dist/commands/improve/salience.js

@@ -1,52 +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/.
-/**
- * WS-1 — Unified SALIENCE model (S1 seam).
- *
- * Replaces the three competing attention formulas that existed across:
- *   - proactive-maintenance.ts:186 — `importance × log(1+freq) × recencyDecay / log10(size)`
- *   - feedback-valence.ts:111      — `combinedEligibilityScore = utility·0.7 + valence·0.3`
- *   - getUtilityScoresByIds        — MemRL utility EMA (#386)
- *
- * ## Salience vector (three independently-stored, independently-decayable sub-scores)
- *
- * | Sub-score         | Brain analogy          | Source                          |
- * |-------------------|------------------------|---------------------------------|
- * | `encodingSalience`| Amygdala tagging (Gap 1)| Set at extract; v1 = type weight|
- * | `outcomeSalience` | Dopaminergic outcome   | WS-2 (0 until that lands)       |
- * | `retrievalSalience`| Hippocampal frequency+recency | usage_events + utility_scores |
- *
- * ## Projection
- *
- * `rankScore = (w_e·encoding + w_o·outcome + w_r·retrieval) × sizePenalty`, normalized [0,1].
- *
- * **WS-2 default-ON (R1 loop closure):**
- * `w_o = 0.15` is applied by default now that `outcome_score` saturates at
- * `OUTCOME_SCORE_MAX` (G2). Operators can opt out via
- * `improve.salience.outcomeWeightEnabled: false`, which restores the WS-1
- * parity weights `w_e=0.30, w_r=0.70, w_o=0`. `outcomeSalience` is populated
- * from `asset_outcome.outcome_score` regardless of the flag.
- *
- * ## Plasticity
- *
- * `consecutive_no_ops` (INTEGER column in `asset_salience`) dampens CONSOLIDATION-
- * SELECTION only — it is intentionally NOT applied to `rankScore`, so a stable
- * asset stays fully retrievable while no longer consuming repeated LLM merge
- * attempts. See `getConsecutiveNoOps` / `recordNoOp` / `resetConsecutiveNoOps`.
- *
- * ## Canonical store
- *
- * The three sub-scores live in `state.db :: asset_salience` (canonical).
- * An optional frontmatter mirror of the stable `encodingSalience` is allowed for
- * portability (issue #608 may write it there), but state.db is the source of truth
- * for ranking. This prevents the frontmatter-vs-state.db split that issue #608
- * would otherwise create (#608 pull-forward decision from Part VI).
- *
- * @module salience
- */
-import path from "node:path";
-import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
 import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
 import { WARM_START_CAP } from "./outcome-loop.js";
@@ -313,24 +267,18 @@ export function buildRankChangeReport(oldRanks, newRanks, oldTopN = 200, forgett
  * map should be treated as never retrieved (lastUseMs = 0).
  *
  * @param indexDb - An open read-capable index database connection.
- * @param refs    - The set of asset refs to look up.
+ * @param candidates - Planned refs carrying their canonical durable item_ref.
  */
-export function getLastUseMsByRef(indexDb, refs, stashDir) {
+export function getLastUseMsByRef(indexDb, candidates) {
     const result = new Map();
-    if (refs.length === 0)
+    if (candidates.length === 0)
         return result;
-    const refSet = new Set(refs);
+    const refByItemRef = new Map(candidates.flatMap((candidate) => (candidate.itemRef ? [[candidate.itemRef, candidate.ref]] : [])));
     const allEntries = getAllEntries(indexDb);
-    const selectedRoot = stashDir ? path.resolve(stashDir) : undefined;
     const idToRef = new Map();
     for (const indexed of allEntries) {
-        if (selectedRoot && path.resolve(indexed.stashDir) !== selectedRoot)
-            continue;
-        // In-memory correlation key, NOT a durable write: it must match the caller's
-        // `refs` (the `ImproveEligibleRef.ref`, now the SHORT conceptId — Chunk-8
-        // WI-8.5c flipped the candidate-ref spelling to match the display flip).
-        const ref = conceptIdFromTypeName(indexed.entry.type, indexed.entry.name);
-        if (refSet.has(ref))
+        const ref = refByItemRef.get(indexed.itemRef);
+        if (ref)
             idToRef.set(indexed.id, ref);
     }
     const ids = [...idToRef.keys()];

package/dist/commands/improve/session-asset.js

@@ -27,7 +27,6 @@ import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
-import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
 /**
  * JSON Schema for the session-summary LLM call. Strict so providers that
  * support schema enforcement constrain the output upstream; the parser only
@@ -151,11 +150,11 @@ export function sessionMeetsDurationGate(data, minDurationMinutes) {
  *
  * Documented convention (#561, checklist item "Document `access` field
  * convention per harness"): the string tells a downstream agent exactly how to
- * read and parse the log at `log_path`. New harnesses fall back to a generic
- * `cat <log_path>` hint, which is always correct for a file-backed log.
+ * read and parse the source at `log_path`. New harnesses fall back to a generic
+ * `cat <log_path>` hint for file-backed logs.
  */
-export function buildSessionAccessInstructions(harness, logPath) {
-    const canonical = normalizeHarnessId(harness);
+export function buildSessionAccessInstructions(harness, logPath, sessionId) {
+    const canonical = harness;
     if (canonical === "claude") {
         return [
             `Read with: cat ${logPath}`,
@@ -164,8 +163,9 @@ export function buildSessionAccessInstructions(harness, logPath) {
     }
     if (canonical === "opencode") {
         return [
-            `Read with: cat ${logPath}`,
-            `The log is opencode session storage (JSON). Inspect with: jq '.' ${logPath}`,
+            `Open the SQLite database at ${JSON.stringify(logPath)} in read-only mode.`,
+            "Query: SELECT m.data, p.data FROM message AS m JOIN part AS p ON p.message_id = m.id WHERE m.session_id = ? AND p.session_id = ? ORDER BY m.time_created, p.time_created;",
+            `Bind both parameters to ${JSON.stringify(sessionId)}.`,
         ].join("\n");
     }
     // Generic fallback — file-backed logs are always readable with cat.
@@ -177,7 +177,7 @@ function isoOrUndefined(ms) {
 }
 /** Default session-name slug: `<harness>-session-<yyyy-mm-dd>-<shortId>`. */
 export function buildSessionAssetName(harness, sessionId, startedAtMs) {
-    const canonical = normalizeHarnessId(harness);
+    const canonical = harness;
     const datePart = isoOrUndefined(startedAtMs)?.slice(0, 10) ?? "unknown-date";
     const shortId = sessionId.slice(0, 8);
     return `${canonical}-session-${datePart}-${shortId}`;
@@ -193,7 +193,7 @@ export function buildSessionAssetContent(data, summary) {
     const endedAt = isoOrUndefined(ref.endedAt);
     const name = buildSessionAssetName(harness, ref.sessionId, ref.startedAt);
     const logPath = ref.filePath;
-    const baseTags = ["session", normalizeHarnessId(harness)];
+    const baseTags = ["session", harness];
     const extraTags = (summary.tags ?? []).filter((t) => typeof t === "string" && t.trim().length > 0);
     const tags = Array.from(new Set([...baseTags, ...extraTags]));
     const frontmatter = {
@@ -205,7 +205,7 @@ export function buildSessionAssetContent(data, summary) {
         ...(endedAt ? { ended_at: endedAt } : {}),
         ...(ref.projectHint ? { project: ref.projectHint } : {}),
         log_path: logPath,
-        access: buildSessionAccessInstructions(harness, logPath),
+        access: buildSessionAccessInstructions(harness, logPath, ref.sessionId),
         tags,
     };
     const topics = summary.keyTopics
@@ -221,7 +221,7 @@ export function buildSessionAssetContent(data, summary) {
 /** Resolve `<stash>/sessions/<harness>/<session-id>.md`. */
 export function resolveSessionAssetPath(stashDir, harness, sessionId) {
     const dir = stashDirFor("session") ?? "sessions";
-    return path.join(stashDir, dir, normalizeHarnessId(harness), `${sessionId}.md`);
+    return path.join(stashDir, dir, harness, `${sessionId}.md`);
 }
 /**
  * Generate (via the injected summarizer) and write a session asset to the stash.
@@ -250,7 +250,7 @@ export async function writeSessionAsset(data, stashDir, generate) {
         // Canonical 0.9.0 conceptId (`sessions/<harness>/<id>`, D-R3) — the same
         // spelling the xrefs / usage-event readers now expect. Historical
         // `session:<harness>/<id>` rows persist un-migrated and are tolerated.
-        ref: conceptIdFromTypeName("session", `${normalizeHarnessId(harness)}/${sessionId}`),
+        ref: conceptIdFromTypeName("session", `${harness}/${sessionId}`),
         logPath: data.ref.filePath,
     };
 }

package/dist/commands/lint/index.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowFrontendDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
+import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowFrontendDiagnostics, workflowYamlSourceDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { adapterForId } from "../../core/adapter/registry.js";
 import { createValidateContext } from "../../core/adapter/validate-context.js";
@@ -16,7 +16,9 @@ import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { parseTaskYaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskYamlParseDetail, } from "../../tasks/schema.js";
+import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail } from "../../tasks/source-v3.js";
+import { resolveWorkflowSourceDomains } from "../../workflows/source-files.js";
+import { compareWorkflowSourceCodePoints } from "../../workflows/source-ir/ordering.js";
 import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
 import { isAdvisoryLintIssue } from "./types.js";
@@ -78,6 +80,63 @@ function collectMarkdownFiles(dir, caseInsensitive = false) {
     }
     return results;
 }
+function isCachedLintPath(filePath) {
+    const posixPath = filePath.replace(/\\/g, "/");
+    return posixPath.includes("/.cache/") || posixPath.includes("/registry/");
+}
+/** Peer workflow sources accepted by the source-IR compiler; `.yaml` remains unsupported. */
+function collectWorkflowFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const results = [];
+    for (const entry of fs
+        .readdirSync(dir, { withFileTypes: true })
+        .sort((left, right) => compareWorkflowSourceCodePoints(left.name, right.name))) {
+        if (entry.name === ".git")
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === ".cache" || entry.name === "registry")
+                continue;
+            results.push(...collectWorkflowFiles(full));
+            continue;
+        }
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        const extension = path.extname(entry.name).toLowerCase();
+        if (extension === ".md" || extension === ".yml")
+            results.push(full);
+    }
+    return results.sort(compareWorkflowSourceCodePoints);
+}
+/**
+ * Resolve the already-enumerated candidates through the same workflow-source
+ * authority used by index/show/run. The bulk surface inspects every canonical
+ * domain without re-reading its parent directory once per workflow. A rejected
+ * domain produces one deterministic finding and none of its sources is parsed.
+ */
+function resolveWorkflowLintOwnership(stashRoot, files) {
+    const ownedFiles = [];
+    const issues = [];
+    for (const resolution of resolveWorkflowSourceDomains(stashRoot, "akm", files)) {
+        if (resolution.source) {
+            ownedFiles.push(resolution.source.path);
+            continue;
+        }
+        if (!resolution.rejection)
+            continue;
+        const representative = resolution.sourcePaths[0];
+        if (!representative)
+            continue;
+        issues.push({
+            file: representative,
+            issue: "invalid-workflow-structure",
+            detail: resolution.rejection.message,
+            fixed: false,
+        });
+    }
+    return { files: ownedFiles.sort(compareWorkflowSourceCodePoints), issues };
+}
 // ── Non-akm adapter dispatch (real `adapter.validate()`, not a re-implementation) ──
 //
 // akm 0.9.0 lint/adapter-dispatch wiring: `akm lint` used to special-case
@@ -92,9 +151,9 @@ function collectMarkdownFiles(dir, caseInsensitive = false) {
 // its OWN configured/detected adapter's `validate()` — the single definition
 // of that format's rules, shared with the (now also wired, advisory-only)
 // change-transaction pre-commit gate in `commands/proposal/repository.ts`.
-// This is intentionally the ONLY branch this module adds: the `akm` sweep
-// below is completely untouched (pinned by the goldens/test suite —
-// CRITICAL: akm findings/`--fix` must not move).
+// The adapter-dispatch work intentionally stays outside the `akm` sweep below.
+// The sweep's workflow branch separately supports authoritative peer `.md` and
+// `.yml` sources while preserving the pinned Markdown findings/`--fix` bytes.
 /**
  * Case-insensitive SUFFIX match against an adapter's declared `extensions`
  * hint. Deliberately NOT `path.extname()`: Node's `extname(".env")` is `""`
@@ -165,6 +224,7 @@ const KNOWN_ADAPTER_ISSUE_TYPES = new Set([
     "missing-description",
     "broken-xref",
     "broken-source",
+    "invalid-workflow-structure",
     "workflow-warning",
 ]);
 /** Map one adapter {@link Diagnostic} onto a {@link LintIssue} — see `types.ts`'s `"adapter-diagnostic"` doc comment for the open→closed reconciliation. */
@@ -444,7 +504,7 @@ export function lintAssetFile(ctx, subdir) {
             issues.push(...factDiagnostics(ctx.relPath, ctx.data));
             break;
         case "tasks":
-            issues.push(...taskDiagnostics(ctx.relPath, ctx.data));
+            issues.push(...taskDiagnostics(ctx.relPath, ctx.raw, ctx.stashRoot));
             break;
         case "memories":
             appendMemoryStubIssue(ctx, issues);
@@ -477,10 +537,20 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
     const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
     for (const subdir of dirsToScan) {
         const dirPath = path.join(stashRoot, subdir);
-        // Tasks are .yml files; everything else (including workflows, one
-        // markdown format now) is .md
-        const files = subdir === "tasks" ? collectTaskFiles(dirPath) : collectMarkdownFiles(dirPath, true);
-        const assetFiles = subdir === "workflows" ? files.filter((file) => path.basename(file).toLowerCase() !== "readme.md") : files;
+        // Tasks have their own `.yml` plus near-miss collector. Workflows accept
+        // peer `.md`/`.yml` sources; every remaining AKM subdir is Markdown.
+        const files = subdir === "tasks"
+            ? collectTaskFiles(dirPath)
+            : subdir === "workflows"
+                ? collectWorkflowFiles(dirPath)
+                : collectMarkdownFiles(dirPath, true);
+        let assetFiles = subdir === "workflows" ? files.filter((file) => path.basename(file).toLowerCase() !== "readme.md") : files;
+        if (subdir === "workflows") {
+            assetFiles = assetFiles.filter((file) => !isCachedLintPath(file));
+            const ownership = resolveWorkflowLintOwnership(stashRoot, assetFiles);
+            assetFiles = ownership.files;
+            flagged.push(...ownership.issues);
+        }
         // Directory-level check: skills require a SKILL.md entry point (was
         // SkillLinter.lintDirectory). Run once per direct subdirectory before the
         // per-file loop.
@@ -505,8 +575,7 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             // Compare on a separator-normalized copy: on Windows these paths carry
             // backslashes, so the forward-slash substring never matched and --fix
             // rewrote files inside the registry cache.
-            const posixPath = filePath.replace(/\\/g, "/");
-            if (posixPath.includes("/.cache/") || posixPath.includes("/registry/"))
+            if (isCachedLintPath(filePath))
                 continue;
             const relPath = path.relative(stashRoot, filePath);
             let raw;
@@ -516,6 +585,21 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             catch {
                 continue;
             }
+            // GitHub-shaped YAML is a peer workflow source, not a Markdown document:
+            // no frontmatter/base/stub checks and no `--fix` mutation apply. Compile
+            // once through the shared source-IR frontend and route its findings.
+            if (subdir === "workflows" && path.extname(filePath).toLowerCase() === ".yml") {
+                const frontend = workflowYamlSourceDiagnostics(relPath, raw, filePath, stashRoot);
+                for (const finding of [...frontend.errors, ...frontend.warnings]) {
+                    if (isAdvisoryLintIssue(finding)) {
+                        warnings.push(finding);
+                    }
+                    else {
+                        flagged.push(finding);
+                    }
+                }
+                continue;
+            }
             let data;
             let body;
             let frontmatter;
@@ -523,21 +607,9 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             // the FILE (its extension, whether it parsed at all), not its fields.
             const fileIssues = [];
             if (subdir === "tasks") {
-                // Task files are pure YAML — parseFrontmatter returns empty data for them.
-                const parsed = parseTaskYaml(raw);
-                data = parsed.data;
-                if (!parsed.ok) {
-                    // A parse failure used to fall through as `data = {}`, and every task
-                    // rule short-circuits on an empty mapping — so an unparseable task
-                    // file reported a CLEAN scan. Report the parse failure itself
-                    // (issue #760).
-                    fileIssues.push({
-                        file: relPath,
-                        issue: "invalid-task-yaml",
-                        detail: taskYamlParseDetail(parsed.error),
-                        fixed: false,
-                    });
-                }
+                // Task files are pure YAML. The canonical task-v3 parser runs once in
+                // taskDiagnostics below; base checks need no parsed frontmatter data.
+                data = {};
                 if (isNearMissTaskFileName(relPath)) {
                     fileIssues.push({
                         file: relPath,
@@ -603,8 +675,8 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             // `ADVISORY_LINT_ISSUES`, never by which half of the pass produced it, so
             // a future compile-warning kind carrying a fatal code cannot slip past
             // `--fail-on-flagged`.
-            // NB: the CLI passes the ABSOLUTE filePath to parseWorkflow (matching the
-            // old WorkflowLinter), whereas the adapter passes the change relPath.
+            // The CLI passes the absolute filePath to the shared source-IR frontend,
+            // whereas the adapter passes the change relPath.
             if (subdir === "workflows") {
                 const frontend = workflowFrontendDiagnostics(relPath, raw, filePath);
                 for (const finding of [...frontend.errors, ...frontend.warnings]) {

package/dist/commands/migrate-cli.js

@@ -3,58 +3,20 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { runMigrationTool } from "./migration-tool.js";
-const configArg = {
-    type: "string",
-    description: "Complete operator-prepared current config; optional when the active config is current",
-};
 /**
- * Split the standalone `akm-migrate` tool's captured stdout into its
- * progress-event lines (if any — `apply` prints one JSON line per completed
- * sub-step, e.g. content migration / proposal-ref repair) and its final
- * result line. `status` and `apply --dry-run` never print progress, so
- * `progress` is empty for them; `apply` may print zero or more.
- *
- * Each `console.log` call in the child produces exactly one `\n`-terminated
- * line, so splitting on `\n` and dropping the trailing empty entry from the
- * final newline recovers exactly the lines it printed, in order.
- */
-function splitToolStdout(stdout) {
-    const lines = stdout.split("\n");
-    if (lines.length > 0 && lines.at(-1) === "")
-        lines.pop();
-    if (lines.length === 0)
-        return { progress: [] };
-    return { progress: lines.slice(0, -1), resultLine: lines.at(-1) };
-}
-/**
- * Runs the standalone `akm-migrate` tool and renders its result through the
- * normal `--format` pipeline (D7) instead of a fixed JSON passthrough.
- *
- * The child's progress-event lines (if any) are not part of the result
- * envelope — they print as-is, in order, regardless of `--format`, the same
- * way `apply` always printed them before this change. Only the final result
- * line — always a well-formed `MigrationPlan` JSON object — is parsed and
- * handed to `output()`, so `text`/`md`/`html`/`yaml` render a real
- * (registered or generic) rendering of it instead of silently staying JSON.
- * `--format json` (the default) is therefore the only format whose BYTES can
- * change here (pretty-printed via `output()` instead of the child's compact
- * `JSON.stringify`) — every value stays identical, which is what the
- * migration-lifecycle integration tests assert via `JSON.parse`.
+ * Run the task-only migrator and render its one JSON plan through the normal
+ * output pipeline.
  */
 async function runMigrateSubcommand(command, args) {
     const result = await runMigrationTool(args);
     if (result.stderr)
         process.stderr.write(result.stderr);
-    const { progress, resultLine } = splitToolStdout(result.stdout);
-    for (const line of progress)
-        console.log(line);
-    if (resultLine !== undefined) {
+    const resultLine = result.stdout.trim();
+    if (resultLine) {
         try {
             output(command, JSON.parse(resultLine));
         }
         catch {
-            // The child is expected to always print one well-formed JSON result
-            // line; if it somehow didn't, don't lose the line, just don't reshape it.
             console.log(resultLine);
         }
     }
@@ -67,45 +29,25 @@ async function runMigrateSubcommand(command, args) {
     }
 }
 export const migrateCommand = defineGroupCommand({
-    // S11 originally hid this from `--help`/completions as an internal,
-    // self-update-only surface. That made it undiscoverable even though the
-    // 0.9.0 upgrade instructions tell users to run it first (`akm migrate
-    // status`, `akm migrate apply`) — the one command those instructions
-    // depend on was invisible. Listed in the SYSTEM section of HELP_SECTIONS
-    // (src/cli.ts) and in shell completions now; `akm migrate status`/`apply`
-    // always executed regardless of `hidden`.
-    meta: { name: "migrate", description: "Inspect or apply config and durable database migrations" },
+    meta: { name: "migrate", description: "Inspect or apply task-v2 to task-v3 migrations" },
     subCommands: {
         status: defineJsonCommand({
-            meta: { name: "status", description: "Read-only cross-artifact migration eligibility check" },
-            args: { config: configArg },
-            run({ args }) {
-                return runMigrateSubcommand("migrate-status", ["status", ...(args.config ? ["--config", args.config] : [])]);
+            meta: { name: "status", description: "Read-only task-v2 migration check" },
+            run() {
+                return runMigrateSubcommand("migrate-status", ["status"]);
             },
         }),
         apply: defineJsonCommand({
-            meta: { name: "apply", description: "Create a verified backup and atomically apply pending migrations" },
+            meta: { name: "apply", description: "Back up and atomically convert task-v2 files to task v3" },
             args: {
-                config: configArg,
-                // R-062: canonical spelling is kebab-case, matching every other
-                // multi-word flag in the CLI. `--dryRun` (the pre-rename spelling)
-                // is kept as an explicit, documented alias — citty registers BOTH
-                // the camelCase and kebab-case spelling of any declared flag name
-                // automatically, so this is a rename, not a breaking change: both
-                // spellings already worked, and both keep working.
                 "dry-run": {
                     type: "boolean",
-                    alias: "dryRun",
                     default: false,
-                    description: "Run the same eligibility checks without mutation. Alias: --dryRun.",
+                    description: "Run the same eligibility checks without mutation.",
                 },
             },
             run({ args }) {
-                return runMigrateSubcommand("migrate-apply", [
-                    "apply",
-                    ...(args.config ? ["--config", args.config] : []),
-                    ...(args.dryRun ? ["--dry-run"] : []),
-                ]);
+                return runMigrateSubcommand("migrate-apply", ["apply", ...(args.dryRun ? ["--dry-run"] : [])]);
             },
         }),
     },

package/dist/commands/migration-tool.js

@@ -14,10 +14,9 @@ function migrationEntryPoint() {
 }
 /**
  * Spawns the standalone `akm-migrate` tool and returns its captured exit
- * status plus stdout/stderr — never writes them itself. `migrate-cli.ts`'s
- * `status`/`apply` commands use this to reshape the child's final JSON result
- * line through the normal `--format` pipeline (D7) while any earlier
- * progress-event lines the child printed still go through verbatim.
+ * status plus stdout/stderr — never writes them itself. `migrate-cli.ts` uses
+ * this packaging boundary to render the task-only plan through the normal
+ * output pipeline.
  */
 export async function runMigrationTool(args) {
     const entry = migrationEntryPoint();
@@ -28,11 +27,9 @@ export async function runMigrationTool(args) {
         throw new NotFoundError("This binary was built without the embedded akm-migrate tool.", "FILE_NOT_FOUND", "Rebuild from scripts/akm-standalone.ts, or run akm-migrate from a source/npm install.");
     }
     // Compiled standalone: no scripts/ tree exists on disk (`import.meta.url`
-    // resolves inside the binary's virtual filesystem), so the documented
-    // `./akm-<ver> migrate status/apply` path used to dead-end with
-    // FILE_NOT_FOUND. Release binaries are compiled from
-    // `scripts/akm-standalone.ts`, which embeds the migrator and dispatches to
-    // it when `AKM_MIGRATE_ENTRY=1` — so re-exec ourselves with the marker.
+    // resolves inside the binary's virtual filesystem). Release binaries embed
+    // the task migrator in `scripts/akm-standalone.ts` and re-exec themselves
+    // with the internal marker.
     // (src must not import scripts/: the dist build's tsc has `rootDir: src`.)
     const result = spawnSync(process.execPath, entry ? [entry, ...args] : [...args], {
         encoding: "utf8",

package/dist/commands/models-cli.js

@@ -0,0 +1,27 @@
+// 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 { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
+import { copyDefaultModelMap } from "../integrations/agent/model-map.js";
+/** Operator-owned model-map lifecycle commands. Alias expansion is consumed through the runtime API. */
+export const modelsCommand = defineGroupCommand({
+    meta: { name: "models", description: "Inspect and customize model intent alias defaults" },
+    subCommands: {
+        "copy-defaults": defineJsonCommand({
+            meta: {
+                name: "copy-defaults",
+                description: "Copy AKM's installed models.json into the user configuration directory",
+            },
+            args: {
+                overwrite: {
+                    type: "boolean",
+                    default: false,
+                    description: "Confirm replacing an existing regular user models.json file",
+                },
+            },
+            run({ args }) {
+                output("models", copyDefaultModelMap({ overwrite: args.overwrite === true }));
+            },
+        }),
+    },
+});