akm-cli 0.9.0-rc.8 → 0.9.0

package/CHANGELOG.md

@@ -4,12 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.9.0] - 2026-07-20
+## [Unreleased]
+
+## [0.9.0] - 2026-08-06
 
 0.9.0 is the format-neutral **bundle / adapter** refactor: it replaces the flat
 asset-type registry with per-format adapters, adopts one canonical ref grammar,
-and consolidates the durable databases and config. This section supersedes the
-earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
+and consolidates the durable databases and config. This section consolidates and
+supersedes the `0.9.0-rc.*` / `0.9.0-beta.*` development entries below.
 
 ### Breaking changes & migration
 
@@ -28,17 +30,18 @@ earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
   fully-qualified `bundle//conceptId`; the short bundle-omitted form is accepted
   input only (resolved against `defaultBundle`, then installation-priority
   order). The pre-0.9.0 `[origin//]type:name` grammar is removed — there is no
-  compatibility parser; the frozen migrator in `src/migrate/legacy/` is the only
-  place it survives.
-- **Explicit, journaled, crash-resumable cutover (`akm migrate apply`).** The
+  compatibility parser; the frozen migrator in `scripts/akm-migrate/migrate/`
+  is the only place it survives.
+- **Explicit, crash-resumable cutover (`akm migrate apply`).** The
   migrator re-keys all durable state to the new spelling, folds the former
   `workflow.db` into `state.db` (four databases down to three: `state.db` /
   `index.db` / a separate `logs.db`), and migrates config from the flat
   `stashDir` / `sources` / `installed` / `wikiName` keys to `bundles` /
-  `defaultBundle`. A verified, installation-scoped **backup manifest v3**
-  (covering the pre-rescue `index.db`) is taken before any ledger is sealed;
-  expected orphans are quarantined, integrity failures fail closed, and the
-  whole cutover resumes idempotently after a crash. Normal commands refuse an
+  `defaultBundle`. A semantically verified, installation-scoped **backup manifest v4**
+  (covering the pre-rescue `index.db`) is taken before mutation. One phase-free
+  incomplete sentinel retains that backup and target; expected orphans are
+  quarantined, integrity failures fail closed, and the whole cutover reruns
+  idempotently after a crash. Normal commands refuse an
   un-migrated or divergent durable schema rather than migrating as a side effect.
   The retired `stashDir` / `sources` / `installed` keys are **hard-rejected** by
   the 0.9.0 config schema whenever present (the error names `akm migrate apply`);
@@ -52,7 +55,7 @@ earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
   index (and renamed by the content migration when they hold a real concept).
 - **`vault` asset type removed.** Use `env` (a whole `.env` group; key names
   surfaced, values never) and `secret` (a single sensitive value), addressed as
-  `env/<name>` and `secrets/<name>`. `akm-migrate-storage` still performs the
+  `env/<name>` and `secrets/<name>`. `akm-migrate storage` performs the
   non-destructive `vaults/` → `env/` copy for older stashes.
 - **0.8-era CLI aliases removed.** The flat proposal verbs (`akm proposals`,
   `akm accept`, `akm reject`, `akm diff`, `akm revert`, `akm show proposal`),
@@ -64,8 +67,95 @@ earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
 See `docs/migration/v0.8-to-v0.9.md` and
 `docs/migration/release-notes/0.9.0.md` for the full upgrade procedure.
 
+### Removed
+
+- **The experimental `akm workflow brief` / `akm workflow report`
+  external-driver protocol is removed**, along with the
+  `experimental.workflowEngine` config key that gated it, its
+  `WORKFLOW_ENGINE_NOT_ENABLED` error code, and the `workflowEngine` block in
+  `akm task doctor`. `akm workflow run` is now the single execution surface.
+
+  The protocol let a calling agent session execute a run's units itself
+  instead of akm dispatching them. Its stated justification was harness
+  neutrality, which measurement did not support: native dispatch already
+  covers **ten** harnesses (opencode, claude, opencode-sdk, codex, copilot,
+  pi, gemini, aider, amazonq, openhands) in 2,214 LOC total, while the
+  protocol cost 2,690 LOC on its own — more than supporting every harness
+  natively — and an eleventh harness is ~220 lines, not a protocol. Removing
+  it also drops the second consumer of `workflow_run_units` and the
+  cross-surface parity obligation on `step-work.ts`, both of which
+  constrained every future engine change. The analysis is recorded in
+  `docs/architecture/specs/driver-protocol-keep-or-cut.md`.
+
+  Legacy configs setting `experimental.workflowEngine` remain valid — the
+  config schema is `.passthrough()`, so the key is accepted and ignored.
+
 ### Added
 
+- **`akm workflow run` and prompt tasks fall back to `opencode-sdk` instead of
+  refusing when no engine is configured.** A clean install that never ran
+  `akm setup` — a bare container, a CI image, an agent-operated session — used
+  to fail closed with `INVALID_CONFIG_FILE` (exit 78). When the `opencode`
+  binary is on PATH, akm now synthesizes a **config-free** `opencode-sdk`
+  engine: it carries no model, endpoint, or credential, so provider, model,
+  and auth all resolve from opencode's own configuration and akm never mirrors
+  or validates it. With `opencode` absent the failure is unchanged, and its
+  remedy now names both routes. An operator-configured `opencode-sdk` engine
+  always wins over the synthesized one.
+
+  The requirement is the **binary**, not the npm package: `@opencode-ai/sdk`
+  is an HTTP client that declares no dependencies and whose own
+  `createOpencodeServer` spawns `opencode serve`, so a host with the package
+  and no binary has no server to reach. Install it with `npm i -g opencode-ai`
+  or opencode's own installer.
+
+  The fallback is **announced, never silent** on every surface that applies
+  it: a workflow run surfaces it once at run creation in the result's
+  `warnings`, a prompt task writes it to the task run log, `akm agent`
+  carries it in its result `warnings` and on stderr, and `propose` and
+  `improve` reflect warn on stderr. The frozen plan records the engine
+  actually used, so a resume never re-announces a decision it did not make.
+
+- **RSS, Bluesky, and X sources.** `akm bundle add` now recognizes three new
+  kinds of URL and snapshots them as knowledge assets instead of crawling
+  them as ordinary web pages:
+
+  ```sh
+  akm bundle add https://blog.example/feed          # RSS 2.0 / Atom / RDF
+  akm bundle add https://bsky.app/profile/<handle>  # public, no auth
+  akm bundle add https://x.com/<user>               # see token note below
+  ```
+
+  Any of these falling through — a `/feed` URL that actually serves HTML, an
+  unresolvable Bluesky handle — degrades to the normal website crawl rather
+  than failing the command.
+
+  X needs credentials: set `X_BEARER_TOKEN` for the X API v2, or
+  `X_RSS_TEMPLATE` to an RSS bridge URL containing `{username}`. To keep the
+  token out of your shell history, store it as an akm secret and inject it
+  per-invocation:
+
+  ```sh
+  akm secret set x-bearer-token
+  akm secret run secrets/x-bearer-token X_BEARER_TOKEN -- akm bundle add https://x.com/<user>
+  ```
+
+  With neither set, the X fetcher emits one warning and falls through.
+
+- **`akm-migrate` derives the 0.9 config from your 0.8 keys instead of
+  demanding one.** Upgrading used to require hand-authoring a complete 0.9
+  config before `migrate apply` would act. The first `apply` with no
+  `--config` now writes a validated starter config — `bundles`/`defaultBundle`
+  derived from the 0.8 `stashDir` / `sources` / `installed` keys — to a
+  predictable path under the backup root and stops, with config and durable
+  state byte-for-byte untouched; a second `apply` picks it up and performs the
+  cutover. Engine settings are never guessed: `profiles.*` and
+  `defaults.llm|agent|improve` are stripped and reported individually in
+  `droppedKeys` by their exact 0.8 dotted path. `status` and `apply --dry-run`
+  preview the same plan, and an explicit `--config` always wins and is never
+  overwritten. `akm migrate --format` now renders text/md/html/yaml through
+  the normal output pipeline instead of warning and printing JSON anyway.
+
 - **Local downstream value attribution for memory inference and graph
   extraction.** Private search-hit sidecars now write versioned, source-qualified
   per-entry `usage_events.metadata` for emitted MI direct/surface value and the
@@ -79,33 +169,25 @@ See `docs/migration/v0.8-to-v0.9.md` and
   migration, dashboard, or health schema was added.
 - **Explicit, crash-resumable 0.9 migration coordination.** `akm migrate
   status` classifies config, `state.db`, and `workflow.db` independently;
