akm-cli 0.8.0-rc.3 → 0.8.0-rc.6

package/{.github/CHANGELOG.md → CHANGELOG.md}

@@ -6,6 +6,117 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+> **CI / Docker users:** the 0.8.0 storage split moved `akm.lock`, the event
+> database, and the registry cache out of `$XDG_CONFIG_HOME/akm/` into
+> `$XDG_DATA_HOME`, `$XDG_STATE_HOME`, and `$XDG_CACHE_HOME` respectively. If
+> you override any of `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_STATE_DIR`,
+> `AKM_CACHE_DIR` in CI to isolate per-job state, set **all four** (or none,
+> and rely on XDG defaults). Overriding only `AKM_CONFIG_DIR` will leave the
+> lock file / event DB pointing at the host's default `$XDG_DATA_HOME`,
+> causing lock contention and bleed between jobs.
+
+### Removed
+
+- **Install-time security audit (`security.installAudit`) and the `--trust`
+  flag**. The audit scanned incoming stash assets for risky patterns (e.g.
+  `curl ... | bash`, "ignore previous instructions") and blocked installs on
+  critical findings. In practice it produced too many false positives on
+  benign documentation strings and forced first-time users to pass `--trust`
+  or twiddle config just to install the official stash. The whole feature is
+  gone:
+  - `akm add` and `akm update` no longer scan synced content.
+  - The `--trust` flag is removed from `akm add` and `akm wiki register`.
+  - The `security.installAudit.*` config keys (`enabled`, `blockOnCritical`,
+    `registryAllowlist`, `registryWhitelist`, `blockUnlistedRegistries`,
+    `allowedFindings`) are no longer recognised; the entire `security` block
+    is removed from the config schema.
+  - The `akm config set security.installAudit.*` keys now error as unknown.
+  - `audit` fields are removed from `AddResponse.installed` and
+    `SourceInstallStatus`.
+
+### Breaking Changes
+
+- **Project-level `.akm/config.json` files are no longer merged**. The
+  multi-layer config discovery introduced in the 0.7 line was deprecated
+  in late-0.8.x with a warning; that warning is now backed by removal.
+  `loadConfig` walks cwd-ancestors only to emit a one-time deprecation
+  warning per discovered file. Move any needed settings to
+  `~/.config/akm/config.json`. `stashInheritance` (a multi-layer-only
+  field) is removed from the schema.
+
+- **`${VAR}` env-var expansion only resolves at the apiKey consumption
+  sites**. The recursive expansion walker that ran on the load path is
+  gone. Other config string values now round-trip verbatim: a literal
+  `${HOME}` in (say) `stashDir` is preserved as the literal `${HOME}`
+  on read. The new exported `resolveSecret(value)` helper is applied
+  only where authorization headers are built (`src/llm/client.ts`,
+  `src/llm/embedders/remote.ts`, `src/integrations/agent/sdk-runner.ts`).
+  Documented `${OPENAI_API_KEY}` recipes in `docs/configuration.md`
+  continue to work because expansion still happens at request time for
+  apiKey fields.
+
+- **`AKM_FORCE_DOWNGRADE_CONFIG` env var removed**. The newer-than-binary
+  read-only guard (`configReadOnlyReason`, `markConfigReadOnlyIfNewer`,
+  `getConfigReadOnlyReason`) is gone. Configs declaring a `configVersion`
+  newer than the running binary now save through silently — unknown
+  fields are stripped on save by `sanitizeConfigForWrite` plus the
+  strict-walled Zod schema. Users on 0.9.x configs should not open them
+  with a 0.8.x binary in writable workflows.
+
+### Changed
+
+- **Config layer rewrite** — single-source-of-truth Zod schema in
+  `src/core/config-schema.ts` replaces the per-field parse switch AND
+  the per-shape load-time parser. Adding a new config field is now one
+  line of schema + zero lines of CLI code. `loadConfig` now consists of
+  parse-text → migrate (pure JSON transforms) → Zod safeParse → overlay
+  defaults — a ~30-line pipeline that absorbs ~900 LOC of legacy
+  per-shape parsers (`parseLlmConfig`, `parseEmbeddingConfig`,
+  `parseIndexConfig`, `parseSourceConfigEntry`, and ~20 more).
+  - **#454**: `akm config set llm.apiKey` / `embedding.apiKey` /
+    `profiles.llm.<name>.apiKey` now throws `UsageError` pointing at the
+    corresponding env var (`AKM_LLM_API_KEY`, `AKM_EMBED_API_KEY`,
+    `AKM_PROFILE_<NAME>_API_KEY`). Was previously a silent strip.
+  - **#455**: every schema-leaf key is now reachable via `akm config set`.
+    Includes previously hand-listed gaps: `defaults.agent`, `search.minScore`,
+    `improve.eventRetentionDays`, `embedding.provider`, `llm.temperature`,
+    `profiles.llm.<name>.*`, `profiles.agent.<name>.*`, etc.
+  - **#456**: `akm config validate` and `akm config migrate` are now real
+    registered subcommands. The orphan implementations in `config-validate.ts`
+    have been removed; the new entry points live in `src/cli/`.
+  - **#457**: project-level `.akm/config.json` files are now flagged with a
+    deprecation warning ("will be ignored in 0.9.0+"). The merge still
+    happens in 0.8.x — one release of grace.
+  - **#458**: malformed JSON or non-object root in the config file now raises
+    `ConfigError("INVALID_CONFIG_FILE")` with the underlying parse error.
+    Was previously a silent fallback to `DEFAULT_CONFIG`, which masked
+    corruption. File-not-existing remains the legitimate cold-start case.
+  - **#459**: `~/.cache/akm/config-backups/` is now bounded to the 5 most
+    recent timestamped backups. Pruning runs on each `saveConfig`.
+    `config.latest.json` is preserved separately.
+  - **#460**: `UNKNOWN_CONFIG_KEY_HINT` is now auto-generated from the
+    schema via `listTopLevelConfigKeys()`. No more stale hand-maintained string.
+  - **#461**: if the auto-migration disk-write fails, `loadConfig` now throws
+    a hard error instead of returning the in-memory migrated shape. Eliminates
+    the silent infinite re-migrate loop on every `akm` command.
+  - **#462**: nested registries[], sources[], profiles.* objects are
+    `.strict()` — unknown keys are rejected with a path-pointing error at
+    both set time and saveConfig time.
+  - **#463**: `schemas/akm-config.json` is now auto-generated from the Zod
+    source via `bun scripts/gen-config-schema.ts`. A drift test fails CI if
+    the committed file disagrees with the regeneration output.
+  - **#464.a**: `defaultWriteTarget` is validated via Zod `.refine()` against
+    `sources[].name`. With no sources configured, save-time validation
+    rejects instead of silently accepting (no implicit "first writable" fallback).
+  - **#464.b**: generic unset works on `semanticSearchMode` and every other
+    key via the dotted-path walker.
+  - **#464.c**: all write paths route through `writeFileAtomic`.
+  - **#464.d**: duplicate `mergeSecurityConfig` / `mergeInstallAuditConfig`
+    in `config-cli.ts` are deleted; merging happens via re-parse through the
+    Zod schema.
+
+See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
+
 ## [0.7.5] - 2026-05-08
 
 ### Added
