akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/CHANGELOG.md

@@ -4,12 +4,721 @@ 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.1-beta.1] - 2026-08-13
+
+### Breaking changes & migration
+
+The 0.9.x series carries breaking changes as it works toward the 0.10.x
+stabilization line. Every item here is detailed further down; this section is
+what an upgrader reads first.
+
+- **A data directory akm cannot READ is now an error, not an empty result.**
+  Commands that previously returned `hits: []` / `entryCount: 0` / "nothing
+  eligible" at exit 0 for an index, lockfile or database they lacked permission
+  on now raise `DATA_DIR_UNREADABLE` (exit 78) naming the path, errno, mode,
+  owner and running uid. *Affected:* anyone whose data dir is partly unreadable
+  — most often a `$XDG_DATA_HOME` shared across uids. *Remedy:* fix the
+  ownership or mode the error names, or point `AKM_DATA_DIR` somewhere this
+  user owns. The old behaviour was a false success, so a script that treated
+  exit 0 as "no results" was already being lied to.
+
+- **Lockfile writes refuse to run against an unreadable `akm.lock`.**
+  `akm bundle add` / `remove` / `update` now fail closed instead of reading the
+  lock as empty and writing the single incoming entry over the whole record.
+  *Remedy:* as above. This one prevented real data loss — see Fixed.
+
+- **`akm workflow run` exits 1 when a run ends `blocked`.** Previously 0.
+  *Affected:* CI steps and scheduled wrappers that branched only on `failed`.
+  *Remedy:* treat nonzero as "not verified"; resume with
+  `akm workflow resume <id>`.
+
+- **`akm index --clean` no longer deletes entries whose file it cannot read.**
+  It keeps and names them. *Affected:* anyone relying on `--clean` to prune
+  aggressively; it is now conservative where it cannot see.
+
+- **Workflow documents are bounds-checked at authoring time.** `engine:` name
+  grammar, `retry.max` 0–100, `gate.max_loops` 1–100, `map.concurrency` and
+  `engines.<name>.concurrency` 1–64, and any `timeout:` ≤ 2 147 483 647 ms are
+  now enforced by the parser. *Affected:* documents that parsed at 0.9.0 but
+  could never actually run — the frozen-plan decoder already refused them.
+  *Remedy:* edit the offending field; the error is now line-anchored.
+
+- **`akm health` no longer emits `secret-file-perms`, and no longer exits 4 for
+  it.** The check is gone. *Affected:* anything parsing health output for that
+  check name.
+
+- **Command-target task logs are now redacted.** Output that previously
+  persisted verbatim may now contain `[REDACTED]`. *Affected:* anything
+  grepping task logs for values that are now recognised as secrets.
+
+- **Leftover `isolation: worktree` trees are garbage-collected after 7 days.**
+  *Remedy:* copy anything you want to keep out of a retained worktree within a
+  week.
+
+### Added
+
+- **`exec` workflow units — run a shell command as a workflow step.** A step
+  whose `unit:` block declares `exec:` runs a command directly instead of
+  dispatching to an LLM or an agent, so deterministic work (test suites,
+  builds, lint, scripts) no longer costs a model dispatch, its latency, its
+  tokens, or its nondeterminism.
+
+  ```yaml
+  - id: test
+    unit:
+      exec:
+        command: ["bun", "run", "test:unit"]
+        pass_env: [CARGO_HOME]   # optional: widen the default env allowlist
+      timeout: "10m"
+      retry: { max: 1, on: [timeout] }
+  ```
+
+  - **`command:` is an argv array; there is no shell-string spelling.** The
+    child is spawned directly, so `;`, `|`, `&&`, `$(…)` and `*` inside an
+    argument are inert literal bytes — the quoting/injection class is
+    structurally absent, not defended against. Write `["bash", "-lc", "…"]`
+    when a pipeline is genuinely wanted, and own that choice in the diff.
+  - **An exec unit names no engine.** It rejects `engine`/`model`/`llm`, spends
+    no tokens, and a workflow made only of exec steps runs on an install with
+    no engine configured at all.
+  - **Everything else about a unit still applies:** `timeout`, `retry`,
+    `on_error`, `output`, `env`, `isolation: worktree`, `map` fan-out and its
+    concurrency limits, the unit journal, budget accounting, and replay/reuse
+    (a completed exec unit is never re-run on resume).
+  - **Output rule:** stdout is the promoted artifact with trailing newlines
+    stripped (like shell `$(…)`); with an `output:` schema on the unit, stdout
+    must be exactly one JSON value, strictly parsed and validated. stderr is a
+    diagnostic channel only. A schema miss is *not* re-prompted — a fixed argv
+    cannot answer feedback, but re-running it could deploy twice.
+  - **Exit codes:** non-zero → `non_zero_exit`, wall-clock expiry → `timeout`,
+    cancellation → `aborted`, failure to start → `spawn_failed`. Those are
+    pre-existing `retry.on` reasons. With the default `on_error: fail`, a
+    non-zero exit fails the step and the run, which is what makes a `test` step
+    a gate.
+  - **A partial capture is never promoted as the artifact.** Exiting 0 does not
+    prove stdout was read to the end: a pipe can error, and a background
+    descendant holding the stdout handle open after the command leader exits
+    keeps the pipe alive past the drain deadline. Both leave a *prefix* of the
+    real output, so the unit fails — with its own reason,
+    `exec_capture_incomplete`, which is deliberately **not** a `retry.on` value.
+    The command already ran; re-dispatching identical argv to fix a capture
+    problem would run its side effects a second time.
+  - **Everything the command can spend is bounded — without inventing failures.**
+    Alongside the wall-clock timeout, akm bounds the memory it spends on the
+    command's behalf and the environment it can hand the command. Both bounds are
+    built so that they only ever *explain* a failure that was going to happen
+    anyway; neither fails a run that would otherwise have succeeded.
+
+    **Retained output: 8 MiB per stream, drain-and-discard.** akm keeps at most
+    8 MiB of stdout and 8 MiB of stderr. Past the cap it keeps *reading* the pipe
+    and throws the extra bytes away, so the child never blocks on backpressure:
+    the command runs to completion and its real exit code decides the unit. A
+    verbose-but-passing test suite is not failed over its log volume. What
+    overflow costs is completeness of the artifact, and that is never hidden —
+    a step with **no** `output:` schema succeeds and its artifact is the retained
+    head with a `__akm_exec_output_truncated__` block appended (naming bytes
+    written vs bytes retained), so truncated data can never be mistaken for
+    complete data by `steps.<id>.output`, a gate judge, or a human. A step **with**
+    an `output:` schema still fails `exec_output_limit`: stdout must parse as
+    exactly one JSON value, a truncated prefix cannot, and promoting it would
+    corrupt every downstream reference to the typed artifact.
+
+    **Context environment: this platform's ceiling, not the smallest one.** The
+    engine-authored `AKM_*` context is capped at **96 KiB per variable / 128 KiB
+    total** on Linux, macOS and BSD, and at **32 767 bytes per variable / 64 000
+    bytes total** on Windows. The numbers cite their sources: Linux's
+    `MAX_ARG_STRLEN` (`32 * PAGE_SIZE` = 131 072 bytes per `argv`/`environ`
+    string), macOS's 256 KiB `ARG_MAX` over argv + environ combined, and Win32
+    `SetEnvironmentVariable`'s 32 767-character per-variable limit. Crossing the
+    bound fails `exec_context_too_large` *before* the spawn, with an error naming
+    the variable, its size, this platform's limit and where that limit comes from
+    — replacing a bare `E2BIG` from the spawn syscall that named neither the
+    variable nor the data behind it. Converting that inevitable failure into an
+    actionable one is the check's *only* job, so it uses the ceiling of the
+    platform the run is on: previously it applied Windows' limit everywhere and
+    refused spawns Linux and macOS would have accepted. Workflows that must also
+    run on Windows should stay under the smaller bound — that is documented
+    guidance now, not something a Linux host enforces.
+
+    `exec_output_limit` and `exec_context_too_large` keep their meanings and
+    their place outside the `retry.on` vocabulary, alongside `exec_cwd_escape`:
+    each is deterministic, so re-dispatching could only spend the budget again.
+    `PROGRAM_RETRY_REASONS` is unchanged.
+  - **A failing command's stderr survives to a durable surface.** The unit
+    journal now keeps each failed unit's redacted diagnostic (clipped to 2000
+    characters), and the step summary carries the first failure's. For an exec
+    unit that is the difference between `akm workflow status --units` saying
+    `non_zero_exit` and it saying *why* — a command that explains itself only on
+    stderr with empty stdout previously left no diagnostic anywhere durable.
+    This is an output surface only: the unit input hash is computed from
+    plan-frozen inputs, so no completed unit re-dispatches because of it.
+  - **The child's environment is an ALLOWLIST, not an inheritance.** The
+    command starts from an empty environment and receives `PATH`, `HOME`, the
+    identity/locale/temp/terminal variables, the Windows process-creation
+    essentials (`SystemRoot`, `SystemDrive`, `WINDIR`, `COMSPEC`, `PATHEXT`)
+    and the Windows home/config roots, plus `AKM_EVENT_SOURCE` — then the
+    unit's `env:` bindings, then the `AKM_*` context. `exec.pass_env: [NAME…]`
+    adds a few more names (for a per-machine toolchain variable like
+    `CARGO_HOME`, which a committed `env:` asset cannot express);
+    `exec.inherit_env: true` opts all the way back into akm's whole
+    environment. Both keys live inside `exec:` because the unit-level `env:`
+    key already means "env asset binding refs", and both are dispatch-
+    significant, so both are in the input hash.
+
+    This is not a claim to stop a determined attacker — a command that runs at
+    all can read the same credentials off disk. It bounds **accidental**
+    exposure (the invoking shell or CI job routinely exports tokens for
+    unrelated services), makes the environment surface **explicit and
+    reviewable**, and **matches the convention akm already applies** to
+    agent-harness children (`profile.envPassthrough`), which now share one
+    mechanism with exec units instead of two.
+  - **Security:** commands run inside the existing workflow trust model.
+    Secrets come from `env:` bindings by NAME — the frozen plan and the replay
+    hash carry only ref names, and resolved values are scrubbed from stdout,
+    stderr, and failure diagnostics by the same redaction contract every other
+    dispatch uses, before anything is journaled. `cwd:` is relative and
+    `..`-free, re-checked against the resolved base (symlinks included) before
+    spawning.
+  - **Cancellation is real:** the child is spawned in its own process group and
+    gets a SIGTERM→SIGKILL ladder on timeout or abort, so `--timeout` / Ctrl-C
+    stop a running command without orphaning its children.
+  - **No replay churn:** the exec spec was added to the unit input-hash preimage
+    as a key present only on exec units, so `hashVersion` stays 4 and every
+    previously-frozen llm/agent/sdk unit hashes byte-identically — runs already
+    in flight neither re-dispatch nor diverge. The env-scope keys are inside
+    that same spec and are frozen only in their non-default form (`inherit_env`
+    only when `true`, `pass_env` only when non-empty), so an exec unit that says
+    nothing about its environment hashes byte-identically too.
+
+  See [Workflow Schema: Exec (shell) units](docs/reference/workflow-schema.md#exec-shell-units)
+  and the worked example in
+  [Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#deterministic-steps-run-a-command-gate-on-it).
+
+### Changed
+
+- **`akm workflow run` now exits non-zero when the run ends `blocked`.** A
+  verification judge that throws, cannot be resolved, or returns a malformed
+  verdict stops the run `blocked` — unverified, and resumable with `akm
+  workflow resume <id>`. That previously exited 0, so a CI step or scheduled
+  wrapper read an unverified run as a passing one. It now exits 1, matching
+  `failed` and gate rejections, and matching how the scheduled-task path
+  already reported it.
+
+- **Workflow dispatch bounds are enforced at authoring time, not only by the
+  frozen-plan decoder.** `engine:` names must match the decoder's own grammar
+  (lowercase dash-separated letters/digits, starting with a letter, ≤63
+  chars); `retry.max` is 0–100; `gate.max_loops` is 1–100; `map.concurrency`
+  and `engines.<name>.concurrency` are 1–64; any `timeout:` must resolve to at
+  most 2 147 483 647 ms (~24.8 days, `setTimeout`'s 32-bit ceiling). Every one
+  of these was already refused by the frozen-plan decoder, so such a document
+  could never actually run — but it *parsed*, so `akm lint`, `akm workflow
+  show` and `akm workflow create` all reported it clean and the failure arrived
+  at `workflow run` as an unlocated "Invalid frozen workflow plan". The error is
+  now line-anchored at parse time. Nothing changes for a document already
+  inside the bounds.
+
+- **`akm lint` gained an advisory channel.** The result envelope carries
+  `warnings: LintIssue[]` alongside `fixed`/`flagged`, `summary` gains a
+  `warnings` count, and text output prints a `warnings` section. Advisories
+  never route into `flagged`, so `--fail-on-flagged` cannot fail a run over
+  one. Workflow compile advisories (`workflow-warning`) are surfaced for the
+  first time — a step with no `output:` schema, a `params.<name>` reference to
+  an undeclared param, a `gate.max_loops` above 1 on an `exec` step — so a
+  bundle that linted clean at 0.9.0 may now report warnings without becoming a
+  failure. Findings that know a location carry `line` in `--format json` and
+  render as `file:line` in text. A new `lint-failed` code reports a file the
+  sweep reached but could not finish.
+
+- **Leftover `isolation: worktree` trees are now garbage-collected.** A run
+  that crashed, or one whose worktree was retained after a dirty unit, used to
+  leave its tree under the worktrees root forever. akm now opportunistically
+  removes such trees once they are 7 days old, confined to the worktrees root,
+  symlinks skipped, containment re-checked. A worktree still in use is never
+  collected: every live tree carries a liveness marker (pid, host, resolved
+  path) in git's administrative directory for it, and the sweep skips a
+  candidate whose holder is still running here.
+
+- **The workflow JSON Schema subset now enforces `allOf`/`anyOf`/`oneOf`/`not`.**
+  A step `output:` or `params:` schema may use the combinators, and the runtime
+  now evaluates them. Previously it ignored them: a schema using one was
+  accepted and simply constrained less than it appeared to. Evaluation stays
+  bounded — nesting is capped at 64 levels and one validation at 100 000 checks,
+  and exhausting either is reported as an error rather than a truncated pass.
+
+  **This one reaches runs already in flight.** The combinators live in the
+  frozen plan, which the decoder still accepts unchanged, so a run frozen before
+  the upgrade is resumed against the *new* evaluation: an artifact that passed
+  when the combinators were ignored can fail validation now. There is no
+  `irVersion` bump to gate it, because the plan bytes did not change — only what
+  they mean. Runs whose schemas use no combinators are unaffected, as is every
+  step already completed.
+
+  `pattern` is **not** part of the subset. It is a recognized-but-unsupported
+  keyword like `format` or `const`: using one is a loud, line-anchored authoring
+  error naming the keyword, so no schema silently fails to constrain what it
+  looks like it constrains. Enforcing it would mean screening every author
+  regex for catastrophic backtracking before the match — and any such screen
+  also refuses regexes authors legitimately write (the usual hand-rolled email
+  pattern among them), which is authoring friction with no workflow asking for
+  it. Where a string's shape matters, `enum` lists the allowed values,
+  `minLength`/`maxLength` bound the size, and a step's `### gate` rubric can
+  check a shape and explain a mismatch. The `format` hint now points at `enum`
+  rather than at `pattern`.
+
+  **Existing workflows that use one of these keywords must be edited before
+  they load again.** They previously parsed — the keyword was silently
+  non-constraining — so a workflow carrying `format: date-time` or `pattern:`
+  ran fine and now fails to parse for every caller: `workflow run`, `workflow
+  show`, `workflow create`, and `akm lint`. The quietest surface is `akm index`,
+  which skips an asset it cannot parse with a scan warning, so the workflow
+  simply stops appearing in the stash index. A run already frozen from such an
+  asset still resumes — the frozen-plan decoder does not re-screen keywords —
+  so resuming works while re-creating the same workflow errors until it is
+  edited.
+
+- **A document-level `defaults.llm` is now rejected at freeze when any step
+  resolves onto an agent engine**, naming the step and the engine. The guard
+  existed before but was unreachable: overrides were computed only for `llm`
+  engines, so `defaults.llm` on a document with an agent step was silently
+  DROPPED for that step — the run proceeded with the author's sampling settings
+  quietly discarded. Failing loudly is the point, but it means a document that
+  mixes `defaults.llm` with any agent-engine step no longer freezes.
+
+  There is no per-step opt-out: `llm: {}` is a no-op, `llm: null` is a parse
+  error, and the layer merge is additive. Move the `llm:` block from
+  `defaults:` onto the `unit:` of each LLM step that wants it.
+
+- **A scheduled workflow task now gets a 6-hour whole-run timeout by default.**
+  This applies to task files that declare no `timeoutMs:` — which is every task
+  file written before this release, since the key was previously rejected on
+  workflow targets. An unattended run that legitimately takes longer will be
+  aborted and the attempt reported failed on every firing until the task is
+  edited. `timeoutMs: null` opts out entirely, and any number overrides the
+  default. The abort itself is graceful: it lands at a step boundary, the
+  journal and lease are kept, and the run stays resumable with
+  `akm workflow resume <id>` — which the failure message names.
+
+- **Workflow `map` steps now fan out in parallel by default.** A `map` step
+  that declares no `concurrency:` freezes a width of **4** instead of 1, and an
+  LLM engine that declares no `engines.<name>.concurrency` freezes **4** for a
+  remote endpoint (loopback endpoints stay at **1** — a local model server holds
+  one loaded model and returns HTTP 500 under concurrent inference). Both
+  defaults previously froze 1, which made every fan-out serial unless the author
+  opted in at two independent layers, and left `workflow.maxConcurrency` and the
+  host CPU cap binding on nothing.
+
+  This is a behavior change on a patch release, so every escape hatch is
+  explicit:
+  - `map.concurrency: 1` on a step is honored exactly as before — an authored
+    `1` is kept distinct from an unset field and always wins.
+  - New config key **`workflow.defaultMapConcurrency`** sets the default for
+    every workflow on the machine. `akm config set workflow.defaultMapConcurrency 1`
+    restores the pre-0.9.1 serial default wholesale.
+  - `engines.<name>.concurrency` pins any engine's own limit (and is now clamped
+    to `1..64` at freeze time instead of freezing a plan the decoder would then
+    refuse to load).
+  - **Runs already in flight are unaffected.** Both values are frozen into
+    `plan_json` when a run starts and the frozen-plan decoder requires them, so
+    a resumed run keeps the widths it began with. The new defaults apply only to
+    runs started after the upgrade.
+
+  The effective width remains the minimum of the step's `concurrency`, the run's
+  frozen `workflow.maxConcurrency`, the selected engine's concurrency, and the
+  current host's CPU cap.
+
+- **`--max-steps` now counts steps, not engine-loop iterations.** The budget is
+  spent by the DISTINCT spine steps that finished — completed, failed, or
+  gate-rejected with the loop budget spent. It was previously spent by entries
+  in the `executed` report,
+  which gains one per gate-loop iteration and one per route-skip, so
+  `--max-steps 3` against a step with `gate.max_loops: 3` could stop after a
+  single step had finished, and an unselected branch target consumed budget for
+  work that was never dispatched. Three steps now means three steps, which is
+  what the flag has always said (`Stop after executing this many steps`). A step
+  the invocation left unfinished — an abort, a judge outage — still consumes
+  nothing, because the work is still owed. The same accounting is what a
+  `--max-retries` reopen subtracts, so loops and skips no longer shrink a
+  retry's remaining budget either, and `maxSteps:` in a workflow task file is
+  the same knob and moves with it. The count is now reported: `akm workflow run`
+  carries a `stepsProcessed` field alongside `executed`, so the number the
+  budget is spent on is visible rather than inferred from a list that counts
+  something else.
+
+  **This loosens the dispatch exposure of one invocation, and the loosening is
+  cumulative across steps.** A step's whole bounded gate loop now costs one step
+  instead of one per iteration, so the rounds a single `akm workflow run` can
+  dispatch go from roughly `N + max_loops` to `N × max_loops`.
+
+  What did **not** change is what the flag bounds within one step. `--max-steps`
+  was never a cap on total dispatch rounds on either version: the budget is
+  tested only BETWEEN steps, so a single step's gate loop could always run out
+  its full `gate.max_loops` no matter how little budget was left. The per-step
+  ceiling is `gate.max_loops` (1–100); the whole-run ceilings are
+  `budget.max_units` and `budget.max_tokens`, which are seeded from the unit
+  journal and hold across resumes.
+
+### Fixed
+
+- **akm's Node fallback no longer aborts at teardown on Node 24.** On Node
+  24.19.0 and later, any command that opened a database could intermittently
+  die with `node::RemoveEnvironmentCleanupHook … Assertion (env) != nullptr`
+  and exit 134 — after its work was done, so the failure looked random and
+  depended on garbage-collection timing.
+
+  The cause was upstream and nothing to do with akm's own code.
+  `better-sqlite3` ships one prebuilt binary per Node ABI and falls back to
+  `node-gyp rebuild` when none matches, and the 11.x line publishes no prebuild
+  for Node 24 — so installing it there silently compiled the driver from source.
+  Node 24.19.0 had just changed the public `node_object_wrap.h` so that
+  `ObjectWrap`'s constructor and destructor register and unregister an
+  environment cleanup hook; a binding compiled against those headers
+  unregisters the hook after the environment is already gone, and aborts from
+  V8's teardown path. Only the Node 24 line was affected, and only from that
+  release on.
+
+  akm now pins `better-sqlite3` to `12.11.1`, which publishes prebuilt binaries
+  for Node 22, 24, 25 and 26 — so no Node version akm supports compiles the
+  driver at all. This affected real installs, not just CI: an npm user on Node
+  24 LTS was getting the same crash-prone from-source build.
+
+  The Node-fallback CI job now installs the exact spec `package.json` declares
+  instead of carrying a range of its own, and both that job and the smoke
+  script fail loudly on a native crash banner — previously an abort was
+  reported only as missing output, and the one step that tolerates a non-zero
+  exit would not have failed at all.
+
+- **A website source interrupted mid-refresh no longer loses the snapshot it
+  already had.** A refresh deleted the whole mirror and then rebuilt it page by
+  page, so a process killed inside that loop left an empty or partial directory
+  with the old content already gone — and the freshness marker still looked
+  recent, so the next `sync()` served the wreckage instead of rebuilding. The
+  new snapshot is built in a dot-prefixed sibling directory and swapped in with
+  renames: an interrupted refresh leaves the PREVIOUS complete snapshot
+  untouched. Abandoned staging directories are dot-prefixed so the indexer's
+  walk skips them, and are swept by the next refresh once an hour old.
+
+- **A resumed workflow run no longer re-dispatches work that already ran.** The
+  single-driver guard was checked at the run level, so a run whose lease had
+  been stolen left its still-owned unit row `running` and discarded the real
+  outcome — the resume then re-dispatched a unit that had already executed its
+  side effects and already spent its tokens. The guard now lives on the row, so
+  a stale driver's finish matches nothing and a live outcome is never dropped.
+
+- **Lowering `retry.max` no longer re-runs finished work.** The completed-attempt
+  scan matched only attempts the *current* retry policy could have produced, so
+  reducing `retry.max` between invocations hid a journaled `~rN` row and the
+  unit was dispatched again. It now matches any journaled attempt of the unit.
+
+- **A scheduled `command` task no longer writes your secrets into its log.**
+  Task logs were scrubbed for credential *shapes* — `Bearer …`, `sk-…`, webhook
+  URLs — but only prompt- and workflow-target runs also scrubbed exact secret
+  *values*. A command that echoed a configured secret shaped like nothing in
+  particular persisted it verbatim into both the run `.log` and `logs.db`, for
+  the whole retention window. Exact-value redaction now runs in the one sink all
+  three target kinds share, so every task kind is covered.
+
+  akm treats a value as secret when your config declares it
+  (`engines.<name>.apiKey`, `embedding.apiKey`, and the
+  `AKM_ENGINE_<NAME>_API_KEY` / `AKM_LLM_API_KEY` / `AKM_EMBED_API_KEY`
+  recipes), and infers others from the variable name (`*_TOKEN`, `*_SECRET`,
+  `*_API_KEY`, `*_PASSWORD`, …) when the value is at least 8 characters. The
+  floor applies only to the *guesses*: a declared secret is redacted at any
+  length. Redaction replaces substrings, so an over-eager rule does real damage
+  — treating every non-allowlisted variable in the inherited environment as a
+  secret classified 127 of 132 variables as credentials, 25 of them one
+  character long, and turned `3 tests passed, 0 failed` into `[REDACTED] tests
+  passed, [REDACTED] failed`.
+
+  For a secret exported under a name none of those rules recognise, any task may
+  name it:
+
+  ```yaml
+  command: ./deploy.sh
+  redact: [ACME_DEPLOY_TOKEN]   # NAMES, never values — max 32
+  ```
+
+  Names only, and a name that is unset at run time contributes nothing. A
+  literal secret in a task file would leak far more widely than the redaction
+  closes: task files are indexed into the search database, can be sent to an
+  embedding provider, are printed verbatim by `akm show`, and ship inside
+  bundles over git and npm — the same rule exec units' `pass_env:` follows.
+
+- **Redacting a log can no longer explode it.** Exact-value redaction took a
+  fast path that rewrote the text once per secret, over an accumulator it had
+  already rewritten — so a secret containing any of the letters in `[REDACTED]`
+  matched the tokens it had just inserted, and the output grew geometrically.
+  Fifty characters against six single-letter values produced 32,450 characters,
+  a 649x blowup reachable from ordinary command output. Matches are now found
+  against the original text and the result emitted once. Overlapping matches
+  merge into a single `[REDACTED]`, and the two redaction paths no longer
+  disagree about output shape depending on whether the text happened to contain
+  a `%`.
+
+- **Redacting a structured value no longer drops fields.** When two distinct
+  object keys redacted to the same string, the rebuilt object silently kept only
+  the last — `{a, b, ab}` came back with two entries, one of them simply gone
+  rather than redacted. Colliding keys are now suffixed, so the value survives
+  with its key still hidden. This affected persisted improve results and
+  journaled workflow outcomes.
+
+- **`akm improve` auto-sync now commits exactly the files the run wrote.**
+  Every akm write path records the file it mutated into a run-scoped
+  write-provenance journal, and the end-of-run (and crash-path) commit stages
+  precisely those paths. A managed-directory file someone else edits while a
+  long run is in flight is left dirty for its author instead of being swept into
+  akm's commit, and a file that was already dirty when the run started and was
+  then rewritten by the run is now committed instead of being silently skipped.
+  Deletions are journaled like writes, so a path written and then reverted or
+  purged stages its final on-disk state — or produces no commit at all. The run
+  reports its journal as `writtenPaths` on the improve result, and the
+  `stash_synced` event gains `attributed` / `unattributed` counts. `akm sync` /
+  `akm push`, which supply no explicit path list, keep the managed-pathspec
+  fallback unchanged. (#652)
+
+- **`akm lint` no longer reports a clean scan for a task file that cannot run.**
+  A `tasks/*.yml` whose YAML does not parse (bad indentation, an unterminated
+  quote, tab characters) produced `flagged: 0`: every task reader collapsed a
+  parse failure onto an empty mapping, and every task rule short-circuits on
+  one — so a CI gate on `--fail-on-flagged` passed a task that would die at
+  schedule time. The parse failure is now its own `invalid-task-yaml` finding.
+  A `tasks/*.yaml` file — a spelling akm never indexes and never schedules —
+  used to be skipped by the directory walk entirely; it is now collected and
+  flagged for the extension, with the rename in the message. Fixed on all three
+  task-lint surfaces (the CLI sweep, the `akm` adapter's `validate`, and the
+  `akm-task` format adapter) from one shared parse, so they cannot disagree.
+
+- **`akm lint --fix` refuses a bundle configured `writable: false`.** Every
+  other mutating command checks the flag before touching disk; `--fix` wrote
+  directly and never consulted it, so it rewrote frontmatter in a bundle
+  explicitly marked read-only. It is now a usage error raised before any file
+  is modified.
+
+- **A `--fix` write failure no longer aborts the run and hides the fixes that
+  already landed.** One unwritable file (read-only file, full disk) threw
+  straight out of `akm lint`, so the caller got an exception instead of a
+  result — with no way to tell which earlier files in the same sweep had
+  already been rewritten. A failed fix is now reported in-band on its own file
+  as `fixed: "failed"`, and the sweep continues through the rest of the bundle.
+
+- **`akm lint --type` says so when it does nothing.** For a non-akm bundle the
+  adapter validates the whole bundle regardless of `--type`, so scoping a run
+  silently had no effect. It now warns, naming the flag and the adapter.
+  Findings are unchanged (full-bundle validation was already a superset), and
+  it is deliberately a warning, not an error, so scripts passing one `--type`
+  across mixed-adapter bundle sets keep working.
+
+- **`missing-skill-md` fires again for an `agent-skills` package with no
+  manifest.** The check iterated pending CHANGES, and a change is always a
+  file — so a package directory holding resources but no `SKILL.md`
+  contributed nothing it could see, and a skills pack with a broken package
+  linted clean. It is now a real directory pass over the bundle root. Related:
+  under opencode's supported singular `skill/` alias the same package went
+  unflagged while an identical one under `skills/` was caught; both spellings
+  are now checked.
+
+- **An index akm cannot read no longer reports as an index that does not
+  exist.** `fs.existsSync()` answers `false` for a permission error exactly as
+  it does for a missing file, and the read path used it as its "is there an
+  index?" gate — so `akm search` and `akm curate` returned no hits at **exit 0**
+  with the tip *"No search index available. Run 'akm index' to build one."* for
+  a populated index sitting right there on disk, and `akm info` reported
+  `entryCount: 0, vecAvailable: false` for the same index. Nothing said
+  "permission". A consuming agent had no way to tell that from a genuine empty
+  result, so it relayed the false answer to its user with an explanation it had
+  invented.
+
+  Absent and inaccessible are now distinct everywhere it matters:
+
+  - `search` / `curate` / the index openers raise a `ConfigError`
+    (`DATA_DIR_UNREADABLE`, exit 78) naming the path, the errno, the mode and
+    owner, and the uid actually running — instead of an empty success.
+  - `akm info` reports an `indexStats.unreadable` diagnostic rather than zeros
+    that look healthy. The field is absent on every healthy run.
+  - `akm health` now *diagnoses* an unreadable `state.db` as a failing
+    `state-db-readable` check instead of dying on the open before it could
+    report anything — it is the command you reach for when this happens.
+  - `probeLock` returns a distinct `inaccessible` state instead of classifying a
+    permission error as a stale lock. "I cannot read this lock" and "the holder
+    is dead" are opposite facts, and `akm improve` now stops rather than
+    reclaiming a lease that may be genuinely held.
+
+  The same conflation existed on the write paths, where the consequence was
+  worse than a wrong answer:
+
+  - **An unreadable `akm.lock` could destroy every bundle record in it.** The
+    lockfile read that exists specifically so a write path never sees `[]`
+    returned `[]` for *any* read failure, permission errors included — and
+    every lockfile write is read-modify-write, so the next atomic write
+    replaced the operator's whole lock record with the single entry being
+    added. Verified by probe: the symlink was replaced by a regular file
+    holding one entry. Lockfile writes now refuse to run against a lock they
+    cannot read.
+  - **The migration recovery gate failed open.** "I cannot tell whether a
+    recovery is pending" cleared the gate exactly as "no recovery is pending"
+    did, so akm would open the canonical databases on top of a half-applied
+    migration. It now fails closed.
+  - **`akm index --clean` deleted rows for files it merely could not look at**,
+    and reported the deletions as a clean success. Unreadable entries are now
+    kept and named.
+  - `indexWrittenAssets` returned `true` — "the index is as you expect" — for
+    an index it could not open, on the strength of which `acceptProposal`
+    advanced its journal to `index-finalized`.
+  - `akm improve` eligibility, `akm feedback`, `akm bundle list` and the graph
+    loaders each turned a permission fault into an empty result, a zero count,
+    or the advice to "Run `akm index` first".
+
+- **akm no longer manages permissions on your data directory, its databases, or
+  your task logs — and no longer reports on them either.** Those take your
+  process umask; their mode is yours to set, and `chmod`/`umask` are your
+  levers.
+
+  This is scoped, not blanket: akm still creates a handful of files at
+  restrictive modes *at creation time*, as it always has — `env` and `secret`
+  assets and config backups at `0600`, their directories at `0700`, and the
+  scheduler invocation files it writes for cron/launchd/schtasks. Those are
+  files akm authors itself and whose contents are credentials; setting their
+  mode when creating them is not the same as re-permissioning a directory you
+  already owned.
+
+  Two 0.9.1 pre-release changes are gone. The first chmodded akm's databases
+  and task logs to `0600`/`0700` on every open — reverted because
+  re-permissioning a directory akm did not create silently broke installs that
+  share `$XDG_DATA_HOME` between two uids (agent sandboxes, containers, service
+  accounts). If a pre-release tightened your data directory, `chmod` it back.
+  The second was an `akm health` advisory (`secret-file-perms`) that reported
+  group/other-readable `env`, `secrets` and `config-backups` paths — removed
+  too: it is meaningless on Windows, and nagging about modes akm does not set
+  is not health reporting. `akm health` no longer emits this check, and no
+  longer exits `4` on account of it.
+
+- **`timeout: none` on an exec unit is genuinely unbounded again.** The
+  stream-drain safety net — a one-hour bound on a pipe still being read after
+  the child is gone — was armed when capture STARTED, so a command that ran
+  past an hour had its output reader cancelled mid-run and was then failed for
+  an incomplete capture even though it exited 0. It is now armed from the
+  child's exit, which is the only window it was ever meant to bound.
+
+- **A bounded exec unit no longer waits out its whole `timeout` after the
+  command has already exited.** The drain deadline for a unit WITH a wall budget
+  ran from the moment capture started — budget plus a 2 s grace — so a command
+  that exited in milliseconds while a background descendant held a pipe open
+  kept the unit, and with it a fan-out slot, occupied for the entire declared
+  timeout before reporting. It now runs from the moment nothing living owns the
+  pipe: the child's exit, or (for a child that outlived its own kill ladder) the
+  budget's expiry, plus the same 2 s grace. A command that really does spend its
+  whole budget sees the identical ceiling it saw before; only the case that used
+  to stall stopped stalling.
+
+- **A stderr drain that never finished no longer fails an exec unit whose
+  command succeeded.** `exec_capture_incomplete` was raised when EITHER pipe
+  failed to drain, so a command that exited 0 with its stdout captured whole was
+  failed — and a valid artifact thrown away — because a background descendant
+  was still holding STDERR open. stderr is a diagnostic channel that never
+  contributes to the artifact, so only an incomplete STDOUT capture fails the
+  unit now; an incomplete stderr drain is reported on the warn stream instead,
+  naming the unit and warning that any stderr shown for it may be missing its
+  tail.
+
+- **A step artifact larger than 1 MiB no longer breaks the next step of the run
+  that produced it.** Step evidence is clipped to bound one SQLite row, and the
+  engine rebuilt each downstream `steps.<id>.output` scope by re-reading those
+  rows — so a large artifact (an exec unit's stdout retains up to 8 MiB) reached
+  the very next step as a truncation marker: a path reference failed with a
+  missing-property error that never mentioned truncation, and a whole-value
+  reference silently handed the marker to the unit as its input. The run now
+  carries its own complete values forward; the row stays clipped for resume,
+  where a reference into a clipped artifact fails by name.
+
+- **A workflow run that completed is no longer reported as timed out.** The
+  deadline is observed between steps, so one landing during a run's final
+  bookkeeping set the timed-out flag on a run that then finished. On a scheduled
+  workflow task that recorded the attempt as failed, with a hint to resume a run
+  that had nothing left to resume; under `akm workflow run --timeout` it
+  rendered a `timedOut` marker on a `completed` run and exited nonzero. Both
+  surfaces now drop the marker once the run reached `completed` — a deadline
+  that lands with nothing left to abort has nothing to report.
+
+- **A rejected gate on an `exec` step no longer re-runs the command.** A gate
+  loop earns its re-dispatch by handing the judge's feedback to a unit that can
+  answer it. An exec unit cannot: its argv is frozen and never interpolated, and
+  the exec context environment carries no feedback variable — so the loop could
+  only re-run the byte-identical command, performing a deploy, a publish, or a
+  migration a second time for a verdict that could not change. The gate still
+  EVALUATES on an exec step and can still fail it: a rejection is final on the
+  first evaluation, carrying the judge's missing criteria and feedback exactly
+  as in the one-shot case. What an author sees is
+  that `gate.max_loops` is capped at 1 on a step whose unit is `exec:` — not an
+  authoring error, and no change at all to an engine step, where a declared
+  `max_loops` is still honored in full. This is the same reasoning that already
+  makes an exec unit's `output:` schema miss fail without a corrective
+  re-dispatch.
+
+- **The stale-worktree sweep no longer collects a worktree that is still in
+  use.** The opportunistic age-based GC of leftover `isolation: worktree` trees
+  judged staleness from the worktree root's mtime, which a unit writing only
+  inside subdirectories never touches — so another akm process minting a
+  worktree could delete the tree a long-running unit was working in. Every live
+  worktree now carries a liveness marker (pid, host, resolved path) in git's own
+  administrative directory for it, and the sweep skips a candidate whose holder
+  is still running here. A marker from a dead pid, from another host, or for a
+  different path is not liveness: crashed runs and retained dirty trees stay
+  collectible, which is what the sweep exists for.
+
+- On Windows, an agent CLI, gate judge, or prompt task was spawned into an
+  environment the loader cannot start from: the shared passthrough allowlist
+  named no `SystemRoot`/`SystemDrive`/`WINDIR`, and without `PATHEXT` a
+  `bin: "bun"` profile was unresolvable — while an exec unit on the same host
+  worked, because its own allowlist names them. Those variables are now added
+  when any allowlisted child environment is built.
+
+- Scheduler PATH repair skipped itself in the environments it exists for. It
+  decided a PATH was "interactive" by testing whether any entry began with the
+  user's home directory as a *string*, so a home of `/` — system crontab,
+  launchd, service accounts — matched every absolute entry, and a sibling home
+  (`/home/alice/bin` against `/home/al`) matched too.
+
+- A directory whose name merely begins with two dots (`..data`) was treated as
+  a path escape. For a workflow exec `cwd` that meant the parser and the frozen
+  plan accepted a spelling the executor then failed as tampering, with a reason
+  no retry can clear.
+
+- `appendEvent` resolved the state.db path outside its own error handling, and
+  did so even when the caller supplied an open connection — so a caller holding
+  a perfectly good handle could take a configuration error from a function whose
+  contract is that it never propagates one.
+
+- Workflow freeze attributed per-step `engine`/`model`/`timeout`/`llm` overrides
+  by matching the compiled draft step list against the source document
+  **positionally**. That was correct only because compilation happens to be 1:1
+  and order-preserving; a compile pass that filtered or reordered steps would
+  have silently applied one step's overrides to another. Attribution is now
+  keyed by `stepId`.
+
+### Security
+
+- **A gate judge's response is now scrubbed before it is journaled.** The judge
+  verdict is written into the gate row's `result_json`, and a judge failure's
+  message becomes the blocked step's notes — but the judge dispatch bypassed
+  the redaction contract every unit dispatch goes through, so a judge that
+  echoed a credential out of the promoted artifact persisted it unredacted into
+  the workflow journal. Both judge paths (agent and llm) now wrap their
+  dispatch in the same scrub, with the sensitive-value set collected per
+  dispatch rather than at build time, so a credential rotated between the two
+  reads is still caught. The dispatch also carries the real run/step/gate ids
+  instead of a synthetic `"gate"` placeholder, so a gate row and its telemetry
+  describe the same thing.
+
+- **Command-target task logs are scrubbed of exact secret values**, closing the
+  last redaction lane — see the `### Fixed` entry above for the full account.
+
+## [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 +737,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 +762,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 +774,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 +876,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 +903,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 +925,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 +1158,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 +1284,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 +1364,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 +3674,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 +3862,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