akm-cli 0.9.31 → 0.10.261002-beta

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` |
@@ -643,7 +643,7 @@ The JSONL file at `$CACHE/events.jsonl` is no longer read or written by akm.
 | `extract_invoked` | `akm proposal extract`, and improve's extract stage | `outcome` (no_candidates\|candidates_queued), `sessionId`, `harness`, `sourceRun`, `candidateCount`, `proposalCount` |
 | `extract_triaged` | the extract triage gate | `evaluated`, `passed`, `triagedOut`, `sourceRun` |
 | `schema_repair_invoked` | improve's schema-repair pass | `outcome` (queued\|error), `reason`, `proposalId`, `error` |
-| `stash_synced` | improve's end-of-run auto-sync | `committed`, `pushed`, `skipped`, `reason`, `attributed`, `unattributed` |
+| `stash_synced` | improve's pre-run and end-of-run sync | `phase`, `committed`, `pushed`, `skipped`, `reason`, `attributed`, `unattributed` |
 | `asset_state_gc` | improve maintenance: orphaned `asset_salience`/`asset_outcome` rows (ref `asset_state/_gc`) | `pending`, `collected`, `byTable` |
 | `events_purged`, `improve_runs_purged`, `task_logs_purged` | improve's retention pass (refs `events/_purge`, `improve_runs/_purge`, `task_logs/_purge`) | `purgedCount`, `retentionDays` |
 | `state_db_vacuumed`, `index_db_vacuumed` | the retention pass's VACUUM of `state.db`; `akm index` compacting `index.db` | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
@@ -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
 ```
@@ -1545,7 +1543,7 @@ akm feedback skills/k8s-deploy --negative \
 - [ ] **CORE** Negative feedback without a reason fails by default with `MISSING_REQUIRED_ARGUMENT`, exit `2`.
 - [ ] **LOCAL** Both signals, missing/nonexistent ref, malformed tag, and more than ten tags fail before durable mutation.
 - [ ] **LOCAL** `feedback.requireReason:false` produces the documented warning rather than the default hard failure.
-- [ ] **LOCAL** User feedback updates ranking immediately and reports `rankingUpdate.applied`; machine-origin signals do not impersonate user demand.
+- [ ] **LOCAL** User feedback updates ranking immediately and reports `rankingUpdate.applied: true`; machine-origin signals (`AKM_EVENT_SOURCE=improve`) report `applied: false` with a reason and do not impersonate user demand.
 - [ ] **LOCAL** Feedback survives full reindex and contains no credential fixture value.
 
 ### 13.2 Durable log and cursors
@@ -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 |