-  `akm migrate apply [--config <prepared>]` creates a verified,
-  installation-scoped backup before sealing ledgers or applying pending
-  migrations. Apply and restore use authenticated phase journals, exact
-  artifact fingerprints, bounded streaming I/O, SQLite integrity checks,
-  active-writer barriers, WAL/SHM-safe publication, and idempotent recovery.
-  Routine reads and current database opens no longer depend on a historical
-  cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
+  `akm migrate apply [--config <prepared>]` creates a semantically verified,
+  installation-scoped config/database backup before applying pending migrations.
+  Apply and restore use one phase-free incomplete sentinel, bounded control-file
+  reads, SQLite integrity and ordered-ledger checks, active-writer barriers,
+  WAL/SHM-safe publication, and idempotent replay. Legacy checksum columns are
+  inert. Routine reads and current database opens no longer depend on a
+  historical cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
 - **Workflow orchestration engine (experimental).** akm can now execute
-  multi-step workflows as deterministic **YAML programs**, driven either by a
-  native engine or by any agent session. This is a new, self-contained
-  surface; classic linear **markdown workflows and the stable workflow CLI
-  contract (`start`/`next`/`complete`/`status`/`list`) are unchanged**. What
-  ships:
-  - **Authoring.** Orchestrated workflows are YAML programs
-    (`workflows/*.yaml`, `version: 2`) validated against a published JSON
-    Schema (`schemas/akm-workflow.json`) by `akm workflow validate`; scaffold
-    one with `akm workflow template --yaml` or `akm workflow create
-    <name>.yaml`. A closed `${{ … }}` expression language (exactly
-    `params.<name>`, `steps.<id>.output.<path>`, `item`, `item_index`, parsed
-    once into an AST) wires steps together. `validate` also surfaces non-fatal
-    **warnings** (a step with no typed `output:` schema; a `${{ params.<name> }}`
-    reference to a param the declared `params:` block omits) that never change
-    the frozen plan or its hash. Creating a workflow whose canonical name
-    collides with an existing asset of a **different** extension (`foo.yaml`
-    while `foo.md` exists, or vice-versa) is refused, since the two would
-    silently shadow each other.
-  - **Compilation + frozen plans.** `akm workflow start` compiles the program
+  multi-step workflows through a native engine or any agent session. Workflow
+  assets use the unified markdown format described above; the stable manual
+  CLI contract (`start`/`next`/`complete`/`status`/`list`) and the experimental
+  engine consume the same asset. What ships:
+  - **Authoring.** A workflow is a markdown asset whose frontmatter graph is
+    validated against `schemas/akm-workflow.json` and whose `## <step-id>` body
+    sections carry instructions and gate rubrics. `akm workflow create`
+    scaffolds that format; `akm lint --type workflows` parses and compiles it.
+    Bare references (`params.<name>` and `steps.<id>.output.<path>`) wire
+    `map.over`, `route.input`, and `inputs`; prose is never interpolated.
+  - **Compilation + frozen plans.** `akm workflow start` compiles the workflow
     into a backend-agnostic Workflow Plan Graph IR (`src/workflows/ir/`) and
     freezes it on the run row (`plan_json` + `plan_hash`); a run executes the
     plan compiled at start, and edits to the source file require a new run.
@@ -114,8 +196,7 @@ See `docs/migration/v0.8-to-v0.9.md` and
     reducer), a typed `output` JSON Schema (validated via a `runStructured`
     retry-with-feedback loop), `env` bindings (resolved through the existing
     `akm env run` machinery — secret tokens, dangerous-key policy, keys-only
-    audit events), classify-and-dispatch `route` steps, and `depends_on`
-    ordering.
+    audit events), and classify-and-dispatch `route` steps.
   - **Determinism + replay.** Journaled unit identity is content-derived
     (`<step>:<sha256(item)[:12]>`, `:solo` for a single unit), so cached
     results survive item-list reordering; a completed unit whose recorded
@@ -137,9 +218,9 @@ See `docs/migration/v0.8-to-v0.9.md` and
     criteria-bearing gate judges that **artifact** (canonical JSON, clipped)
     rather than machine prose, and each engine-driven evaluation is journaled
     as a gate unit row. `gate.max_loops` bounds an evaluator-optimizer retry
-    loop (feedback threaded into re-dispatched unit prompts); `gate.required`
-    (or the run-wide `--require-gates`) makes a gate with no available judge
-    **block** for a human instead of failing open.
+    loop (feedback threaded into re-dispatched unit prompts). Gates are
+    optional validation: omitted/empty rubrics and unavailable or malformed
+    judges skip validation.
   - **Failure policy.** Per-unit `on_error: fail | continue` (fail-fast
     default) plus bounded `retry: { max, on: [<failure_reason>…] }` keyed on
     the persisted failure taxonomy.
@@ -370,6 +451,62 @@ See `docs/migration/v0.8-to-v0.9.md` and
 
 ### Changed
 
+- **X source tokens now resolve from the secret store during bundle update.**
+  The `secrets/x-bearer-token` akm secret is honored on the provider
+  `sync()` / bundle-update path, not just when adding or importing a URL —
+  closing a gap where a refresh saw only the `X_BEARER_TOKEN` environment
+  variable. Implemented as a `SecretResolver` capability injected from above
+  the source-provider import cycle; internals are documented in
+  `docs/architecture/reviews/env-secret-access.md`.
+
+- **`website` crawls now have a hard time limit.** `crawlTimeoutMs` (default
+  600000 — 10 minutes) bounds the entire crawl, and unlike the previous
+  between-page check it aborts work already in flight: a `Retry-After` sleep
+  could previously park `akm bundle add` for as long as a rate-limiting server
+  asked, well past the advertised cap. Raise it for a large site, or set
+  `"crawlTimeoutMs": 0` to disable the cap. Relatedly, `fetchWithRetry` now
+  honors its caller's `AbortSignal` during retry backoff, so any operation that
+  passes a signal can actually interrupt a long wait.
+
+- **Website snapshots now extract the page's main content.** Conversion moved
+  from a hand-rolled regex converter to a DOM parse plus Turndown, scoped to
+  the page's content region (`<main>`, `<article>`, `[role=main]`, then common
+  content ids/classes, falling back to `<body>` minus nav/header/footer/aside).
+  Navigation, ads, and boilerplate no longer land in snapshots, and tables,
+  nested lists, and fenced code blocks with language hints now survive
+  conversion. **Existing website snapshots will change on their next refresh**
+  — expect them to get shorter and cleaner. Link discovery still scans the
+  whole page, so crawl coverage is unchanged.
+
+
+- **`website` sources now respect `robots.txt` by default.** Before crawling
+  an origin, akm fetches and parses that origin's `/robots.txt` and skips
+  paths disallowed for the `akm`/`akm-cli` product tokens (or `*`), honoring
+  `Crawl-delay` (clamped to 10s) between page fetches. This is a deliberate
+  behavior change: **existing website sources may return fewer pages, or
+  fail with an error if the start URL itself is disallowed, after
+  upgrading.** Re-running `akm bundle update` on a website source is what
+  surfaces it. Opt out with `"respectRobots": false` on the website
+  descriptor to restore the exact pre-upgrade behavior (no `/robots.txt`
+  request at all):
+
+  ```json
+  { "bundles": { "docs": { "website": { "url": "https://docs.example.com", "respectRobots": false } } } }
+  ```
+
+- **`akm lint` now routes through each bundle adapter's own `validate()`.**
+  `validate()` was a required member of the adapter interface that nothing
+  called: `akm lint` branched on adapter id and re-implemented OKF's checks
+  inline (with drifted semantics for `missing-type`), OKF's `missing-ref`
+  never ran at all (a bundle with a dangling link reported nothing), and
+  llm-wiki's `uncited-raw` / `broken-xref` / `broken-source` /
+  `missing-description` checks were unreachable dead code. **Existing OKF and
+  llm-wiki bundles may surface new lint findings after upgrading.** akm-bundle
+  lint output is byte-identical. Proposal promotion also runs the adapter
+  check immediately before the write — advisory-only: it warns and never
+  rejects, because the adapter resolver and the legacy promotion gate still
+  disagree on foreign-typed cross-bundle refs.
+
 - **Improve-stage extraction and proactive maintenance now ship opt-in.** The
   built-in `default` and `frequent` strategies resolve extract off, while
   `default` and `reflect-distill` resolve `proactiveMaintenance` off. The
@@ -440,6 +577,61 @@ See `docs/migration/v0.8-to-v0.9.md` and
 
 ### Fixed
 
