akm-cli 0.9.0-rc.8 → 0.9.0

package/STABILITY.md

@@ -0,0 +1,497 @@
+# Stability policy
+
+`akm-cli` follows [Semantic Versioning](https://semver.org/) on the 0.x line
+**with one caveat**: until 1.0, minor releases (0.x → 0.x+1) may include
+breaking changes.
+
+**0.9.x series exception.** The 0.9.x releases are a deliberate refactoring
+and clean-up series: the goal is to pay off all remaining technical debt and
+land every planned breaking change before 0.10. While that work completes,
+**0.9.x patch releases may also contain breaking changes** — each one called
+out in the CHANGELOG with a migration note. The 0.10.x series returns to bug
+fixes and tuning, and aims to restore the normal discipline of breaking
+changes only in major and minor releases.
+
+This document classifies **every** user-facing surface by stability so you can
+decide which parts of `akm` are safe to script against today and which to
+treat as still-evolving. If a surface is not listed here, that is a bug —
+please file it.
+
+## How to read this
+
+| Tier | Contract |
+| --- | --- |
+| **Stable** | Scripted use is supported. Changes are additive within a minor release; breaking changes are called out in the CHANGELOG with a migration note. |
+| **Evolving** | Available across minor releases, but flag names, prompts, and payload shapes may shift. Breaking changes are flagged in the CHANGELOG. |
+| **Experimental** | Subject to change without notice. Not recommended for scripted use. Some experimental surfaces additionally require an explicit opt-in — see [`akm improve` autonomy](#akm-improve-autonomy--opt-in-in-090). |
+| **Internal** | Not a public interface. May change or disappear in any release, without a CHANGELOG note. Listed here only so you can recognize it. |
+
+## Command tier index
+
+The canonical index: every command and subcommand group in the current tree
+(enumerated from `main.subCommands` in `src/cli.ts` and each group's own
+`subCommands`), with its tier. The prose sections below remain the detailed
+explanation of *why*; this table is the lookup. Two spots have no single
+explicit sentence naming their tier and were resolved by reading neighbors:
+`akm bundle show` is assigned Evolving because it is discussed only inside
+the Evolving "Bundles & the workspace model" bullet, alongside the still-
+shifting adapter set, unlike its sibling `akm bundle list`, which the Stable
+section names explicitly; and `akm proposal list` is assigned Stable — the
+Stable section names it explicitly ("list filters"), which takes precedence
+over its incidental mention inside the Evolving "Improvement loop" bullet's
+enumeration of the whole `proposal` noun group.
+
+| Command | Tier | Notes |
+| --- | --- | --- |
+| `akm setup` | Stable | |
+| `akm index` | Stable | |
+| `akm health` | Evolving | Exit codes are Evolving; report *content* and rendered `md`/`html` layout are Experimental — do not script against report layout. |
+| `akm info` | Stable | |
+| `akm bundle create` | Stable | |
+| `akm bundle add` | Stable | |
+| `akm bundle list` | Stable | |
+| `akm bundle show` | Evolving | See note above. |
+| `akm bundle remove` | Stable | |
+| `akm bundle update` | Stable | |
+| `akm upgrade` | Evolving | |
+| `akm search` | Stable | |
+| `akm curate` | Stable | |
+| `akm show` | Stable | |
+| `akm workflow status` | Stable | |
+| `akm workflow list` | Stable | |
+| `akm workflow create` | Stable | |
+| `akm workflow resume` | Stable | |
+| `akm workflow abandon` | Stable | |
+| `akm workflow run` | Stable | Canonical start/resume/execute command. |
+| `akm remember` | Stable | |
+| `akm import` | Stable | |
+| `akm sync` | Stable | |
+| `akm clone` | Stable | |
+| `akm registry list` | Evolving | |
+| `akm registry add` | Evolving | |
+| `akm registry remove` | Evolving | |
+| `akm migrate status` | Internal | Forwards to the standalone `akm-migrate` tool; renders its result through the normal `--format` pipeline (not exempt — see below). Listed (not hidden) in `--help`/completions. |
+| `akm migrate apply` | Internal | Forwards to the standalone `akm-migrate` tool; renders its result through the normal `--format` pipeline (not exempt — see below). Listed (not hidden) in `--help`/completions. |
+| `akm config path` | Stable | |
+| `akm config list` | Stable | |
+| `akm config get` | Stable | |
+| `akm config set` | Stable | |
+| `akm config unset` | Stable | |
+| `akm feedback` | Stable | |
+| `akm log` | Evolving | |
+| `akm agent` | Evolving | |
+| `akm lint` | Evolving | |
+| `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
+| `akm proposal list` | Stable | See reconciliation note above. |
+| `akm proposal show` | Evolving | |
+| `akm proposal diff` | Evolving | |
+| `akm proposal accept` | Evolving | |
+| `akm proposal reject` | Evolving | |
+| `akm proposal revert` | Evolving | |
+| `akm proposal drain` | Evolving | |
+| `akm proposal extract` | Evolving | Former top-level `akm extract`. |
+| `akm proposal new` | Evolving | Former top-level `akm propose`. |
+| `akm help` | Stable | |
+| `akm help agents` | Stable | |
+| `akm help migrate` | Stable | Only renders release notes. |
+| `akm hints` | Stable | Format-exempt agent guide; `--detail brief` selects the compact version. |
+| `akm completions` | Stable | Format-exempt (emits shell script source). |
+| `akm env list` | Stable | Read-and-inject surface. |
+| `akm env path` | Stable | Read-and-inject surface. |
+| `akm env export` | Stable | Read-and-inject surface. |
+| `akm env run` | Stable | Read-and-inject surface. |
+| `akm env create` | Experimental | Write verb. |
+| `akm env remove` | Experimental | Write verb. |
+| `akm secret list` | Stable | Read-and-inject surface. |
+| `akm secret run` | Stable | Read-and-inject surface. |
+| `akm secret set` | Experimental | Write verb. |
+| `akm task add` | Evolving | |
+| `akm task run` | Evolving | |
+| `akm task history` | Evolving | |
+| `akm task sync` | Evolving | |
+| `akm task doctor` | Evolving | |
+
+## Stable
+
+- **Asset ref syntax** — `[bundle//]conceptId[#fragment]`. A `conceptId` is
+  subdir-qualified within its bundle: `memories/<name>`, `lessons/<name>`,
+  `knowledge/<name>`, `skills/<name>`, `scripts/<name>`, `workflows/<name>`,
+  `env/<name>`, `secrets/<name>`, `tasks/<name>`, `facts/<name>`,
+  `sessions/<name>`, `commands/<name>`, `agents/<name>`. Other adapters
+  declare their own conceptId layouts. The optional `bundle//` prefix names an
+  installed bundle; omit it and the ref resolves against the workspace
+  `defaultBundle`, then the remaining bundles in installation-priority order.
+  Durable state always stores the fully-qualified `bundle//conceptId`; the
+  short form is accepted input only, at the CLI, the programmatic surface, and
+  inside bundle content (where it resolves against the containing bundle). The
+  older `<type>:<name>` grammar is no longer accepted.
+  - `#fragment` is **input-only** and never stored. On markdown-document items
+    the core resolves it as a section selector — `akm show <ref>#<heading-slug>`
+    returns that one section, no fragment returns the whole item, and an
+    unmatched fragment lists the available slugs. Elsewhere it is an
+    adapter-owned selector opaque to the core. See
+    [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md).
+  - **Refs in prose** must be fully qualified (`bundle//conceptId`) or a native
+    adapter link form. A bare conceptId in prose is ordinary text, not a ref,
+    and no akm tool rewrites it.
+- **ConceptId-prefix enumeration** — `akm search "memories/"`,
+  `"memories/projecta/"`, `"bundle//"`, `"bundle//skills/"`. A trailing `/` is
+  required. The prefix matches the **conceptId** — the spelling every emitted
+  `ref` carries — so a ref copied out of search output can be truncated to a
+  prefix and pasted back in. Enumeration is not tied to any adapter's type set,
+  so every adapter's items browse the same way, and `bundle//` lists a whole
+  bundle (this replaced `akm bundle items`). A prefix is explicit intent, so
+  `search.defaultExcludeTypes` does not apply to it. The pre-0.9.0
+  `"<type>:"` / `"<type>:<prefix>/"` spelling was removed; a query in that
+  shape is now an ordinary keyword search whose empty-result tip names the
+  conceptId spelling that replaces it.
+- **Read commands** — `akm search`, `akm show`, `akm bundle list`, `akm curate`,
+  `akm info`, `akm config get`, `akm config list`, `akm config path`,
+  `akm env list`, `akm secret list`, `akm proposal list` (list filters),
+  `akm help`, `akm help agents`, `akm hints`, `akm completions`.
+- **Write commands core surface** — `akm bundle add`, `akm bundle update`,
+  `akm bundle remove`, `akm clone`, `akm import`, `akm sync`, `akm index`,
+  `akm bundle create`, `akm setup`, `akm remember`, `akm feedback`,
+  `akm config set`, `akm config unset`.
+- **Renames are delete + create** — moving or renaming an item gives it a new
+  identity; learned state does not follow it. Cross-bundle movement is
+  copy/import plus delete. The procedure is a plain filesystem move, then
+  `akm index`, then `akm lint` to catch inbound refs the move left dangling.
+  `akm mv` was **removed in 0.9.0**: it claimed to preserve identity across a
+  rename, but its inbound-ref rewriting targeted bare conceptIds rather than
+  the anchored `bundle//conceptId` prose form, so it could rewrite non-refs
+  while leaving real refs dangling. To carry an asset's earned signal
+  (feedback, usage, salience/outcome history) across a rename, the maintainer
+  script `scripts/rekey-asset-ref.ts` re-keys those rows old -> new; it is
+  Internal tooling, not a supported command surface.
+- **Asset `type` is a free-form, open string** — `--type` filtering is an
+  exact match against an open set and is deliberately **not validated**: an
+  unrecognized type returns zero hits, not an error. Adapters emit types
+  outside the built-in set, so there is no closed list to validate against —
+  `--type website` or `--type wiki-source` are ordinary, valid filters.
+- **Output contracts** — JSON output shape (the top-level keys) and the error
+  envelope `{ok: false, error, code?, hint?}` on envelope surfaces: `ok` and
+  `error` are always present; `code` is a stable machine-readable identifier
+  present on every classified failure (exit 1 / 2 / 78) and absent only on
+  unexpected internal errors (exit 70); `hint` is best-effort and may be absent. Prefer
+  `code` over matching on `error` prose. Plus the exit-code table below.
+  **All six** `--format` values (`json|jsonl|yaml|text|md|html`) are available
+  on every non-exempt command. `json`, `jsonl`, and `yaml` serialize the
+  envelope; `text`, `md`, and `html` render it. A command may register a bespoke
+  renderer for a document format — `akm health` does, for its per-run and
+  window-compare tables and its full HTML report — and anything unregistered
+  falls back to a generic rendering derived from the envelope's own shape. No
+  command emits one format's bytes when another was asked for, none rejects a
+  format outright, and **no command reads `--format` to decide what data to
+  fetch**: a registered renderer fires on the shape of the result (`akm health
+  --report` carries the report dataset in the envelope, so the same data is
+  available as JSON), never on the format alone.
+  `--detail` is verbosity only (`brief|normal|full`);
+  `--shape` (`human|agent|summary`) is the output-projection axis (see
+  Experimental). A small set of commands is **format-exempt** because their
+  output is not a result envelope at all: `completions` (shell script source),
+  child-process passthrough in `env run` / `secret run`, a bare-path payload
+  from `env path`, and document payloads from `help` (bare, `help agents`, and
+  `help migrate`). The set is declared in
+  `src/output/format-exempt.ts`, and
+  passing `--format` to one of them warns rather than silently doing something
+  else. Scripted `setup` modes emit a normal format-aware result; interactive
+  `setup` is a terminal UI and emits no result document. `agent` leaves
+  inherited child streams raw and formats its final result envelope.
+  `migrate status`/`apply` both spawn the standalone `akm-migrate` tool but are
+  NOT in the exempt set: `src/commands/migrate-cli.ts` parses the child's
+  final JSON result line and renders it through the same `output()` pipeline
+  (registered shape `src/output/shapes/migrate.ts`, text renderer
+  `src/output/text/migrate.ts`), so all six `--format` values work on them
+  like any other command. Any progress-event lines the child prints during a
+  real `apply` (content migration, proposal-ref repair) still print verbatim,
+  ahead of the formatted result — those are operational logging, not part of
+  the result envelope.
+
+  | Exit code | Meaning |
+  | --- | --- |
+  | `0` | Success |
+  | `1` | Not found / command-reported failure |
+  | `2` | Usage / bad input |
+  | `4` | Health warning (`akm health` only) |
+  | `70` | Internal / unclassified |
+  | `78` | Configuration error |
+- **Install scripts** — `install.sh` and `install.ps1` URLs; the `--prefix`
+  / `AKM_INSTALL_DIR` environment override.
+- **Runtime** — the npm package requires Node.js >= 22 as its bootstrap and
+  prefers a working Bun >= 1.0 for execution when both are available; old,
+  unusable, or absent Bun installations fall back to Node.js. Standalone
+  binaries are runtime-free.
+- **On-disk storage** — durable workspace state (events, proposals, history,
+  workflow runs, salience) lives in `state.db`; the search index (`index.db`)
+  is a fully **regenerable** cache rebuilt by `akm index`; high-volume logs stay
+  in a separate `logs.db`. Asset metadata lives as file-local frontmatter plus
+  the index (there is no separate metadata sidecar). Treat the on-disk schema
+  as internal (use `akm` commands, not direct SQL).
+
+## Evolving
+
+These surfaces are in active iteration as we learn from users. They will
+remain available across minor releases, but flag names, prompts, and
+proposal-queue shape may shift. Breaking changes will be flagged in the
+CHANGELOG with a migration note.
+
+- **Improvement loop** — `akm improve` and the proposal noun group
+  `akm proposal {extract,new,list,show,diff,accept,reject,revert,drain}`
+  (`extract` and `new` are the former top-level `akm extract`/`akm propose`,
+  moved under `proposal` in 0.9.0). Output JSON keys
+  are stable; CLI flags (`--strategy`, `--task`, `--generator`) may add
+  options or tighten validation across releases. `akm improve` stays on by
+  default and is **review-first**: the lanes that mutate assets without review
+  require `experimental.improveAutonomy` — see
+  [`akm improve` autonomy](#akm-improve-autonomy--opt-in-in-090).
+  `--auto-accept` was removed in 0.9.0. It is now accepted-and-warned rather
+  than silently absorbed: passing it prints a deprecation warning naming the
+  replacement, and the space-separated form (`--auto-accept 90`) no longer
+  poisons the asset-type positional — its value is discarded with a second
+  warning instead of silently reducing the run to a zero-match no-op. It
+  becomes a hard error in 0.10. The replacement is
+  `akm improve && akm proposal drain --promote --yes`, or a `triage` block
+  with `applyMode: "promote"` in your strategy.
+- **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
+  history`; no alias, no `list`/`remove`/`init`/`enable`/`disable`); strict
+  version-2 YAML for scheduled tasks. Prompt tasks use named engines and task
+  history metadata is versioned. Schema additions in patch releases; removals
+  only at minor. Bare `akm task` is a usage error naming the subcommands
+  (`akm task doctor` reports scheduler diagnostics).
+- **Events / log** — `akm log` is the event-stream surface (0.9.0: the
+  asset-scoped `akm history` surface, and `log`'s own `tail` subcommand, were
+  both removed; `log` is now a leaf command — the former `list` surface).
+- **Bundles & the workspace model** — installed sources are *bundles*; each is
+  recognized by a built-in *adapter* (native Agent Skills, Claude and OpenCode
+  commands/agents, knowledge, YAML workflows, tasks, env/secret files, scripts,
+  OKF and LLM-wiki knowledge bases). Config is keyed by `bundles` and
+  `defaultBundle`. The adapter set, bundle-recognition rules, and the
+  `bundles` config shape may still shift. Bundles are inspected through
+  `akm bundle list` / `akm bundle show <name>` and enumerated through
+  `akm search "bundle//"`. (An earlier `akm bundle items` noun group was
+  removed in 0.9.0 as duplicative of `akm search`; the current `akm bundle`
+  group — `create | add | list | show | remove | update` — is the
+  lifecycle-management surface consolidated from the former top-level
+  `init`/`add`/`list`/`remove`/`update` commands, not a revival of that one.)
+  OKF is the
+  first-class baseline for Markdown concept identity and generic reads; every
+  applicable OKF conformance case is required to pass. AKM-authored Markdown is
+  an OKF-compatible superset whose adapter adds native behavior progressively.
+- **LLM Wiki bundles** — the Karpathy-style LLM wiki is a first-class built-in
+  bundle format (the `llm-wiki` adapter owns `schema.md` / `index.md` /
+  `log.md` / `raw/` / `pages/` and its ingest flow); wiki pages are addressed
+  as ordinary concepts inside their bundle. Adapter behavior and page
+  conventions are still iterating.
+- **Agent dispatch** — `akm agent` subcommand. Supported backends: `claude`,
+  `opencode`, `opencode-sdk`, `codex`, `copilot`, `pi`, `gemini`, `aider`,
+  `amazonq`, `openhands`. The set will grow.
+- **Proposal queue** — quality classifications (`accepted`, `pending`,
+  `proposed`, `rejected`, `archived`) are stable; the JSON shape of a
+  proposal record may add fields.
+- **Registries** — `akm registry {list,add,remove}`. Searching registries is
+  `akm search --from registry` (0.9.0: `registry search` was folded into
+  `search`). Building a registry index is maintainer tooling (Internal) and
+  lives outside the CLI, in `scripts/build-registry-index.ts`.
+- **Upgrade** — `akm upgrade`. Checksum verification is not optional; the
+  recovery hatch is the `AKM_UPGRADE_SKIP_CHECKSUM` environment variable
+  (Internal), not a flag.
+- **Lint** — `akm lint`. The rule set and finding shapes iterate; the
+  `--fail-on-flagged` CI contract and the exit codes are stable.
+- **Health** — `akm health` and its exit codes (0 pass / 4 warn / 1 fail) are
+  Evolving; the *content* of the report (metrics, advisories) and the rendered
+  `md` / `html` layouts are Experimental — do not script against report layout.
+
+## Experimental
+
+Subject to change without notice within minor releases. Not yet recommended
+for scripted use.
+
+- **`lesson` asset type** — schema (`when_to_use`, `description`) is
+  stable, but lesson-distillation triggers and ranking are tuning targets.
+- **`--shape agent` and `--shape summary`** — the output-projection axis
+  (`--shape human|agent|summary`). `summary` is implemented only on
+  `akm show`; `agent` is implemented on `search`, `show`, and `curate`.
+  Coverage will expand. `--detail` is verbosity only (`brief|normal|full`).
+- **Protected env & secret values** — `env` (a whole `.env` group; key names
+  are surfaced for discoverability, values never are) and `secret` (a single
+  sensitive value). Values are never written to stdout, the index, or
+  structured output; the safe injection path is `akm env run <name> --
+  <command>` (or `akm secret run <name> <VAR> -- …`). The `env` / `secret`
+  **write** verbs (`create`, `set`, `unset`, `remove`) are Experimental; the
+  `list` / `path` / `run` / `export` read-and-inject surface is Stable.
+- **Memory belief-state transitions** — `captureMode`, `beliefState`,
+  contradiction edges, and the consolidate journal are observable but
+  the algorithm that writes them is tuning across patch releases.
+- **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
+  engines, limits, gates, and the anti-collapse / CLS / fidelity knobs) and
+  the `index.*` per-pass config. The 0.9.x series is explicitly still settling
+  the design of the improve processes, so **keys in these two families may be
+  added, renamed, or dropped in any 0.9.x or 0.10.x release**. The `akm
+  improve` *command* surface is Evolving (above); its tuning config is not.
+
+### `akm improve` autonomy — opt-in in 0.9.0
+
+**`akm improve` is review-first by default in 0.9.0.** The command itself is ON
+— its schedules, reflect/distill proposals, and graph extraction all run — but
+the lanes that mutate assets *without* review require an explicit opt-in:
+
+```sh
+akm config set experimental.improveAutonomy true
+```
+
+Without it, these three lanes are downgraded, and each downgrade is **reported,
+not silent**: it warns on stderr naming the lane and the key, appends an
+`improve_skipped` event with `reason: "autonomy_gated"`, is counted in
+`akm health`'s improve skip-reason summary, and is listed by `akm task doctor`
+under `improveAutonomy.gatedLanes` — which is where to look when a *scheduled*
+run stops doing something it used to. `akm task doctor` also reports the
+**effective** `improveTriage.applyMode`, so a `promote` strategy under a
+review-first config correctly shows `queue`.
+
+| Lane | What it does when enabled | With autonomy off |
+| --- | --- | --- |
+| `memoryInference` | Writes `.derived.md` children and rewrites parent frontmatter | disabled |
+| memory cleanup | Belief-state frontmatter rewrites, archive moves | analyzed but not applied |
+| `triage` `applyMode: "promote"` | Auto-accepts queued proposals into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+
+Consolidation remains enabled with autonomy off because merge, delete, and
+contradiction operations are advisory; promotion only emits a reviewable
+proposal.
+
+Because the gate is applied before the LLM preflight, a review-first workspace
+also needs fewer engines configured: a strategy whose only model-backed process
+is a gated lane resolves without an engine at all.
+
+**Three direct writes are deliberately NOT gated**, because they are additive or
+already independently controlled:
+
+| Write | Why it stays ungated |
+| --- | --- |
+| `extract` session indexing | Additive `sessions/**` writes; nothing is overwritten or deleted |
+| distill's encoding-salience stamp | Frontmatter metadata only |
+| `sync.push` | Publishes already-committed content to a remote the user configured for that purpose, and has its own `improve.strategies.<name>.sync.push: false` and `--no-push` |
+
+Autonomy is never inferred: an absent `experimental` section, an absent key, and
+an explicit `false` all read as off, so a partially-written or older config is
+review-first rather than accidentally permissive.
+
+Reflect, distill, extract candidates, validation, proactive-maintenance
+selection, and graph extraction are proposal-only and never write assets
+directly. Two further direct writes are ungated by design: `extract`'s session
+indexing (additive `sessions/**` writes,
+`processes.extract.indexSessions`, default on) and distill's
+encoding-salience frontmatter stamp (metadata only).
+
+## Internal
+
+Not public interfaces. Listed so you can recognize them, not so you can rely
+on them.
+
+- **Migration surfaces** — the standalone `akm-migrate` tool owns the one-time
+  0.8→0.9 cutover, storage migration, and recovery backups (`akm-migrate
+  backup` / `restore`). `akm migrate` is a thin process forwarder; `akm backup`
+  and `akm config migrate` are removed. `akm help migrate <version>` is Stable
+  and only renders release notes.
+- **`bun scripts/build-registry-index.ts`** — maintainer tooling for building a
+  registry index. It is a repository script, not a CLI command (the former
+  `akm registry build-index` subcommand was removed).
+- **Environment variables** — see the table below.
+
+### Environment variables
+
+**Supported** — documented interfaces; changes get a CHANGELOG note:
+
+| Variable | Purpose |
+| --- | --- |
+| `AKM_BUNDLE_DIR`, `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` | Filesystem layout overrides |
+| `AKM_LLM_API_KEY`, `AKM_EMBED_API_KEY`, `AKM_ENGINE_<NAME>_API_KEY` | Credential provision for `$VAR` config references |
+| `AKM_LLM_ENDPOINT`, `AKM_LLM_BASE_URL` | Setup provider inference |
+| `AKM_VERBOSE`, `AKM_DEBUG` | Diagnostics |
+| `AKM_REGISTRY_URL` | akm registry mirror override |
+| `AKM_NPM_REGISTRY` | npm mirror override — redirects BOTH the trusted-tarball host allowlist and package metadata lookups (`npm view`-equivalent resolution) to the given registry base, replacing `registry.npmjs.org` wholesale rather than merging with it |
+| `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode (network filesystems) |
+| `AKM_BIN` | Absolute `akm` path for scheduler registration |
+| `AKM_INSTALL_DIR` | Install-script prefix |
+| `AKM_FORCE_SETUP_TMP_STASH` | Documented escape hatch for intentional temp-directory bundles |
+| `AKM_UPGRADE_SKIP_CHECKSUM` | Recovery hatch for a broken upgrade checksum |
+
+**Internal** — no compatibility guarantee, may vanish without notice:
+`AKM_NODE_ENTRY`, `AKM_EVENT_SOURCE`, `AKM_SESSION_ID`, `AKM_AGENT_HARNESS`,
+`AKM_EMBED_DETERMINISTIC`, `AKM_CLAUDE_PROJECTS_DIR`,
+`AKM_FORCE_INIT_TMP_STASH`, `AKM_STATE_DIR`.
+
+Anything matching `AKM_TEST_*` is test-only fault injection. Never set it.
+`AKM_VERSION` is the only variable actually stripped from release builds, via
+`bun build --define` (see `.github/workflows/release.yml`); no `src/` code
+reads an `AKM_TEST_*` variable, so the compiled `akm` binary itself carries
+none. That said, three fault-injection hooks are NOT compiled out and DO ship
+in every install: `AKM_TEST_MIGRATION_FAIL_INDEX_QUARANTINE`,
+`AKM_TEST_MIGRATION_FAIL_WORKFLOW_DELETE`, and
+`AKM_TEST_MIGRATION_FAIL_RESTORE_AFTER` (`scripts/akm-migrate/`). The migration
+tool ships separately from the compiled `akm` binary, so these throw-only hooks
+remain physically present. At rest they are runtime-guarded no-ops unless the
+exact internal test value is set. Never set them.
+
+## On the horizon
+
+These changes are planned and will land in a known future release. They
+are not part of the current stability contract; you should plan migrations
+around them.
+
+**The 0.9.0 decision record is fully shipped.** The
+[decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md) settles a set of
+breaking changes; every one of them is now in the code, and each decision
+carries its own shipped status.
+
+Shipped from that record: **D1** (`#fragment` section selection),
+**D2** (the `akm show <ref> toc|section|lines|frontmatter|full` view grammar is
+gone — `#fragment` is the only section selector), **D4** (conceptId /
+`bundle//` prefix browse), **D5** (`akm bundle` removed), **D6** (open `type`
+set at runtime), **D7** (all six `--format` values everywhere), **D8** (the
+`experimental.improveAutonomy` gate), **D9** (`--auto-accept` warn-and-ignore),
+and partially **D10** (an `akm-migrate` binary now exists, though the code still
+lives in this repo). **D3** shipped too, in the end: `akm mv` was removed in
+0.9.0 (see the Renames bullet above), with `scripts/rekey-asset-ref.ts` as the
+Internal replacement for the one capability nothing else covered.
+
+- **0.10 — migration extraction.** The migration machinery leaves the CLI for
+  a separately published `akm-migrate` package (see Internal above).
+- **0.10 — `--auto-accept` hard error.** It is currently accepted-and-warned;
+  see the Improvement loop entry.
+- **0.10 — `BundleAdapter.placeNew()` wiring.** The interface declares
+  `placeNew()` as an optional capability method, and 8 of the built-in
+  adapters already implement it, but nothing in the write path calls it —
+  writes still resolve through AKM's native flat type→directory table.
+  Placement for every existing bundle is already correct today; this is a
+  deliberately sequenced routing change, not unfinished behavior. See
+  [D12](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)
+  for why it is scoped out of 0.9.0. Nothing user-visible changes in 0.10 for
+  this alone.
+- **1.0 contract freeze** — the `[bundle//]conceptId[#fragment]` ref grammar,
+  the supported source model, search behavior, and write-target rules are
+  frozen at 1.0. The SDK and in-process plugin story ship on top of that
+  frozen core.
+
+## Reporting stability regressions
+
+If you script against a stable surface and a release breaks it without a
+CHANGELOG migration note, please open an issue at
+<https://github.com/itlackey/akm/issues> labeled `regression`. We treat
+stable-surface regressions as priority bugs.
+
+For experimental surfaces, expect change — but file an issue if a change
+isn't called out in the CHANGELOG, since that's still a documentation gap
+worth fixing.
+
+## See also
+
+- [`CHANGELOG.md`](./CHANGELOG.md) — every release's behavior changes.
+- [`SECURITY.md`](./SECURITY.md) — security supported-version policy
+  (independent of the feature-stability policy above).
+- [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the
+  normative ref grammar.
+- [`docs/architecture/specs/0.9.0-decisions.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md)
+  — the decision record behind the 0.9.0 surface changes.
+- [`docs/reference/data-and-telemetry.md`](./docs/reference/data-and-telemetry.md) — what
+  state akm reads and writes locally.