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

package/CHANGELOG.md

@@ -6,6 +6,721 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **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: 1`) 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
+    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.
+  - **Per-step orchestration.** A step can declare a runner, model, timeout,
+    fan-out (`map`/`over` with a `concurrency` cap and a `collect` | `vote`
+    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.
+  - **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
+    inputs differ on replan is a hard **replay-divergence** failure naming the
+    unit, never a silent re-dispatch. Every unit is recorded in the new
+    `workflow_run_units` table behind a serialized writer queue.
+  - **Execution (`akm workflow run`).** A semaphore-bounded scheduler fans a
+    step's units out (concurrency defaults to 1 per the local-model
+    LLM-defaults rule, capped by the engine-wide `workflow.maxConcurrency`
+    config knob — unset = `min(16, max(1, cores − 2))`, explicit values
+    clamped to `[1, 64]`), enforces per-unit
+    timeouts (default 10 m) and run **budget ceilings** (`budget.max_tokens` /
+    `budget.max_units`, seeded from the journal so they span resumes), and
+    advances the run **strictly through `completeWorkflowStep`** so completion
+    gates are never bypassed. Every dispatched unit gets a standard akm
+    preamble (run/unit ids, knowledge + env/secret + reporting contract).
+  - **Typed artifacts + honest gates.** A step's promoted artifact is
+    validated against its declared `output` schema before completion; a
+    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.
+  - **Failure policy.** Per-unit `on_error: fail | continue` (fail-fast
+    default) plus bounded `retry: { max, on: [<failure_reason>…] }` keyed on
+    the persisted failure taxonomy.
+  - **Isolation + leases.** `isolation: worktree` runs each file-mutating unit
+    in a fresh detached git worktree (journaled path; clean trees
+    auto-removed, dirty ones retained). A run **lease** (`engine_lease_*`)
+    ensures a run is driven by exactly one engine or one external driver at a
+    time; manual `complete` is refused while a live engine lease is held.
+  - **Harness-neutral driver protocol.** An orchestrated run can be driven by
+    ANY agent session (Claude Code, opencode, Codex, a human at a shell), not
+    only the native engine. **`akm workflow brief <run>`** is read-only (takes
+    no lease, mutates nothing) and emits the active step's expected work-list —
+    per-unit content-derived id, resolved instructions + input hash
+    (byte-identical to the engine's dispatch), output schema, env binding
+    NAMES only, and the exact `report` command lines. **`akm workflow report
+    <run> --unit <id> --status completed|failed|running`** is the one mutating
+    verb, ingesting a unit's result through the SAME shared step semantics the
+    engine uses (idempotent same-hash re-report, replay-divergence on a
+    differing hash, budget enforcement, schema validation, and the
+    artifact-judged gate/`max_loops` completion path). `--status running`
+    claims/heartbeats a unit for stale-driver detection without advancing the
+    spine; `--rerun` records a fresh attempt for a failed unit (carrying its
+    prior token total forward). Every report command carries `--expect-step`
+    (refused if the spine has moved since the brief), and `report --settle`
+    (no `--unit`) advances a step that dispatches no reportable units — a
+    params-only route, an empty fan-out, or an all-unresolvable work-list — so
+    a driver is never wedged. The engine and the brief/report surfaces are
+    proven to produce **identical unit graphs**
+    (`tests/workflows/conformance/driver-parity.test.ts`).
+  - **Observability.** `akm workflow watch <run>` tails the run's `workflow_*`
+    / `workflow_unit_*` events as NDJSON (`--stream` foreground-polls to a
+    terminal status, no daemon); `akm workflow status --units` lists per-unit
+    diagnostics (failure reason + result/error text) without feeding them into
+    the deterministic artifact graph; unit lifecycle emits
+    `workflow_unit_started` / `workflow_unit_finished` events carrying
+    ids/status/enums only. `akm show workflow:<name>` summarizes each step's
+    orchestration.
+  - **Harness adapters.** Seven local coding-agent CLIs are first-class
+    dispatch targets — Codex, Copilot CLI, Pi, Gemini, Aider, Amazon Q, and
+    OpenHands — each registered in `HARNESS_REGISTRY` with a command builder +
+    result extractor; agent-identity detection and the session-log provider
+    list are derived from the registry, and harness-native session ids are
+    journaled opportunistically for future session reuse.
+  - **Storage.** Additive `workflow.db` migrations 004–009 (unit journal,
+    harness session ids, frozen plans + run leases, check-in heartbeats,
+    attempt counter, unit claims); migrations 001–003 are untouched and linear
+    workflows behave exactly as before.
+
+  See "Orchestrated steps" and "Driving a run from any agent" in
+  `docs/features/workflows.md`, the redesign addendum in
+  `docs/technical/akm-workflows-orchestration-plan.md`, and `STABILITY.md`
+  (Experimental).
+- **`fable` built-in model alias** — resolves to `claude-fable-5`
+  (`opencode/claude-fable-5` on opencode); recommended resolution target for
+  the `deep` workflow model tier.
+
+### Fixed
+
+- **Check-in directives now survive plain-text output and `workflow
+  status`** (check-in review C2/M1): `formatWorkflowNextPlain` and
+  `formatWorkflowStatusPlain` render the `CONTINUE` directive, and every
+  run-detail response (status/start/complete) evaluates the check-in instead
+  of only `workflow next`.
+- Workflow frontmatter validator error message now lists the actually-allowed
+  keys (`name`, `updated` were missing); removed the documented-but-nonexistent
+  `akm workflow step` alias from `docs/features/workflows.md`.
+
+## [0.9.0] — 2026-06-30
+
+### Fixed
+
+- **improve/recombine: cap-aware decay — the `maxClustersPerRun` cap no longer
+  traps recurring hypotheses below `confirmThreshold` (#658).** Recombine is a
+  two-pass design: a cluster must be re-induced on `confirmThreshold` (=2) runs
+  before its `type:hypothesis` proposal promotes to an auto-accepted
+  `type:lesson`. But only the top-`maxClustersPerRun` (=5) clusters are
+  processed per run, and `decayUnseenRecombineHypotheses` hard-reset the
+  confirmation streak of every hypothesis not processed that run. A cluster that
+  genuinely re-forms every run but is displaced out of the top-5 (slots are tied
+  on member-count and broken by an arbitrary alphabetical tiebreak) had its
+  streak zeroed — it could never win two consecutive slots, so its proposal sat
+  pending forever (6 such proposals were stuck in one production stash).
+  `decayUnseenRecombineHypotheses` is now **cap-aware**: `recombine.ts` passes
+  the FULL pre-cap cluster set, and a hypothesis is spared from reset when its
+  cluster still Jaccard-matches a present cluster (same signature, overlap ≥ 0.7
+  — the same rule used for re-induction). Only hypotheses with no matching
+  current cluster (the corpus stopped supporting them) decay. This does **not**
+  lower the recurrence bar: the confirmation count is still advanced only by
+  genuine re-induction in the processed slice (`recordRecombineInduction`);
+  sparing merely avoids an artificial reset, so a genuinely non-recurring
+  hypothesis still decays to 0 and never confirms (no new bland-hypothesis churn,
+  cf. #632/#633). No schema change. The cap now lives in a new `capClusters`
+  helper split out of `buildRelatednessClusters` so the full ranked set stays
+  available for the decay sweep.
+- **`improve` reflect no longer emits proposals doomed to fail the
+  `invalid-description` gate when the source asset has no frontmatter
+  `description` (#636).** Reflect echoed the source frontmatter, so for assets
+  that carry other keys but no `description` (notably scraped docs:
+  `source`/`title`/`scraped`) the proposal inherited the missing/empty
+  description and the promote-time validator (`isValidDescription`, 20–400
+  chars) rejected it — observed as ~14/16 rejects in one triage pass, blocking
+  the whole scraped-doc/knowledge cluster from reflect improvement. The fix is
+  **generation-time only**: (1) `buildReflectPrompt` now injects an explicit
+  "synthesize a `description`" instruction whenever the source lacks a non-empty
+  `description` and the asset type requires one (per `authoring-rules.ts`
+  `DESCRIPTION_TYPES`), telling the model it MUST author a valid 20–400-char
+  plain-prose description from the asset's `title:`/first `# Heading`/opening
+  body; and (2) a deterministic reflect-side belt-and-suspenders in
+  `sanitizeReflectPayload` — if a source that already had frontmatter still ends
+  up with a missing/empty description after generation, reflect derives one
+  deterministically from `title:`/first heading (validated against
+  `isValidDescription`, never free-form invention) **before** the proposal is
+  created. The validator, `authoring-rules.ts` bounds, `repairProposalContent`,
+  and the drain are unchanged — nothing in the validator/promote path fabricates
+  content to pass itself.
+- **The high-salience improve admission lane (#608) now requires a
+  content-derived encoding score, not the per-type weight stub (#655,
+  #608/#644 follow-up).** The lane previously admitted any zero-feedback ref
+  whose `asset_salience.encoding_salience >= salienceThreshold` (default 0.75).
+  But for assets distill has not content-scored, `encoding_salience` is just the
+  per-type WEIGHT STUB (skill/agent 0.9, command/workflow 0.8, lesson 0.75), so
+  "high-salience" degenerated into "is a skill/agent/command/lesson" — which
+  selected the type-stub `lore-writer` agent on every run (prod: 1 content-scored
+  / 37 type-stub / 1826 NULL-legacy rows). The gate now also requires
+  `isContentEncodingRow(row, parseAssetRef(ref).type)` (the #644 provenance
+  helper), so only genuinely content-scored assets qualify. This preserves
+  #608's intent — distilled assets, the lane's real targets, keep their real
+  content score and still qualify — while cutting the type-stub waste; type-stub
+  rows must earn retrieval/feedback signal via the other lanes. NULL-legacy rows
+  follow `isContentEncodingRow`'s differs-from-stub heuristic. An aggregated log
+  line now reports how many refs the lane admitted so lane composition is
+  observable. The threshold, type-weight table, 10% cap, and `isContentEncodingRow`
+  are unchanged.
+
+- **Auto-sync no longer refuses to commit akm's own changes when unrelated
+  non-akm files are present in the stash working tree.** When a stash root is
+  shared with a project repo, stray files written into the stash root (e.g. a
+  `tasks.bak-…` backup dir or report artifacts like `data.js`,
+  `akm-health-report.html`, `reports/`) previously tripped the #476 safety
+  guard, which threw `refusing to push: … has uncommitted non-akm changes` on
+  **every** `akm improve` end-of-run auto-sync, `akm sync`, and `akm push`. In
+  one production incident this silently blocked all commits for ~1.5 days while
+  akm kept accepting proposals it never persisted. `saveGitStash` now **scopes
+  what it stages** instead of refusing: (1) an explicit modified-file list when
+  the caller passes `opts.paths`, else (2) the akm-managed pathspecs
+  (`TYPE_DIRS` values + `.akm`) that exist on disk — which by construction never
+  stages non-akm WIP, preserving the #476 protection without an all-or-nothing
+  refusal — and only as a last resort (3) `git add -A` when no managed pathspec
+  can be resolved. If nothing akm-managed is staged the run returns
+  `nothing to commit` (no empty commit, no throw). Unrelated non-akm files are
+  left untouched and uncommitted.
+
+### Changed
+
+- **BEHAVIOR CHANGE — `akm init --dir <path>` no longer silently repoints your
+  default stash.** Previously, `akm init --dir X` unconditionally wrote
+  `stashDir: X` to `config.json` whenever `X` differed from the configured
+  default — so initializing a throwaway or secondary stash (e.g.
+  `akm init --dir /tmp/scratch`) would hijack the user's real default stash
+  pointer (the footgun documented in `memory:akm-init-persists-stashdir-warning`).
+  Now `init` persists `stashDir` to config **only** when one of the following
+  holds: (a) **no `--dir`** was provided (the default `~/akm` setup flow —
+  unchanged), (b) `--dir` was provided and **no `stashDir` exists in config yet**
+  (first-time bootstrap), or (c) `--dir` was provided **with the new
+  `--set-default` flag** (explicit opt-in). Otherwise `init` still scaffolds and
+  backfills the target dir exactly as before, but **leaves your default stash
+  pointer untouched** and prints:
+  `Your default stash is unchanged (<existing>). Re-run with --set-default to make <dir> the default.`
+  The `InitResponse` JSON gains `defaultStashUpdated: boolean` and an optional
+  `previousStashDir`. To make a `--dir` target your default, pass
+  `akm init --dir <path> --set-default`. (`akm setup` is unaffected — it remains
+  the explicit configuration flow and always sets the default.)
+
+### Added
+
+- **Per-type SOFT authoring conventions are now user-editable stash facts.** A
+  third authoring-guidance layer joins the hard rules (#645) and general stash
+  standards (#642): a stash owner can author
+  `facts/conventions/assets/<type>.md` (e.g. `…/skill.md`, `…/command.md`) to
+  capture soft, type-specific guidance — voice, structure, length *preference*,
+  naming style. When an agent authors a `skill:x`, the body of
+  `fact:conventions/assets/skill` is injected (type-scoped — authoring
+  `command:y` pulls the `command` convention, never the `skill` one), labeled
+  as soft guidance and kept separate from the validator-enforced hard rules.
+  The basename must be a `getAssetTypes()`-validated asset type; facts are read
+  straight from disk (no index rebuild) and degrade to empty safely. When no
+  per-type fact exists, the built-in `TYPE_HINTS` fallback is unchanged (no
+  regression). These facts carry soft conventions only and can never weaken the
+  authoring contract the gate enforces (`authoringRulesForType` remains the sole
+  source of validator-rejecting rules). The general convention/meta resolver now
+  excludes `facts/conventions/assets/*` so per-type guidance never leaks
+  un-type-scoped into other authoring flows. (#646)
+- **`akm init` now seeds default per-type SOFT convention templates.** Starter
+  `facts/conventions/assets/<type>.md` templates ship in the stash skeleton for
+  the authored types (`lesson, skill, command, agent, knowledge, memory,
+  workflow, script, fact`; `wiki`/`env`/`secret` excluded) so a stash owner has
+  an editable starting point. Each expands the matching built-in `TYPE_HINTS`
+  one-liner into soft starter guidance, carries `category: convention`
+  frontmatter, and states in-body that it is advice, not enforced — it carries
+  **no** validator-rejecting rules, so editing or deleting one cannot weaken the
+  gate (#645). The stash-skeleton copy is now recursive (preserving nested
+  subpaths), and `akm init` seeds **unconditionally** rather than only on first
+  create: re-running it on an existing stash backfills any missing skeleton,
+  convention, or `.meta/index.md` files. Seeding stays absent-only and never
+  overwrites a user-edited file. (#646)
+
+## [0.9.0-beta.36] — 2026-06-22
+
+### Added
+
+- **Stash standards + wiki schemas are surfaced to authoring agents at write
+  time.** When an agent edits a page under `wikis/<name>/`, that wiki's
+  `schema.md` body is injected into the prompt; when it creates/edits a non-wiki
+  asset, the bodies of `category: convention`/`meta` `fact` assets are injected.
+  Two mutually-exclusive features selected by target type, sharing one
+  `standardsContext` prompt seam. Wired into reflect, propose, and every
+  improve authoring pass (distill, consolidate, recombine, procedural, extract,
+  schema-repair). (#642)
+- **Unified, validator-sourced authoring-rules seam.** A new
+  `authoringRulesForType(type)` injects the hard authoring rules (no
+  pseudo-frontmatter in body, exactly two `---` fences, description/`when_to_use`
+  length + shape) into every authoring prompt. The numeric bounds live in one
+  module that the validators import, so the prompt can no longer drift from what
+  the gate enforces. (#645)
+
+### Fixed
+
+- **High-salience reflect lane now reflects each asset at most once.** The
+  `#608` admission gate lacked the cooldown its sibling high-retrieval gate has,
+  so zero-feedback assets were re-selected on every run (auto-accept emits
+  `promoted`, not `feedback`), burning LLM calls and churning assets. (#643)
+- **Stuck validation-failing proposals no longer dead-end.** The triage drain no
+  longer overwrites an `auto-rejected` gate stamp with a misleading
+  `auto-accepted` (the failure stays truthful and visible). A bounded,
+  content-preserving auto-repair (strip pseudo-frontmatter / stray `---`, repair
+  truncated descriptions) runs at the promote boundary and re-validates — fixable
+  proposals promote; genuinely unrepairable ones stay `pending` for manual
+  review, with nothing fabricated and validation never bypassed. (#645)
+- Corrected a prompt/validator drift where the distill system prompt asked for an
+  80–200 char description while the gate enforced 20–400. (#645)
+
+## [0.9.0-beta.35] — 2026-06-21
+
+### Fixed
+
+- **Default extract discovery window is now "since the last run" (floored at 48h),
+  not a fixed 24h.** An intermittently-online host that was off for longer than
+  the old 24h window could permanently miss sessions that ended during the gap.
+  Discovery now looks back to the last recorded extract run for the harness, never
+  less than 48h. Widening is free of redundant LLM cost — the content-hash ledger
+  skips unchanged sessions with zero LLM calls. An explicit `--since`/`defaultSince`
+  still wins.
+- **Per-session lock prevents concurrent double-extraction.** A session-end hook
+  firing `extract --session-id` while the periodic `akm improve` extract pass runs
+  discovery could both LLM-process the SAME session (duplicate spend + near-dup
+  proposals). A per-(harness, session) advisory lock (co-located with state.db,
+  PID + age staleness recovery) now makes the second run skip without any LLM call.
+- **`minNewSessions` is read from the ACTIVE improve profile, not always `default`.**
+  A non-default profile (e.g. `frequent`) setting `minNewSessions` was silently
+  ignored because the gate (and its candidate-count discovery window) read
+  `profiles.improve.default`. They now read the resolved active profile, matching
+  how `extract.enabled` already resolves.
+
+### Docs
+
+- Documented that `processes.extract.indexSessions` (default on) makes a second
+  LLM call per processed session (the session summary); set it to `false` to halve
+  per-session extract cost. Unchanged/skipped sessions still cost zero.
+
+## [0.9.0-beta.34] — 2026-06-21
+
+### Fixed
+
+- **`akm extract --type opencode` reads opencode's SQLite session store.** opencode
+  migrated session storage from per-file JSON (`storage/session/<projectId>/<id>.json`
+  + `storage/message/<id>/*.json`) to a single Drizzle-managed database at
+  `<base>/opencode.db` (tables `session`/`message`/`part`; message text lives in
+  `part` rows with `data` JSON `type:"text"`). The legacy JSON layout went stale
+  ~2026-02, so extract discovered 0 sessions on current opencode and the
+  `session.idle` extract hook had nothing to read. `OpenCodeProvider` now prefers
+  `opencode.db` when present (read-only, via the cross-driver `openDatabase` seam)
+  and falls back to the JSON layout. Verified end-to-end through the plugin's
+  `session.idle` hook.
+
+## [0.9.0-beta.33] — 2026-06-21
+
+### Fixed
+
+- **`akm extract` decoupled from the improve-stage toggle.** `processes.extract.enabled`
+  now gates extract only as a STAGE of `akm improve` (the active improve profile, per
+  #593/#594); an explicit `akm extract` command always runs. Previously dropping extract
+  from the daily improve profile silently disabled the standalone command (and its LLM
+  calls, via the shared `session_extraction` feature gate).
+- **`extract --session-id` now respects the content-hash ledger; `--force` overrides.**
+  Explicit single-session extraction previously bypassed the #602 already-extracted skip
+  unconditionally — re-paying the LLM on every call and risking double-extraction against
+  the cron. Now a targeted `extract --session-id <id>` is idempotent (skips an unchanged,
+  already-extracted session with zero LLM calls) and only `--force` re-extracts. This
+  makes a session-end hook firing `extract --session-id <id>` precise AND idempotent.
+
+## [0.9.0-beta.32] — 2026-06-21
+
+### Added
+
+- **Recombine acceptance path — confirmed lessons now auto-accept.** Recombine
+  hypotheses that reach the confirmation threshold (promoted to `type: lesson`,
+  #625/#633) now flow to ACCEPTED by reusing the existing drain mechanism instead
+  of piling up pending forever: the `personal-stash` drain policy gains a
+  `{ generator: "recombine", requireType: "lesson", maxDiffLines: 200 }` rule, via
+  a new optional `requireType` frontmatter filter on `DrainAcceptRule`. Only
+  confirmed `type: lesson` proposals auto-accept; unconfirmed `type: hypothesis`
+  proposals stay pending; the existing proposal quality gate still applies.
+- **`processes.reflect.lowValueFilter` (opt-in, default OFF)** — deterministic
+  semantic value-floor that defers trivial reflect rewrites (#639A).
+- **`processes.extract.triage.proceduralAwareFloor` (opt-in, default OFF)** —
+  triage floor requiring markers/edits so real lessons always pass (#641).
+
+### Fixed
+
+- **Select-time proactive cooldown leak.** `selectProactiveMaintenanceRefs` plans
+  the due set BEFORE acquiring `reflect-distill.lock`, so overlapping/back-to-back
+  improve runs reused stale due-state and re-reflected the same asset repeatedly
+  (observed up to ~16× in a day). The orchestrator now re-applies the dueDays gate
+  with freshly-read timestamp maps INSIDE the lock (`filterProactiveDue`), dropping
+  refs a concurrent run already reflected.
+
+## [0.9.0-beta.31] — 2026-06-20
+
+### Changed
+
+- **#632 — recombine now filters junk tags structurally.** Frontmatter tags that
+  are pure numbers, dates (`20260529`), short hex hashes (`002c624c`), version
+  strings (`0.8.0`, `v2`), single chars, or common English stopwords (`is`, `the`,
+  `for`, `when`, …) carry no topical signal and never form a recombine cluster.
+  Unlike `excludeTags` (a fixed project list), this catches the OPEN-ENDED junk —
+  every new date or commit hash — with no config upkeep. Exposed as `isJunkTag`.
+  On the live stash this turns the recombine cluster set from generic 66–171-member
+  buckets into tight topical clusters (`auth`, `architecture`, `patterns`, …).
+
+## [0.9.0-beta.30] — 2026-06-20
+
+### Changed / Fixed
+
+- **#632 — recombine cluster tuning (opt-in, default-preserving).** Recombine
+  clustered memories by frontmatter tag and preferred the LARGEST buckets, so it
+  always picked the coarsest whole-stash tags (`session`/`claude`/`akm`, 63–171
+  members) and produced bland generalizations. Two new `processes.recombine` knobs:
+  `maxClusterSize` (skip clusters larger than N, so over-broad buckets no longer
+  reach/starve the largest-first slice) and `excludeTags` (tags that may never form
+  a tag cluster). Both UNSET = byte-identical to prior behavior.
+- **#633 — recombine confirmation loop fixed.** The hypothesis confirmation streak
+  was keyed on a hash of the EXACT member set, so a growing stash drifted the key
+  every run → a fresh row at count 1 → `confirmThreshold` never reached → no
+  hypothesis ever promoted to a lesson (a dead two-pass loop). A freshly-induced
+  cluster now matches an existing pending row by signature + Jaccard
+  membership-overlap (≥ 0.7) and reuses its stable ref, so the streak accumulates
+  through membership drift. First/non-overlapping induction is unchanged.
+
+## [0.9.0-beta.29] — 2026-06-20
+
+### Reverted
+
+- **#630 — `fact` asset type phase 2 reverted (#631).** The pinned-core assembly +
+  `akm fact` CLI shipped in beta.28 was reverted pending rework. Phase 1 (#629, the
+  `fact` asset type itself) remains in place.
+
+## [0.9.0-beta.27] — 2026-06-20
+
+All new behavior is **opt-in / default-preserving** — default runs are byte-identical.
+
+### Added
+
+- **#624 P2 — priority-ranked graph extraction.** `processes.graphExtraction.topN`:
+  when set, the graph-extraction pass ranks eligible files by asset utility
+  (`utility_scores`, read-only join) and processes only the top-N per run, so
+  high-value assets get graphed first instead of a ~55h full-corpus sweep. Unset
+  (default) = no ranking, byte-identical.
+- **#624 P3 — lazy on-demand graph extraction.** New `graph_extraction_queue` table
+  + `enqueueGraphExtraction`/`drainExtractionQueue`/`extractGraphForSingleFile`.
+  `akm curate` enqueues an ungraphed hit (non-blocking); `akm show` can extract a
+  missing graph inline — gated on `index.graph.lazyGraphExtraction: true`
+  (**default off**: `show` makes no LLM call by default), model-guarded, and bounded
+  by a 30s timeout so it never hangs. The pass drains the queue before the ranked
+  sweep. This **closes #624** (all three layers shipped).
+- **#616 — bounded multi-cycle phasing.** `profiles.improve.<name>.maxCycles`
+  (default 1): when > 1, the improve passes run in an N-cycle loop so gate-accepted
+  output of cycle N feeds cycle N+1 within the same run (re-running ensureIndex +
+  ref selection each cycle), stopping at a fixed point and respecting the run budget.
+  `maxCycles: 1` = byte-identical to today.
+
+### Fixed
+
+- **Release CI unblocked.** `runCliCapture` (test harness) restored `process.exitCode`
+  to a captured `undefined`, which under `bun test` does not clear a previously-set
+  non-zero exit code — so the unit suite exited 1 with 0 failures at `TEST_PARALLEL=1`
+  (exactly how `release.yml` runs), silently blocking every npm publish since beta.11.
+  Fixed to restore to `0`. (This is why beta.26 was the first successful workflow publish.)
+
+### Changed
+
+- **CI/release tests sharded across runner jobs (~15 min → ~2 min).** Bun 1.3.x
+  in-process test parallelism (`--parallel=N`, N>1) hits an intermittent
+  `epoll_ctl EEXIST` race / busy-spin hang on the `--isolate` workers, which had
+  forced fully-sequential (`TEST_PARALLEL=1`) runs. Tests now shard across separate
+  runner jobs (each a separate process tree, so no cross-shard fd/epoll collisions)
+  with `--parallel=1` within each shard; the matrix runs shards concurrently. The
+  release gate runs the identical set of tests. Local `bun run check` defaults to
+  sequential too (the only safe mode on this Bun version). Coverage unchanged.
+  Each shard runs through `scripts/run-test-shard.sh`, which retries **only on a
+  hang/timeout** (the busy-spin can rarely fire even at `--parallel=1`) and never
+  on a real test failure, so genuine red tests still fail fast and are never masked.
+
+## [0.9.0-beta.26] — 2026-06-20
+
+### Added
+
+- **#628 — configurable SQLite journal mode (`AKM_SQLITE_JOURNAL_MODE`) for network
+  filesystems.** AKM previously opened every database with `PRAGMA journal_mode = WAL`
+  unconditionally, which cannot run on a network filesystem (NFS/SMB/Azure Files) —
+  WAL's `-shm` shared-memory wal-index can't be `mmap`'d over a network mount. You can
+  now set `AKM_SQLITE_JOURNAL_MODE` to `WAL` (default), `DELETE`, or `TRUNCATE`, applied
+  at **all five** db openers (`state.db`, `index.db` ×2 paths, `workflow.db`, `logs.db`).
+  At the `WAL` default AKM auto-detects a network mount for the data dir and transparently
+  falls back to `DELETE` (rollback journal + `synchronous = FULL`) with a one-line warning;
+  invalid values warn once and fall back to `WAL`. **Default behavior is byte-identical.**
+  This lets the AKM database subtree live on a shared volume (e.g. Azure Files under
+  Azure Container Apps). New docs section "Hosting AKM databases on a network share
+  (NFS/SMB)" in `docs/configuration.md`.
+
+## [0.9.0-beta.25] — 2026-06-19
+
+Completes the recombine / extract-efficiency / graph thread. All new improve
+passes are **opt-in (default off)**, so default behavior is unchanged.
+
+### Added
+
+- **#606 — event-driven extract (`akm extract --watch`).** Opt-in watch mode: an
+  injectable, debounced watcher triggers extraction shortly after a session file
+  appears, with a clean `stop()` handle. The `8,28,48` cron remains the fallback;
+  no daemon is auto-launched.
+- **#625 — recombine second pass (hypothesis → lesson).** The opt-in `recombine`
+  process (#609) now consumes `confirmThreshold` (default 2): a generalization
+  re-induced that many consecutive runs is promoted from a `type: hypothesis`
+  proposal to a `type: lesson` proposal through the normal queue + quality gate
+  (never a direct stash write). Hypotheses that stop recurring decay. Backed by a
+  new `recombine_hypotheses` table in `state.db`.
+
+### Changed
+
+- **#624 (P1) — graph storage decoupled from `entries.id`.** `graph_files` is
+  re-keyed on `(stash_root, file_path, body_hash)`, so extracted graph data now
+  **survives a reindex** of unchanged files instead of being cascade-wiped. The
+  upgrade is migrated in a **targeted, graph-only path** that preserves existing
+  graph data and leaves the entry index, embeddings, FTS, and LLM-enrichment cache
+  untouched — **no full index rebuild and no re-embed** on upgrade. (P2 priority-
+  ranked extraction and P3 lazy/on-demand extraction remain deferred.)
+
+### Fixed
+
+- Graph re-key migration no longer triggers a destructive full-index rebuild: it
+  is a graph-scoped table migration (no `DB_VERSION` bump), and it **copies** the
+  existing graph rows into the new schema rather than dropping them.
+- Test-suite `/tmp` hygiene: sandbox teardown now fires on `SIGINT`/`SIGTERM`/
+  `SIGHUP` (not just clean exit), and a `sweep:tmp` step reclaims stale `akm-*`
+  sandbox dirs left by force-killed workers — eliminating the tmpfs accumulation
+  that caused intermittent `EEXIST: epoll_ctl` test flakes.
+
+## [0.9.0-beta.20] — 2026-06-18
+
+### Fixed
+
+- **`akm update --all` no longer fails for writable `github:` entries stored as `source:"git"`**. `updateRegistryEntry` was using `synced.source` (re-derived from the ref scheme as `"github"`) instead of the existing `entry.source`, causing the config validator to reject `writable:true` on every update cycle.
+
+## [0.9.0-beta.19] — 2026-06-17
+
+### Fixed
+
+- **`akm feedback` now completes in ~0.3s** (was 3+ minutes). Root cause: the command was calling `ensureIndex` with `mode: "blocking"` inside `withIndexWriterLease`, triggering a full reindex on every feedback call. Fix: removed the `ensureIndex` call entirely (feedback only needs the index to exist, not be current — a stale index is fine for ref lookup); removed the application-level writer lock (SQLite WAL + `busy_timeout=30s` handles concurrent access with `akm improve`); added a fast DB-exists guard with a clear error for first-time users.
+- **`akm health --format html` now completes in ~11s** (was ~18s). Root cause: `akmHealth()` was called twice — once for the main result and once to get `deltas`. Fix: merged into a single call passing both `groupBy: "run"` and `windowCompare` together.
+
+## [0.9.0-beta.18] — 2026-06-17
+
+### Changed
+
+- **Health report: Recent Runs table now shows all filtered runs in descending order** (newest first) instead of capping at the last 10.
+- **Health report: Removed "Command Set Used" section.**
+- **Health report: All timestamps now display in the viewer's local timezone** (chart axis labels, runs table, freshness line, executive summary, footer). Server-rendered ISO strings are wrapped in `<time data-iso>` elements and converted to local time by client-side JS on page load.
+
+### Changed (migration required)
+
+- **WS-2 outcome loop (#613) — default-off weight change (state.db migration 010).**
+  Every `akm improve` run now writes an `asset_outcome` row per processed asset
+  (state.db migration `010`) and computes a differential usefulness signal
+  (`outcome_score`) per ref. The outcome signal is persisted and visible in the
+  health report, but the **weight change is gated behind a config flag** (see
+  below). Ranking is unchanged from WS-1 by default.
+
+  **Opt-in weight change.** The WS-2 projection weights (`w_e=0.25, w_o=0.15,
+  w_r=0.60`) affect ranking only when you explicitly set
+  `improve.salience.outcomeWeightEnabled: true` in your `akm.yaml`. The default
+  (`false`) keeps WS-1 parity weights (`w_e=0.30, w_r=0.70`, `w_o=0`), so
+  existing users see no ranking change on upgrade.
+
+  **Part-V measurement gate.** Before enabling the weight change, run the Part-V
+  T0 baseline (`scripts/akm-eval` + `akm health`; confirm proactive accept
+  ≥ 0.9× reactive; reversion ≤ 0.15; retrieval-delta ≥ 0; coverage not
+  regressed). That gate requires a running production stash and cannot be
+  exercised in CI. Once confirmed, set
+  `improve.salience.outcomeWeightEnabled: true` to activate the three-way split.
+
+  **Outcome loop mechanics.** `outcome_score` is a differential prediction-error
+  signal: `(retrieval_delta − expected_delta) − PENALTY × retrieval_delta × (1 −
+  accepted_change_rate) + valence`, tracked via an EMA (α=0.3). New rows are
+  warm-started from the utility EMA score (clipped to 0.3) so the signal is
+  non-zero from launch. A stash-wide diversity floor (10% of the max score) prevents
+  rare-but-correct assets from being permanently outcompeted. An inverted-proxy
+  tripwire (`corr(outcome_score, accepted_change_rate) < −0.3`) emits an
+  `outcome_proxy_inverted` health event when the signal degrades.
+
+  `review_pressure` is computed and persisted per asset but is **not yet wired into
+  the admission policy** — that is deferred to a later work stream per plan §Part-VI
+  #613. The column is present and populated; routing it into the consolidation-
+  selection filter is the next step.
+
+- **WS-1 salience vector (#618) — default-on ranking change.** The eligibility sort
+  for all `akm improve` runs (whole-stash, type, and ref scope) has changed from
+  `combinedEligibilityScore = utility·0.7 + negativeOnlyRatio·0.3` to
+  `rankScore = (0.3·encodingSalience + 0.7·retrievalSalience) × sizePenalty`
+  (feedback valence and utility EMA dropped from ordering until WS-2 re-introduces
+  outcome salience). Assets are now ranked by retrieval frequency × recency × type
+  importance rather than by feedback magnitude. Because the old
+  `combinedEligibilityScore` ordering was never persisted, a forgetting comparison is
+  not possible on the first run; instead a one-time `improve_salience_first_run` marker
+  event is emitted to record the transition. On every subsequent run a stash-wide
+  `improve_salience_rank_change` drift report (including `stashSize`) is emitted so
+  rank movement under the new scoring can be tracked over time.
+  The Part-V measurement protocol (T0 baseline via `scripts/akm-eval` + health report,
+  throughput/quality gate) is deferred to the WS-2 milestone, when outcome salience
+  re-joins the projection and re-tuning is triggered.
+
+## [0.9.0-beta.12] - 2026-06-15
+
+Improve-tuning work streams (all **default-off / parity-preserving** — no behavior
+change until explicitly enabled).
+
+### Added
+
+- **#617 — deterministic near-duplicate memory dedup** (`processes.consolidate.dedup`,
+  default off). A cheap no-LLM pre-pass in front of consolidation collapses obvious
+  duplicates — `.derived`+origin pairs and content twins (normalized content-hash
+  equality, or embedding cosine ≥ `cosineThreshold`, default 0.97). Each dropped
+  variant is archived + backed up before deletion; hot memories are never
+  collapsed; distinct-but-related memories fall through to the LLM.
+- **#581 — judged-state cache for consolidation** (`processes.consolidate.judgedCache`,
+  default off). New state.db table (`consolidation_judged`) records each memory's
+  content hash + outcome when the LLM judges it; subsequent runs skip
+  judged-unchanged memories, converting coverage from O(time-window) to
+  O(changed/new) so a run can sweep the full corpus. Fails open; failed chunks
+  and dry-runs never poison the cache. (state.db migration `007`.)
+- **#612 — auto-accept gate calibration** (`improve.calibration`, auto-tune default
+  off). Joins predicted gate confidence to realized accept/reject outcomes into a
+  reliability table + calibration gap, surfaced in `akm health` (+ summary rows in
+  the HTML report). Opt-in bounded threshold auto-tune nudges the accept threshold
+  within a configured band toward a target accept rate, logged via a
+  `calibration_autotune` event. (Replay-prioritization from prediction error is
+  deferred — it depends on the #610 replay budget, a 0.10 item.)
+
+### Fixed
+
+- **#614 — symmetric valence weighting** (`profiles.improve.*.symmetricValence`,
+  default off). The eligibility sort weighted feedback negative-only; when enabled
+  it uses a symmetric `|valence|` magnitude so strong positive and strong negative
+  feedback both drive attention (utility stays the dominant factor), routing
+  high-negative → fix and high-positive → reinforce lanes.
+
+## [0.9.0-beta.11] - 2026-06-15
+
+### Added
+
+- **`extract.maxSessionsPerRun`** (default 25) — caps the NEW sessions the
+  extract pass LLM-processes in a single run so a backlog (e.g. after downtime)
+  can't push one run past its scheduled-task timeout. Overflow sessions stay
+  unseen and are picked up by later runs, so coverage is preserved. `0` disables.
+
+### Fixed
+
+- **Auto-accept validation failures are no longer a blind leak.** When a
+  confidence-passing proposal fails promotion validation, the gate now captures
+  the reason (the `validateProposal` finding kind, e.g. `validation:description-quality`),
+  records it on the proposal (`akm proposal show` explains the rejection), logs
+  it, and exposes `failedByReason` on the gate result — so the ~5% leak is
+  diagnosable instead of silently warned-and-dropped.
+- **Inflated skip-reason aggregates in `akm health`.** `no_new_signal` /
+  `profile_filtered_all_passes` are per-run snapshots of a stable set; the
+  window aggregator summed their per-run counts (≈2.7M / 3M). It now uses the
+  most recent run's count for these aggregated-snapshot reasons while still
+  summing genuine per-occurrence skips.
+
+## [0.9.0-beta.10] - 2026-06-15
+
+### Added
+
+- **#603** — `akm health` pool-saturation advisory. Instead of alerting on the
+  raw `sessionsScanned` count (which false-alarmed on normal cadence changes),
+  a new `pool-saturation` advisory reports the ratio of new (unseen) sessions
+  to the total session pool: informational below 10% (expected steady state),
+  warning below 2% (possible discovery/dedup bug). Heuristic, never gates
+  overall status.
+- **#576** — the `akm health` HTML report now renders the real per-stage LLM
+  token/time aggregate (a "🧠 LLM Work" KPI card + LLM token/call/wall-time
+  summary rows) from the captured `llm_usage` events, replacing the GPU-time
+  proxy.
+- **Built-in `akm health --format html` report overhaul** — the report is now a
+  strict superset of (and supersedes) the external `akm-health-report` stash
+  skill. Restored the interactive filter bar (time-slice 1d–21d, task, status)
+  with client-side chart/table re-render and the Last-10 "Task" column;
+  reordered sections to a decision-first flow (verdict → action items → KPIs →
+  table → charts); added a synthesized one-sentence **Verdict** (status + 2–3
+  drivers) and a freshness line; merged the duplicate Advisories / What-to-Watch
+  into one prioritized, de-duplicated **Action Items** list (P1/P2/P3 +
+  remediation command); added a per-stage **LLM token** stacked-bar chart and
+  `dataZoom` sliders on dense charts; fixed the failed-run scatter x-alignment
+  (now shape-encoded); KPI-card colors are now health signals (not decoration);
+  added metric-glossary tooltips, chart `aria-label`s, contrast fixes, and
+  empty-state overlays. Deterministic output preserved.
+
+### Fixed
+
+- **Health report accuracy** (follow-ups to the overhaul): the per-run **Task**
+  column/filter now show the real scheduled task (`akm-improve-frequent`, …) via
+  a ±5min `task_history` join instead of the run's scope (which is `all` for
+  every scheduled run); the time-**slice** filter options are now derived from
+  the report's `--since` window (e.g. All/3d/1d/12h/6h for a 7d report) and
+  default to "All" — replacing the hard-coded 1d–21d list that didn't match the
+  window; and the trend **deltas** now default their compare window to `--since`
+  (like-for-like, e.g. last 7d vs prior 7d) instead of a fixed 24h, which had
+  produced nonsensical period-over-period percentages on multi-day reports.
+- **Inflated stash-snapshot metrics in `akm health`.** `memorySummary`
+  (derived/eligible) and `profileFilteredRefs` are whole-stash snapshots recorded
+  on every run, but the window aggregator was **summing** them across all runs —
+  e.g. "915,258 of 1,226,025 eligible" and a 2.4M filtered-ref count. They now
+  take the most recent run's snapshot (the current state). Per-run *work* metrics
+  (promoted, MI written, graph entities, …) remain genuine window sums.
+- **Health report polish:** the akm version is stamped in the header (under the
+  AKM logo) and footer; the steady-state `no new signal since last proposal`
+  distill reason is excluded from the skip-reason chart (it drowned out the
+  actionable reasons); and the Consolidation Output chart now draws Promoted as a
+  line on a secondary right-hand axis (it dwarfs merged/deleted) with merged and
+  deleted as bars on the left axis.
+
+- **#598** — process-level tuning fields (`consolidate.incrementalSince`,
+  `minPoolSize`, `neighborsPerChanged`, `extract.minContentChars`, per-process
+  `enabled` flags) now survive an `akm config` rewrite. They are first-class
+  typed `ImproveProcessConfigSchema` fields, so the load→save round trip no
+  longer silently drops them. Unknown process sub-keys hard-error at load
+  (`ConfigError`) rather than being silently discarded — the deliberate,
+  documented resolution. Regression-guarded by
+  `tests/config-process-roundtrip.test.ts`.
+
 ## [0.9.0-beta.9] - 2026-06-14
 
 Restore and instrument `akm improve` steady-state output. The reflect/distill