+- **Fresh 0.8 installs can actually upgrade.** A config that 0.8.x wrote
+  itself carries no `configVersion` key at all (0.8 stamped it only when a
+  0.7-era migration did substantive work), and the migrator read the absent
+  key as `inconsistent` — an unconditional blocker. `migrate status` reported
+  `blocked` and `migrate apply` refused with exit 78 for every fresh 0.8
+  install; reproduced end to end against the published `akm-cli@0.8.14`. An
+  absent `configVersion` on a positively pre-cutover-shaped config now
+  classifies as `old`; a present-but-unparseable version still fails closed.
+  Relatedly, `migrate` reports `not-applicable` (exit 0) instead of `blocked`
+  when there is no akm installation to migrate at all, and `apply` warns when
+  an active workflow run targets an asset that fails 0.9 structural
+  validation, naming the asset and `akm workflow abandon <run-id>`.
+
+- **`akm lint` fails closed on mistyped invocations.** A nonexistent `--dir`,
+  or an unknown `--type` on an akm bundle (the classic singular/plural typo,
+  `--type workflow`), used to scan nothing and report a clean
+  `ok:true, flagged:0` — silently passing scripted `--fail-on-flagged`
+  gates. Both are now usage errors (exit 2), the `--type` error listing the
+  valid values.
+- **Registry search survives a briefly unreachable registry.** Once the
+  cached registry index aged past its refresh TTL, a failed fetch
+  hard-failed the command even though a serviceable index sat in the cache.
+  A failed fetch now serves the last cached index — past its TTL — with a
+  warning naming the fetch error.
+- **`akm upgrade` verifies the package manager actually delivered the new
+  version.** A lagging `@latest` dist-tag (partial publish, registry mirror
+  lag) exits 0 while leaving the old version on PATH; upgrade used to report
+  success anyway — and then run `migrate apply` against the old binary. It
+  now re-reads `akm --version` after the install: a confirmed mismatch
+  reports `upgraded: false` with an exact-version pin command, and a
+  verified match is named in the success message.
+- **`akm info` no longer overstates semantic-search health.** After a run
+  with partial sqlite-vec fast-path insert failures, the verification
+  reported `ready-vec` ("sqlite-vec active") even though search had already
+  routed to the slower JS-cosine fallback. The status now reflects the path
+  search actually takes, with an `akm index --full` hint when the fast path
+  is degraded. Relatedly, `embedding.dimension` is now bounded to the
+  vec table's own 1–4096 limit at config validation, so an out-of-range
+  value fails at `akm config set` with a clear message instead of crashing
+  `akm index` mid-run.
+- **Standalone `akm remember --enrich` actually enriches.** With no other
+  metadata flag, `--enrich` fell through to the zero-flag raw-write hot path
+  and never attempted the LLM call — an unenriched memory with no warning.
+  `--enrich` now routes to the enrichment dispatch exactly like `--auto`;
+  the fail-soft contract is unchanged (no configured LLM still warns and
+  writes without enrichment).
+- **Read paths no longer plant a broken `index.db` on a fresh install.**
+  The fire-and-forget usage telemetry behind `search` / `show` / `curate`
+  opened `index.db` with create-on-open: with no index built yet, the open
+  itself left an empty, schema-less `index.db` behind, and every later
+  command then saw an existing-but-broken index ("no such table: entries") —
+  hard-failing proposal acceptance among others. `openExistingDatabase` now
+  refuses to create the file (a missing index throws, naming `akm index` as
+  the remedy) and the telemetry paths skip cleanly instead.
+
 - **Improve RC stabilization.** Restored one ownership-safe whole-run lock from
   triage through final sync; `--skip-if-locked` is a true no-op; the run deadline
   now starts before indexing and reaches index waits, generation, reindexing, and
@@ -465,6 +657,833 @@ See `docs/migration/v0.8-to-v0.9.md` and
   keys (`name`, `updated` were missing); removed the documented-but-nonexistent
   `akm workflow step` alias from `docs/features/workflows.md`.
 
