akm-cli 0.10.261016-beta → 0.10.261017-beta

package/dist/assets/stash-skeleton/facts/conventions/organization.md

@@ -23,11 +23,10 @@ path is therefore the one facet you **cannot express twice and cannot change
 without breaking the ref** — so spend it deliberately, on exactly one axis.
 
 Retrieval is search, not browse: no one walks these folders at query time. A
-subdirectory buys you three things: its tokens are indexed as part of the
-asset's **name** (the highest-weighted search field), they are auto-added to
-`tags` (even when you set `tags` explicitly), and for scope-born types a slug
-matching the current repo's name earns an automatic in-project ranking boost.
-Every other facet belongs in frontmatter, where the index can actually read it.
+subdirectory buys you two things: its tokens are indexed as part of the
+asset's **name**, and they are auto-added to `tags` (even when you set `tags`
+explicitly). Search weighs every indexed field equally. Every other facet
+belongs in frontmatter, where the index can actually read it.
 
 ## Choose the partition axis by asset TYPE, not per-asset judgment
 
@@ -38,9 +37,8 @@ differently and bake the wrong guess into an immutable ref. Decide by type:
   `memory`, `lesson`, `task`, `env`, `secret`. These are born bound to the work
   in front of you, so the working context *is* the answer — no judgment needed.
   When the scope is a single repo, use its repo/package name as the slug (as
-  `git remote`/package.json spell it) — ranking auto-boosts assets whose name
-  or tags match the current repo. Client/team slugs get no such boost; just
-  reuse the existing spelling.
+  `git remote`/package.json spell it). For a client or team slug, reuse the
+  existing spelling.
   - `memories/projectA/auth-token-refresh`
   - `lessons/clientX/migration-rollback-gotcha`
   - `secrets/clientX/api-key`
@@ -58,11 +56,8 @@ differently and bake the wrong guess into an immutable ref. Decide by type:
   the type root — if any single project would break when it changes, it is
   scope-born.
 
-**Why reuse types don't take the project axis:** project relevance is already
-recovered at query time — AKM blends a per-project usage signal into ranking
-(scoped utility, keyed off the current repo, not the asset's path). Free the
-scarce path segment for the domain — the *only* handle that co-locates
-cross-project reuse.
+**Why reuse types don't take the project axis:** free the scarce path segment
+for the domain — the *only* handle that co-locates cross-project reuse.
 
 ## Placement rules
 
@@ -86,16 +81,15 @@ cross-project reuse.
   (`acme` vs `acme-corp`) so the prefix does not fragment. Keep the domain
   vocabulary in `facts/conventions/domains`.
 - **Off-axis facets go in `tags:`, not a bare field.** The indexed FTS fields are
-  name, description, tags, hints, and bounded low-weight body content — there is **no `project`
+  name, description, tags, hints, and bounded body content — there is **no `project`
   field**, so `project: projectA` in
   frontmatter is invisible to search. Put the off-axis facet in `tags` instead
   (a project-scoped memory adds `tags: [auth]`; a domain-scoped asset genuinely
   tied to a project adds `tags: [projectA]` sparingly).
 - **Directory tokens join `tags` on their own.** The scope/domain segments of
   the path are always auto-added to `tags` — even when you set `tags`
-  explicitly — so there is no need to restate them; the tag-match ranking
-  boost fires for the scope token either way. Filename tokens are auto-added
-  only when `tags` is empty.
+  explicitly — so there is no need to restate them. Filename tokens are
+  auto-added only when `tags` is empty.
 
 ## Renames and evolution
 

package/dist/cli.js

@@ -112,9 +112,6 @@ function applyEarlyStderrFlags(argv) {
         setVerbose(true);
     }
 }
