akm-cli 0.9.30 → 0.9.31

package/docs/architecture/specs/0.9.0-release-surface-review.md

@@ -0,0 +1,636 @@
+# 0.9.0 release surface review — v2 (reconciled action list)
+
+Supersedes v1 of this document. v1 was an end-to-end critical sweep of the
+user-facing surface (41 top-level commands, ~120 subcommands, ~230 flags, the
+Zod config schema, env vars, output contracts). v2 reconciles it with three
+inputs:
+
+1. **Owner corrections** — `--type` is free-form *by design*; the global
+   `--format` set must work on **all** commands with no bespoke shims;
+   migration code should live outside the main tool; test-only env vars should
+   not ship; `akm bundle` should be removed as duplicative; the `show` view
+   modes should be replaced by `#fragment` section addressing.
+2. **The improve-autonomy review** — do not gate the whole `akm improve`
+   feature; gate *autonomy* (direct mutation, auto-promotion) behind an explicit
+   opt-in, keep the feature and its schedules visibly alive. (Unattended push
+   was in this list originally; D8 leaves it ungated — see the outcome note in
+   C6.)
+3. **A verification pass** (8 parallel read-only audits of the tree) that
+   confirmed, refuted, or sharpened each claim. Two v1 claims were wrong and
+   are corrected below.
+
+**Corrections to v1:**
+
+- v1 said `AKM_DISABLE_PROJECT_CONTEXT=1` was the working escape hatch for the
+  broken `--no-project-context` flag. **False** — that env var is never read
+  anywhere in `src/` (it survives only in help text at
+  `src/commands/read/search-cli.ts:68` and comments). There is currently *no*
+  working way to disable the project-context boost. Same for
+  `AKM_DISABLE_SCOPED_UTILITY` (comments only).
+- v1 recommended validating `search --type` against a closed enum. **Wrong
+  direction** — `IndexDocument.type` is an open string by contract
+  (`src/core/adapter/types.ts:156-157`), the closed union was deliberately
+  deleted (`src/core/recognition-util.ts:71-77`), and adapters emit types
+  outside the placement set (`website`, `wiki-source`, open `pageKind`
+  values). The fix is documentation, not validation.
+
+Grouped by action. Ordering within groups is by cost-of-deferral.
+
+---
+
+## A. Fix — defects, before anything else
+
+### A1. `akm search --no-project-context` is a no-op, and there is no fallback
+
+`search-cli.ts:65` declares an arg literally named `no-project-context`; the
+parser's `--no-*` negation makes passing it identical to omitting it. With the
+env var confirmed dead (see corrections), the boost cannot be disabled at all.
+
+**Action:** declare `project-context` (boolean, default `true`) so
+`--no-project-context` works via native negation — the same pattern `sync
+--push/--no-push` already uses. Remove the dead `AKM_DISABLE_PROJECT_CONTEXT`
+mention from the help text (or implement it deliberately; pick one). Replace
+the current test (which only asserts the flag doesn't touch `process.env`)
+with one that asserts the boost is actually disabled.
+
+### A2. Fresh installs emit a fault-shaped warning on every search
+
+**Status: superseded by R-039 / X-RULING-9** — `semanticSearchMode` now
+defaults to `"off"` (`src/core/config/schema/*.ts`: `.default("off")`), so a
+bare/headless install no longer attempts semantic search or emits this
+warning at all; the interactive `akm setup` wizard still pre-selects it on,
+with the download warning moved ahead of the prompt. The finding below is
+kept as the evidence record for the default that motivated the ruling.
+
+Verified end-to-end at the time: `semanticSearchMode` defaulted to `auto`
+(`config.ts:108`); with no embedding configured the implicit local-transformers
+path fails (optional dependency, or offline), `verifyIndexState` writes
+`blocked` (`indexer.ts:1699-1715`), and every subsequent search for 24h-cycles
+emits *"Semantic search is currently blocked … until the semantic backend is
+healthy again"* (`db-search.ts:222-226`) — describing a fault when the state
+is "not configured".
+
+**Action:** split the `blocked` branch at `db-search.ts:196-226` on the same
+predicate the `pending` branch already uses (`!config.embedding?.endpoint ||
+!config.embedding?.model`, line 205):
+
+- **Unconfigured** → no warning (or the existing actionable #480-style note:
+  configure `embedding` or set `semanticSearchMode off`). The out-of-box
+  `warnings` array must be empty/stable for scripted consumers.
+- **Configured-but-failing** → keep the warning, enriched with the status
+  ledger's `reason`/`message` (already in scope, currently discarded) and the
+  retry instruction.
+
+### A3. `--type` help text: document free-form, stop implying an enum
+
+Types are an open set by design (see corrections). But the help enum on
+`search`/`curate` lists 10 of the 13 placement types (omits `task`,
+`session`, `fact`), omits `instruction`, and omits the entire adapter-defined
+space; `cli-hints-full.md:21` repeats the stale list; completions only
+complete placement types.
+
+**Action:** rewrite the `--type` description on `search` and `curate` (and
+`cli-hints-full.md`): *"Asset type filter. Built-in types: skill, command,
+agent, knowledge, workflow, script, memory, env, secret, lesson, task,
+session, fact, instruction — or any adapter-defined type (e.g. `website`,
+`wiki-source`, a wiki `pageKind`). Matching is exact; an unknown type returns
+no hits. Default: any."* No validation added — a typo returning zero hits is
+the documented contract of a free-form filter.
+
+---
+
+## B. One output contract — every global format on every command
+
+Owner direction: `json|jsonl|yaml|text|md|html` must all work on all commands;
+no bespoke shims. The verification pass mapped the full gap: 37 commands
+silently emit JSON under `--format text`; `md` silently emits JSON everywhere
+except `health`; `html` throws everywhere except `health`; `jsonl` is per-item
+only for `search`; ~10 surfaces bypass `output()` entirely.
+
+### B1. Registry-driven renderers with generic fallbacks
+
+The infrastructure exists — the shapes and text registries already follow the
+exact pattern (`src/output/shapes.ts:78-99`, `src/output/text.ts:104-133`).
+
+**Action:**
+- Add md and html renderer registries mirroring shapes/text. `output()`
+  becomes a uniform lookup: shape → (registered renderer ?? generic renderer
+  for that format) → `deliverRendered`. The `html` throw and the silent `md`
+  JSON fallback in `shared.ts:201-215` both disappear.
+- **Generic md renderer:** key-value table for flat fields, md table for the
+  envelope's dominant array field, fenced JSON for nested objects.
+- **Generic html renderer:** one `generic.html` template (styled shell around
+  the md rendering). `resolveTemplatePath`/`escapeHtml` already exist.
+- **Generic text fallback:** route `formatPlain`'s `null` branch through the
+  generic md renderer instead of pretty JSON — closes the 37-command text gap
+  in one move.
+- **jsonl list-awareness:** replace the `search`-only special case
+  (`text.ts:138-148`) with a declared per-shape list field (per-item lines +
+  `_kind:"trailer"` envelope line — the precedent `log tail` already ships).
+- **health** keeps its rich html/md output by *registering* its renderers
+  (moving `renderRunsDetailMd`/`renderWindowCompareMd` and the ECharts
+  template behind the registry); the pre-`output()` intercepts in `cli.ts`
+  are deleted. The report layout is presentation, not contract.
+- Snapshot test: every command × 6 formats produces non-empty output with the
+  expected leading bytes.
+
+### B2. Remove `akm graph export --format`
+
+Verified clean: the local flag already leaks into the global mode (one token,
+two parsers), the two payload formats map 1:1 to the global values with the
+same defaults, and payload (`--out` file) vs envelope (stdout) never collide.
+
+**Action:** delete the local arg; the export handler reads
+`getOutputMode().format`; keep a UsageError for payload formats other than
+`json|jsonl`. This also removes the last subcommand-declared `format:` arg —
+which is what forced the citty workarounds in `sync` and `env unset`
+(`sources-cli.ts:214-256`, `env-cli.ts:470-482`); delete those too.
+
+### B3. Migrate raw-stdout bypasses onto `output()`
+
+`config path` (bare), `config validate` success strings, and `migrate
+status|apply` (`console.log(JSON.stringify(plan))`, unshaped, unstamped)
+bypass the envelope entirely; `env path`/`secret path` print a raw scalar and
+ignore `--format json` (breaking `| jq` pipelines).
+
+**Action:** give each a passthrough shape and route through `output()`. Path
+commands keep raw-scalar output in `text` mode; gain `{path}` envelopes under
+json/yaml/jsonl. (Payload *values* of env/secret remain excluded from
+structured output — that security contract is untouched.)
+
+### B4. Declare the format-exempt set
+
+Some surfaces are exempt *by nature*: `completions` (output is a bash
+program), `env run`/`secret run`/`agent` child stdio, the interactive `setup`
+wizard branch, and document payloads (`workflow template`, `hints`,
+`help migrate`).
+
+**Action:** a `FORMAT_EXEMPT_COMMANDS` set in `src/cli/shared.ts` that (a)
+emits a stderr note when a non-default `--format` is passed to an exempt
+command, (b) generates the exemption table in `docs/reference/cli.md`, and
+(c) powers a test asserting every command is either exempt or 6-format
+capable.
+
+### B5. Cleanup that falls out
+
+Widen `OutputConfigSchema.format` to the full six values (users currently
+cannot persist `jsonl|md|html`); delete the vestigial `distill`/`reflect`
+shape+text registrations (no `output()` call sites exist); delete the
+doc-only local `format:` arg declarations on search/curate/show with their
+stale enums; fix the stale "fall back to YAML" comments.
+
+---
+
+## C. Remove — deletions while 0.9.x still permits them
+
+### C1. Remove `akm bundle` (list/show/items)
+
+Owner decision, and verification confirmed it is cheap: undocumented in
+`docs/reference/cli.md`, absent from STABILITY.md, zero consumers outside its
+own CLI file and one test.
+
+**Action:** delete `src/commands/bundle/` and the three passthrough shapes.
+Preserve the unique data additively on `akm list` (a passthrough shape, so
+all additive): `default` marker + top-level `defaultBundle`, the desired
+source descriptor (`kind`/`locator`/`maxPages`), `registryId`, the full lock
+block (`resolvedRevision`/`integrity`/`manifestDigest`/`adapterIds`/
+`installedAt`), `components`, and per-bundle `itemCount`/`byType` (one
+`getAllEntries` pass grouped by `bundleId`). Per-bundle item *enumeration*
+lands in C2. This also retires the pre-bundle `--kind local|managed|remote`
+vocabulary (rename values to the bundle model while touching it).
+
+### C2. Replace the `<type>:` browse grammar with conceptId-prefix browsing
+
+**Status: SHIPPED** (D4, ruled Q-02). `parseRefPrefixQuery` now accepts
+`bundle//`-qualified and bare conceptId-prefix slash forms; the colon
+grammar has no code path. See
+[the drift register](0.9.0-docs-code-drift-register.md#q-02--ref-prefix-browse-grammar-slash-decided-vs-colon-implemented)
+for the verified-live evidence.
+
+Three confirmed defects in the current grammar: it resurrects the singular
+`type:` spelling the release just removed; it validates against
+`placementTypes()` so adapter-defined types can never be enumerated; and it
+matches `namePrefix` against name-space while every displayed ref is in
+plural conceptId-space — copying a displayed ref prefix (`memories/projecta/`)
+into a query silently degrades to keyword FTS.
+
+**Action:** replace `parseRefPrefixQuery` with conceptId-prefix enumeration:
+`akm search "memories/"`, `akm search "memories/projecta/"`, and
+bundle-qualified `akm search "team//"` / `"team//skills/"`. This matches the
+canonical `bundle//conceptId` grammar, covers adapter types (their conceptIds
+are enumerable even when their type strings are foreign), and gives C1 its
+`bundle items` replacement (`akm search "team//"` = all items in bundle
+`team`). Also lift the empty-query rejection when `--source <bundle>` names a
+configured source, and document named `--source` in the flag table (today it
+is prose-only).
+
+### C3. Replace `akm show <ref> toc|section|lines|frontmatter|full` with `#fragment`
+
+Owner decision. One spec decision is required first, because the verification
+pass found the grammar is **stable-on-paper, rejected-in-practice**:
+STABILITY.md declares `[bundle//]conceptId[#fragment]` Stable, yet
+`parseRefInput` rejects every fragment at every input boundary
+(`resolve-ref.ts:263-269`), and the spec defines the fragment as an
+adapter-owned **export selector** (spec §11.3, `ref.md:24`) for the
+unimplemented Tier-B exports system — not a heading anchor.
+
+**Action:**
+1. **Write the spec decision:** for markdown-document assets the fragment
+   resolves to a heading (GitHub-style slug match over `parseMarkdownToc`
+   headings, falling back to case-insensitive raw heading text — today's
+   `extractSection` semantics). Fragments remain adapter-owned selectors
+   elsewhere; the two uses coexist per the spec's own "adapter-owned and
+   opaque to the core" language, but written down. Amend `ref.md`, spec
+   §11.3, and STABILITY.md.
+2. **Implement:** drop the fragment rejection on the `show` path (add
+   `fragment` to `AssetRef` or re-parse via `parseBundleRef` in show);
+   `akm show knowledge/guide#authentication` renders that section. An
+   unmatched fragment errors with the list of available fragment slugs —
+   this absorbs `toc`'s discovery role.
+3. **Delete** the whole view-mode apparatus: `normalizeShowArgv` + the
+   `process.argv` mutation in `cli.ts`, `SHOW_VIEW_MODES`, the hidden
+   `--akmView/--akmHeading/--akmStart/--akmEnd` flags, the `KnowledgeView`
+   threading, the renderer switch, and the view-only markdown helpers
+   (`extractLineRange`, `extractFrontmatterOnly`, `formatToc`;
+   `parseMarkdownToc` stays — it has non-view consumers). `full` is the
+   no-fragment default. `lines` is dropped (every response carries `path`;
+   callers can slice the file). `frontmatter` is dropped; if a raw-YAML
+   projection proves needed it returns later as a `--shape` value, which
+   STABILITY.md already designates as the projection axis.
+4. CHANGELOG migration note (the positional view grammar was a documented
+   Stable spelling; 0.9.x may break it, but it must be called out).
+
+### C3b. Remove `akm mv`
+
+> **Outcome: NOT ADOPTED.** `akm mv` ships in 0.9.0. The findings below stand —
+> they are what classifies the command **Experimental** and outside the
+> stability contract, and why the documented rename procedure is a plain
+> filesystem move plus `akm index` and `akm lint`. The removal action list and
+> the transaction-kind cleanup it prescribes are not being carried out. See
+> [D3 in the decision record](./0.9.0-decisions.md#d3--renames-are-delete--create-akm-mv-ships-experimental).
+> The rest of this section is the review as written.
+
+Reverses this document's earlier "gate it behind `experimental.mv`"
+recommendation. A dedicated review recommended removal; every load-bearing
+claim in it verified against the tree, and the decisive one is that this is a
+*correctness inversion*, not a rough edge — an experimental flag would ship
+silent content corruption to whoever opts in.
+
+Verified findings:
+
+- **Its primary integrity promise is inverted.** Spec §11.1 names the command
+  directly: *"Lint's missing-ref scan and `akm mv`'s inbound-xref rewriting
+  operate only on these anchored [`bundle//conceptId`] forms; bare short refs
+  in prose are not recognized as refs."* `buildRewritePatterns`
+  (`mv-cli.ts:167-186`) emits five patterns — three dead `type:name`
+  spellings and two bare-conceptId spellings — and **no `bundle//` arm at
+  all**. It rewrites exactly what the spec says is not a ref, and leaves
+  every real prose ref dangling. The code's own comment asserts the opposite
+  of the spec ("needs no arm here … always emitted SHORT").
+- **The reserved-file guard the spec requires of it does not exist.**
+  `ref.md:83-91` says item writes "(`placeNew`, **`akm mv`**, item
+  write-transactions) refuse a reserved-filename target". The validation
+  block (`mv-cli.ts:1205-1250`) checks cross-type, `.md` alias, empty name,
+  empty path segments, and the `.derived` suffix — there is no `index.md` /
+  `log.md` check anywhere in the file.
+- **It bypasses the bundle model**: seven hardcoded types
+  (`MV_SUPPORTED_TYPES`, `mv-cli.ts:104`), primary writable stash only, paths
+  reconstructed from type/name rather than resolved through the index.
+- **It can change bundle provenance**: the finalizing
+  `indexWrittenAssets(stashDir, …)` call omits `bundleId`
+  (`mv-cli.ts:1071`), so the indexer re-derives identity from the stash path
+  (`index-written-assets.ts:101-108`).
+- **Docs and code disagree on failure**: `cli.md:957-964` promises "the move
+  still succeeds" with warnings; the implementation throws after the
+  irreversible filesystem commit (`mv-cli.ts:1064`, `1078`).
+- **Cost**: 1,452 LOC plus ~2,190 LOC of tests, and two permanent entries in
+  the function-size ratchet (`run` 294 lines,
+  `withAssetMutationLease#arg1` 282) — for what its own originating spec
+  called "the highest-effort, lowest-frequency operation".
+
+**Action:**
+1. Delete the command, `src/commands/mv-cli.ts`, its tests, its hints, and
+   the `mv` event type.
+2. **Delete the `mv` transaction kind and the indexer's hook for it.**
+   `index-written-assets.ts:78-81` hardcodes
+   `recoverTxnsForRoot(stashDir, j => j.kind === "mv")` on *every* write-path
+   index refresh, and `requireKind` throws on an unregistered kind
+   (`fs-txn.ts:122-125`). Deleting `mv-cli.ts` removes the
+   `registerTxnKind("mv", …)` side effect while leaving the caller — so a
+   single leftover journal would hard-fail every subsequent index refresh.
+   Old journals are being ignored by decision, so: remove the hook, and make
+   `recoverTxnsForRoot` sweep unknown kinds instead of throwing.
+3. Document renames as delete + create: move the file, update intentional
+   refs, `akm index`, `akm lint`. The destination gets a fresh identity and
+   fresh learned state. Cross-bundle movement is copy/import + delete, never
+   identity-preserving.
+4. **Amend spec §11.2**, which currently says a rename "MUST use an explicit
+   state-rekey transaction" — that was a product choice made in the same
+   refactor, not an independent constraint (see D3 in the decision record).
+5. If real usage later shows that preserving learned state through renames
+   matters, reintroduce a narrow same-bundle `akm rename` built the right
+   way: resolve through the index, adapter-owned placement, qualified refs
+   only, rewrite only anchored `bundle//conceptId` forms, one old→new state
+   mapping, and rebuild derived index data rather than preserving row IDs.
+
+### C4. Remove `akm config enable|disable`
+
+A hardcoded alias for one vendor registry (`skills.sh`), currently listed
+Stable. **Action:** remove; the replacement is
+`akm registry add https://skills.sh` / `akm registry remove skills.sh`.
+
+### C5. Remove the undocumented `akm init --stashDir/--stash-dir` aliases
+
+They point at a config key 0.9.0 hard-rejects. **Action:** delete
+(`stash-cli.ts:73-75`).
+
+### C6. Move `upgrade --skip-checksum` off the flag surface
+
+A tab-completable way to disable integrity verification on a self-updating
+binary. **Action:** remove the flag; keep the recovery hatch as
+`AKM_UPGRADE_SKIP_CHECKSUM=1`, documented as internal.
+
+### C7. Split `akm add --allow-insecure`
+
+One flag authorizes two unrelated risks (plain-HTTP transport; installing
+bundles whose env keys — `LD_PRELOAD`, `PATH` — can hijack execution via
+`akm env run`). **Action:** `--allow-insecure-transport` and
+`--allow-dangerous-env-keys`, each gating only its own check.
+
+### C8. Scrub internal tracker IDs and retired-grammar examples from help text
+
+`"F-6:"` ×8, `"(F-3 / #384)"`, `"(F-4 / #385)"`, `"(#485)"`, `"(#22)"`,
+`"(v1 spec §4.2)"` in flag descriptions; `skill:akm-dream`,
+`memory:projectA/old-note`, `knowledge:auth-flow`, `npm:…//script:deploy.sh`
+examples in ~8 help strings that use the removed `type:name` grammar; the
+`stashDir` mentions in `init --set-default`, `setup --dir`, `config get`
+help. **Action:** one help-text sweep; goldens update.
+
+### C9. Env-var hygiene (the shippable subset of "eliminate test-only vars")
+
+Verified disposition — full elimination is not achievable (SIGKILL
+crash-recovery tests structurally require a real child process; the
+deterministic embedder exists for *cross-version* out-of-process benchmarks),
+but the surface shrinks a lot:
+
+- **Delete now:** `AKM_DEBUG_LLM` (one read, zero setters — fold into
+  `AKM_VERBOSE`); all mentions of the dead `AKM_DISABLE_PROJECT_CONTEXT` /
+  `AKM_DISABLE_SCOPED_UTILITY` (see A1); the stale `AKM_ECHARTS` comment.
+- **Replace with DI:** `AKM_ABLATE_CONTRIBUTORS` — the filter is already a
+  pure function; thread an option through `RankEntriesOptions` and delete the
+  env read (`ranking.ts:251`). Its claimed eval consumer doesn't use it.
+- **Compile out of release builds:** the three `AKM_TEST_MIGRATION_*`
+  crash/fault-injection hooks, via `bun build --define` (the same mechanism
+  as `AKM_VERSION`) — dev/test builds keep them, shipped binaries physically
+  lack them. (If D1 lands, they leave the core package entirely.)
+- **Keep but reclassify:** `AKM_FORCE_SETUP_TMP_STASH` is *not* test-only —
+  the production guard's error message instructs real operators to set it;
+  document as supported. `AKM_FORCE_INIT_TMP_STASH` is inert in production
+  (its guard only fires under a test runner) and is needed by spawned-CLI
+  tests; keep, documented internal. `AKM_EMBED_DETERMINISTIC`,
+  `AKM_CLAUDE_PROJECTS_DIR`, `AKM_NODE_ENTRY`, `AKM_EVENT_SOURCE`,
+  `AKM_SESSION_ID`/`AKM_AGENT_HARNESS` — internal-documented (H3).
+- Fix the stale `AKM_PROFILE_<NAME>_API_KEY` comment (the real pattern is
+  `AKM_ENGINE_<NAME>_API_KEY`).
+
+---
+
+## D. Extract — migration machinery out of the core
+
+### D1. Move apply/backup/restore into a separately published `akm-migrate`
+
+Owner direction, and the audit sized it: **~8,820 LOC of production migration
+code + ~7,130 LOC of tests/fixtures** ship inside every binary today, pinned
+to a one-time 0.8→0.9 cutover, spread across five surfaces (`akm migrate`,
+`akm backup` — which hard-rejects any `--for` value except the literal
+`0.9.0` — `akm config migrate`, the `akm-migrate-storage` bin, plus startup
+gates).
+
+**Action (target end-state):**
+- **Move to `akm-migrate` (own repo/package):**
+  `scripts/akm-migrate/migrate/**`, `scripts/akm-migrate/config-migrate.ts`,
+  `scripts/akm-migrate/migration-backup.ts`,
+  `scripts/migrate-storage.ts` + launchers, and the `migrate`/`backup`
+  command bodies, re-homed as `akm-migrate status|apply|backup|restore`.
+  Vendor the frozen legacy ref grammar's four live-core imports so it becomes
+  genuinely frozen.
+- **Core keeps (~1.6k LOC):** the pending-operation journal gate, the
+  migration-ledger inspect/assert + divergent-schema refusal, the config
+  hard-reject, the skew advisory, the vaults guard, `akm help migrate`
+  (release-notes rendering only), and ~40-line forwarder stubs: `akm migrate`
+  / `akm backup` detect state and either spawn `akm-migrate` from PATH or
+  print the exact `npx akm-migrate@<pinned>` line. Refusal messages are
+  reworded to name the external tool.
+- **Version-skew is the main hazard:** exact-pin peer dependency plus a
+  generation handshake (the migrate tool refuses a CLI whose migration
+  generation it doesn't match).
+- **Remove from core now regardless:** the `akm config migrate` alias, and
+  the `akm-migrate-storage` bin entry from `package.json` (its npm-only
+  precedent already exists — `install.sh` never shipped it).
+- **If the extraction doesn't make 0.9.0:** ship 0.9.0 with all five surfaces
+  declared *internal, removed at 0.10* in STABILITY.md and the CHANGELOG, so
+  the later removal is a documented plan, not a break. The extraction itself
+  can land in a 0.9.x patch (the series allows it).
+
+---
+
+## E. Improve — gate autonomy, not the feature
+
+Adopting the split model from the autonomy review; the lane audit confirmed
+its factual basis and added one item it missed. Verified direct-mutation
+lanes: **consolidate** (merge writes, archive+hard-delete of secondaries,
+`contradictedBy` frontmatter edges), **memoryInference** (`.derived.md`
+children + parent frontmatter rewrites), **memory cleanup / belief-state
+archiving** — which runs on *any* improve run covering memories, **not gated
+by any strategy flag at all** (`eligibility.ts:500-510`), **triage
+`applyMode: "promote"`** (real `writeAssetToSource` accepts; wired in
+`reflect-distill` and `proactive-maintenance`), **extract session indexing**
+(`indexSessions` default *on*, direct `sessions/**` writes), and **unattended
+sync+push** (`push ?? true`, enabled in 8 of 10 strategies). Reflect,
+distill, extract candidates, validation, and proactiveMaintenance selection
+are proposal-queued; graphExtraction touches only the regenerable index.
+
+### E1. `akm improve` stays on by default, review-first
+
+Keep the command, the default schedules, and the proposal-generating lanes
+(reflect, distill, extract, validation, proactiveMaintenance selection,
+graphExtraction) exactly as they are. No blanket experimental gate.
+
+### E2. One autonomy gate for the mutating lanes
+
+**Action:** a single config opt-in — `experimental.improveAutonomy: true`
+(mechanism per F1) — required for: consolidate's merge/delete/contradict
+operations (its memory→knowledge *promotion* proposals stay ungated), the
+memory cleanup + contradiction pre-pass, memoryInference's direct writes,
+triage `applyMode: "promote"` (including the judgment tier's accepts), and
+unattended **push** (commit stays; `push` default flips to `false` — an
+hourly cron job pushing to a remote is not a defensible default).
+
+> **Outcome note (D8):** the push half was NOT adopted. `sync.push` keeps its
+> `true` default and stays outside the gate — it publishes already-committed
+> content to a remote the user configured for that purpose, and it already has
+> `sync.push: false` and `--no-push`. The other five lanes are gated as
+> recommended. See D8 in the decision record.
+
+Ship an
+`experimental-autonomous` strategy that enables all of it with the existing
+guardrails (bounded triage ceilings, validators, protected refs, budgets,
+audit events); `reflect-distill` and `proactive-maintenance` keep their
+promote wiring but refuse to run it without the gate.
+
+Two deliberate scope notes: extract's `indexSessions` (additive-only
+`sessions/**` writes) and distill's salience frontmatter stamp
+(metadata-only) stay ungated but get documented as direct writes in H1.
+
+### E3. Never a silent no-op
+
+A scheduled run that hits a gated lane emits an `improve_skipped` event with
+the exact config key to set, surfaces in `akm tasks doctor`, and raises a
+health advisory. Existing 0.8-era schedules therefore keep running
+review-first and *tell* the operator what changed.
+
+### E4. `--auto-accept`: remove the retired flag
+
+The strict 0.9 runtime does not preserve a dead confidence-gate flag. Scheduled
+commands must remove it and use the explicit replacement when promotion is
+desired:
+
+```
+akm improve && akm proposal drain --promote --yes
+```
+
+(defaults: `personal-stash` policy, 25-accept ceiling), plus the config-only
+alternative (triage block with `applyMode: "promote"` — noting it drains the
+*standing* backlog, see E5).
+
+### E5. Close the same-run promotion gap
+
+Verified: triage runs only as a **pre-pass** before generation
+(`improve.ts:241-243`); with config-only triage, run N's proposals promote at
+the start of run N+1. The compound command above is currently the only
+same-slot shape. **Action:** add an opt-in post-generation drain
+(`triage.postPass: true` or `akm improve --drain`) sharing the same policy,
+ceilings, and gate — so the documented replacement doesn't need shell `&&`
+chaining to match 0.8 behavior.
+
+### E6. Setup: ask about schedules explicitly; align `--yes` with interactive
+
+Today interactive setup installs OS scheduler entries (hourly + 4-hourly
+LLM-calling improve jobs) with only a "server install?" question, while
+`--yes` installs none — materially different installs. **Action:** one
+explicit question — "Install scheduled maintenance tasks? (review-first;
+they queue proposals for your review)" — and `--yes` registers the same
+review-first task set (autonomous variants additionally require the E2
+gate). Upgrades: existing schedules continue review-first with the E3
+signposting; customized 0.8 profiles get a documented manual migration.
+
+### E7. Declare the tuning config experimental
+
+`improve.strategies.*.processes.*` (~60 fields, most commented "Default
+OFF" / "advisory in v1") and `index.*` (catchall pass names, retired-but-
+tolerated keys, "accept-any until Chunk 2" fields) are still being designed —
+the roadmap says so. **Action:** STABILITY.md declares both key families
+Experimental (droppable in any 0.9.x/0.10.x release); schema-reject or delete
+the already-deprecated `symmetricValence`. The `akm improve` *command*
+surface stays Evolving.
+
+---
+
+## F. Gate — one experimental mechanism for the half-built surfaces
+
+### F1. A single `experimental.*` config namespace
+
+Scattered "EXPERIMENTAL:" help-text labels gate nothing today. **Action:**
+one mechanism — `experimental.<feature>: true` config keys (settable via
+`akm config set`). An ungated invocation fails with a structured error naming
+the exact key (never a silent no-op, per E3). Features:
+
+- `experimental.workflowEngine` — `akm workflow run|brief|report|watch` and
+  YAML program creation (`workflow create <name>.yaml` currently routes users
+  onto the experimental engine from a stable verb; live `TODO(R2)` markers
+  remain in the engine). Classic markdown workflows and
+  `start/next/complete/status/list` stay stable and ungated.
+- `experimental.improveAutonomy` — E2.
+
+(`akm mv` was the third candidate here; C3b recommended removal instead. That
+recommendation was not adopted — mv ships classified Experimental, with the
+documented rename procedure routed around it. See D3 in the decision record.)
+
+`akm graph` needs no gate — it is read-only diagnostics — but gets classified
+Experimental in H1. `health --format html` is resolved by B1 (a registered
+renderer; layout documented as non-contractual).
+
+---
+
+## G. Unify — naming, while breaking is still cheap
+
+- **G1.** `--filter` (search) vs `--scope` (show) are the same multi-tenant
+  narrowing with identical syntax. Pick one spelling (recommend `--filter`);
+  alias-free.
+- **G2.** `--source` means "bundle name/path" on `graph` but
+  `stash|registry|both` on `search`/`curate`. Rename the latter axis to
+  `--from stash|registry|both`; named-bundle narrowing stays on `--source`
+  (documented, per C2).
+- **G3.** `--target` = write destination on write commands (keep), but
+  "bundle to operate on" on `tasks` (rename to `--bundle`). Positional
+  `target`s on `workflow`/`remove` are fine (positionals, different axis).
+- **G4.** `claude` vs `claude-code`: make the harness id `claude` canonical
+  everywhere; `extract --type` accepts both, docs use `claude`. Fix
+  `extract --auto`'s description ("every available harness" = 2 of 10
+  registered).
+- **G5.** Help-text spellings `--dryRun`/`--showSimilar` → `--dry-run`/
+  `--show-similar` (both parse already; the help is what gets scripted).
+- **G6.** Small polish, one pass: `curate --limit` default `"4"` → numeric
+  handling note; `hints --detail` shadowing the global flag with a different
+  default; bare `akm tasks` → keep the doctor default but document it.
+
+---
+
+## H. Document — make STABILITY.md whole
+
+- **H1.** Classify the twelve unlisted top-level commands (`health`, `graph`
+  (Experimental), `upgrade`, `registry`, `migrate`/`backup` (per D1:
+  internal, removal scheduled), `lint`, `extract`, `hints`, `completions`,
+  `init`) and every `env`/`secret` write verb. Note the two ungated direct
+  writes kept in E2's scope notes.
+- **H2.** Fix stale enumerations: agent backends (10, not 5), improve
+  strategies (10, not 5), the free-form type story (A3), every `stashDir`
+  and `type:name` mention (C8).
+- **H3.** ✅ **Shipped** — `STABILITY.md` § "Environment variables" now
+  carries a supported/internal-split table. **Add the env-var table:**
+  **supported** (`AKM_STASH_DIR`,
+  `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR`, api-key vars incl.
+  `AKM_ENGINE_<NAME>_API_KEY`, `AKM_VERBOSE`, `AKM_DEBUG`,
+  `AKM_NON_INTERACTIVE`, `AKM_REGISTRY_URL`, `AKM_NPM_REGISTRY`,
+  `AKM_SQLITE_JOURNAL_MODE`, `AKM_BIN`, `AKM_FORCE_SETUP_TMP_STASH`) vs
+  **internal, no compatibility guarantee** (`AKM_NODE_ENTRY`,
+  `AKM_EVENT_SOURCE`, `AKM_SESSION_ID`/`AKM_AGENT_HARNESS`,
+  `AKM_EMBED_DETERMINISTIC`, `AKM_CLAUDE_PROJECTS_DIR`,
+  `AKM_FORCE_INIT_TMP_STASH`, `AKM_STATE_DIR`, and — until compiled out —
+  `AKM_TEST_MIGRATION_*`).
+- **H4.** Make the ref-grammar entry truthful: `#fragment` is consumed by
+  `akm show` on markdown-document assets (heading slug) and reserved as an
+  adapter-owned selector elsewhere (per C3's spec decision); reconcile the
+  1.0-freeze line, which currently spells the grammar *without* the fragment.
+
+---
+
+## Suggested cut line for 0.9.0
+
+1. **A1–A3** — defects; A1 especially (there is currently *no* way to disable
+   the boost).
+2. **E2 + E3 + E4's warning text** — the autonomy gate and the no-silent-no-op
+   rule are the difference between "review-first by default" being true and
+   being marketing. E5/E6 can follow in 0.9.x.
+3. **C1–C3b** — the four structural removals (bundle, browse grammar, show
+   views→fragment, mv). Each gets dramatically more expensive after release;
+   C3 requires its one-paragraph spec decision first, and C3b must land its
+   txn-kind cleanup in the same change or the indexer breaks.
+4. **B1–B2** — the format contract. If the generic renderers slip, the
+   minimum bar is: uniform UsageError for unimplemented md/html (no silent
+   JSON), and the `graph export --format` removal.
+5. **C4–C9** — cheap deletions, all one-way doors after 0.9.x.
+6. **D1** — extraction can land in a 0.9.x patch, but the *declaration*
+   (migrate/backup internal, removal scheduled) must ship in 0.9.0's
+   STABILITY.md.
+7. **G, H** — naming unification and the docs pass close the release.