akm-cli 0.9.31 → 0.10.26101002-alpha

package/docs/architecture/improvement.md

@@ -39,8 +39,9 @@ everything else routes through `akm proposal accept`.
   `src/assets/improve-strategies/*.json`) — named presets that decide which
   improve processes run and with what engine/model/limits.
 - **Autonomy gate** (`src/commands/improve/autonomy-gate.ts`) — downgrades
-  the handful of processes that would otherwise mutate assets without review,
-  unless `experimental.improveAutonomy` is explicitly set.
+  the handful of processes that would otherwise mutate assets without review
+  (memory inference, memory cleanup, and a judged triage promote), unless
+  `experimental.improveAutonomy` is explicitly set.
 - **Reflect / distill / consolidate subprocesses** — the improve pipeline's
   proposal generators, invoked per asset (reflect, distill) or across the
   whole memory corpus (consolidate). See
@@ -80,10 +81,11 @@ everything else routes through `akm proposal accept`.
    reason or note, which gives the writer nothing to distil (10 of the 11
    lessons made from such memories were rejected). Unless
    `--require-feedback-signal` is set, the
-   fallback lanes (high salience, and proactive maintenance where the strategy
-   enables it) pick what the retrieval scope below admits, for scoring only:
-   they plan nothing, so improve does not rewrite assets on a proactive
-   cadence. It ranks the selected assets by salience, applies the limit, then
+   proactive-maintenance lane (where the strategy enables it, as `default`
+   does) adds the stable assets due for a revisit that the retrieval scope below
+   admits, and plans them with the feedback-bearing ones. At most `maxPerRun`
+   (15) assets are picked per run, an asset is due only if not reflected or
+   distilled for `dueDays` (30), and reflect's `limit` (25) bounds the run. It ranks the selected assets by salience, applies the limit, then
    runs whichever processes the selected strategy enables against each one (see
    [Improve Workflow](internals/improve-workflow.md#ledger-pre-filter-signal-delta)).
 4. Reflect and distill each emit at most one proposal per asset per run;
@@ -146,9 +148,8 @@ for the storage-level summary.
 ### Strategy inheritance
 
 Improve presets live under `improve.strategies` (config) and the built-in
-set: `default`, `quick`, `thorough`, `consolidate`, `catchup`,
-`reflect-distill`, and `proactive-maintenance`
-(`src/assets/improve-strategies/*.json`). Selection
+set: `default` and `consolidate` (`src/assets/improve-strategies/*.json`). The removed `quick`, `thorough`,
+`catchup`, `reflect-distill` and `proactive-maintenance` still work as user-defined strategies. Selection
 order is `--strategy`, then `defaults.improveStrategy`, then `default`.
 
 Resolution is a two-step deep merge (`resolveImproveStrategy`): a named
@@ -157,16 +158,16 @@ any user-defined override for that same name (under `improve.strategies` in
 config) is merged on top. So a strategy — built-in or user-defined — that
 omits a field, or an entire process block, inherits it from `default`; an
 explicit `enabled: true`/`false` in the more specific layer always wins. This
-is why, for example, `proactiveMaintenance` stays off in `default` and
-`reflect-distill`, but a preset that doesn't mention it at all still inherits
-that "off" rather than defaulting to on.
+is why, for example, `proactiveMaintenance` is on in `default` and off in
+`consolidate`, and a preset that doesn't mention it at all inherits the
+`default` value. A user-defined strategy named `proactive-maintenance` (the name
+of the retired built-in) resolves the same way, merged onto `default`.
 
 ### Retrieval scope
 
 Improve reworks only what gets read (#986). Fresh feedback and an explicit ref
 scope (`akm improve skills/x`) are usage evidence of their own. Every other
-pick — the proactive-maintenance and high-salience lanes (which only score what
-they pick), and the memories consolidation judges — must be in the retrieval
+pick — the proactive-maintenance lane, and the memories consolidation judges — must be in the retrieval
 scope (`src/commands/improve/retrieval-scope.ts`):
 
 - **Retrieved:** a user-attributed `search`, `curate` or `show` returned the
@@ -217,7 +218,10 @@ both stay on the proposal when the drain accepts it, so a later audit can read
 why it passed (`akm proposal show --format json`). A distill pass is not staged:
 the lesson or promotion is minted `deferred` for a person (reason
 `distill-review`, same gate) with the same `scores` and `judgeReason`, and the
-triage drain and its judgment tier leave it alone. On 2026-10-05 the gate had
+triage drain and its judgment tier leave it alone. A lesson that repeats an existing
+lesson may instead be proposed as an update of that lesson (reason
+`distill-update`, same gate), with only what the memory adds; the drain leaves
+it for a person too. On 2026-10-05 the gate had
 staged 12 lessons and 10 were bad (they restated the memory, claimed what it
 does not say, or filed a dated status as a lesson), and no score separated them
 from the two good ones. Reflect revises only an asset's
@@ -225,6 +229,28 @@ from the two good ones. Reflect revises only an asset's
 those that fixed a frontmatter defect and left the body alone were good 24
 times in 26, and those that also rewrote the body were bad 175 times in 224.
 
+### Judgment tier: promotions only
+
+The triage drain's judgment tier (`processes.triage.judgment`, off in every
+built-in strategy) may accept only a consolidate promotion, a memory proposed as
+a new knowledge note. A retirement, an exact fix or a reflect revision it would
+accept is left for a person (`judgment-not-promotion`); it may still reject.
+Measured on the nightly eval with `experimental.improveAutonomy` (#1132, #1094),
+judging every kind solved 0.49 (gpt-5.6-terra) and 0.53 (qwen3.8-27b) of the
+items, harmed 14 and 11, and changed 18 and 21 notes outside the planted set.
+Judging promotions alone: precision 0.87, recall 0.78 and 4.8% of bad promotions
+accepted on qwen3.8-27b; precision 1.0, recall 0.17 on gpt-5.6-terra.
+
+### Proactive-lane proposals wait for a person
+
+A proposal planned by the proactive-maintenance lane (`eligibilitySource:
+"proactive"`, an asset with no feedback behind it) is never accepted by the
+drain, whether a deterministic gate (a staged quality-judge pass), the judgment
+tier or an accept staged by an earlier drain would take it. It is left for a
+person with reason `proactive-needs-review`, and the judgment tier does not see
+it. An empty diff is still rejected. Proposals driven by feedback (`signal-delta`,
+`scope`) follow the one rule unchanged (#1147).
+
 ### Retrieval regression gate
 
 Reflect refuses a revision of an existing asset that grades lower on the
@@ -297,8 +323,7 @@ but nothing assigns or emits it any more.
 ### Dry-run planning boundary
 
 Dry and live improve runs call the same selectors for signal-delta eligibility,
-the fallback lanes (proactive maintenance and high salience, which score and
-plan nothing), the retrieval scope, salience ranking, disk presence, and the
+the proactive-maintenance lane, the retrieval scope, salience ranking, disk presence, and the
 final cap, and resolve the bundle they plan the same way: `--bundle`, else
 `defaultWriteTarget`, else the working bundle (`AKM_BUNDLE_DIR`, else
 `defaultBundle`). Each invocation reports a best-effort observation assembled
@@ -337,13 +362,20 @@ equals `effective`. When the run is unbounded, `totalCeiling` is omitted.
 candidates, validation, and proactive-maintenance selection are proposal-only
 and never write assets directly regardless of this gate.
 Three specific lanes *would* mutate assets without review and are downgraded
-unless `experimental.improveAutonomy` is explicitly set to `true`:
+unless `experimental.improveAutonomy` is explicitly set to `true` (the triage
+lane only when its judgment tier is on; see below):
 
 | Lane | What it does when enabled | With autonomy off |
 | --- | --- | --- |
 | `memoryInference` | Writes `.derived.md` children and rewrites parent frontmatter | disabled |
 | memory cleanup | Belief-state frontmatter rewrites, archive moves | analyzed but not applied |
-| `triage` `applyMode: "promote"` | Auto-accepts queued proposals into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+| `triage` `applyMode: "promote"` **with judgment on** | The judgment tier auto-accepts consolidate promotions into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+
+A deterministic-only `promote` (triage with judgment off) is not gated (#1143):
+the `default` strategy drains the queue through the deterministic gates, up to
+`maxAcceptsPerRun` (200) per run, with no opt-in. The nightly eval's baseline is
+exactly this path (`proposal drain --promote` without judgment): 0.91 (terra) and
+0.89 (qwen) of items solved, 0 to 1 harmed.
 
 Every downgrade is reported, not silent: it warns on stderr, appends an
 `improve_skipped` event with `reason: "autonomy_gated"`, and is counted in
@@ -361,8 +393,7 @@ explicit promote surface independent of this gate.
 For git-backed bundles (detected by a `.git` directory), `akm improve`
 automatically commits its changes as a single batch at the end of the run —
 the same operation as `akm sync` — and pushes if the bundle is writable, per
-the active strategy's `sync` setting. The `reflect-distill` and
-`proactive-maintenance` strategies skip sync entirely, so an interrupted run
+the active strategy's `sync` setting. A user-defined strategy can turn sync off, so an interrupted run
 does not leave an uncommitted backlog. `--no-sync` disables sync for a single
 run; `--no-push` commits without pushing. Strategy sync behavior is
 configured via the `sync` block under `improve.strategies.<name>`.

package/docs/architecture/internals/improve-workflow.md

@@ -13,7 +13,7 @@
 | `--limit` | `number` | Cap the number of assets processed, taken from the salience ranking, highest first (refs routed to distill only come last). |
 | `--timeout-ms` | `number` | Wall-clock budget for the entire run. Default: 7 200 000 ms (2 hours). |
 | `--skip-if-locked` | `boolean` | If another improve owns the whole-run lock, return an exit-0 no-op result before triage, indexing, events, or sync. Without the flag, contention is a transient error (`IMPROVE_LOCK_HELD`, exit 75). |
-| `--require-feedback-signal` | `boolean` | Turn the fallback lanes (high salience, proactive maintenance) off for the run: they only select and score assets, and a rewrite needs negative feedback. |
+| `--require-feedback-signal` | `boolean` | Turn the proactive-maintenance lane off for the run, so only assets with recent feedback are planned. |
 
 Injected function seams (`reflectFn`, `distillFn`, `ensureIndexFn`, `reindexFn`) replace production defaults in tests.
 
@@ -49,7 +49,7 @@ flowchart TD
     P -- yes --> P1[Log failures; refs that still fail\nare excluded from selection]
     P -- no --> L[Signal delta\nreflect: negative feedback, distill: any signal,\nnewer than the last ledger attempt\nand no hard ledger window]
     P1 --> L
-    L --> L2[Fallback lanes\nproactive maintenance, high salience:\nonly retrieved or new material,\nscored and never planned]
+    L --> L2[Proactive maintenance lane:\nonly retrieved or new material,\nmaxPerRun picks, due after dueDays]
     L2 --> M[scoreSalience\nsalience vector per ref: encoding, outcome, retrieval\nutility scores from SQLite seed the outcome term]
     M --> N[Sort by salience rank DESC, no-op dampened\ndrop refs missing on disk\napply --limit if set]
     N --> Q
@@ -100,7 +100,7 @@ flowchart TD
             DISTILL_G -- no --> DISTILL_J{quality gate judge:\nreusable, non-redundancy, grounding}
             DISTILL_J -- pass --> DISTILL_H[createProposal lessons/slug-lesson\nor knowledge/slug\nsource: distill, gate decision deferred\nappendEvent: outcome=queued]
             DISTILL_J -- mean in the review band --> DISTILL_REVIEW[createProposal, gate decision deferred\nappendEvent: outcome=review_needed]
-            DISTILL_J -- any criterion 2 or below, or the mean too low --> DISTILL_REJECT[improve_ledger row, no proposal\nappendEvent: outcome=quality_rejected]
+            DISTILL_J -- any criterion 2 or below, or the mean too low --> DISTILL_REJECT[improve_ledger row, no proposal\nappendEvent: outcome=quality_rejected\nunless a repeated lesson gets an update proposal, step 10]
             DISTILL_PROMOTE --> DISTILL_RETURN
             DISTILL_SKIP --> DISTILL_RETURN
             DISTILL_EXISTS --> DISTILL_RETURN
@@ -245,10 +245,17 @@ Reflect changes only an asset's `description`, `when_to_use` and title. The engi
    - **Grounding** asks whether every cause, step, number, rule and limit in the lesson is stated by the source or its feedback; 4–5 when each is, 3 when one stretches what the source says, 1–2 when any is in neither, when the lesson drops a limit the source states, or when it is about another subject. It is not part of the mean.
    - A criterion at 2 or below is `quality_rejected` whatever the mean is (the reason names the criterion: `grounding 2/5: …`). Otherwise the lesson passes when reusable and non-redundancy both score 4 or more, and a mean of those two of 2.5 or more is `review_needed`. A pass is also queued for a person (step 9), so the rejection is the only thing that keeps a lesson from a reviewer: on 2026-10-05 the old rubric (novelty, non-redundancy, and a grounding that scored 3 for a lesson that "goes beyond the source") passed 10 of the 17 bad lessons, because a lesson that adds to its memory scored as novel. The old novelty question was also the reason the judge rejected a faithful lesson of a lesson-worthy memory. A distill with no source to read (an unindexed ref distilled "from feedback signal alone") gives the judge an empty source, so its lesson is expected to be rejected.
    - `quality_rejected` writes an `improve_ledger` row for the input (30-day distill rejection window) and a `distill_invoked` event carrying `score`, the per-criterion `criteria` and the `reason`. It mints no proposal.
-   - `review_needed` mints a pending proposal stamped `deferred` / `quality-gate` for a human; the triage drain leaves it alone. It is the outcome for a non-passing mean of 2.5 or more when no criterion is at 2 or below, a judge that times out or returns something unparseable or incomplete, the optional fidelity check's contradiction (`processes.distill.fidelityCheck.enabled`, off by default; a lesson that contradicts its source reaches a human this way, not through grounding), and a heuristic lesson-quality finding (for example an invalid `description`), which is found before the judge is called.
+   - `review_needed` mints a pending proposal stamped `deferred` / `quality-gate` for a human; the triage drain leaves it alone. It is the outcome for a non-passing mean of 2.5 or more when no criterion is at 2 or below, a judge that times out or returns something unparseable or incomplete, and a heuristic lesson-quality finding (for example an invalid `description`), which is found before the judge is called.
 9. Create proposal: `createProposal(stash, { ref: lessonRef, source: "distill", payload })` through `mintProposal`. A pass is minted `deferred` (gate `quality-gate`, reason `distill-review`) with the judge's per-criterion `scores` and `judgeReason`, for a person: the triage drain and its judgment tier leave it alone, and the improve ledger records `review_needed`. It is never `staged`. On 2026-10-05 the gate had staged 12 lessons and 10 were bad (they restated the memory, claimed what it does not say, or filed a dated status as a lesson); no judge score separated them from the two good ones. A promotion to knowledge that passes is deferred the same way. With `processes.distill.qualityGate` off nothing was judged, so the proposal is minted unstamped for the drain to decide.
 10. Emit `distill_invoked` event with `outcome: "queued"`.
 
+**Updating a lesson the memory repeats (#1090):** when the lesson repeats one the library holds, distill extends that lesson instead of only dropping the duplicate. It happens in two places, both with the quality gate on: the judge scored the writer's lesson 2 or below on non-redundancy (step 8), or the writer answered `NONE` (step 5). Either way the update is tried for the related lessons (among the top 3 nearby assets, as for the judge, in the bundle the proposal is filed in) that the writer's `reason`, or the judge's, names by ref or name, or for the only related lesson when it names none. One lesson among several that merely sit near the memory costs no call. A second call shows the writer the memory, its feedback and the candidate lessons' bodies, and asks it to pick the lesson that already states the memory's rule, list in `new_facts` each cause, step, number, limit or consequence the memory states and the lesson lacks (the memory's own incident retold is not one), and return that lesson's whole body with a line added for each; it answers `decision: "none"` when no listed lesson states the rule, when `new_facts` is empty (an update with none is not proposed), or when the memory contradicts a line. Then:
+
+- Every existing body line must still be there (compared by words, in any case and spacing). A body that drops or rewords one is not proposed.
+- The extended lesson (existing frontmatter and the whole new body) is judged as one lesson, in one call, by step 8's judge with an edit variant of its rubric: **reusable** and **grounding** read the whole lesson (a line is grounded when the memory, its feedback or the lesson being extended states it), and **non-redundancy** is asked of each added line against the lesson being extended: 1–2 when it only says again what the lesson says (its rule or cause in other words, or the same rule on an example from the memory), 4–5 when it states a fact the lesson lacks, however specific. The lesson being extended is shown to the judge as such, not as an asset the new lesson might repeat. Judging the added lines alone as a new lesson failed `reusable` for a lone fact, and no update passed. A body that adds no line is not proposed; anything short of a judge pass is not proposed.
+- The update is a pending proposal on the existing lesson's ref (`source: distill`), the lesson's frontmatter unchanged except that the memory is added to `xrefs`. Its `beforeHash` is the lesson's as read, so accepting it after the lesson changed is refused as stale. It is minted `deferred` (gate `quality-gate`, reason `distill-update`) with the judge's `scores` and `judgeReason`, so the triage drain and its judgment tier leave it for a person. The result and the `distill_invoked` event are `queued` with `proposalRef` set to the lesson and `updatesExisting: true`.
+- When nothing is proposed, the outcome is what it was before: `quality_rejected` with the judge's reason after a duplicate lesson, `skipped` / `nothing_reusable` after `NONE`.
+
 **Lesson-ref derivation rule:** `lessons/<type>-<name>-lesson` where `<type>-<name>` is derived from the input ref with origin stripped and non-alphanumeric characters replaced by `-`. Example: `skills/deploy` → `lessons/skill-deploy-lesson`. A lesson already at that ref is never overwritten (see step 4).
 
 **What it writes:** one durable proposal row in `state.db`. Never writes asset files directly.
@@ -610,7 +617,7 @@ Two proposals can share the same `ref`; their UUID primary keys prevent collisio
 
 ## Scope restrictions
 
-`akm improve` reads and writes one bundle, its write target: `--bundle`, else `defaultWriteTarget`, else the working bundle. The candidate set is that bundle's assets and nothing else, because every proposal is filed in the write target. An asset that another writable bundle owns is never planned: reflect would read it from its own bundle and the proposal would land in this one, either forking the asset as a `create` or overwriting this bundle's copy with content taken from the other's (#1000). A bare ref scope (`akm improve skills/x`) resolves inside the write target only, and distill's memory-to-knowledge promotion merges only with a doc that already exists there. To improve another writable bundle, select it with `--bundle team` or a bundle-qualified scope such as `team//skills/code-review`; a scheduled run therefore covers only its write target, and each other bundle needs its own scheduled `akm improve --bundle <name>` run. A dry run (`--dry-run`, `--plan`) resolves the bundle the way a live run does, with the working bundle starting from `AKM_BUNDLE_DIR` before `defaultBundle`, so it previews the bundle a live run improves. As a second line of defence, `createProposal` refuses a proposal whose `itemRef` names an asset owned by a different configured bundle than the queue's.
+`akm improve` reads and writes one bundle, its write target: `--bundle`, else `defaultWriteTarget`, else the working bundle. The candidate set is that bundle's assets and nothing else, because every proposal is filed in the write target. An asset that another writable bundle owns is never planned: reflect would read it from its own bundle and the proposal would land in this one, either forking the asset as a `create` or overwriting this bundle's copy with content taken from the other's (#1000). A bare ref scope (`akm improve skills/x`) resolves inside the write target only, and distill's memory-to-knowledge promotion merges only with a doc that already exists there. To improve another writable bundle, select it with `--bundle team` or a bundle-qualified scope such as `team//skills/code-review`; a scheduled run therefore covers only its write target, and each other bundle needs its own scheduled `akm improve --bundle <name>` run. A dry run (`--dry-run`) resolves the bundle the way a live run does, with the working bundle starting from `AKM_BUNDLE_DIR` before `defaultBundle`, so it previews the bundle a live run improves. As a second line of defence, `createProposal` refuses a proposal whose `itemRef` names an asset owned by a different configured bundle than the queue's.
 
 `akm improve` and `akm lint` only operate on writable bundle sources (sources with `writable: true`). Read-only sources (git, npm, website) are excluded from the candidate set before any other filtering; a read-only write target plans nothing.
 
@@ -622,12 +629,12 @@ Every stage reads the improve ledger (`improve_ledger` in `state.db`, one row pe
 
 - A ref that passes reflect is planned for the loop. If it does not pass distill, distill is skipped for it (a `distill-skipped` action and an `improve_skipped` event with reason `distill_no_new_signal`).
 - A ref that passes only distill, and is a distill candidate, is planned distill-only.
-- A ref with no in-window feedback and no reflect window is left to the fallback lanes (proactive maintenance and high salience), which pick only what retrieval returned or new material (see [Retrieval scope](../improvement.md#retrieval-scope)). The lanes only select and score: a ref they pick is not planned for reflect or distill, so improve does not rewrite assets on a proactive cadence.
-- Every ref the loop does not take is counted in the plan's `signal` gate (or its `retrieval` gate, when the fallback lanes could not pick it for lack of usage evidence) and reported once, in aggregate, as an `improve_skipped` event (`no_new_signal`, `not_retrieved`).
+- A ref with no in-window feedback and no reflect window is left to the proactive-maintenance lane, which picks only what retrieval returned or new material (see [Retrieval scope](../improvement.md#retrieval-scope)) and plans its picks with the feedback-bearing refs. The cap against a proposal flood: `maxPerRun` (15) picks per run, an asset due only after `dueDays` (30) without a reflect or distill, and reflect's `limit` (25).
+- Every ref the loop does not take is counted in the plan's `signal` gate (or its `retrieval` gate, when the proactive lane could not pick it for lack of usage evidence) and reported once, in aggregate, as an `improve_skipped` event (`no_new_signal`, `not_retrieved`).
 - A memory flagged wrong is not distilled: when a negative feedback in the 30-day window recorded the hash of the body it judged (`contentHash`, the `body` hash of `content-hash.ts`) and the file's body still has it, the loop skips distill for it (a `distill-skipped` action and an `improve_skipped` event with reason `distill_flagged_wrong`) and records the attempt in the ledger as `unchanged`, so the ref waits for newer feedback. Reflect still plans it. A write that leaves the body alone (an inference stamp, a frontmatter repair) does not lift the flag; changing the body does. Feedback recorded without a hash keeps the earlier test: it flags the memory while it is newer than the file's last write, whose modification time is the edit signal, as for the retrieval scope's new material.
 - A memory whose only feedback in the 30-day window is positive without a reason or note (`hasOnlyBarePositiveFeedback` in `preparation.ts`) is not distilled either: the loop skips distill for it (a `distill-skipped` action with the reason "only positive feedback, without a reason" and an `improve_skipped` event with reason `distill_positive_without_reason`) and records the attempt in the ledger as `unchanged`, so it waits for newer feedback. A bare `--positive` only records that a note helped, which gives the writer nothing to distil: 10 of the 11 lessons made from such a memory were rejected on 2026-10-05, and the 11th was good. A reason, a note or a negative signal among the feedback, or an explicit ref scope, lets it through.
 - A memory whose frontmatter says `beliefState: deprecated` or `superseded` (`isDeprecatedOrSuperseded` in `preparation.ts`) is not distilled either: the loop skips distill for it (a `distill-skipped` action with the reason "marked deprecated or superseded" and an `improve_skipped` event with reason `distill_deprecated_or_superseded`) and records the attempt in the ledger as `unchanged`. An explicit `--scope` ref still runs. `contradicted` is not skipped: it marks an open conflict, not a retired note.
-- The loop's refs are ranked by salience (`scoreSalience` in `preparation.ts`, which also scores the fallback lanes' picks and computes each vector with `computeSalience` from `salience.ts`): encoding, outcome, and retrieval frequency and recency, discounted for file size, with a ref that was repeatedly skipped as a no-op ranked lower. Refs missing on disk are dropped, and `--limit` cuts the list: reflect-path refs first, then distill-only refs.
+- The loop's refs are ranked by salience (`scoreSalience` in `preparation.ts`, which also scores the lane's picks and computes each vector with `computeSalience` from `salience.ts`): encoding, outcome, and retrieval frequency and recency, discounted for file size, with a ref that was repeatedly skipped as a no-op ranked lower. Refs missing on disk are dropped, and `--limit` cuts the list: reflect-path refs first, then distill-only refs.
 
 An explicit ref scope bypasses every gate. Consolidation, extract and schema repair read their own ledger sources in their own stages.
 

package/docs/architecture/internals/indexing.md

@@ -429,7 +429,7 @@ so a layout change is applied in place rather than by discarding the index.
 Durable workflow, task, proposal, event, and usage state in `state.db` is
 never touched by these paths.
 
-Workflow `.md` and `.yml` adapters compile directly to source IR version 1.
+The workflow `.md` adapter compiles directly to source IR version 1.
 The index stores only the ordinary normalized `entries` row and searchable
 metadata derived from that IR. It does not cache a second workflow AST or an
 executable plan. Starting a run recompiles the authored source once and freezes

package/docs/architecture/internals/search.md

@@ -223,11 +223,10 @@ By default (`--format json`, `--detail brief`), search emits minimal fields:
 `--detail normal` emits `type`, `name`, `description`, `action`, `score`, and
 `estimatedTokens`, plus optional warning, quality, or env-key fields.
 `--detail full` adds `whyMatched`, `origin`, `path`, and timing data.
-`--shape summary` returns metadata only (no content), under 200 tokens.
 
 ### Agent-optimized output
 
-For each materialized local hit, `--shape agent` includes `name`, canonical
+For each materialized local hit, `--detail agent` includes `name`, canonical
 `ref`, `type`, absolute `path`, current-policy `editable`, `description`,
 `action`, `score`, and optional `estimatedTokens`/env keys. `editHint` appears
 only when `editable` is `false`. The hint is supplemental: `action` remains the

package/docs/architecture/internals/storage-locations.md

@@ -253,7 +253,7 @@ extension, so an install without `sqlite-vec` leaves the unread table in place.
 
 #### Workflow source indexing
 
-Peer `.md` and `.yml` workflow sources compile directly to source IR version 1.
+Workflow `.md` sources compile directly to source IR version 1.
 The index stores the ordinary normalized `entries` row and metadata derived from
 that IR; there is no workflow-specific AST cache or parallel persisted source
 representation. Executable durable plans belong only to `state.db`.
@@ -503,7 +503,7 @@ Keys of `metadata_json`, each written only when the proposal has it:
 | `gateDecision` | `{ outcome: auto-accepted\|deferred\|staged\|auto-rejected, reason, gate?, contentHash?, measured?, thresholds?, scores?, judgeReason?, decidedAt }`; `scores` (per criterion) and `judgeReason` are the quality judge's evidence on its `staged` pass (or on a distill pass it deferred for review as `distill-review`), and stay on the row when the drain accepts it; a reflect pass deferred as `body-edit` by an older release carries them too |
 | `backupContent` | The target's content before promotion, for `revert` |
 | `acceptedTarget` | `{ source, root, path, contentHash }`, where accepted content went |
-| `eligibilitySource` | The improve lane that planned the asset: `signal-delta` or `scope`; `proactive` and `high-salience` only on rows an older release wrote, since those lanes score assets and no longer plan them |
+| `eligibilitySource` | The improve lane that planned the asset: `signal-delta`, `proactive` or `scope`; `high-salience` only on rows an older release wrote, since that lane was removed |
 | `promotionSource`, `promotionSourceHash` | A consolidate promotion's source memory and its raw body hash at mint: accept archives the memory only if the hash still matches, and once the promotion is decided the ledger holds the memory until its body changes |
 | `retirement` | A `consolidate-pair` retire proposal's verdict: `retiredRef`, `successorRef`, `cosine`, `judgeLabel`, `judgeReason`, `onlyInRetired` and `onlyInSuccessor` (the judge's claim lists by role, each at most 20 x 200 chars; absent before they were recorded), `retiredContentHash`, `successorContentHash`, `reason`, and `continuityRisk` when the retirement continuity check flagged it |
 | `retiredArchive` | `{ dirs }`, the archive directories of an accepted retirement, for `revert` |
@@ -632,7 +632,7 @@ The JSONL file at `$CACHE/events.jsonl` is no longer read or written by akm.
 | `improve_invoked` | `akm improve`, live runs | `strategy`, `scope`, `dryRun`, `eligibleCount` |
 | `improve_completed` | `akm improve`, end of a run | `strategy`, `plannedRefs`, per-mode and per-class action counts, memory-cleanup counts |
 | `improve_failed` | `akm improve`, a run that crashed | `strategy`, `error` (redacted), `durationMs` |
-| `improve_skipped` | `akm improve`: a ref, a lane, or a group of refs left out | `reason`: `no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`; with `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
+| `improve_skipped` | `akm improve`: a ref, a lane, or a group of refs left out | `reason`: `no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`; with `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
 | `improve_lock_recovered` | `akm improve` reclaiming a stale run lock | `lockName`, `stalePid`, `lockedAt`, `recoveredAt`, `lockAgeMs`, `reason` |
 | `improve_review_needed` | `akm feedback`, when a high-utility asset's utility drops below the review threshold | `previousUtility`, `nextUtility`, `reason` |
 | `improve_reflect_outcome` | the improve loop, after each reflect call | `ok`, `durationMs`, `engine`, `reason` |
@@ -703,7 +703,7 @@ One line per memory belief-state transition: `{ appliedAt, ref, parentRef, fromS
 
 All asset files live under `$STASH/` in type-specific subdirectories defined by the `PLACEMENT_SPECS` map in `src/core/asset/asset-placement.ts`:
 
-The `workflows/` directory holds peer `.md` and `.yml` workflow sources. The
+The `workflows/` directory holds `.md` workflow sources. The
 `tasks/` directory holds task source v4 `.yml` sources.
 
 | Subdirectory | Asset Type | Format |
@@ -713,7 +713,7 @@ The `workflows/` directory holds peer `.md` and `.yml` workflow sources. The
 | `agents/<name>.md` | agent | YAML-FM + Markdown |
 | `knowledge/<name>.md` | knowledge | YAML-FM + Markdown |
 | `instructions/<name>.md` | instruction | YAML-FM + Markdown |
-| `workflows/<name>.md` / `workflows/<name>.yml` | workflow | Peer `.md` Markdown and `.yml` GitHub-shaped sources; both compile through source IR v1 |
+| `workflows/<name>.md` | workflow | Markdown source; compiles through source IR v1 |
 | `scripts/<name>.<ext>` | script | sh / ts / js / ps1 etc. |
 | `memories/<name>.md` | memory | YAML-FM + Markdown |
 | `env/<name>.env` | env | `KEY=VALUE` pairs |

package/docs/architecture/persisted-data-compat.md

@@ -8,7 +8,16 @@ close each format is to that contract today.
 
 ## The contract
 
-A reader must tolerate anything an earlier release wrote: convert the old
+**Version floor (0.10, #1091): 0.9.15.** A 0.10 reader owes data written by
+0.9.15 or later, and nothing older. An install on an earlier release runs
+`akm migrate apply` under akm 0.9.x first, then upgrades. A reader that meets a
+shape older than the floor does not convert it: it refuses, with one message
+naming `akm migrate apply` under akm 0.9.x (config: the retired
+`stashDir`/`sources[]`/`installed[]` keys; `engines.*.extraParams` keys that
+shadow a first-class field). A shape that 0.9.15 or later still wrote stays
+readable; the rows below say which those are.
+
+Above the floor, a reader must tolerate anything an earlier release wrote: convert the old
 shape in memory, warn once, and name `akm migrate apply` as the on-disk
 cleanup path — the migrator is where an explicit, backed-up rewrite happens,
 never a precondition for reading. The only refusal a reader is allowed is data
@@ -27,11 +36,11 @@ and named once, round-trips through ordinary writes, and is dropped by
 
 | Format | Where written | Version marker | Older data | Newer data | Gate |
 | --- | --- | --- | --- | --- | --- |
-| `config.json` | `src/core/config/config.ts` | `configVersion` field | `configVersion` is read, never gated on (`readConfigVersion`, `src/core/config/config.ts`): a missing field or `"0.9.0"` — the only value akm has shipped — loads silently, and any other value is named once and read as `0.9.0`; like the `extraParams` keys, the legacy `stashDir`/`sources[]`/`installed` shape is converted rather than dropped — `migrateLegacySourceShape` (`src/core/config/legacy-source-shape-shim.ts`) folds it into `bundles`/`defaultBundle` in memory on every load; `akm migrate apply`'s `configFile` step (`normalizeConfigFile`) persists all of it — `configVersion: "0.9.0"`, the converted source layout, the lifted `extraParams`, unknown keys dropped — to the file once, under a backup | Same as older: the value is named once and the file is read as `0.9.0`; there is no `UNSUPPORTED_CONFIG_VERSION` refusal. `akm health`'s `binary-config-skew` advisory (`src/commands/health/config-skew.ts`) is what says "a newer akm wrote this config, upgrade this install" | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/config-v09.test.ts` |
+| `config.json` | `src/core/config/config.ts` | `configVersion` field | `configVersion` is read, never gated on (`readConfigVersion`, `src/core/config/config.ts`): a missing field or `"0.9.0"` — the only value akm has shipped — loads silently, and any other value is named once and read as `0.9.0`. Below the 0.9.15 floor the file is refused, not converted: the retired `stashDir`/`sources[]`/`installed[]` layout fails validation (`AkmConfigSchema`, `src/core/config/config-schema.ts`) and an `extraParams` key that shadows a first-class engine field (`temperature`, `maxTokens`, `enableThinking`, `reasoningEffort`) is rejected by `validateExtraParams`, each telling the user to run `akm migrate apply` under akm 0.9.x or to set the field. A config with no `scheduler.enabled` (0.9.15 wrote none) is read as "keep what is installed": `akm task sync` adopts the akm-written scheduler rows as the list (`tests/integration/upgrade-rehearsal/`'s 0.9.15 origin). 0.9.16's `{kind, ref, sourceId}` `scheduler.enabled` entries are still read, as their `ref`, and written back as plain refs; `akm migrate apply`'s `configFile` step (`normalizeConfigFile`) persists that — `configVersion: "0.9.0"`, unknown keys dropped — to the file once, under a backup | Same as older: the value is named once and the file is read as `0.9.0`; there is no `UNSUPPORTED_CONFIG_VERSION` refusal. `akm health`'s `binary-config-skew` advisory (`src/commands/health/config-skew.ts`) is what says "a newer akm wrote this config, upgrade this install" | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/config-v09.test.ts` |
 | `state.db` | `src/core/state/migrations.ts` (append-only `MIGRATIONS` registry, applied by `src/storage/sqlite-migrations.ts`) | `schema_migrations` ledger table | `openStateDatabase` opens one connection (mkdir, open, standard pragmas), reads the ledger on it, and runs every migration not yet applied forward in one transaction; a missing/empty/table-less file is simply a fresh database. Before a migration that drops schema (`018-drop-dead-lane-schema`, `028-improve-ledger`; `STATE_MIGRATION_SAFETY_BY_ID`) runs against a database that already has migrations applied, the file is copied beside itself to `state.db.pre-<migration id>.bak` via `VACUUM INTO` on the same connection | An older binary opening a `state.db` migrated by a newer akm continues with the schema it knows and warns once (`warnNewerStateLedger`, `src/core/state-db.ts`); it does not refuse; only a ledger that diverges from this akm's registry is refused (`assertMigrationLedger`) | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`) |
 | `index.db` | `src/storage/repositories/index-schema.ts` (`ensureSchema`; `index-entry-schema.ts` for the DDL and the layout constant) | `index_meta.version` = `CANONICAL_INDEX_DB_VERSION` (26), a layout marker | Readers (`openExistingDatabase` / `openReadonlyExistingDatabase`) serve it as-is and name `akm index` once (`checkIndexLayout`); the writable opener migrates in place — added columns via `ALTER TABLE`, a one-time FTS rebuild from `entries` for the layout-23 content-copy tables, and for layout 24 the drops of the sqlite-vec mirror `entries_vec` (when sqlite-vec loads; dropping a vec0 table needs it) and `entry_fragments_fts`, with `entries.search_text` hashed into `embed_hash` before the column is dropped so no vector is re-embedded, and for layout 25 the declared links (`asset_links`, #935) derived from each entry's stored `document_json` with no file read (only the directories holding workflows and tasks, whose targets no earlier layout stored, lose their incremental cursor and re-drain on the next `akm index`) — never dropping `embeddings`, `utility_scores*`, or `llm_enrichment_cache`. It drops the lazy-extraction queue `graph_extraction_queue`, retired in 0.9.17, and, on any layout, the LLM entity graph (`graph_meta`, `graph_files`, `graph_file_*`) and its `llm_enrichment_cache` rows, retired in 0.9.17-alpha.9 — an older release's `CREATE TABLE IF NOT EXISTS` recreates the graph tables (empty) if it ever opens this index again. It also deletes `llm_enrichment_cache` rows at the default `cache_variant` — the metadata-enhance pass, retired in 0.9.17-alpha.9 — on any layout; memory inference uses its own named variant and is unaffected. A migration leaves `index_meta.vacuumPending`, and the next `akm index` VACUUMs the freed pages. An `entries` table older than layout 21 has its entries-keyed tables recreated: one that lacks a column this release reads, or that still has a transitional column layout 21 removed (`entry_key`, `dir_path`, `stash_dir`, `entry_json`, `entry_type`), as the table 0.9.1 wrote does, with `document_json` empty on every row. A reader finds such a table unservable (`hasCurrentEntriesTable`), so a read rebuilds it inline. Only `SQLITE_CORRUPT` deletes and rebuilds the file (#865) | Refused by readers and the writable opener alike (`INDEX_SCHEMA_INCOMPATIBLE`, "Upgrade akm to use this index.", `newerIndexLayoutError`), leaving the file untouched: a newer layout may lack a column this akm reads, as layout 25 lacks `search_text` | `tests/integration/indexer/index-layout-migration.test.ts` (layout-23 and layout-24 fixtures); `tests/integration/previous-release-corpus.test.ts` (the layout-25 index 0.9.17-alpha.7 wrote, `index-v25.sql`, and the layout-20 index 0.9.1 wrote, `index-v20.sql`); `tests/integration/storage/index-generation-read-boundary.test.ts`; upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`) |
-| Task source (`tasks/*.yml`) | `src/tasks/source/parse-task-source.ts` | `version: 4` (`TASK_SOURCE_V4_VERSION`) | **The named exception to the contract (#987): the runtime reads only v4.** `version: 2` or `version: 3` throws `TASK_SCHEMA_VERSION_UNSUPPORTED`, and a declared `version: 4` document whose `schedule[]` still carries 0.9.15's retired `enabled` key throws `TASK_SOURCE_INVALID`; both messages name `akm migrate apply`, the one place the conversion happens (`scripts/akm-migrate/migrate/task-files.ts`, planning every v2/v3/v4 file straight to v4 with the pure planner `src/tasks/source/task-to-v4.ts`, rewriting under a backup; `akm upgrade` runs it after an install). It covers every stash the runtime reads tasks from: each enabled configured bundle, and the stash `AKM_BUNDLE_DIR` selects when no bundle names it; the `akm-task` probe still recognizes a root of v2/v3 task files, so one without a recorded adapter is found. Every caller reports the refusal for that one file: `akm task sync` keeps reconciling every other task and leaves the file's installed row as it is | Any other `version` throws `TASK_SCHEMA_VERSION_UNSUPPORTED` naming `akm migrate apply` | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/integration/previous-release-corpus.test.ts` (each older shape is refused at runtime and converted by the migrator) |
-| Workflow IR (frozen plans) | `src/workflows/freeze/freeze.ts`, read back in `src/workflows/runtime/run-plan.ts` (`readRunPlan`, `decodeWorkflowPlan`) | `irVersion` (`WORKFLOW_PLAN_VERSION`, 6) on the plan and in `plan_ir_version`; `plan_hash` alongside | Every workflow compiles to one plan type. `decodeWorkflowPlan` reads the irVersion 4 and 5 shapes (their `sourceReadSet` and host-identity fields included) as well as the current one, and keeps keys it does not know. Neither the version nor the hash gates a read: a stored plan that decodes runs whatever `irVersion` froze it, with one warning; one that cannot be decoded is abandoned by `akm workflow run` (status `failed`) with a message naming `akm workflow run <ref>` to start afresh — a status change, never an exception; `status`/`list`/`abandon` never read the plan | A newer akm's plan that still decodes runs the same way; one that does not decode is left untouched and refused with a message naming "Upgrade akm" (`readRunPlan`'s `newer`) | `tests/workflows/run-plan.test.ts`; `tests/integration/workflows/frozen-plan.test.ts` — the rehearsal builds no workflow run |
+| Task source (`tasks/*.yml`) | `src/tasks/source/parse-task-source.ts` | `version: 4` (`TASK_SOURCE_V4_VERSION`) | **The named exception to the contract (#987): the runtime reads only v4.** `version: 2` or `version: 3` throws `TASK_SCHEMA_VERSION_UNSUPPORTED`, and a declared `version: 4` document whose `schedule[]` still carries 0.9.15's retired `enabled` key throws `TASK_SOURCE_INVALID`; both messages name `akm migrate apply`, the one place the conversion happens (`scripts/akm-migrate/migrate/task-files.ts`, planning every v2/v3/v4 file straight to v4 with the pure planner `scripts/akm-migrate/migrate/task-to-v4.ts`, rewriting under a backup; `akm upgrade` runs it after an install). It covers every stash the runtime reads tasks from: each enabled configured bundle, and the stash `AKM_BUNDLE_DIR` selects when no bundle names it; the `akm-task` probe still recognizes a root of v2/v3 task files, so one without a recorded adapter is found. Every caller reports the refusal for that one file: `akm task sync` keeps reconciling every other task and leaves the file's installed row as it is | Any other `version` throws `TASK_SCHEMA_VERSION_UNSUPPORTED` naming `akm migrate apply` | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/integration/previous-release-corpus.test.ts` (each older shape is refused at runtime and converted by the migrator) |
+| Workflow IR (frozen plans) | `src/workflows/freeze/freeze.ts`, read back in `src/workflows/runtime/run-plan.ts` (`readRunPlan`, `decodeWorkflowPlan`) | `irVersion` (`WORKFLOW_PLAN_VERSION`, 6) on the plan and in `plan_ir_version`; `plan_hash` alongside | Every workflow compiles to one plan type. `decodeWorkflowPlan` reads the irVersion 5 shape 0.9.15 and 0.9.16 wrote (its `sourceReadSet` and host-identity fields included) as well as the current one, and keeps keys it does not know. Neither the version nor the hash gates a read: a stored plan that decodes runs whatever `irVersion` froze it, with one warning; one that cannot be decoded is abandoned by `akm workflow run` (status `failed`) with a message naming `akm workflow run <ref>` to start afresh — a status change, never an exception; `status`/`list`/`abandon` never read the plan | A newer akm's plan that still decodes runs the same way; one that does not decode is left untouched and refused with a message naming "Upgrade akm" (`readRunPlan`'s `newer`) | `tests/workflows/run-plan.test.ts`; `tests/integration/workflows/frozen-plan.test.ts` — the rehearsal builds no workflow run |
 | Native scheduler rows (crontab, launchd plists, Task Scheduler) | `src/tasks/backends/cron.ts`, `launchd.ts`, `schtasks.ts`; the invocation grammar in `src/tasks/scheduler-invocation.ts` | The row's own invocation shape: current rows set their environment inline (a cron `VAR=value` prefix, a plist `EnvironmentVariables` entry, a PowerShell `$env:` assignment) — always `AKM_BUNDLE_DIR`, the syncing shell's working stash — and carry no `--scheduler-context`; 0.9.0 – 0.9.17-alpha.6 rows carry `--scheduler-context <descriptor>` holding the same values; older rows carry neither. A cron command over 1,000 bytes runs an akm wrapper script (`sh <log dir>/.akm-cron-wrapper-…sh`) that holds the same line | Every shape is listed and parsed (`parseScheduledInvocationArgv`; a spilled cron row from its wrapper script): a row inside akm's own `# akm:task` markers from before `--scheduler-context` (#881), and a `--scheduler-context` row, which keeps firing (the CLI applies its descriptor, below) until the next plain `akm task sync` rewrites it in place — an update that keeps the row's launcher and schedule, never an add or remove. The primary bundle proves a row by the `AKM_BUNDLE_DIR` it carries, inline or in its descriptor (#846); any other bundle owns rows by name. Rows that still carry the pre-0.9.17 workflow execution-evidence marker (`# akm:workflow-evidence` in the crontab, an `akm-workflow-evidence` plist comment or PowerShell literal) are listed like any other and rewritten once without it. Plain `akm task sync` keeps an installed row's own launcher (`installOptionsFor`, `src/tasks/scheduler-sync.ts`) and recomputes its environment; `akm task sync --rebind` repoints the launcher | A row inside akm's markers, `com.akm.task.` label namespace, or `\akm\` task folder whose argv this binary cannot parse (for example one a newer akm wrote) is not listed: sync leaves it alone unless an enabled source renders a row with the same native id, which then replaces it — the row is derived state and its source is the record. A crontab whose akm markers are malformed is refused unmodified (`parseBlocks`, `cron.ts`) | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`: the previous release's `--scheduler-context` rows fire under the candidate, then `task sync --dry-run` shows them only as updates); `tests/tasks-sync.test.ts` (`--scheduler-context` rows and spilled rows are updates, never adds) |
 | Scheduler-context descriptor (`$DATA/tasks/context/<sha256>.json`, written by 0.9.0 – 0.9.17-alpha.6) | No longer written: a row carries its own environment (#987). Read by `src/tasks/scheduler-invocation.ts` (`readLegacySchedulerContext`) | `version: 1`; the environment key set | When a row that names one fires, the CLI reads the file as plain JSON and applies its `AKM_*_DIR` keys and, in one written before 0.9.17, `PATH`; nothing else about the file (name, mode, owner, link) is checked. Sync reads its `AKM_BUNDLE_DIR` to attribute the row. A plain `akm task sync` that reconciles the row rewrites it without the argument; a row a sync leaves as it is (its source failed, a `--bundle` sync did not cover it) keeps naming the file | A key this binary does not know is ignored. A file that is gone or is not JSON fails the run with `INVALID_CONFIG_FILE` naming `akm task sync`; sync cannot attribute such a row to the primary bundle and leaves it in place, and `akm task prune` reports it as `invalid-context` | `tests/tasks-scheduler-invocation.test.ts`; `tests/integration/scheduler-context-launcher.test.ts`; upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`) fires the previous release's rows under the candidate before and after its plain `task sync` |
 | Proposal `metadata_json` | `src/storage/repositories/proposals-repository.ts` | No explicit version field; presence/absence of the `changes` key | Rows from before the `changes` key existed (~89% of archived rows on real installs) are treated as a known legacy gap — decoded with an empty change list rather than thrown (`proposals-repository.ts:47-56`). 0.9.17-alpha.9 adds a consolidate pair-pass `retire` proposal's `changes[0].op: "delete"` (no `after`, already a valid `FileChangeOp`) and its `retirement` / `retiredArchive` / `promotionSource` / `promotionSourceHash` metadata keys, plus the retirement continuity check's `retirement.continuityRisk` (rule R3, item 1) — a person can accept a proposal carrying it by id even though it is excluded from bulk accept; an older reader's `validatePresentMetadata` does not enumerate these keys, so it neither inspects nor rejects them — the row decodes with them silently absent, same as any other field an older release predates. 0.9.19 adds `reviewHistory` (the rejections `akm proposal reopen` undid, oldest first, each with its gate verdict) the same way: a proposal reopened by 0.9.19 and read by an older release is an ordinary pending proposal with its history absent, and that release drops the key if it rewrites the row. The quality judge's evidence, `scores` and `judgeReason`, is added inside the existing `gateDecision` object (Unreleased): an older reader's `validatePresentMetadata` checks only the gate fields it knows and carries the object through whole, so the evidence survives a rewrite by an older release unread. An older release also counts a pending proposal's age (retention expiry, `--older-than`) from `createdAt`, so after a downgrade a reopened proposal can expire at the next `akm improve` run (a retire proposal never expires), or be swept by a scheduled `--older-than` bulk action or drain | 0.9.17-alpha.8 and earlier predate the retire proposal shape entirely — they were never taught to read a delete-primary change with no `after`. `akm proposal show` / `diff` / `drain` exit 70 on one, and drain's own nightly pre-pass failing on the first pending retire proposal it meets stops that run's auto-promotion for the whole stash, not just that one proposal. **Downgrade gate:** every pending retire proposal must be accepted or rejected (`akm proposal accept` / `reject`) before downgrading to 0.9.17-alpha.8 or earlier — once decided it is archived, out of the pending set `show`/`diff`/`drain` iterate, and no longer trips this. **Gap** otherwise (no code-level guard; this is operator guidance only). Downgrading also revives the starvation the second review round's B1 fixed forward-only: 0.9.17-alpha.8's `retrieval-scope.ts` counts a `consolidate-pair` ledger row as processed, so the pair pass's own nightly attempts crowd new material back out of every other improve lane's scope, the same way they did before B1 — measured on the real bundle, two alpha.9 nights left only 341 of 2,183 new-only assets still in scope once read under alpha.8. **Gap** here too (the ledger `source` string carries no version of its own; operator guidance only — do not downgrade across a pair-pass run without expecting this). | `tests/proposal-repository-pure.test.ts` — unit only; the rehearsal builds no proposal |

package/docs/architecture/specs/0.9.0-decisions.md

@@ -34,7 +34,7 @@ removing a half-built surface over shipping it behind a label.
 | D9 `--auto-accept` warn-and-ignore | **Shipped** (warns, and no longer poisons the scope positional) |
 | D10 extract migration machinery | Partial (`akm-migrate` bin exists; code still in-repo) |
 | D11 OKF foundational | Partial (the `okf` adapter has landed) |
-| D12 `placeNew()` wiring | **Deferred to 0.10** |
+| D12 `placeNew()` wiring | **Dropped in 0.10** (method removed; see [#1163](https://github.com/itlackey/akm/issues/1163)) |
 
 ---
 
@@ -491,7 +491,11 @@ without changing AKM-native refs or classification.
 
 ## D12 — `BundleAdapter.placeNew()` stays unwired until 0.10
 
-**Status: DEFERRED to 0.10.** The interface declares `placeNew(c, conceptId)`
+**Status: DROPPED in 0.10 (owner decision 2026-10-10).** `placeNew()` and its
+implementations were removed; nothing ever called them. Restoring per-adapter
+placement is only needed for writable bundles in a non-akm layout, tracked in
+[#1163](https://github.com/itlackey/akm/issues/1163). The text below is the
+0.9.0 record. The interface declared `placeNew(c, conceptId)`
 OPTIONAL (`src/core/adapter/bundle-adapter.ts`), and 8 of the built-in adapter
 modules already implement it — `generic-files`, `akm`, `llm-wiki`,
 `agent-skills`, `dotenv`, `akm-workflow`, `akm-task`, and the shared

package/docs/architecture/specs/improve-collapse-churn-detector-design.md

@@ -5,8 +5,8 @@
 > `scripts/refresh-canary-set.ts` were deleted with the improve ledger change
 > (migration 028 drops the tables); recorded telemetry shows no alert ever fired. The
 > generation and lexical-diversity merge checks, which never refused a merge,
-> went with it; only the random-cluster injection in
-> `src/commands/improve/anti-collapse.ts` remains. The history below is kept
+> went with it, and so did the random-cluster injection
+> (`consolidate.antiCollapse`, removed in 0.10, #1131). The history below is kept
 > for reference.
 >
 > **Earlier status:** Partially implemented. The COLLAPSE alert class (§1, three

package/docs/architecture/specs/workflow-format-unification.md

@@ -121,7 +121,7 @@ steps:
     map:
       over: steps.intake.output.issues
       concurrency: 3
-      unit: { isolation: worktree, retry: { max: 2, on: [timeout] } }
+      unit: { retry: { max: 2, on: [timeout] } }
     # `output` describes the REDUCER RESULT: the default `collect` reducer
     # folds per-item unit results into an array.
     output: { type: array }
@@ -131,11 +131,6 @@ steps:
   - id: verdict
     inputs: [steps.implement.output]
     output: { type: object }
-  - id: pick-outcome
-    route:
-      input: steps.verdict.output.status
-      when: [{ match: clean, step: announce }]
-      default: escalate       # both targets are LATER steps — routes are forward-only
   - id: escalate
     inputs: [steps.verdict.output]
   - id: announce

package/docs/architecture/testing/manual-testing-checklist.md

@@ -231,13 +231,12 @@ akm() { bun "$REPO/src/cli.ts" "$@"; }
 
 ### 3.2 Verify isolation before mutation
 
-`config path --all` is a read-only recovery surface and works before config
-exists.
+`info` is read-only and works before config exists.
 
 ```sh
-akm config path --all --format json >"$AKM_SANDBOX/paths.json"
+akm info --format json >"$AKM_SANDBOX/paths.json"
 jq -e --arg root "$AKM_SANDBOX/" \
-  'all(to_entries[]; (.value | tostring | startswith($root)))' \
+  '[.bundleDir, .configDir, .dataDir, .cacheDir, .stateDir] | all(startswith($root))' \
   "$AKM_SANDBOX/paths.json"
 ```
 
@@ -370,7 +369,7 @@ Copy this only after exact ranking assertions:
 cp -R "$REPO/tests/fixtures/manual-qa/bundle/." "$AKM_BUNDLE_DIR/"
 akm index
 akm show knowledge/qa-guide | jq -e '.name == "qa-guide"'
-akm show workflows/typed-route | jq -e '.type == "workflow"'
+akm show workflows/typed-params | jq -e '.type == "workflow"'
 akm show tasks/manual-success | jq -e '.type == "task"'
 ```
 
@@ -536,7 +535,7 @@ for command in \
       or `propose`.
 - [ ] **[CORE]** Bare `akm` and `akm help` print the sectioned overview without
       reading or rewriting invalid config.
-- [ ] **[CORE]** `help agents`, `help agents --full`, `hints`, and
+- [ ] **[CORE]** `hints` and
       `hints --detail brief` are nonempty and have the expected relative detail.
 - [ ] **[LOCAL]** `help bundle|env|secret|workflow|task|proposal` agrees with the
       corresponding `--help` command tree.
@@ -598,9 +597,8 @@ test ! -s "$AKM_SANDBOX/silent.out"
       never materialize values.
 - [ ] **[LOCAL]** Concurrent independent `config set` processes preserve both
       changes or one fails cleanly; JSON stays valid and no temp file remains.
-- [ ] **[LOCAL]** `config path --all` honors output formatting. Bare
-      `config path` is a raw path primitive; if format/output are ignored it
-      must warn explicitly. Silent ignoring is a failure.
+- [ ] **[LOCAL]** Bare `config path` is a raw path primitive; if format/output
+      are ignored it must warn explicitly. Silent ignoring is a failure.
 
 ### 6.5 Help migration notes
 
@@ -810,9 +808,9 @@ grep -qi '<html' "$AKM_SANDBOX/info.html"
 ### 8.3 Shape, detail, and output destination
 
 - [ ] **[CORE]** Brief/normal/full increase detail without identity drift.
-- [ ] **[CORE]** Summary succeeds only on show; all other commands reject it
-      before side effects with exit `2`, `INVALID_SHAPE_VALUE`.
-- [ ] **[LOCAL]** Agent shape keeps action fields and strips non-action metadata.
+- [ ] **[CORE]** `--shape` is an unknown flag on every command: it exits `2`,
+      `UNKNOWN_FLAG`, before side effects.
+- [ ] **[LOCAL]** `--detail agent` keeps action fields and strips non-action metadata.
 - [ ] **[LOCAL]** `show --format md --output <file>` writes file, empty stdout.
 - [ ] **[LOCAL]** Output replacement is atomic; unwritable/directory target does
       not truncate existing content.
@@ -837,7 +835,7 @@ expect_error 1 ASSET_NOT_FOUND show skills/does-not-exist
 expect_error 2 UNKNOWN_FLAG info --totally-bogus
 expect_error 2 INVALID_FORMAT_VALUE info --format xml
 expect_error 2 INVALID_DETAIL_VALUE info --detail maximum
-expect_error 2 INVALID_SHAPE_VALUE search docker --shape summary
+expect_error 2 UNKNOWN_FLAG search docker --shape agent
 expect_error 2 MISSING_REQUIRED_ARGUMENT help migrate
 expect_error 2 INVALID_FLAG_VALUE completions --shell zsh
 ```
@@ -1618,7 +1616,7 @@ akm lint --type workflows --fail-on-flagged
 
 - [ ] **CORE** Create-print emits raw valid Markdown and writes nothing.
 - [ ] **CORE** Create-from writes/indexes valid workflow with preamble and exact sections.
-- [ ] **LOCAL** Flat name plus safe path creates hierarchy; slash/traversal/duplicate step/missing section/unknown route/invalid params fail before write.
+- [ ] **LOCAL** Flat name plus safe path creates hierarchy; slash/traversal/duplicate step/missing section/invalid params fail before write.
 - [ ] **LOCAL** Existing workflow requires force plus from/reset; force alone fails.
 - [ ] **LOCAL** Lint catches structure without rewriting valid prose.
 - [ ] **CORE** A schema keyword outside the enforced subset (`format`, `pattern`,
@@ -1638,11 +1636,11 @@ akm lint --type workflows --fail-on-flagged
 
 ### 14.2 Typed params and partial run without an engine call
 
-The `typed-route` fixture executes a route-only first step. `--max-steps 1`
+The `typed-params` fixture's first step is an exec unit (no engine). `--max-steps 1`
 tests parameter parsing and durable run creation without agent/LLM dispatch.
 
 ```sh
-akm workflow run workflows/typed-route \
+akm workflow run workflows/typed-params \
   --include_processes=true --count 2 \
   --labels api --labels worker --max-steps 1 \
   > "$AKM_SANDBOX/typed-run.json"
@@ -1664,7 +1662,7 @@ jq -e '
 - [ ] **LOCAL** Params supplied to active run fail because creation-only.
 - [ ] **LOCAL** Invalid max-steps values fail; bounded partial exits `0`, remains active.
 - [ ] **LOCAL** `--max-steps` counts **finished spine steps**: a step's whole
-      bounded gate loop counts as one, and a route-skipped step consumes none.
+      bounded gate loop counts as one.
       It does not bound the dispatches inside a single step's gate loop — pair
       it with `budget.max_units` when that is what you need capped.
 
@@ -1672,8 +1670,8 @@ jq -e '
 
 ```sh
 akm workflow status "$QA_RUN_ID"
-akm workflow status workflows/typed-route
-akm workflow list --active --ref workflows/typed-route
+akm workflow status workflows/typed-params
+akm workflow list --active --ref workflows/typed-params
 akm workflow status "$QA_RUN_ID" --units
 akm workflow abandon "$QA_RUN_ID"
 akm workflow resume "$QA_RUN_ID"
@@ -1826,7 +1824,7 @@ Environment scope and context:
       **before** the spawn, naming the variable, rather than surfacing a raw
       `E2BIG`.
 
-`cwd` and isolation:
+`cwd`:
 
 - [ ] **LOCAL** `cwd` is relative and contained: absolute paths, drive letters,
       `~`, and `..` **segments** are rejected by the parser *and* the
@@ -1834,13 +1832,6 @@ Environment scope and context:
       base (symlinks included) immediately before the spawn.
 - [ ] **LOCAL** A directory whose *name* merely begins with dots (`..data`) is a
       legal contained `cwd` and must **not** fail `exec_cwd_escape`.
-- [ ] **LOCAL** Under `isolation: worktree` each unit gets a fresh detached
-      worktree; a clean one is gone once the step resolves, a dirty one is
-      retained and its path logged.
-- [ ] **LOCAL** When a dirty leftover is moved aside and the worktree then fails
-      to mint, the failure still reports **where the preserved work went**.
-- [ ] **DESTRUCTIVE** The stale-worktree sweep removes abandoned trees after
-      seven days but leaves a tree that is still in use by a live run.
 
 Gates, retry, and reuse:
 
@@ -2196,7 +2187,7 @@ akm improve skills/k8s-deploy \
 - [ ] **AI** Lock contention without skip is a transient error, exit `75` (`IMPROVE_LOCK_HELD`); `--skip-if-locked` exits `0`, reports `skipped.reason:"lock-held"`, and emits no `improve_invoked`.
 - [ ] **AI** Stale lock is reclaimed with an observable recovery event; active lock is never stolen.
 - [ ] **AI** Timeout/SIGINT/SIGTERM/SIGHUP persist one terminated run with redacted reason and release locks/children.
-- [ ] **AI** Default/quick/thorough/reflect-distill/consolidate/catchup/proactive-maintenance strategies enable exactly documented processes. Autonomy-gated mutations remain off without explicit experimental opt-in.
+- [ ] **AI** Default/consolidate/proactive-maintenance strategies enable exactly documented processes. Autonomy-gated mutations remain off without explicit experimental opt-in.
 - [ ] **AI** No sync/push occurs under explicit flags; git publication is tested separately only against disposable remote.
 - [ ] **AI** Credential/prompt/session values are absent from improve result, state DB, proposal provenance, health report, event stream, and logs.
 
@@ -3073,7 +3064,7 @@ and not a substitute for the full check.
 | Sources/registry/write-source | provider/write/publication suites, controlled service; LIVE git/npm/HTTPS when lifecycle changed |
 | Storage/migration/transactions | crash/concurrency/property/published-upgrade gates, section 19, destructive rehearsal for cutover changes |
 | Workflow | workflow unit/integration, gate fake agents, slow expansion, crash/contention when scheduler changed |
-| Workflow exec units / subprocess capture | section 14.5 end to end on an engine-less install, plus the worktree isolation and stale-sweep gates; any capture, timeout, or process-group change also runs the agent spawn suites, which share that subprocess layer |
+| Workflow exec units / subprocess capture | section 14.5 end to end on an engine-less install; any capture, timeout, or process-group change also runs the agent spawn suites, which share that subprocess layer |
 | Workflow child environment / allowlist | section 14.5 environment gates plus section 11; a change to the shared floor is native Windows, not Linux emulation |
 | Task/scheduler | task suites, Linux standalone; native macOS/Windows for backend/quoting/binding; published upgrade for schema changes |
 | Env/secret/security path/archive/network | env/secret plus traversal/SSRF/archive/redaction/dangerous-key suites, section 20 |