-// resolveHelpMigrateVersionArg moved to ./cli/invocation (chunk-9 WI-9.9
-// argv-normalization fold — it re-scanned process.argv, same as
-// findCittyTopLevelCommand and parseAllFlagValues below).
 /**
  * Stderr-only human-friendly hint after a non-interactive `setup` invocation.
  * Default --format is `json`, so a CI or piped consumer sees only the JSON on
@@ -155,10 +152,9 @@ const setupCommand = defineCommand({
         description: "Interactive configuration wizard. Enables agent programs (Claude Code, Codex, OpenCode, ...), sets up a model connection and embeddings, and picks bundle sources and registries. Flags answer individual questions; --yes takes the detected default for the rest, for scripting.",
     },
     args: {
-        // R-051/S11: `setup` is a raw `defineCommand` (not `defineJsonCommand`),
-        // so it does not get `GLOBAL_OUTPUT_ARGS` for free — same gap `health`
-        // already had. Three of its four run branches call `output()`; spreading
-        // this in is a `--help` visibility fix, not a behavior change.
+        // `setup` is a raw `defineCommand` (not `defineJsonCommand`), so it does
+        // not get `GLOBAL_OUTPUT_ARGS` for free. Three of its four run branches
+        // call `output()`; spreading this in is a `--help` visibility fix.
         ...GLOBAL_OUTPUT_ARGS,
         endpoint: {
             type: "string",
@@ -285,11 +281,11 @@ const healthCommand = defineCommand({
         description: "Check akm runtime health, artifacts, and improve metrics",
     },
     args: {
-        // R-051: `health` is a raw `defineCommand` (not `defineJsonCommand`), so
-        // it does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
-        // `--output` already parsed correctly here (this command has
+        // `health` is a raw `defineCommand` (not `defineJsonCommand`), so it does
+        // not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
+        // `--output` parse correctly here regardless (this command has
         // no positional for a stray value to fall into), so this is purely a
-        // `--help` visibility / consistency fix, not a behavior change.
+        // `--help` visibility / consistency measure.
         ...GLOBAL_OUTPUT_ARGS,
         since: {
             type: "string",
@@ -389,8 +385,8 @@ const healthCommand = defineCommand({
             }
             output("health", base);
         });
-        // R-067: `emitJsonError` (src/cli/shared.ts) no longer force-exits on the
-        // error path — it sets `process.exitCode` and returns, so a `--report`
+        // `emitJsonError` (src/cli/shared.ts) does not force-exit on the error
+        // path — it sets `process.exitCode` and returns, so a `--report`
         // failure thrown AFTER `resultStatus` was already assigned (e.g. the
         // proposal-queue read above) would otherwise leave `resultStatus`
         // populated here too. Skip the status-derived exit entirely once
@@ -443,14 +439,12 @@ const completionsCommand = defineCommand({
         },
     },
     run({ args }) {
-        // R-052(b): this was a bare `run()` throwing directly, so an unsupported
-        // `--shell` value escaped straight to citty's top-level error handling
-        // instead of the standard JSON envelope — exit 1 with a raw stack trace
-        // instead of the classified exit-2 usage error every other command
-        // produces (`completions` is format-exempt, so it stays a raw
-        // `defineCommand` rather than `defineJsonCommand`, but still needs the
-        // same error-classification wrapper other bare `defineCommand`s in this
-        // file use, e.g. `help migrate` below).
+        // An unsupported `--shell` value must reach the standard JSON envelope as
+        // the classified exit-2 usage error, not escape to citty's top-level error
+        // handling as a raw stack trace (`completions` is format-exempt, so it
+        // stays a raw `defineCommand` rather than `defineJsonCommand`, but still
+        // needs the same error-classification wrapper other bare `defineCommand`s
+        // in this file use, e.g. `help migrate` below).
         return runWithJsonErrors(() => {
             if (args.shell !== "bash") {
                 throw new UsageError(`Unsupported shell: ${args.shell}. Only bash is supported.`);
@@ -678,7 +672,7 @@ const EXIT_GENERAL = EXIT_CODES.GENERAL;
 const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // ── Top-level driver (replaces citty's `runMain`) ───────────────────────────
 //
-// R-032: citty's own `runMain` catches EVERY error escaping `runCommand` —
+// citty's own `runMain` catches EVERY error escaping `runCommand` —
 // including its unexported `CLIError`, thrown for "Unknown command …", "No
 // command specified.", "Missing required argument/positional …", and invalid
 // enum values — and unconditionally calls `process.exit(1)`, regardless of
@@ -692,7 +686,7 @@ const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // of `runMain`, replicating `runMain`'s `--help` / `--version`
 // short-circuits and its CLIError → usage-banner rendering, but classifying
 // a CLIError as USAGE (2) instead of GENERAL (1). Every other error escaping
-// this boundary keeps the previous GENERAL (1) mapping — this only
+// this boundary keeps the GENERAL (1) mapping — this only
 // reclassifies the one error family citty itself throws before any of our
 // own command bodies (and their `runWithJsonErrors` / `emitJsonError`
 // classification) ever run.
@@ -762,7 +756,7 @@ function resolveCittyCommandPath(cmd, rawArgs, path = []) {
  * dropping the `akm ` root prefix every top-level command's `--help` already
  * shows. Building a synthetic parent whose `meta.name` is the full prefix
  * (`akm task`) fixes it for any depth without patching the vendored
- * dependency (S11 item 4).
+ * dependency.
  */
 function buildUsageParentForPath(path) {
     // `version` carries through too — citty's renderUsage falls back to
@@ -776,7 +770,7 @@ function buildUsageParentForPath(path) {
         },
     };
 }