+## [0.9.0-rc.13] - 2026-07-31
+
+### Security
+
+- **`akm update` no longer deletes a previous install directory without
+  confirmation.** When a managed source's resolved content location moves,
+  `update` removed the old directory outright, while `akm remove` had always
+  required `--yes` in non-interactive mode. Only that destructive branch is
+  gated — a normal refresh, where the location does not move, still needs no
+  prompt and no flag, so existing CI invocations are unaffected. Pass
+  `-y`/`--yes` to allow the deletion non-interactively. A cleanup that fails
+  now warns instead of failing silently.
+
+- **The dangerous-env-key install gate now scans `env/` recursively.** It
+  previously read only the top level, so a stash carrying `LD_PRELOAD` in
+  `env/nested/inner.env` installed cleanly with no warning. Files without a
+  `.env` suffix are still not scanned — no akm code path loads them as
+  environment variables.
+
+### Added
+
+- **The `okf` adapter reads OKF v0.2's trust/provenance and lifecycle
+  frontmatter families.** `generated: {by, at}` (with `generated.at` taking
+  precedence over the legacy `timestamp` field, which remains a valid
+  fallback), `verified` (a list, or v0.2's permitted single-mapping
+  shorthand), `sources` (an object list — `resource` required; `id`/`title`/
+  `author`/`usage_count`/`last_modified` optional), `status`
+  (`draft`/`stable`/`deprecated`), and `stale_after` are now parsed leniently
+  from any OKF concept's frontmatter and surfaced on new, namespaced
+  `IndexDocument` fields (`provenance`, `lifecycleStatus`, `staleAfter`,
+  `okfVersion`) that never overload the pre-existing AKM-native `sources`
+  (wiki citation strings), `generation` (consolidation depth), or `quality`
+  fields. As with every other optional OKF field, a missing or malformed
+  value never rejects the document. The `okf` adapter remains consumer-only.
+
+- **Accepting a proposal now stamps OKF v0.2 provenance onto the written
+  asset's frontmatter**, for AKM-native writes only (never through the `okf`
+  adapter, which stays consumer-only and unaffected by this). `promoteProposal`
+  projects the proposal system's own `source`/`sourceRun`/`gateDecision`/
+  `review` bookkeeping — already tracked in `state.db` but previously never
+  written to disk. `generated: {by, at}` and `verified: [{by, at}]` are written
+  **bare at the top level**, exactly as OKF v0.2 spells them, so a third-party
+  OKF v0.2 reader pointed at an AKM stash sees conformant trust metadata;
+  `sources` alone is namespaced as `provenance: {sources}`, because a bare
+  `sources:` collides with the pre-existing wiki citation-string convention.
+  `generated.by` records whether the content came from an automated pipeline
+  (`akm/<version>`) or a human-initiated source (`human:<id>`); `verified`
+  records whether the promotion itself was an automated gate decision or a
+  direct human accept, and accumulates rather than overwriting across
+  re-promotions; `evidenceSources`, when present, projects as
+  `provenance.sources`. AKM's own adapter rereads what it wrote, so `akm show`
+  surfaces it. Every AKM-native markdown type is stamped, `workflow` included.
+
+  Two consequences worth knowing: promotion re-serializes the whole frontmatter
+  block, so YAML **comments** in a hand-written proposal's frontmatter are not
+  preserved (values and body bytes are); and for a human-attributed promotion
+  with no configured actor id, `by` falls back to `human:<OS username>`, which
+  puts that username into content you may later commit and share.
+
+- **Internal: a `capturedAtHead` integrity guard**
+  (`scripts/lint-golden-captured-at-head.ts`, wired into `bun run lint`) now
+  checks every golden fixture's recorded `capturedAtHead` commit SHA — it must
+  exist in the local object database and be reachable from at least one known
+  branch. Post-hoc review of this PR found all four new OKF format-family
+  goldens pointed at a commit that existed locally but was unreachable from
+  any ref (a pre-amend duplicate left behind by an interrupted git operation),
+  which would have 404'd on GitHub and vanished under a local `git gc`; a
+  human fixed that one by hand because nothing caught it. This guard is that
+  catch, going forward. In CI's shallow (`fetch-depth: 1`) checkout, a merely
+  *absent* commit object is inconclusive (indistinguishable from "just not
+  fetched") and only warns; a commit that *exists but is unreachable from any
+  branch* — the actual bug class above — still fails there too, since a
+  shallow clone can tell presence apart from absence just fine.
+
+- **`akm log list --limit <n>`** returns the most recent N events. The flag was
+  documented but silently ignored, and there was no limiting mechanism at all
+  in the read path — the command returned the entire events table regardless of
+  history size. The default remains unlimited.
+
+- **`--track-usage` (default on) on `akm search`, `akm curate`, and `akm show`.**
+  Pass `--no-track-usage` for a read-only lookup that does not feed usage
+  telemetry or the utility-score ranking signal. Previously a bare `akm search`
+  silently wrote a `utility_scores` row that influenced future ranking, with no
+  disclosure and no way to opt out.
+
+- **`akm show` returns the canonical `ref` in every shape.** It was present only
+  under `--shape agent`, so a `--shape summary` consumer had to make a second
+  call at a different shape just to learn which asset it was looking at.
+
+- **`akm info` gained `stashDir`, `defaultBundle`, and `indexStats.byType`.**
+  Answering "which stash is primary" previously required a separate
+  `akm sources list`.
+
+- **`instruction` is a stash-resident asset type.** It was already in
+  `KNOWN_TYPES` and had a presentation entry, but had no placement spec — so
+  there was nowhere to put one and the indexer never recognized one. `akm bundle create`
+  now creates an `instructions/` directory, `.md` files under it index as
+  `instruction`, and `--type instruction` is accepted and tab-completable
+  everywhere `--type` is. A compile-time assertion now pins
+  `placementTypes() ⊆ KnownType`, so the half-registered state this fixes
+  cannot recur silently.
+
+- **Schedule tasks from any configured bundle via `--bundle <bundle>`** (#711).
+  `akm task add`, `run`, `sync`, and `history` accept `--bundle` to
+  operate on a non-default bundle instead of only the primary stash. `add`
+  resolves through the normal writable-target rules; `run --bundle X` resolves
+  the task file and relative asset refs from bundle X. A non-default bundle is
+  recorded in the scheduler entry as `--bundle <bundle>`, so scheduled
+  `akm task run` resolves the right bundle. Scheduler ids stay bare and a
+  collision with another bundle is a hard error rather than a silent clobber.
+
+- **Orphan-GC pass for unresolvable `asset_salience` / `asset_outcome` state
+  rows** (#733). A new improve maintenance pass (`runOrphanStateGcPass`, run
+  next to the existing orphan-proposal purge) stamps `missing_since` on any
+  state row whose ref no longer resolves against `entries.item_ref`, clears
+  the stamp the moment the ref resolves again, and — only when
+  `improve.stateGc.collect` is set to `true` (**default `false`**) — deletes
+  rows whose stamp is older than a fixed 7-day grace window
+  (`STATE_GC_GRACE_MS`). The pass always runs and always reports counts via
+  the new `asset_state_gc` event (`{pending, collected, byTable}`), emitted
+  only when there is something to report, so live data can prove the report
+  clean before `collect` is ever turned on. Additive migration
+  `021-asset-state-missing-since` adds the `missing_since` column to both
+  tables. Deliberately lean by design (Workstream C): no quarantine archive,
+  no circuit breaker, no health-advisory plumbing, no new tables — "ref not
+  present in `entries.item_ref`" is trusted as the authoritative-deletion
+  predicate because the indexer already preserves a source's last-known-good
+  rows when its scan is incomplete, so a temporarily unreachable source never
+  contributes false candidates. `usage_events` is out of scope (already
+  covered by cascade-on-delete plus its own 90-day retention purge).
+
+### Changed
+
+- **Workflow execution is consolidated on stable `akm workflow run`.** The
+  public `workflow start`, `next`, and `complete` commands are removed with
+  explicit `UNKNOWN_COMMAND` migration hints; `run <ref|run-id>` now owns
+  creation, active-run continuation, native dispatch, completion, and durable
+  replay. It is no longer gated by `experimental.workflowEngine`; only the
+  experimental `brief`/`report` external-driver protocol retains that opt-in.
+  Workflow parameters move from the opaque `--params '<json>'` bag to exact
+  declared flags (`--version 1.2.3`, repeated array flags, JSON object/array
+  values) coerced through the frozen parameter schemas. New invocation controls
+  add bounded failed-step retries (`--max-retries`) and a whole-run timeout
+  (`--timeout N|Nms|Ns|Nm`); failures, gate rejection, timeout, and signals now
+  produce non-zero process statuses while leaving interrupted work resumable.
+
+  Criteria-bearing gates now require `workflow.judgeEngine`, which may name a
+  configured LLM or agent engine and is frozen into the run. Verification is
+  fail-closed: a missing/failing verifier or malformed verdict rejects instead
+  of silently advancing. Scheduled workflow tasks now execute through the same
+  native orchestrator rather than stopping after run creation. Migration:
+  replace `workflow start/next/complete` loops with `workflow run`, replace
+  `--params` with exact declared flags, and configure `workflow.judgeEngine`
+  before running a workflow with a non-empty `### gate` rubric.
+
+- **The two workflow authoring formats — markdown documents and YAML
+  orchestration programs — are unified into one format**, per
+  `docs/architecture/specs/workflow-format-unification.md`. A workflow is
+  now always a single markdown asset: the standard AKM frontmatter envelope
+  carries the whole orchestration graph (`params`, `steps` with
+  `unit`/`map`/`route`, `inputs`, `output`, `gate`, `defaults`, `budget`),
+  and the body carries each step's instructions under a bare `## <step-id>`
+  heading, joined to the frontmatter by step id. `.yaml`/`.yml` workflow
+  files, the `# Workflow:` / `## Step:` / `Step ID:` markdown headings, and
+  `akm workflow create <name>.yaml` are all gone; `akm workflow create`
+  always writes the one unified template
+  (`src/assets/workflows/workflow-template.md`).
+
+  **Prose is never interpolated.** The YAML program's `${{ … }}` template
+  language, and the markdown format's decorative — and never
+  substituted — `{{ … }}` moustaches, are both removed. Data reaches a
+  dispatched unit as *attached context* instead: the run's params, its
+  item and index for a map unit, and the artifacts its step's new
+  `inputs:` key declares. Instructions refer to that context in plain
+  language ("clone the repository named by the `repo` parameter") rather
+  than splicing a value into the instruction string. Bare reference
+  strings (two roots, `params.<name>` and `steps.<id>.output…`) now appear
+  only in three frontmatter positions: `map.over`, `route.input`, and
+  `inputs:`.
+
+  **Gate rubrics move to the body.** A step's completion criteria are no
+  longer a frontmatter `gate.criteria` list or a `### Completion Criteria`
+  bullet section — they live under a step's `### gate` sub-heading, the
+  format's one reserved marker, as full prose a judge receives byte-exact.
+  Frontmatter `gate:` now carries only optional `max_loops` configuration.
+  Omitted or empty rubric text skips validation; a non-empty rubric requires
+  the frozen `workflow.judgeEngine`, and unavailable or malformed judges reject
+  the gate.
+
+  This is a **pre-1.0 format change**. The ten example workflows under
+  `scripts/akm-eval/example-stash/workflows/` are rewritten to the unified
+  format in this change; existing user-authored workflow assets must be updated
+  manually before execution.
+
+- **akm is described as a knowledge toolkit, not a package manager** (R-048).
+  The npm one-liner, the README lede, and the `concepts.md` opener all led with
+  "a package manager for AI agent capabilities", which misstates the product to
+  its distribution channel and sets package-manager expectations for verbs
+  (`update` / `upgrade` / `sync`) that don't mean what a package manager's do.
+
+- **BREAKING: a command group invoked with no subcommand is now always a usage
+  error, exit 2** (owner ruling 12). The eleven `akm <group>` groups did three
+  different things when invoked bare: `graph`, `config`, `env`, `secret`,
+  `task`, `workflow`, and `proposal` ran an implicit default action and exited
+  0 (bare `akm graph` silently rendered `graph summary`); `registry`, `log`, and
+  `lessons` printed citty's human usage banner to stdout; only `migrate` raised
+  a structured error. All eleven now emit the same
+  `MISSING_REQUIRED_ARGUMENT` envelope on stderr, naming the available
+  subcommands, and exit 2 — matching STABILITY.md's exit-code table (2 =
+  usage) and the exit code already used for unknown commands. Matching exit
+  codes alone was not enough: a script could not parse the failure uniformly
+  while three groups answered on stdout in prose.
+
+  Migration: name the subcommand. `akm graph` → `akm graph summary`,
+  `akm config` → `akm config list`, `akm env` → `akm env list`, `akm secret` →
+  `akm secret list`, `akm task` → `akm task doctor`, `akm workflow` →
+  `akm workflow list --active`, `akm proposal` → `akm proposal list` (which
+  takes the same `--status`/`--queue`/`--ref`/`--type` flags the bare form did).
+
+- **BREAKING: `akm sync` persists `eventType: "sync"`, not the legacy
+  `"save"`.** The event name now matches the command name. Historical
+  `state.db` rows are left as-is — `akm log` and `akm log tail` treat `"save"`
+  and `"sync"` as synonyms on **read**, so `akm log --type save` keeps
+  returning both old and new rows. Only newly written events use `"sync"`.
+
+  Migration: none for `akm log --type save`. A script matching raw event rows
+  by `eventType === "save"` — reading state.db directly, bypassing `akm log` —
+  should also match `"sync"` to see new syncs.
+
+- **BREAKING: dropped the dead `installedKitCount` field from the `add`,
+  `remove`, and `update` JSON envelopes.** It was a raw lockfile-entry count
+  that nothing — internal code or test — ever read.
+
+  Migration: a script parsing `.config.installedKitCount` should stop; the
+  field is gone, not renamed. `config.sourceCount` remains and is unaffected.
+
+- **BREAKING: dropped the dead `graphPath` field from every `akm graph *` JSON
+  envelope** (`summary`, `entities`, `relations`, `export`, `related`, `entity`,
+  `orphans`). It always resolved to the shared state.db path, never a
+  per-graph artifact, and carried nothing `stashPath` did not already provide.
+
+  Migration: a script reading `.graphPath` from any `akm graph` subcommand
+  should stop; `stashPath` remains.
+
+- **BREAKING: `semanticSearchMode` now defaults to `"off"`.** A bare or
+  headless install (`akm init`, `akm setup --yes`, `akm setup --config`) was
+  silently downloading the ~130 MB local embedding model on its first `akm
+  index`, because the fallback used when the key is absent was `"auto"`. The
+  interactive `akm setup` wizard still pre-selects semantic search **on** — a
+  human is present to decide — and now shows the asset/download warning
+  *before* the prompt rather than after, so the pre-checked box is an informed
+  choice. When a remote `embedding.endpoint` is configured, enabling semantic
+  search downloads nothing.
+
+  Migration: existing saved configs are unaffected — the flip only changes the
+  fallback used when the key is absent. To keep semantic search on for a
+  headless or CI install, set `semanticSearchMode: "auto"` explicitly, or point
+  `embedding.endpoint` at a remote embedder.
+
+- **BREAKING: `akm workflow run|brief|report` refuse to run until
+  `experimental.workflowEngine` is set** (0.9.0 decision Q-05). The native
+  workflow executor — including fan-out scheduling and worktree isolation —
+  is experimental, and shipping it enabled by default would have made an
+  unreviewed execution engine reachable from a plain `akm workflow run`. The
+  gated surfaces now exit `78` with a `ConfigError` naming the exact key, and
+  `akm task doctor` reports the gate's state. Authoring and linting the unified
+  markdown format, along with every other `akm workflow` subcommand, remain
+  ungated.
+
+  Migration: `akm config set experimental.workflowEngine true`.
+
+- **BREAKING: the `env:<name>` / `secret:<name>` colon ref spelling is
+  rejected** (0.9.0 decision Q-08). Refs are slash conceptIds only — `env/foo`,
+  `secrets/deploy-key`. The colon form previously resolved as an undocumented
+  alias in some places and fell through as a literal filename in others. It now
+  fails with a usage error naming the slash replacement, rather than silently
+  doing the wrong thing.
+
+  Migration: rewrite `env:<name>` as `env/<name>` and `secret:<name>` as
+  `secrets/<name>`. The error message prints the exact replacement.
+
+- **`akm improve` is review-first by default; autonomy is opt-in** (0.9.0
+  decision D8). The command stays ON — schedules, reflect/distill proposals, and
+  graph extraction are unchanged — but the lanes that mutate assets *without*
+  review now require `akm config set experimental.improveAutonomy true`:
+  memory-inference writes, the memory-cleanup pass, and triage
+  `applyMode: "promote"` (which downgrades to `queue` rather than disabling
+  triage). Consolidation remains review-oriented and is not gated.
+
+  A gated lane is never a silent no-op: it warns on stderr naming the lane and
+  the key, appends an `improve_skipped` event with `reason: "autonomy_gated"`,
+  and is counted in `akm health`'s improve skip-reason summary.
+
+  Migration: set `experimental.improveAutonomy: true` to restore the previous
+  behavior. `sync.push` is **not** affected — it keeps its `true` default and its
+  own `sync.push: false` / `--no-push` controls. Two other direct writes stay
+  ungated by design: `extract`'s additive session indexing and distill's
+  encoding-salience frontmatter stamp. Because the gate is applied before the LLM
+  preflight, a review-first workspace may now need fewer engines configured than
+  before.
+
+  Also: `akm improve` no longer rejects the global `--format`. It emits an
+  envelope through `output()` (always under `--dry-run`, otherwise under
+  `--json-to-stdout`), so `--format` applies to that envelope; progress output
+  stays on stderr. Previously it exited 2 with `INVALID_FLAG_VALUE`, which made
+  it the one command that rejected a valid global flag.
+
+- **`akm health --report` replaces the html-only full report** (D7
+  follow-through). The full health report — per-run rows, trend deltas vs the
+  prior window, and the pending proposal queue — is now a **data** flag, not a
+  side effect of asking for html: `akm health --report --format html` renders
+  the rich report, and the identical dataset comes back under `--format json`
+  (previously that data was reachable only as html). The registered md/html
+  renderers fire on the shape of the result, and `akm health` no longer reads
+  `--format` at all.
+
+  Migration: `akm health --format html` → `akm health --report --format html`
+  (the bare form now renders the plain check generically); the html-only
+  `--compare` flag is removed — use `--window-compare`, which with `--report`
+  defaults to the `--since` window so trend deltas stay like-for-like.
+
+- **Global output flags parse correctly next to positionals.** citty parses
+  each command level against only its own declared args, so a root-declared
+  global flag was unknown at the leaf and its space-separated value fell
+  through as a positional — `akm sync --format json` synced a bundle named
+  "json", and `akm env unset env:x KEY --format json` tried to unset a key
+  named "json". The global output flags (`--format`, `--detail`, `--shape`,
+  `--output`) are now declared on every leaf command so their values are
+  consumed by the parser; the two bespoke argv-inspection workarounds this
+  replaces are deleted. Three more non-exempt commands (`akm health`, `akm
+  index`, `akm lint`) now declare these flags too, purely for `--help`
+  visibility — all three already parsed `--format`/`--detail`/`--shape`/
+  `--output` correctly, since none of them has a positional a stray value
+  could fall into.
+
+- **BREAKING: unknown commands and missing required arguments now exit `2`
+  (usage), not `1`.** citty's own command-dispatch wrapper unconditionally
+  called `process.exit(1)` for any error it raised before a command's own
+  body ever ran — `akm totally-bogus` (unknown command), bare `akm log` /
+  `akm lessons` (a subcommand group invoked with no subcommand), and a
+  command missing a required positional (e.g. bare `akm import`) all exited
+  `1`, contradicting the documented exit-code table (`1` = general error /
+  not found, `2` = usage / bad input). The CLI now drives command dispatch
+  directly instead of going through that wrapper, so it can reclassify this
+  one error family as `2` while leaving `--help`, `--version`, and every
+  other exit code unchanged.
+
+  Migration: a script that treated exit `1` as "something went wrong" for a
+  mistyped command or missing argument should check for `2` instead (or
+  keep treating any non-zero exit as failure, which was already correct).
+
+- **BREAKING: `akm completions --shell <unsupported>` now exits `2` with the
+  standard JSON error envelope, not `1` with a raw stack trace.**
+  `completions` stays format-exempt (its own output is shell-script source,
+  not a result envelope — see STABILITY.md), but its body is now wrapped in
+  the same error-classification path every other command uses.
+
+  Migration: a script parsing this failure should now expect
+  `{"ok":false,"error":"...","code":"INVALID_FLAG_VALUE","hint":...}` on
+  stderr and exit code `2` in place of a stack trace and exit code `1`.
+
+- **BREAKING: `akm index --dry-run` without `--clean` now exits `2` instead
+  of running a real index.** The flag only ever gated the `--clean`
+  stale-entry removal pass — every other phase (walk, LLM enrichment,
+  embeddings, FTS, the adapter-detection config write) ran for real
+  regardless, so `akm index --dry-run` alone silently performed a full index
+  despite its name. The combination is now rejected with the standard usage
+  envelope instead of quietly doing something other than what "dry run"
+  promised.
+
+  Migration: a script or cron invoking bare `akm index --dry-run` was
+  already getting a real index, so nothing there needs to change in effect —
+  but it will now fail loudly instead. Pass `akm index --clean --dry-run` to
+  preview the stale-entry removal pass, or `akm index --clean` to apply it;
+  drop `--dry-run` entirely to keep running a plain real index.
+
+- **BREAKING: a corrupt or unparseable `akm.lock` now makes lockfile WRITES
+  throw, instead of silently destroying every entry.** The previous lenient
+  reader returned `[]` on unparseable JSON; a write path that upserted a
+  single entry onto that `[]` then overwrote the file, permanently deleting
+  every other tracked bundle's lock entry. Install/update/remove write paths
+  now use a strict reader that throws on the same corruption instead of
+  reaching the destructive overwrite.
+
+  Migration: if a write now fails with a lockfile-parse error, `akm.lock` is
+  genuinely corrupt — inspect and repair it by hand, or restore it from a
+  backup (e.g. git history), before retrying the write. Reads elsewhere are
+  unaffected; the lenient read contract is unchanged.
+
+- **BREAKING: `AKM_NPM_REGISTRY` now redirects npm package METADATA lookups,
+  not just the trusted-tarball allowlist.** Previously the override only
+  widened which tarball hosts were trusted for download while metadata
+  queries stayed hardcoded to `registry.npmjs.org`, so a configured private
+  mirror was never actually consulted for package info — the error hint that
+  points users at this variable was false. The override now also replaces
+  the metadata registry base, matching how a private npm registry is meant
+  to work (like npm's own `--registry` flag: wholesale replacement, not a
+  merge with the public registry).
+
+  Migration: an operator who set `AKM_NPM_REGISTRY` expecting only tarball
+  downloads to be redirected, with metadata still served from the public
+  registry, should confirm the mirror actually serves equivalent package
+  metadata — `akm add`/`akm update` for npm-sourced bundles now resolve
+  entirely against the configured mirror when it is set.
+
+- **`akm remember --show-similar` and `akm migrate apply --dry-run` are the
+  documented, canonical spellings** (previously `--showSimilar` /
+  `--dryRun`), matching every other multi-word flag in the CLI. Not a
+  breaking change: citty registers both the camelCase and kebab-case
+  spelling of any declared flag name automatically, so `--showSimilar` /
+  `--dryRun` keep working — they're now explicit, documented aliases instead
+  of an undocumented accident.
+
+- **`--detail` and `--shape` help text is scoped honestly.** The per-command
+  `--detail` description now names `info`, `list`, and `remember` as the
+  commands where it has no effect (verified byte-identical output at every
+  level — `akm show` is not one of these; it has three distinct
+  brief/normal/full payloads). `--shape`'s per-command help now repeats the
+  "`summary` is only valid on `akm show`" caveat the root help already
+  documented.
+
+- **All six `--format` values work on every command** (0.9.0 decision D7).
+  `json|jsonl|yaml|text|md|html` are now universal. Previously there were three
+  inconsistent behaviours: `md` silently emitted the JSON envelope everywhere
+  except `akm health`, `html` was rejected with exit 2 everywhere except
+  `akm health`, and `akm health` reached neither because it intercepted the
+  format itself. Rendering is now registry-driven — a command may register a
+  renderer for a document format, and anything unregistered falls back to a real
+  rendering of its own envelope (headings, tables for arrays of uniform objects,
+  lists otherwise). `akm health` keeps its per-run/window-compare tables and its
+  full HTML report by registering them; the output is unchanged.
+
+  Migration: none required for `json|jsonl|yaml|text`. `--format md` on a
+  non-health command previously returned JSON and now returns Markdown; a script
+  that parsed that JSON should ask for `--format json` explicitly. `--format
+  html` previously exited 2 on non-health commands and now succeeds.
+
+  Also: `akm graph export --format` is **removed** — it declared `--format`
+  locally as well as globally (one token, two parsers). The artifact payload
+  now follows the `--out` extension (`--out g.jsonl` writes JSONL, anything
+  else JSON); the global flag only renders the command's own envelope. A dead
+  local `--format` declaration on `akm history` was removed too (it was never
+  read). Commands
+  whose output is not an envelope (`completions`, `setup`, `env run`,
+  `secret run`, `agent`, `workflow template`, `help migrate`) are declared
+  format-exempt in `src/output/format-exempt.ts` and now warn when given
+  `--format` instead of ignoring it silently. `output.format` in config accepts
+  all six values.
+
+- **Subtree browse is a conceptId prefix, not `<type>:`** (0.9.0 decision D4).
+  `akm search` enumerates on `memories/`, `memories/projecta/`, `bundle//`, and
+  `bundle//skills/`; a trailing `/` is still required. The prefix now matches the
+  **conceptId** rather than the item name, so a ref copied out of search output
+  can be truncated to a prefix and pasted straight back in — previously that
+  round-trip degraded silently into a keyword search. Enumeration no longer
+  validates against the `akm` adapter's placement types, so items from every
+  adapter browse the same way, and `bundle//` lists a whole bundle (the
+  replacement for the removed `akm bundle items`).
+
+  Migration: `akm search "memory:"` → `akm search "memories/"`;
+  `akm search "memory:projectA/"` → `akm search "memories/projectA/"`;
+  `akm search "session:"` → `akm search "sessions/"`. The retired spelling is
+  now an ordinary keyword search; when it returns nothing, the tip names the
+  conceptId spelling that replaces it. `scripts/lint-shipped-assets.ts` no
+  longer exempts the old spelling, so it is an offense in agent-facing assets.
+
+- **`akm task sync [--bundle <bundle>]` reconciles a single bundle.** Sync now
+  attributes each installed scheduler entry to its bundle (parsed from the
+  `--bundle` token; absent ⇒ primary) and reconciles only the entries for the
+  bundle being synced. A plain (primary) sync never installs from, updates, or
+  removes another bundle's entries, and sync never scans all bundles — task
+  activation stays explicit (`add --bundle` or `sync --bundle`), so registering a bundle
+  still never activates code. When the target is the default bundle (or omitted),
+  installed scheduler entries are byte-identical to before, so upgrading shows no
+  spurious drift.
+
+- **The R2 salience ranking boost no longer applies to default `search`/`curate`
+  ranking** (#692). `asset_salience.rank_score` (an encoding + outcome +
+  retrieval projection, recomputed every `improve` run) previously composed
+  into every default search as a bounded multiplicative boost
+  (`salience-ranking`, ×[1.0–1.2]), loaded best-effort from `state.db` on the
+  hot path. On live data it measured as noise (max observed multiplier
+  ×1.071, mean ×1.016): the boost was retrieval-dominated with no source
+  filter — double-counting the same `usage_events` the utility-score
+  contributor already reinforces — warm-started non-zero with no outcome
+  evidence, and had zero pack coverage, so it could only ever favor
+  self-generated personal assets over an equally-relevant pack asset.
+  Removing the default `state.db` load also fixes a confirmed hot-path
+  defect: whenever `state.db` already existed, every default search
+  synchronously waited on the maintenance-activity barrier before ranking
+  could even start — up to a 5-second stall on a blocking wait loop, plus a
+  lock-file create, before the load's own 250ms SQLite `busy_timeout` ever
+  applied. No config gate was added: a key for a term being removed would be
+  dead surface for the upcoming 1.0 contract freeze to carry forever.
+  `rank_score` itself, and everything `improve` computes and does with it
+  internally, are unchanged — only its promotion into user-facing ranking is
+  removed. The contributor stays in the codebase (unwired) for a future
+  gated, outcome-backed experiment.
+
+- **Internal: `asset_salience` / `asset_outcome` state.db access moved behind
+  `src/storage/repositories/{salience,outcome}-repository.ts`** (#672 part 2).
+  Mirrors the existing state.db repository precedents
+  (`proposals-repository.ts`, `improve-runs-repository.ts`,
+  `events-repository.ts`): the raw SQL, row-mapping, and the #644
+  encoding-provenance CASE guards are extracted verbatim, only relocated —
+  `commands/improve/salience.ts` and `outcome-loop.ts` re-export the moved
+  functions, so no importer or test churns. A new `state-table-sql` rule in
+  `scripts/lint-repository-sql.ts` now fails the build if raw
+  `asset_salience`/`asset_outcome` SQL reappears outside the repository
+  directory (or `core/state/migrations.ts`). Not a user-visible behavior
+  change: `rank_score`, `outcome_score`, and everything `improve`/`health`
+  compute from them are identical.
+
+### Fixed
+
+- **The compiled standalone binary can run `akm migrate`.** Release binaries
+  compiled only `src/cli.ts`, and the migrator was resolved as a sibling file
+  and spawned — neither candidate exists inside a compiled executable, so the
+  documented `./akm-0.9 migrate status/apply` upgrade path always failed with
+  `FILE_NOT_FOUND`. Standalone builds now compile `scripts/akm-standalone.ts`,
+  a wrapper that embeds both the CLI and the migrator (src never imports
+  scripts/ — the dist build's tsc forbids it); `akm migrate` re-execs the
+  binary with an `AKM_MIGRATE_ENTRY` marker the wrapper dispatches on. The
+  repo and npm layouts keep the subprocess path.
+
+- **Quarantined migration rows are retained in full, not reduced to a count.**
+  When the 0.8→0.9 cutover met a durable ref it could not map, it recorded
+  surface/ref/count in `legacy_state` and then deleted the rows — destroying
+  proposal payloads, event and task history, fingerprints, and canary anchors,
+  contrary to the migration guide's "quarantined, not dropped". Complete rows
+  are now preserved as JSON in `legacy_state_rows` before leaving the live
+  tables.
+
+- **A failed content migration fails the apply instead of reporting success.**
+  Root discovery, sidecar folding, or the legacy-proposal import throwing was
+  swallowed and logged; the apply then advanced and cleared its journal, and —
+  because 0.9 removed the live `.stash.json` and filesystem-proposal readers —
+  the affected metadata and pending proposals became permanently inaccessible
+  behind an apparently successful upgrade. The step now fails the apply with
+  the journal intact; the committed cutover is untouched and the next apply
+  retries.
+
+- **Sidecar provenance survives the fold.** Folding a `.stash.json` into
+  frontmatter dropped `xrefs` and `sources` entirely and mapped legacy
+  `sourceRefs` to a `source_refs` key that could never fire (the validator
+  stopped copying the field) and that 0.9 never reads — then deleted the only
+  copy. `xrefs`/`sources` now fold through, and legacy `sourceRefs` merge into
+  `xrefs`.
+
+- **A reserved-filename rename re-keys durable state.** The D-R6 rename of a
+  mis-named `index.md`/`log.md` concept ran after the cutover had keyed usage,
+  salience, and proposal rows to the old conceptId, stranding that learned
+  state. The rename now feeds the same re-key engine the cutover uses, with
+  the pairs persisted before re-keying so a crash between the two stays
+  retryable.
+
+- **v1 tasks in a read-only bundle are surfaced with a remedy instead of being
+  silently skipped.** The 0.9 runtime removed the v1 task parser, so silently
+  skipping a `writable: false` bundle left tasks that would start failing after
+  an upgrade that reported current. The preflight now warns per bundle and
+  lists the stranded files in the plan (`readOnlyLegacyTasks`). It does not
+  block the apply: the migration deliberately never rewrites a read-only
+  bundle, and the fix for a lock-materialized git/npm bundle belongs upstream.
+
+- **Lock resolution metadata survives migration.** Merging the migrator's
+  sparse lock entries replaced whole rows by id, discarding
+  `resolvedVersion`/`resolvedRevision`/`integrity`/`installedAt` recorded by a
+  real install. Merge now preserves existing fields the incoming entry does
+  not define.
+
+- **Migrating a pre-0.9 config no longer silently changes source policy.**
+  Three settings were dropped by the config-shape migration: an explicit
+  `writable: false` (an omitted filesystem `writable` reads as `true` in the
+  new shape, so a source the user deliberately protected became writable), an
+  explicit `enabled: false` (resuming refreshes and indexing for content the
+  operator had turned off), and a website source's `maxDepth` (silently
+  resetting crawl depth). All three now round-trip to the runtime source entry;
+  `bundles.<id>.enabled` is a supported key.
+
+- **`akm mv` refuses a bundle marked `writable: false`.** It renamed the file
+  and rewrote citers anyway, because its preflight checked adapter
+  compatibility rather than writability — every other write command already
+  refused.
+
+- **Memory belief edges written by `--supersedes` are no longer ignored.**
+  `writeSupersededEdge` persists a fully-qualified conceptId, but the belief
+  analyzer accepted only the internal `memory:<name>` spelling, so every edge
+  from `akm remember --supersedes` / `akm import --supersedes` was dropped and
+  a superseded memory read back as active.
+
+- **`akm env run <ref> -- <cmd> --help` runs the command.** The builtin
+  help-flag scan read the child tail after `--` and printed akm's own usage
+  instead.
+
+- **`akm mv` works under an `AKM_STASH_DIR` override again.** A valid override
+  not owned by a configured bundle failed with `No configured bundle owns move
+  source`.
+
+- **An unexpected internal error exits 70 with the JSON failure envelope.** The
+  residual dispatch boundary exited 1 with an unstructured message, so
+  automation could not tell an internal defect from an ordinary failure.
+
+- **Concurrent `akm config set` processes no longer give up prematurely.** The
+  contended-lock wait budget was 500ms total, so several concurrent writers on
+  a loaded machine could exhaust it and fail with "Timed out waiting for config
+  lock" against a healthy but busy lock. Abandoned locks are still reclaimed by
+  the stale probe, which this budget does not gate.
+
+- **Config keys named in indexer output and comments now exist.** Four sites
+  pointed at a top-level `llm.*` namespace that the config schema has no such
+  key for — including the user-facing "Increase llm.timeoutMs" warning on an
+  exceeded enrichment budget. The enrichment budget lives at
+  `index.enrichment.timeoutMs` (or `index.defaults.timeoutMs`). Indexing
+  concurrency is auto-derived (2 remote / 1 local) and currently has no config
+  override on that path: `engines.<name>.concurrency` is a valid schema field
+  but the engine resolver does not forward it (documented in
+  `docs/architecture/internals/indexing.md`).
+
+- **The bundle-identity-drift warning stops naming a command that doesn't
+  exist.** It told users to "rekey it atomically via the bundle-rename
+  command"; 0.9.0 ships no such command. It now gives the two remedies that
+  work: restore the previous bundle id in `config.json`, or keep the new id and
+  `akm index --full` to re-mint, accepting the loss of learned state keyed to
+  the old id.
+
+- **The scaffolded `organization.md` convention no longer contradicts `akm
+  mv`.** It told authoring agents "there is no command that preserves an
+  asset's identity or learned state" across a rename and showed a raw `mv`.
+  `akm mv` does exactly that — it rewrites inbound refs and re-keys the index
+  row, usage history, and state.db salience/outcome rows. The convention now
+  points at it, flagged Experimental.
+
+- **`setup.taskSchedules` is no longer documented.** The key was removed from
+  the schema in 0.9.0 (nothing ever read or wrote it), but
+  `docs/reference/configuration.md` still described its two sub-keys.
+
+- **A freshly scaffolded stash passes its own `akm lint`.** All 12 shipped
+  `facts/conventions/**` convention templates carry frontmatter but none
+  carried an `updated` field, so the first `akm lint` after `akm init` flagged
+  12 `missing-updated` issues on files the user never wrote. The templates now
+  ship the field, and a regression test lints a freshly scaffolded stash and
+  requires nothing flagged.
+
+- **`akm show akm//meta` is the documented spelling for the primary stash.**
+  `docs/reference/cli.md` and `docs/guides/concepts.md` showed
+  `akm show local//meta`, which errors with `ASSET_NOT_FOUND` — `local//` is no
+  longer a scoping prefix, so it reads as a bundle named `local`.
+
+- **`akm sync` emits `shape: "sync"`.** The envelope kept the `"save"` shape
+  from the command's pre-rename name even after the persisted `eventType` was
+  renamed. Unlike the event log, the shape is per-invocation and never
+  persisted, so it needs no read-side synonym.
+
+- **`akm add <pkg> --provider npm` adds an npm source instead of a broken
+  filesystem bundle.** `--provider` was only read inside the remote-URL branch,
+  so any non-URL target fell through to the filesystem path with the flag
+  ignored, producing a bundle pointed at `<cwd>/<pkg>`. A URL target with
+  `--provider npm` is now rejected at add time rather than storing the URL as a
+  package spec and failing much later at first sync.
+
+- **`akm add --provider` no longer prints `Installed undefined`.** Two
+  incompatible result shapes reached one text formatter; each is now rendered
+  honestly, including whether a follow-up `akm update` or `akm index` is needed.
+
+- **`akm update --all` accounts for every configured source.** It previously
+  considered only registry-managed installs and reported `nothing to update`
+  for a stash full of plain sources — nothing was updated because nothing was
+  looked at. Plain git and npm sources are now synced (npm is promoted to a
+  lock-backed install on first sync) and website/filesystem sources are
+  reported through a new `skipped` field with the reason. A successful update of
+  a plain source no longer renders as `nothing to update` either.
+
+- **`akm search` with no query browses**, as `--help` has always documented,
+  instead of exiting 2.
+
+- **`akm curate --type <t>` curates within the type instead of bypassing
+  curation.** The filter skipped ranking, intent nudges, the score floor, and
+  family collapse entirely — and could return a hit of the *wrong* type while
+  dropping a higher-scoring correct one.
+
+- **`akm curate` respects `--limit` for registry hits**, which were capped at a
+  hard-coded 2 regardless.
+
+- **`akm search --no-project-context` works.** citty strips a leading `--no-`
+  before consulting declared args, so a flag *declared* as `no-project-context`
+  could never be set — the ranking boost was identical with and without it. The
+  flag users type is unchanged.
+
+- **`akm env run`, `akm secret run`, `akm migrate`, `akm agent`, `akm proposal new`,
+  `akm task run`, and `akm improve` no longer skip cleanup on exit.** They
+  called `process.exit()` directly — in two cases even on success — bypassing
+  teardown of spawned subprocesses. Exit codes, including forwarded non-zero
+  child codes, are unchanged.
+
+- **The `blocked` semantic-search warning names the cause.** It emitted one
+  fixed string for every failure and discarded the status ledger's reason, so
+  "no embedding provider configured" and "the configured endpoint is failing"
+  read identically.
+
+- **Shell completion for `--source` no longer suggests `stash|registry|both`
+  on commands where that enum doesn't apply.** `--source` means a closed
+  `stash|registry|both` enum on `akm search`/`akm curate`, but a free-form
+  stash name/path on every `akm graph` subcommand and a free-form URL/ref/
+  path on `akm remember`. The generated completion script keyed its value
+  list by flag name only, so the search/curate enum leaked onto `akm graph
+  --source <TAB>` and `akm remember --source <TAB>`. Value completion is now
+  scoped per command path; commands without a fixed value set get no
+  suggestion instead of the wrong one.
+
+- **`akm setup --config <file>` / `--from <file>` no longer silently drops
+  six valid config keys** (`index`, `search`, `feedback`,
+  `archiveRetentionDays`, `workflow`, `experimental`). The allowlist was a
+  hand-copied set that had drifted out of sync with the config schema; a
+  user handing setup a config containing any of these keys got a different,
+  silently truncated config written back, with only a warning and exit `0`.
+  The allowlist is now derived from the schema's own key list so it cannot
+  drift again. Keys that remain genuinely retired (`profiles`, `llm`,
+  `agent`, `features`, `stashes`, `bindings`, `writable`) still warn-and-drop
+  as before.
+
+  Note: a config that previously relied on one of these six keys being
+  ignored (because the drop was silent) will now have it applied — re-check
+  `--config`/`--from` inputs if you were unknowingly depending on that gap.
+
+- **`akm index` no longer persists adapter auto-detection to `config.json`
+  with zero disclosure.** Detecting and writing a bundle component's adapter
+  (`bundles.<id>.components.<component>.adapter`) previously happened
+  silently on every index run. It is now reported in the result envelope as
+  an additive `configUpdated.detectedAdapters` map and on stderr, and only
+  when a write actually happened.
+
+- **`akm add owner/repo` now resolves as GitHub shorthand instead of failing
+  with "Local path not found".** Any ref containing a `/` was treated as an
+  explicit local path, so the local-ref resolver threw before the
+  GitHub-shorthand fallback ever ran, making the advertised `owner/repo` form
+  unreachable. A bare two-segment `owner/repo` (or `owner/repo#ref`) now
+  falls through to the registry resolver when no such directory exists on
+  disk; `./`, `../`, absolute, and three-or-more-segment paths still resolve
+  as explicit local paths exactly as before.
+
+- **Internal output-shape command keys renamed `events-list`/`events-tail` →
+  `log-list`/`log-tail`**, matching the `akm log` command they back (the
+  command group used to be `akm events`, removed in 0.9.0). Internal-only:
+  the shape name is a registry lookup key that never reaches the wire (no
+  output field, no schema change), so this is not a user-visible behavior
+  change and carries no `schemaVersion` bump. The documented `[events-tail]`
+  stderr trailer text is deliberately left as-is pending a separate ruling.
+
+### Removed
+
+- **BREAKING: `akm upgrade --skip-checksum` is removed.** STABILITY.md has
+  always said checksum verification is not optional and that the recovery hatch
+  is an environment variable — but the flag shipped anyway, tab-completable,
+  while the documented variable existed nowhere in the source. The code now
+  matches the spec: set `AKM_UPGRADE_SKIP_CHECKSUM=1` if you must bypass a
+  genuinely broken `checksums.txt`. It is deliberately undiscoverable.
+
+- **BREAKING: `akm config enable|disable` is removed.** It was a hard-coded
+  toggle for one target, the skills.sh registry, and the bare `akm enable` /
+  `akm disable` aliases were already removed in 0.9.0. Use
+  `akm registry add|remove`.
+
+- **BREAKING: `akm mv` is removed.** No alias, no stub — `akm mv …` fails with
+  the standard unknown-command error. It claimed to preserve identity across a
+  rename, but its inbound-ref rewrite matched bare conceptIds rather than the
+  anchored `bundle//conceptId` prose form, so it could rewrite ordinary prose
+  while leaving real refs dangling. Renames are delete + create per
+  `STABILITY.md`: move the file, `akm index`, `akm lint`. The one capability
+  nothing else covered — carrying an asset's earned signal across the rename —
+  moves to `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` (maintainer
+  tooling, `--dry-run` supported, idempotent), which re-keys the index
+  `entries` row in place plus the `asset_salience` / `asset_outcome` /
+  `usage_events` rows. The `mv` event type and output shape are gone; the
+  script emits a `rekey` event instead. A leftover `kind:"mv"` transaction
+  journal from an rc build is now swept by the recovery scanner rather than
+  failing it — an unregistered journal kind no longer bricks index refresh or
+  proposal accept/reject.
+
+- **The CHURN alert class is removed from the collapse detector.** Its input was
+  a hard-coded `0` from the 0.9.0 confidence-gate deletion onward, so the alert
+  could never fire. The other three alert classes are unaffected. The
+  `improve_cycle_metrics.accepted_actions` column stays and is written as `0`
+  because deployed 0.8 `state.db` files already contain it.
+
+- **`IndexResponse.graphQuality` is removed** from the `akm index` envelope — it
+  was declared but never assigned in any code path, so it was always absent.
+
+- **`akm secret path` and `akm secret remove` are removed.** The two resolved a
+  secret ref through *different* stash-selection logic — `path` through the
+  read-side, all-sources resolver and `remove` through the write-target
+  resolver — so for a ref present in more than one stash they could name
+  different files: you could inspect one secret and delete another. Rather than
+  reconcile the resolvers, both subcommands are gone; `akm secret` now exposes
+  only `list`, `run`, and `set`. Both spellings exit 2 with `Unknown command`.
+
+  Migration: a ref's file lives at `<stash>/secrets/<name>` (run `akm sources
+  list` for stash roots) — locate or delete it directly, or use `akm secret run
+  <ref> <VAR> -- <command>` to consume the value without it touching disk. `akm
+  env path` and `akm env remove` are unaffected.
+
+- Removed the dead `"backup"` output-shape registration left over from the
+  removed `akm backup` command (superseded by `akm-migrate backup`). Already
+  unreachable; no user-visible effect.
+
+- **`akm task list`, `akm task show`, and `akm task remove` are removed** as
+  redundant with the generic asset commands. List and inspect tasks with `akm
+  search` / `akm show <bundle//tasks/id>` (both already cross-bundle); to remove a
+  scheduled task, delete its file in the owning bundle and run `akm task sync`
+  (sync uninstalls the orphaned scheduler entry). Run `akm task doctor` for
+  scheduler diagnostics — bare `akm task` is a usage error, see the canonical
+  bare-group change above.
+
+- **The `akm show <ref> toc|section|lines|frontmatter|full` view-mode grammar is
+  removed** (0.9.0 decision D2). `#fragment` is now the only section selector,
+  and a positional after the ref is a usage error that names it. Migration:
+
+  | Old | New |
+  | --- | --- |
+  | `akm show knowledge/guide section "Auth"` | `akm show knowledge/guide#auth` |
+  | `akm show knowledge/guide full` | `akm show knowledge/guide` |
+  | `akm show knowledge/guide toc` | `akm show knowledge/guide#<unmatched>` — the error lists the available fragment slugs |
+  | `akm show knowledge/guide lines 10 30` | no replacement — every response carries `path`, so slice the file yourself |
+  | `akm show knowledge/guide frontmatter` | no replacement — if a raw-YAML projection proves necessary it returns as a `--shape` value |
+
+  The undocumented `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
+  flags the grammar injected into argv are gone with it.
+
 ## [0.9.0-rc.1] - 2026-06-30
 
 ### Fixed
@@ -1948,7 +2967,7 @@ behind an interactive prompt (or `-y` / `--yes` in non-interactive use).
 
 ### Changed
 
-- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Management** — `akm` stands for Agent Knowledge Management going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
+- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Manager** — `akm` stands for Agent Knowledge Manager going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
 
 - **Config layer rewrite** — single-source-of-truth Zod schema in
   `src/core/config-schema.ts` replaces the per-field parse switch AND
@@ -2136,7 +3155,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 
 ### Migration
 
-- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and the [archived pre-1.0 plan](docs/archive/pre-1.0-migration.md) for the historical per-surface delta from any 0.6.x baseline.
+- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and the [archived pre-1.0 plan](https://github.com/itlackey/akm/blob/be3a6a632b0cbe7a63ce71b7d093d8ac266e857c/docs/archive/pre-1.0-migration.md) for the historical per-surface delta from any 0.6.x baseline.
 
 ## [0.6.0] - 2026-04-23