@@ -19,7 +130,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Workflow runs are now scoped to the current workspace** — ref-based workflow commands (`workflow next/status/list`) now resolve runs within the current project, worktree, or non-repo directory instead of sharing active-run state globally across the whole cache. Direct run-id commands still target the exact run.
 - **Help, hints, and workflow docs now explain run scoping** — CLI descriptions, embedded hints, operator docs, and workflow guides now describe the current-scope semantics so users understand how ref-based run resolution behaves across repos and local sandboxes.
 - **`akm show` auto-indexes stale state instead of falling back to raw filesystem reads** — show/search parity is tighter because stale index state now triggers refresh rather than silently drifting to a separate fallback path.
-- **Release metadata lookup follows the published `.github/CHANGELOG.md` layout** — migration-help, package publish metadata, and related docs now consistently reference the shipped changelog location.
+- **Release metadata lookup follows the published `CHANGELOG.md` layout** — migration-help, package publish metadata, and related docs now consistently reference the shipped changelog location at the package root.
 - **Documentation refresh across README and posts** — README positioning, command-tour docs, workflow examples, and dev.to post organization were refreshed to better match the current CLI surface.
 
 ### Fixed

package/README.md

@@ -7,17 +7,32 @@
 [![license](https://img.shields.io/github/license/itlackey/akm)](https://github.com/itlackey/akm/blob/main/LICENSE)
 
 `akm` is a package manager for AI agent capabilities -- scripts, skills, commands,
-agents, knowledge, and memories. It works with any AI coding assistant that can
-run shell commands, including [Claude Code](https://claude.ai/code),
+agents, knowledge, memories, workflows, wikis, vaults, lessons, and scheduled
+tasks. It works with any AI coding assistant that can run shell commands,
+including [Claude Code](https://claude.ai/code),
 [OpenCode](https://opencode.ai), [Cursor](https://cursor.com), and more.
 
 ## Install
 
+**Option 1 — Prebuilt binary (recommended, no runtime required):**
+
+```sh
+# Linux / macOS
+curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash
+
+# Windows (PowerShell)
+irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
+```
+
+**Option 2 — Bun (requires [Bun](https://bun.sh) >= 1.0):**
+
 ```sh
 bun install -g akm-cli
 ```
 
-Requires [Bun](https://bun.sh) runtime. Upgrade in place with `akm upgrade`.
+Upgrade in place with `akm upgrade`.
+
+> **AKM 0.8 requires the prebuilt binary or the Bun runtime. Node.js / npm / pnpm are not supported in 0.8.0** — running `npm install -g akm-cli` on a Node.js-only machine will print an error from the preinstall hook and exit without installing. Cross-runtime support (Node, npm, pnpm) is planned for 0.9.0.
 
 ## Quick Start
 
@@ -44,7 +59,8 @@ Add this to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 ## Resources & Capabilities
 
 You have access to a searchable library of scripts, skills, commands, agents,
-knowledge, and memories via the `akm` CLI. Use `akm -h` for details.
+knowledge, memories, workflows, wikis, vaults, lessons, and scheduled tasks
+via the `akm` CLI. Use `akm -h` for details.
 ```
 
 ## Install Stashes from Anywhere

package/SECURITY.md

@@ -0,0 +1,93 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made on the latest minor release line of `akm-cli`. The
+0.x line is pre-1.0 — please upgrade promptly when a fix lands.
+
+| Version | Supported |
+| --- | --- |
+| 0.8.x  | ✅ active |
+| 0.7.x  | ❌ no longer maintained |
+| < 0.7  | ❌ no longer maintained |
+
+## Reporting a vulnerability
+
+Please report security issues **privately** via GitHub Security Advisories:
+
+- https://github.com/itlackey/akm/security/advisories/new
+
+If GitHub Security Advisories is unavailable, email `itlackey@gmail.com`
+with the word `SECURITY` in the subject. Please include reproduction steps,
+the impacted akm version, and your operating environment.
+
+We will acknowledge receipt within 72 hours and aim to ship a fix or a
+mitigation guidance within two weeks, depending on severity.
+
+## Threat model
+
+`akm` is a local CLI that reads and writes user files, executes user-authored
+shell commands (via scripts, workflows, and agent dispatch), and talks to
+explicitly configured external services (LLM endpoints, git remotes, npm,
+HTTP sources). It does **not** ship telemetry, send data to anyone by
+default, or open network listeners. See
+[`docs/data-and-telemetry.md`](docs/data-and-telemetry.md) for the on-disk
+inventory.
+
+Several akm surfaces execute user-controlled code or data with the full
+permissions of the akm process. These are documented design decisions, not
+bugs, but you should be aware of them:
+
+### Workflows execute shell commands with full environment access
+
+Workflow steps run in your shell with your PATH and your environment
+variables — including any secrets you have exported or loaded via
+`akm vault load`. **Only add workflow sources you trust.** See
+[`docs/features/workflows.md` — "Security: workflow sources are executed
+code"](docs/features/workflows.md#security-workflow-sources-are-executed-code)
+for the full discussion.
+
+### Scripts execute shell commands
+
+`akm show script:<name>` returns a `run:` command line the user (or an
+integrating agent) then executes. The same trust model applies: scripts you
+install from third-party stashes are third-party code.
+
+### Agents and commands embed user-authored prompts
+
+`akm show agent:<name>` and `akm show command:<name>` return prompt
+templates and system prompts that an LLM will execute. A malicious stash
+maintainer could write a system prompt that instructs the LLM to read
+sensitive files in your working tree and exfiltrate them via the LLM
+response. Audit the prompt body the same way you'd audit a script.
+
+### Vaults are plaintext on disk
+
+`akm vault` files are `0o600`-permissioned plaintext at
+`<stash>/vaults/<name>.env`. They are protected against other local users
+by filesystem permissions but not encrypted at rest. Do not commit vault
+files to source control — they are `.gitignore`d in the default stash
+layout for that reason. The `akm vault show` / `akm vault list` commands
+never echo values; `akm vault load` produces shell-eval output meant to be
+piped to `eval`, never displayed.
+
+### Improve / propose / distill send asset content to the configured LLM
+
+`akm improve`, `akm propose`, `akm distill`, `akm reflect`, and `akm
+consolidate` send asset frontmatter and body to whatever LLM endpoint is
+configured in `~/.config/akm/config.json` (under `llm.endpoint`). If you
+have configured a third-party LLM, your asset content goes to that
+third-party. Use a local model (`http://localhost:11434` via Ollama, etc.)
+for assets containing secrets or private notes.
+
+## Known non-issues
+
+- **`akm` requires Bun or the prebuilt binary** — Node.js is not supported
+  in 0.8.0 because Bun-specific APIs are used in hot paths. This is a
+  compatibility limitation, not a security risk; the prebuilt binary is a
+  Bun-compiled standalone executable.
+- **Workflows can read any file the akm process can read.** This is not a
+  bug — see "Threat model" above.
+- **`bun install -g akm-cli` runs the preinstall hook.** The hook only
+  emits an error message and exits non-zero on Node.js; it does not phone
+  home or write outside the install directory.

package/dist/cli/config-migrate.js

@@ -0,0 +1,144 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+import { stripJsonComments } from "../core/config";
+import { unifiedDiff, withConfigLock, writeConfigAtomic } from "../core/config-io";
+import { migrateConfigShape } from "../core/config-migration";
+import { getCacheDir, getConfigPath } from "../core/paths";
+import { warn } from "../core/warn";
+export { migrateConfigShape } from "../core/config-migration";
+const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
+function backupConfigFile(configPath) {
+    if (!fs.existsSync(configPath))
+        return;
+    const backupDir = path.join(getCacheDir(), "config-backups");
+    fs.mkdirSync(backupDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
+    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
+    fs.copyFileSync(configPath, backupPath);
+    const latestPath = path.join(backupDir, "config.latest.json");
+    fs.copyFileSync(configPath, latestPath);
+}
+function acquireMigrateLock(lockPath, noWait) {
+    const lockDir = path.dirname(lockPath);
+    fs.mkdirSync(lockDir, { recursive: true });
+    const maxAttempts = noWait ? 1 : 20;
+    const delayMs = 200;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+            return () => {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // ignore
+                }
+            };
+        }
+        catch {
+            if (noWait) {
+                return null;
+            }
+            // Simple busy-wait — synchronous since this is a one-shot CLI action
+            const deadline = Date.now() + delayMs;
+            while (Date.now() < deadline) {
+                // spin
+            }
+        }
+    }
+    return null;
+}
+export async function migrateConfigFile(filePath, opts) {
+    if (!fs.existsSync(filePath)) {
+        return { changed: false, result: {} };
+    }
+    const text = fs.readFileSync(filePath, "utf8");
+    let raw;
+    try {
+        const stripped = stripJsonComments(text);
+        const parsed = JSON.parse(stripped);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            warn(`[akm] config-migrate: ${filePath} is not a valid JSON object, skipping.`);
+            return { changed: false, result: {} };
+        }
+        raw = parsed;
+    }
+    catch {
+        warn(`[akm] config-migrate: failed to parse ${filePath}, skipping.`);
+        return { changed: false, result: {} };
+    }
+    const { changed, result } = migrateConfigShape(raw);
+    if (!changed) {
+        return { changed: false, result };
+    }
+    const migratedText = `${JSON.stringify(result, null, 2)}\n`;
+    // WS-2: compute a diff when requested (always computed for --print-diff;
+    // never requires a write so safe in --dry-run).
+    const diff = opts.printDiff ? unifiedDiff(text, migratedText, filePath) : undefined;
+    if (opts.dryRun) {
+        return { changed: true, result, diff };
+    }
+    // WS-3: acquire config write lock + use atomic write (tmp → rename).
+    withConfigLock(() => {
+        backupConfigFile(filePath);
+        writeConfigAtomic(filePath, result);
+    });
+    return { changed: true, result, diff };
+}
+function discoverProjectConfigPaths(startDir) {
+    const paths = [];
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const configPath = path.join(currentDir, PROJECT_CONFIG_RELATIVE_PATH);
+        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
+            paths.unshift(configPath);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    return paths;
+}
+export async function runConfigMigrate(opts) {
+    const userConfigPath = getConfigPath();
+    const projectPaths = discoverProjectConfigPaths(process.cwd());
+    const allPaths = [userConfigPath, ...projectPaths].filter((p, i, arr) => arr.indexOf(p) === i && fs.existsSync(p));
+    if (allPaths.length === 0) {
+        console.log("No config files found to migrate.");
+        return;
+    }
+    const lockPath = path.join(getCacheDir(), "config-migrate.lock");
+    const releaseLock = acquireMigrateLock(lockPath, opts.noWait ?? false);
+    if (!releaseLock) {
+        warn("[akm] config-migrate: another migration is already in progress, skipping.");
+        return;
+    }
+    try {
+        let anyChanged = false;
+        for (const filePath of allPaths) {
+            const { changed, diff } = await migrateConfigFile(filePath, { dryRun: opts.dryRun, printDiff: opts.printDiff });
+            if (changed) {
+                const action = opts.dryRun ? "would migrate" : "migrated";
+                console.log(`[akm] ${action}: ${filePath}`);
+                // WS-2: print the unified diff to stdout when --print-diff is set.
+                if (diff) {
+                    console.log(diff);
+                }
+                anyChanged = true;
+            }
+            else {
+                console.log(`[akm] already up to date: ${filePath}`);
+            }
+        }
+        if (!anyChanged) {
+            console.log("All config files are already at the current version.");
+        }
+    }
+    finally {
+        releaseLock();
+    }
+}

package/dist/cli/config-validate.js

@@ -0,0 +1,39 @@
+// 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/.
+/**
+ * `akm config validate` — verify the on-disk config matches the schema.
+ *
+ * Reads the user config file, validates against AkmConfigSchema, and either
+ * prints "All checks passed." or a list of structured errors (path + message).
+ * Exits non-zero on errors so it composes well in CI hooks.
+ */
+import fs from "node:fs";
+import { parseConfigText } from "../core/config-io";
+import { validateConfigShape } from "../core/config-schema";
+import { ConfigError } from "../core/errors";
+import { getConfigPath } from "../core/paths";
+export async function runConfigValidate() {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+        console.log(`No config file at ${configPath} — nothing to validate.`);
+        return;
+    }
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new ConfigError(`Could not read config at ${configPath}: ${detail}`, "INVALID_CONFIG_FILE");
+    }
+    // parseConfigText throws ConfigError on malformed JSON (#458). Surface as-is.
+    const raw = parseConfigText(text, configPath);
+    const result = validateConfigShape(raw);
+    if (result.ok) {
+        console.log(`All checks passed. (${configPath})`);
+        return;
+    }
+    const lines = result.errors.map((e) => `  - ${e.path || "(root)"}: ${e.message}`).join("\n");
+    throw new ConfigError(`Config at ${configPath} has ${result.errors.length} validation error${result.errors.length === 1 ? "" : "s"}:\n${lines}`, "INVALID_CONFIG_FILE", "Fix the listed fields, or run `akm config migrate` if the errors look like legacy-shape leftovers.");
+}

package/dist/cli/confirm.js

@@ -0,0 +1,73 @@
+// 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/.
+/**
+ * Confirmation helper for destructive CLI commands.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { confirmDestructive } from "../cli/confirm";
+ *
+ * async function run({ args }) {
+ *   const yes = await confirmDestructive(
+ *     `Remove source "${args.target}"? This cannot be undone.`,
+ *     { yes: args.yes === true }
+ *   );
+ *   if (!yes) { console.error("Aborted."); return; }
+ *   // proceed...
+ * }
+ * ```
+ *
+ * ## Non-TTY policy
+ *
+ * In non-interactive contexts (stdin is not a TTY), destructive commands
+ * **fail by default** and require explicit `--yes` to proceed. This prevents
+ * accidental destruction in scripts that forget to pass `-y`.
+ *
+ * This is intentionally stricter than many CLIs that silently proceed in
+ * non-TTY mode. The rationale: vault keys, sources, and proposals cannot be
+ * recovered after deletion, so the cost of requiring `--yes` in scripts is
+ * low and the cost of accidental deletion is high.
+ *
+ * ## Safety exemptions
+ *
+ * `--quiet` NEVER suppresses the confirmation prompt — it is safety-critical
+ * output. The auto-migration banner is similarly exempt from `--quiet`.
+ */
+import * as p from "@clack/prompts";
+import { UsageError } from "../core/errors";
+/**
+ * Prompt the user to confirm a destructive action.
+ *
+ * Returns `true` if the user confirmed (or `--yes` was passed).
+ * Returns `false` if the user declined.
+ * Throws `UsageError("NON_INTERACTIVE_REQUIRES_YES")` when stdin is not a
+ * TTY and `--yes` was not passed — callers should propagate this error.
+ *
+ * The prompt defaults to NO so accidental Enter presses do not proceed.
+ *
+ * @param message  Human-readable description of what will be destroyed.
+ * @param opts     Options controlling confirmation behaviour.
+ */
+export async function confirmDestructive(message, opts) {
+    // --yes always skips the prompt
+    if (opts.yes)
+        return true;
+    // Non-TTY: fail loudly — require explicit --yes in scripts
+    const isInteractive = process.stdin.isTTY === true;
+    if (!isInteractive) {
+        throw new UsageError(`This command requires confirmation in non-interactive mode. Pass --yes / -y to proceed without prompting.\n\nAction: ${message}`, "NON_INTERACTIVE_REQUIRES_YES");
+    }
+    // Interactive: prompt with default = NO (false)
+    const confirmed = await p.confirm({
+        message,
+        initialValue: false,
+    });
+    // p.confirm returns a symbol when the user cancels (Ctrl+C)
+    if (p.isCancel(confirmed)) {
+        p.outro("Cancelled.");
+        process.exit(0);
+    }
+    return confirmed === true;
+}

package/dist/cli/parse-args.js

@@ -1,3 +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/.
 /**
  * Shared argument-parsing utilities for the AKM CLI entry point.
  *
@@ -65,6 +68,50 @@ export function parseNonNegativeIntFlag(raw, flagName) {
     }
     return parseInt(trimmed, 10);
 }
+// ── Auto-accept flag parsing ─────────────────────────────────────────────────
+/**
+ * Parse the value of `akm improve --auto-accept` into a confidence threshold.
+ *
+ * Semantics (see docs/migration/v0.7-to-v0.8.md):
+ * - `undefined` (flag absent) → `undefined` (default-OFF; pre-prod flip)
+ * - `""` (bare `--auto-accept`, no value) → `undefined` (treated as flag absent)
+ * - `"false"` (case-insensitive) → `undefined` (explicit disable)
+ * - `"safe"` (case-insensitive) → `90` (permanent back-compat alias)
+ * - integer string `"0".."100"` → that integer
+ * - anything else → throws `UsageError("INVALID_FLAG_VALUE")`
+ *
+ * Citty's `type: "string"` resolves bare flags to `""` and an absent flag to
+ * `undefined`. Both forms now disable auto-accept; users must pass an explicit
+ * threshold (`--auto-accept=N` or `--auto-accept=safe`) to opt in. This is a
+ * deliberate flip from the earlier 0.8.0-RC behaviour, which defaulted to ON
+ * at threshold 90 and surprised users who didn't expect Phase B operations to
+ * apply without confirmation.
+ *
+ * Until proposals expose per-operation confidence scores, any non-`undefined`
+ * threshold causes the consolidate path to auto-accept the whole batch
+ * (legacy "safe" behaviour). The threshold value is preserved for the eventual
+ * per-operation comparison; see the TODO in `consolidate.ts`.
+ */
+export function parseAutoAcceptFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return undefined;
+    const lower = trimmed.toLowerCase();
+    if (lower === "false")
+        return undefined;
+    if (lower === "safe")
+        return 90;
+    if (!/^\d+$/.test(trimmed)) {
+        throw new UsageError(`Invalid --auto-accept value: "${raw}". Must be an integer 0-100, 'safe', or 'false'.`, "INVALID_FLAG_VALUE");
+    }
+    const parsed = parseInt(trimmed, 10);
+    if (parsed < 0 || parsed > 100) {
+        throw new UsageError(`Invalid --auto-accept value: "${raw}". Must be an integer 0-100, 'safe', or 'false'.`, "INVALID_FLAG_VALUE");
+    }
+    return parsed;
+}
 // ── String flag parsing ──────────────────────────────────────────────────────
 /**
  * Extract a string value from a parsed citty argument object by key.