-// ── Sectioned root help (S11) ────────────────────────────────────────────────
+// ── Sectioned root help ────────────────────────────────────────────────
 //
 // citty's own generated COMMANDS list is a flat, unordered dump of every
 // top-level command — fine for a handful of commands, not for the ~28 this
@@ -853,7 +847,7 @@ function renderCommandSections() {
     return HELP_SECTIONS.map(({ title, commands }) => `${title}\n${formatCommandRows(commands)}`).join("\n\n");
 }
 /**
- * Sectioned replacement for citty's root COMMANDS list (S11 item 1). Reuses
+ * Sectioned replacement for citty's root COMMANDS list. Reuses
  * `renderUsage(main)` for the banner + exit-code table (kept verbatim) +
  * USAGE line + global OPTIONS, then cuts the string before citty's own
  * "COMMANDS" heading (present because `main` has `subCommands`) and appends
@@ -938,7 +932,7 @@ function cittyCliErrorUsageCode(error) {
 }
 /**
  * Route a citty `CLIError` through the standard JSON envelope instead of
- * citty's own usage-banner + raw `console.error(message)` (S11 item 3): the
+ * citty's own usage-banner + raw `console.error(message)`: the
  * one-line diagnosis is the error's own message (e.g. "Unknown command
  * foo"), and the hint is a short pointer — with a did-you-mean suggestion
  * prepended when the unresolved token is close to a real sibling command —
@@ -962,12 +956,10 @@ export function normalizeCittyCliError(error, rawArgs) {
 }
 /**
  * The CLI's real startup sequence, extracted into a function so error paths
- * can `return` early — top-level `return` is a syntax error in an ES module,
- * and this used to rely on `emitJsonError`'s `never` return type (a
- * synchronous `process.exit`) to stop execution instead. Now that
- * `emitJsonError` (src/cli/shared.ts, R-067) only records `process.exitCode`
- * and returns, every direct call site here needs its own explicit `return;`
- * to stop the rest of startup from running after a fatal early error.
+ * can `return` early — top-level `return` is a syntax error in an ES module.
+ * `emitJsonError` (src/cli/shared.ts) only records `process.exitCode` and
+ * returns, so every direct call site here needs its own explicit `return;` to
+ * stop the rest of startup from running after a fatal early error.
  */
 export async function runCli() {
     try {
@@ -978,7 +970,7 @@ export async function runCli() {
         return;
     }
     // Mint the ParsedInvocation singleton from the (normalized) argv — the ONE
-    // place argv is parsed for the whole process (plan §10.7 / chunk-9 WI-9.9).
+    // place argv is parsed for the whole process.
     // Every out-of-cli.ts command module reads argv state through
     // `getParsedInvocation()` from here on instead of re-scanning process.argv.
     setParsedInvocation(process.argv);
@@ -1024,11 +1016,10 @@ export async function runCli() {
         return;
     }
     const commandPath = resolveCittyCommandPath(main, process.argv.slice(2));
-    // D7 — every command that renders through output() honours all six --format
+    // Every command that renders through output() honours all six --format
     // values. The declared exempt set (src/output/format-exempt.ts) does not
     // render an envelope at all, so warn rather than pretend: silently ignoring
-    // the flag is what made the old md/html behaviour so hard to discover. A
-    // warning, not an error, because the flag is harmless here and scripts that
+    // the flag makes the behaviour hard to discover. A warning, not an error, because the flag is harmless here and scripts that
     // pass --format globally to a mixed batch of commands should still work.
     const invocation = getParsedInvocation();
     if ((invocation.hasFlag("--format") || invocation.getFlagValue("--format") !== undefined) &&
@@ -1082,7 +1073,7 @@ export async function runCli() {
         if (HELP_FLAGS.some((flag) => ownArgs.includes(flag))) {
             const resolved = resolveDeepestCittyCommand(main, rawArgs);
             if (resolved === main) {
-                // Root `--help` (S11 item 1): the sectioned overview, not citty's
+                // Root `--help`: the sectioned overview, not citty's
                 // flat COMMANDS dump.
                 process.stdout.write(`${await renderSectionedRootHelp()}\n`);
             }
@@ -1097,14 +1088,14 @@ export async function runCli() {
             return;
         }
         // citty's parseArgs (strict: false) silently ignores undeclared flags, so
-        // a typo used to run the command with defaults and exit 0. Checked here, after --help and
-        // --version, so those keep working on any command.
+        // a typo would otherwise run the command with defaults and exit 0. Checked
+        // here, after --help and --version, so those keep working on any command.
         assertKnownFlags(main, rawArgs);
         await runCommand(main, { rawArgs });
     }
     catch (error) {
         if (isCittyCliError(error)) {
-            // R-032/S11: reclassify citty's own "unknown command" / "no command
+            // Reclassify citty's own "unknown command" / "no command
             // specified" / "missing required argument" family as USAGE (2) and
             // route it through the SAME JSON envelope every other command's
             // failure uses (`emitJsonError`), rather than citty's own usage-banner

package/dist/commands/feedback-cli.js

@@ -435,10 +435,11 @@ export const feedbackCommand = defineJsonCommand({
             "next search; no reindex is needed. Each recorded positive raises the asset's\n" +
             "score and each negative lowers it, the same way for every asset: the more\n" +
             "positives, the higher it ranks (5 outrank 2), and each further vote counts\n" +
-            "for a little less. The effect is small, so it reorders close matches and\n" +
-            "does not override relevance. Only feedback recorded as the user counts, not\n" +
-            "feedback from improve, task or audit runs. Feedback also moves the utility\n" +
-            "score that improve and `akm metrics` read.",
+            "for a little less. The effect is small: in keyword-only search one vote\n" +
+            "moves a hit one place, and with embeddings it breaks only near-ties. Only\n" +
+            "feedback recorded as the user counts, not feedback from improve, task or\n" +
+            "audit runs. Feedback also moves the utility score that improve and\n" +
+            "`akm metrics` read.",
     },
     args: {
         // Optional in citty so run() is invoked even when omitted; we re-validate

package/dist/commands/health.js

@@ -72,21 +72,21 @@ function validateAkmHealthOptions(options) {
         }
     }
 }
-// ── akmHealth phase helpers (chunk-9 WI-9.5b; file-level decompose following
-// the function's natural gather/advise/check/assemble phases) ───────────────
+// ── akmHealth phase helpers (the function's natural
+// gather/advise/check/assemble phases) ──────────────────────────────────────
 /** Event type appended + read back by the state.db round-trip probe. */
 const HEALTH_PROBE_EVENT = "health_probe";
-/** Synthetic sentinel ref (ref-grammar decision D-R3): a colon-free
+/** Synthetic sentinel ref: a colon-free
  * `<subsystem>/_<marker>` label. `health` has no asset stash-subdir, so
  * `health/_probe` names the subsystem. */
 const HEALTH_PROBE_REF = "health/_probe";
 /**
  * Verify state.db can accept a write and read it back — WITHOUT leaving any
- * permanent trace (R-030). Earlier versions appended a `health_probe` event
- * on every `akm health` invocation and never removed it: a read-only health
- * check ran on a cron would grow state.db without bound (the only purge is
- * `improve`'s retention pass, which a health-only user never runs). The probe
- * row inserted here is deleted again inside the SAME connection once the
+ * permanent trace. Leaving the `health_probe` event in place after every
+ * `akm health` invocation would grow state.db without bound for a read-only
+ * health check run on a cron (the only purge is `improve`'s retention pass,
+ * which a health-only user never runs). The probe row inserted here is
+ * deleted again inside the SAME connection once the
  * round trip is confirmed, so the net effect on the `events` table is always
  * zero rows — the round trip still genuinely exercises append + read against
  * the real table, it just doesn't accumulate.
@@ -132,7 +132,7 @@ export function probeStateDbRoundTrip(stateDbPath) {
     }
 }
 /**
- * Item 7: dedupe stuck-active rows by task_id (keeping the oldest/largest age
+ * Dedupe stuck-active rows by task_id (keeping the oldest/largest age
  * per id) so the `active-runs` check can name WHICH tasks are stuck instead of
  * just a count. No pid/liveness probing — purely a projection of the rows
  * already read.
@@ -148,7 +148,7 @@ function dedupeStuckActiveTasks(rows, now) {
     return [...byTask.entries()].map(([taskId, ageMs]) => ({ taskId, ageMs }));
 }
 /**
- * Item 6: group task_history rows by task_id and return the one with the
+ * Group task_history rows by task_id and return the one with the
  * highest fail rate among tasks with at least MIN_ROWS_FOR_WORST_TASK_FAIL_RATE
  * rows in the window — surfaces a consistently-failing task that a large,
  * mostly-healthy population would otherwise hide behind the aggregate rate.
@@ -184,7 +184,7 @@ function gatherTaskHistoryPhase(db, since, stateDbPath, now, readOnly) {
     const requiredTables = ["events", "proposals", "schema_migrations", "task_history"];
     const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
     const probe = readOnly ? { ok: true, durationMs: null, skipped: true } : probeStateDbRoundTrip(stateDbPath);
-    // R0: read-only, independent of the round-trip probe above — integrity_check
+    // Read-only, independent of the round-trip probe above — integrity_check
     // catches corruption a successful append/read cannot (out-of-order rowids,
     // bad index entry counts), and the freelist reading is purely informational.
     const stateDbIntegrity = runStateDbIntegrityCheck(stateDbPath);
@@ -251,7 +251,7 @@ function gatherAncillaryAdvisories(db, options, egressConfigView) {
     const indexStateMismatch = detectIndexStateGenerationMismatch(db);
     if (indexStateMismatch)
         advisories.push(indexStateMismatch);
-    // 08-F1: surface a `stash-git-exposure` advisory when env/secret assets are
+    // Surface a `stash-git-exposure` advisory when env/secret assets are
     // git-tracked AND a remote is configured (the leak moment). Best-effort.
     // Cheap guard: only shell out to git when the stash has its OWN `.git` (or a
     // test injected a fake seam), so the hot path never spawns for a non-git
@@ -295,8 +295,7 @@ function gatherAncillaryAdvisories(db, options, egressConfigView) {
     catch {
         // Non-fatal.
     }
-    // Item 4 (alpha.9 plan §5.4/§8 step 8): a bundle with no git history of its
-    // own never gets the purge sweep, so its memory-cleanup archive only ever
+    // A bundle with no git history of its own never gets the purge sweep, so its memory-cleanup archive only ever
     // grows — report its size and file count instead. Best-effort — an
     // unreadable archive must not abort the health report.
     try {
@@ -425,7 +424,7 @@ function detectIndexStateGenerationMismatch(stateDb) {
     }
 }
 /**
- * Phase 3 — window-compare mode. Resolves `--window-compare`/`--windows` into
+ * Window-compare mode. Resolves `--window-compare`/`--windows` into
  * per-window bundles and computes deltas between the earliest and latest
  * window. Top-level metrics retain the primary `--since` query.
  */
@@ -655,7 +654,7 @@ export async function akmHealth(options = {}) {
         const hardFailure = hardChecks.some((check) => check.status === "fail");
         const deterministicWarnings = [...hardChecks, ...advisories].some((check) => check.status === "warn" && check.kind === "deterministic");
         const status = hardFailure ? "fail" : deterministicWarnings ? "warn" : "pass";
-        // ── Per-run mode (Phase 2) ────────────────────────────────────────────
+        // ── Per-run mode ────────────────────────────────────────────
         const runs = options.groupBy === "run" ? perRunSummaries : undefined;
         return {
             schemaVersion: 3,

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

@@ -390,7 +390,7 @@ const proposalDrainCommand = defineJsonCommand({
         },
         promote: {
             type: "boolean",
-            description: "Promote (accept) matching proposals. Default is queue mode (stage only, no writes to assets).",
+            description: "Promote (accept) matching proposals. Without it, the strategy's apply mode decides, and the default strategy's is promote (akm#1274).",
             default: false,
         },
         judgment: {

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

@@ -14,8 +14,11 @@ export async function searchRegistry(query, options) {
         return { query: "", hits: [], warnings: [] };
     }
     const limit = clampLimit(options?.limit);
+    // AKM_REGISTRY_URL outranks the caller's list: `akm search` passes
+    // `config.registries`, which would otherwise shadow the override.
+    const envOverride = process.env.AKM_REGISTRY_URL?.trim() ? resolveRegistries() : undefined;
     // resolveRegistries() already filters by enabled; explicit registries are filtered here
-    const raw = options?.registries ?? resolveRegistries();
+    const raw = envOverride ?? options?.registries ?? resolveRegistries();
     const warnings = [];
     const entries = (options?.registries ? raw.filter((r) => r.enabled !== false) : raw).filter((entry) => {
         if (!hasRegistryUrlCredentials(entry.url))

package/dist/commands/read/search.js

@@ -5,7 +5,7 @@
  * `akm search` — entry point.
  *
  * Search consults the local FTS5 index. There is one query path
- * because there is one data store. Provider fan-out is gone.
+ * because there is one data store; there is no provider fan-out.
  *
  * The orchestration here is thin: build the FTS query, optionally interleave
  * a registry search behind `--from registry|all`, and log a usage event.
@@ -214,9 +214,9 @@ function resolveEntryIds(db, hits) {
         try {
             const entryId = getEntryIdByFilePath(db, hit.path);
             if (entryId !== undefined) {
-                // F4c: persist the DURABLE fully-qualified `bundle//conceptId` spelling,
-                // derived from the resolved entry row's `item_ref` (D-R3: durable keys
-                // come from the resolved item, never raw input).
+                // Persist the DURABLE fully-qualified `bundle//conceptId` spelling,
+                // derived from the resolved entry row's `item_ref` (durable keys come
+                // from the resolved item, never raw input).
                 const itemRef = getItemRefById(db, entryId);
                 if (itemRef !== null) {
                     results.push({ entryId, ref: itemRef, hit });
@@ -254,7 +254,7 @@ function logSearchEvent(rawQuery, response, mode = "keyword", eventSource = "use
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
-    // D8: include registry hit refs so a show following a registry-only search generates a select event
+    // Include registry hit refs so a show following a registry-only search generates a select event
     const registryHitRefs = (response.registryHits ?? []).map((h) => `registry:${h.id}`);
     const allResultRefs = [...stashHits.map((h) => h.ref), ...registryHitRefs];
     appendEvent({
@@ -267,7 +267,7 @@ function logSearchEvent(rawQuery, response, mode = "keyword", eventSource = "use
         // Under contention these usage hints are skipped, not waited for.
         withIndexDb((db) => {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
-            // usage_events telemetry now writes to state.db (Chunk-8 WI-8.3);
+            // usage_events telemetry writes to state.db;
             // entry_id/entry_ref are resolved from index.db above and carried across.
             const stashHitCount = response.hits.length;
             const registryHitCount = Array.isArray(response.registryHits) ? response.registryHits.length : 0;

package/dist/commands/sources/self-update.js

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap, readChunkWithDeadline, } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
+import { isQuiet, warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
 import { resolveNpmGlobalRoot } from "../../tasks/resolve-akm-bin.js";
@@ -428,7 +428,11 @@ async function runMigrationStep(runTool) {
     return { status: "failed", error: result.stderr.trim() || line || `akm-migrate exited ${result.status}` };
 }
 /**
- * Rebuild the derived index after a successful upgrade.
+ * Rebuild the derived index after a successful upgrade. The first index after
+ * an upgrade can re-embed part of the corpus and take minutes, so the child's
+ * stderr (its progress lines) goes straight to the terminal; its stdout, never a
+ * terminal here, is captured. `--format json` keeps the progress on stderr
+ * whatever output format the user has configured, and `--quiet` is passed on.
  */
 function runPostUpgradeTasks(akmBin, opts) {
     if (opts.skip) {
@@ -439,10 +443,10 @@ function runPostUpgradeTasks(akmBin, opts) {
         };
     }
     try {
-        const result = childProcess.spawnSync(akmBin, ["index"], {
+        const result = childProcess.spawnSync(akmBin, ["index", "--format", "json", ...(isQuiet() ? ["--quiet"] : [])], {
             encoding: "utf8",
             env: process.env,
-            stdio: "pipe",
+            stdio: ["pipe", "pipe", "inherit"],
         });
         if (result.error) {
             return {
@@ -452,7 +456,7 @@ function runPostUpgradeTasks(akmBin, opts) {
             };
         }
         if (result.status !== 0) {
-            const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+            const detail = (result.stdout ?? "").trim() || `exit code ${result.status}`;
             return {
                 ok: false,
                 skipped: false,

package/dist/commands/tasks/tasks.js

@@ -178,10 +178,10 @@ export async function akmTasksRun(id, options = {}) {
     const adapterId = bundle.source.adapterId ?? detectAdapterId(bundle.source.path);
     const resolvedId = taskIdForAdapter(parsed.id, adapterId);
     const scheduled = options.scheduled === true;
-    // Built ONCE at this invocation boundary. eventSource is "task"
-    // whether or not --scheduled was passed — scheduled stays a
-    // separate field carrying its own pre-existing meaning (activation policy,
-    // scheduler env), never selecting the event source.
+    // Built ONCE at this invocation boundary. eventSource is "task" whether or
+    // not --scheduled was passed — scheduled stays a separate field carrying its
+    // own meaning (activation policy, scheduler env), never selecting the event
+    // source.
     const provenance = createExecutionProvenanceContext(scheduled);
     // The raw, exact-name input flags `tasks-cli.ts`'s Stage 1 captures ride
     // through unchanged to `runTask` -> `loadPreparedTask`'s Stage 2 materializer,
@@ -206,8 +206,8 @@ export async function akmTasksRun(id, options = {}) {
     // projectability, and resolver failures therefore create no history row.
     const result = await runTask(resolvedId, runOptions);
     // "command" means the agent/LLM arm — the native shell/script arm reports
-    // "shell" / "script" — so a shell/script task's process exit 78 still passes
-    // through as CLI exit 78 (documented behavior, src/assets/hints/cli-hints-short.md).
+    // "shell" / "script". A shell/script task's process exit 78 passes through
+    // as CLI exit 78 (documented behavior, src/assets/hints/cli-hints-short.md).
     const exitCode = result.status === "failed" &&
         (result.target.kind === "shell" || result.target.kind === "script") &&
         result.detail?.exitCode === 78
@@ -597,10 +597,9 @@ export async function akmTasksDoctor(deps = {}) {
     const config = loadConfig();
     const defaultEngine = (defaultHarness(config) ?? defaultConnection(config))?.name;
     const engines = [...Object.keys(config.connections ?? {}), ...Object.keys(config.harnesses ?? {})];
-    // §6.1: surface the effective triage settings for the default improve
-    // strategy. The struct is a fixed shape, so this is a deliberate addition.
+    // Surface the effective triage settings for the default improve strategy.
     const improveStrategyName = config.improve?.strategy ?? "default";
-    // D8 — report the EFFECTIVE strategy, not the raw one. Resolving the raw
+    // Report the EFFECTIVE strategy, not the raw one. Resolving the raw
     // strategy here would report `applyMode: "promote"` for a promote strategy
     // under a review-first config, while the run actually uses "queue" — a doctor
     // command lying about the thing it exists to diagnose.
@@ -753,7 +752,7 @@ function errorMessage(cause) {
 }
 /**
  * Infer a JSON-Schema-subset `type` keyword from one `--params` value's
- * runtime shape. `null` is not one of the five runtime types
+ * runtime shape. `null` is not one of the five usual runtime types
  * (string/number/boolean/object/array) but is a value JSON.parse can still
  * produce for a param; `src/core/json-schema.ts`'s subset validator accepts
  * `"null"` as a `type`, so it is handled rather than mis-typed.
@@ -768,9 +767,9 @@ function jsonSchemaTypeOf(value) {
 /**
  * Render `--params` as typed `inputs:` declarations, one per key, each
  * carrying a `default:` equal to the authored value and a `type:` inferred
- * from its own JSON runtime shape (row B-20). Never emitted as `with:` —
- * task source v4 accepts `with:` only on `uses: akm/command` (§3.2.6's
- * `parseTarget`/`checkTopLevelKeys`), and a workflow target's declared
+ * from its own JSON runtime shape. Never emitted as `with:` —
+ * task source v4 accepts `with:` only on `uses: akm/command`
+ * (`parseTarget`/`checkTopLevelKeys`), and a workflow target's declared
  * inputs are what `load-task.ts`'s existing v4 delivery override binds into
  * the child run's params.
  */

package/dist/core/adapter/adapters/agent-skills-adapter.js

@@ -2,7 +2,7 @@
 // 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/.
 /**
- * The `agent-skills` adapter — akm 0.9.0 format-family work item (#46).
+ * The `agent-skills` adapter.
  *
  * Recognizes a COLLECTION of standalone SKILL.md packages (like
  * github.com/anthropics/skills): each `<name>/SKILL.md` is one `skill` item
@@ -38,7 +38,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/agent-skills/` + goldens
- * `tests/fixtures/format-family-goldens/agent-skills/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/agent-skills/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -52,7 +52,7 @@ const SKILL_MANIFEST = "SKILL.md";
 /** Agent Skills hard limits. */
 const NAME_MAX = 64;
 const DESCRIPTION_MAX = 1024;
-/** Agent Skills reserved words a name must not contain (real-world source). */
+/** Agent Skills reserved words a name must not contain. */
 const RESERVED_NAME_WORDS = ["anthropic", "claude"];
 /** name charset/shape rule. */
 const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -98,7 +98,7 @@ function recognize(c, file) {
         doc.tags = tags;
     return doc;
 }
-/** The Agent Skills §4.5 hard-rule checks for one SKILL.md (name + description). */
+/** The Agent Skills hard-rule checks for one SKILL.md (name + description). */
 function skillFieldDiagnostics(relPath, dirName, data) {
     const diagnostics = [];
     const name = typeof data.name === "string" ? data.name.normalize("NFKC") : "";
@@ -176,8 +176,8 @@ async function scanPackageCandidate(dir, entries, ctx, depth) {
  *
  * `validate` walks CHANGES, and a change is always a file — so a package
  * directory carrying resources but no manifest contributes nothing the
- * change-loop can see, and the check the spec (§4.5) and the lint golden's
- * `missingSkillMd` edge case both name was unreachable. This scans the
+ * change-loop can see, and the check the lint golden's `missingSkillMd` edge
+ * case names would be unreachable. This scans the
  * component root through {@link ValidateContext.list} instead, so the case is
  * actually reported.
  *
@@ -230,7 +230,7 @@ export const agentSkillsAdapter = {
     readCandidates(c, conceptId) {
         return [{ path: path.join(c.root, conceptId, SKILL_MANIFEST), conceptId }];
     },
-    /** Install-time probe (§1.2): a root that directly contains one or more `<name>/SKILL.md` skill packages. */
+    /** Install-time probe: a root that directly contains one or more `<name>/SKILL.md` skill packages. */
     looksLikeRoot(root) {
         let entries;
         try {

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -26,7 +26,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
- * `tests/fixtures/format-family-goldens/akm-task/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/akm-task/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/akm-workflow-adapter.js

@@ -15,7 +15,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-workflow/` + goldens
- * `tests/fixtures/format-family-goldens/akm-workflow/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/akm-workflow/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/claude-adapter.js

@@ -16,7 +16,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/claude/` + goldens
- * `tests/fixtures/format-family-goldens/claude/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/claude/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";