akm-cli 0.9.29 → 0.9.31

package/docs/architecture/specs/0.9.0-public-api-issue-backlog.md

@@ -0,0 +1,740 @@
+# Public API review — tracked issue backlog (v0.9.0-rc.10)
+
+Status: proposed — reconciled 2026-07-26 against the maintainer rulings on
+Q-01..Q-19. Items carrying a `> Ruled 2026-07-26 (Q-NN)` note below are
+settled, re-scoped, or partially cancelled by a ruling; where a ruling bears on
+an item, **the ruling is authoritative**.
+Source: implementation-only review of the CLI surface and code (documentation claims
+deliberately ignored). Line references are against the tree at the time of review
+and may drift; each item names the file and the observable behavior so it can be
+re-verified independently.
+Note: items below cite `docs/agents/AGENTS.md` / `AGENTS.full.md`. Those files
+were deleted during the 0.9.0 docs sweep — they fed nothing at runtime after
+R-006 and kept re-diverging from the embedded copy. Their still-true content
+now lives in `src/assets/hints/cli-hints-full.md` / `cli-hints-short.md`, which
+is what `akm hints` prints and what `loadHints` reads.
+Baseline: items were found against `a8464f2` and re-verified 2026-07-26 against
+the base branch `claude/0-9-0-release-review-bcjxxu` @ `453a0ba`, which has
+since fixed some of them. A further pass on 2026-07-27 @ `2d2edc1` (code
+identical to `453a0ba`) re-checked the contested items individually and added
+`> Status 2026-07-27:` notes where the tree disagrees with the item as
+written — including two items this register had over- or under-reported
+(R-004 fixed-in-surface; R-046 superseded by the D6 ruling). Items carrying a **Fixed / Reframed / Rejected on the
+base branch** note have been re-checked; the rest were not re-verified
+individually and may have been incidentally affected. See the
+"Implementation status against the base branch" table in the companion drift
+register for per-ruling status.
+Companion: `0.9.0-docs-code-drift-register.md` covers the docs-vs-code
+comparison this review deliberately excluded — including the intent questions
+(Q-01..Q-19) where the decision record and the code conflict. All 19 were ruled
+by the maintainer on 2026-07-26; see the **"Maintainer rulings — 2026-07-26"**
+table in that register for the authoritative direction.
+
+## Framing
+
+This backlog evaluates akm as what it has grown into: **a self-contained agent
+toolkit** — one CLI that gives AI agents the capabilities that normally require a
+stack of tools and a database server (indexed knowledge retrieval, secret/env
+management, harness-agnostic workflow execution and delegation, scheduling), while
+staying agent-, harness-, and content-format-agnostic (e.g. OKF alongside
+markdown).
+
+Under that identity, the env/secret manager, the workflow engine, the agent
+dispatcher, the OS-scheduler integration, and the improve loop are **in-scope
+features, not scope creep**, and no issue below asks for their removal. The
+identity instead raises the bar in three specific ways, and most of this backlog
+follows from them:
+
+1. **Agents are the primary consumers.** Machine-facing guidance (`akm hints`,
+   rendered command suggestions, help text, completions) is the product's API
+   documentation *and* its runtime behavior. Every place it misleads an agent is a
+   P0, not a docs nit.
+2. **The abstraction claims must hold at the seams.** "Harness-agnostic" and
+   "format-agnostic" are testable properties; half-wired normalizers and
+   format special-cases are gaps in the core value proposition.
+3. **An autonomous toolkit must be trustworthy by default.** Defaults that
+   schedule LLM rewrites, push git remotes, or mine other tools' session
+   transcripts need explicit opt-in or loud disclosure.
+
+Severity legend:
+
+- **P0** — the surface actively misleads its consumers, or an advertised path is
+  broken/unreachable.
+- **P1** — incorrect or surprising behavior/semantics; wrong results or side
+  effects.
+- **P2** — coherence, naming, and abstraction-seam debt.
+- **P3** — cleanup: dead code, stale comments, duplication.
+
+Counts: 9 × P0, 26 × P1, 21 × P2, 12 × P3 (68 tracked). The counts reflect the
+tier labels as written; two items carry ruling-driven re-tier recommendations
+not yet applied — R-045 (Q-18 makes it mandated feature work) and the `--format`
+half of R-050 (Q-04 makes it Stable-tier contract work, and the item should be
+split first). Recompute when those land.
+
+---
+
+## A. Agent-facing guidance correctness (P0)
+
+- **R-001 (P0) — `akm hints` documents a `wiki` command that does not exist.**
+  The short and full hints corpora instruct agents to run `akm wiki list`,
+  `akm wiki show <name>`, `akm wiki ingest <name>`, use `--type wiki`, and
+  `akm show wiki:<name>`. No `wiki` subcommand is registered in
+  `src/cli.ts:509-550`; an agent following the tool's own onboarding issues
+  failing commands. Either ship the command or strip it from
+  `src/assets/hints/cli-hints-*.md` and `docs/agents/AGENTS*.md`.
+  > Note (Q-02, ruled 2026-07-26): the quoted `akm show wiki:<name>` example
+  > uses the colon grammar Q-02 removes — the hints sweep hits these lines
+  > either way; if the wiki content is kept (ship-the-command path), its ref
+  > examples must move to the slash form.
+
+- **R-002 (P0) — `akm show --format text` renders copy-pasteable commands in the
+  retired `type:name` ref grammar.** `appendShowDirectives` builds
+  `` `${assetType}:${r.name}` `` and emits e.g.
+  `akm feedback 'knowledge:guide' --positive` (`src/output/show-directives.ts:26,57,75,87`),
+  which the 0.9 parser rejects. The same file renders `workflows/${name}`
+  correctly two lines down. Every APPLY footer suggestion currently fails when
+  executed.
+  > Ruled 2026-07-26 (Q-02): the colon grammar is removed entirely — no alias,
+  > no deprecation window — so re-accepting `type:name` in the parser is not a
+  > fix option. `appendShowDirectives` must emit slash refs (as it already does
+  > for `workflows/${name}`); include `show-directives.ts` in the Q-02 colon
+  > sweep alongside `search --help`, `akm hints`, and the ref-prefix tests.
+  > **Still open at base `0475870`** — and now strictly worse: Q-02 landed
+  > (the colon browse grammar is gone) while `show-directives.ts:26` still
+  > builds `` `${assetType}:${r.name}` ``. Raise with the Q-02 sweep.
+  > Status 2026-07-27: confirmed still open; the file now lives at
+  > `src/output/text/show-directives.ts` (`:26` builds the colon ref that
+  > `:37,57,75` interpolate into `akm feedback` suggestions). The fix is one
+  > line — build `assetRef` from the entry's conceptId (`workflows/${name}`
+  > two lines down shows the pattern) — plus refreshing the show-format text
+  > goldens that pin the footer.
+
+- **R-003 (P0) — `akm feedback` help contradicts the implementation.** Help
+  (`src/cli.ts` command description; `src/commands/feedback-cli.ts:189-206`)
+  states negative feedback "does NOT immediately lower the asset's ranking — run
+  `akm index` after". The code applies the EMA utility update unconditionally
+  and immediately for both signals (`feedback-cli.ts:170-176`). Fix the text or
+  the behavior — currently agents are told to run an unnecessary reindex.
+
+- **R-004 (P0) — feedback threshold hint references a nonexistent command.**
+  `feedback-cli.ts:365` prints "run `akm events list --type improve_review_needed`";
+  the command is `akm log`. (`events-list`/`events-tail` shape names and text
+  formatter headers carry the same retired name — see R-060.)
+  > Status 2026-07-27: ✅ **fixed in surface** — the printed hint no longer
+  > exists; `akm events list` survives only in two code comments
+  > (`feedback-cli.ts:341,365`). Downgrade to comment cleanup and fold into
+  > R-065; the R-060 shape-name half is unaffected.
+
+- **R-005 (P0) — the shipped conventions fact contradicts `akm mv`.** The
+  scaffolded `facts/conventions/organization.md` asset teaches "A rename is
+  delete plus create. There is no command that preserves an asset's identity or
+  learned state across one" and demonstrates raw `mv` + manual grep — while
+  top-level `akm mv` exists precisely to move the file, rewrite inbound refs,
+  and re-key the index row plus usage/salience history in place
+  (`src/commands/mv-cli.ts`). Agents reading the stash's own guidance will avoid
+  the safe command and hand-roll the dangerous procedure it automates.
+  > Ruled 2026-07-26 (Q-01): `akm mv` stays; D3 is superseded. The fix is
+  > one-directional — rewrite `facts/conventions/organization.md` and the other
+  > D3-side docs to teach `mv`, and add the missing Experimental tier entry for
+  > `mv` to STABILITY.md. Removing `mv` is off the table.
+
+- **R-006 (P0) — `akm hints` output depends on install method, and the copies
+  have drifted.** `loadHints` prefers `<pkgroot>/docs/agents/AGENTS[.full].md`
+  on disk and falls back to embedded `src/assets/hints/cli-hints-*.md`
+  (`src/commands/observability-cli.ts:240-257`). npm packs neither `docs/agents/`
+  nor `src/` (`package.json` `files`), so npm installs always get the embedded
+  copy while repo checkouts get `docs/` — and the two corpora already differ in
+  size and content. Single-source the corpus.
+  > Note (Q-02/Q-08, ruled 2026-07-26): both rulings mandate spelling sweeps of
+  > `akm hints` (colon→slash ref grammar; `env:`/`secret:`→slash) — land the
+  > single-sourcing first, or sweep both copies atomically, so the ruled
+  > changes don't re-drift the corpora.
+
+- **R-007 (P0) — advertised `owner/repo` shorthand is unreachable.**
+  `add-cli.ts:234` and `git-install.ts:489` advertise the form, but
+  `isPathLikeRef` returns true for any string containing `/`
+  (`src/registry/resolve.ts:298`), so `tryParseLocalRef` throws
+  `Local path not found` before the `parseGithubShorthand` fallback at
+  `resolve.ts:86-90` can run. The fallback is dead code; `akm add itlackey/akm-stash`
+  fails. Reorder the dispatch (try shorthand when the local path doesn't exist).
+  > Note (Q-19, ruled 2026-07-26): the resolver fix (`resolveSourcesForOrigin`
+  > matching `github:owner/repo` install refs) confirms install-ref shorthand is
+  > intended surface, so the fix direction here — reorder the dispatch, don't
+  > retire the advertised form — is sanctioned. Land both together so
+  > `show //meta`'s "Run: akm add …" hint chain works end to end.
+
+- **R-008 (P0) — `akm registry search` ignores registries added via
+  `akm registry add`.** `registry-cli.ts:128` calls `searchRegistry` without a
+  `registries` option; the fallback resolves `DEFAULT_CONFIG.registries`, never
+  the on-disk config (`src/commands/read/registry-search.ts:35,166`). Meanwhile
+  `akm search --source registry` passes `config.registries` and honors them.
+  Configured registries are listed by `registry list` but never searched by
+  `registry search`.
+
+- **R-009 (P0) — `akm search` rejects the empty query its own help advertises.**
+  The positional's description says "omit to list all assets"
+  (`src/commands/read/search-cli.ts:36-39`) but the handler throws
+  `MISSING_REQUIRED_ARGUMENT` for an empty query (`:79-86`), making the
+  `enumerateEntries` browse path reachable only via `<type>:` prefix queries or
+  queries that sanitize to empty. Allow the bare listing or fix the description.
+  > Note (Q-02, ruled 2026-07-26): the `<type>:` escape hatch named here is
+  > removed with the colon grammar; post-ruling the browse path is reachable via
+  > the slash forms (`memories/`, `bundle//`). The empty-query question itself
+  > is unaffected — update the parenthetical when Q-02 lands.
+
+---
+
+## B. Broken or surprising command behavior (P1)
+
+- **R-010 (P1) — the lockfile locks nothing.** `akm.lock` records
+  `resolvedVersion`/`resolvedRevision`/`integrity`, but the only field consumed
+  for behavior is `localRoot` (`src/integrations/lockfile.ts:122-130`).
+  `akm update` re-resolves the original ref (npm `latest`, git branch HEAD) and
+  overwrites the lock (`installed-stashes.ts:384`); nothing reproduces a locked
+  state; stored integrity is never re-verified. Either implement
+  lock-consumption (frozen installs, integrity re-check) or stop recording the
+  fields and drop the "lockfile" concept from the surface.
+
+- **R-011 (P1) — git/github installs have no integrity verification at all.**
+  `verifyArchiveIntegrity` returns early for git sources
+  (`src/sources/providers/tar-utils.ts:42`); the sha256 computed at install time
+  is stored and never compared.
+
+- **R-012 (P1) — corrupt lockfile fails silently open.** Unparseable JSON →
+  `return []`; malformed entries silently filtered (`lockfile.ts:99-106`). Every
+  managed bundle vanishes from `akm list` with no warning.
+
+- **R-013 (P1) — `akm add --provider` combinations are broken.**
+  `providerType` is honored only when the target is a remote URL
+  (`source-manage.ts:71-100`): `akm add lodash --provider npm` silently creates
+  a *filesystem* bundle at `./lodash`; `akm add <url> --provider npm` stores the
+  URL as an npm path that later resolves as a filesystem path
+  (`config-sources.ts:102-104`, `npm.ts:54-59`).
+
+- **R-014 (P1) — `akm add`'s two paths return two incompatible response
+  shapes.** Path A (`--provider`) returns `SourceAddResult`, Path B returns
+  `AddResponse`; the shared text renderer reads Path B fields and prints
+  `Installed undefined (0 directories scanned, 0 total assets indexed)` for
+  Path A (`output/text/command-format.ts:510-514`).
+
+- **R-015 (P1) — `akm update --all` silently skips plain (non-lock-backed)
+  sources.** `selectManagedTargets` returns lock-backed installs only
+  (`installed-stashes.ts:519-522`); a configured plain `git`/`website` bundle is
+  never refreshed by `--all` and must be named individually. Skip should at
+  minimum be reported.
+  > Note (Q-09, ruled 2026-07-26): the user-facing kind axis stays
+  > `filesystem`/`git`/`npm`/`website`, so the lock-backed "managed" split stays
+  > behavioral-only with no taxonomy surface — making the skip report asked for
+  > here the sole disclosure of it.
+
+- **R-016 (P1) — `akm setup --yes` silently skips 7 of 8 wizard steps.** Only
+  the `stash-dir` step sets `nonInteractive: true` (`setup/setup.ts:436`;
+  skip logic `setup/steps.ts:98`); embedding, llm, semantic-search, registries,
+  stash-sources, agent-cli, and output steps never run, while the call-site
+  comment claims defaults are applied (`setup.ts:776`). Also
+  `runSetupWithDefaults` hardcodes `online: false` yet still runs network
+  detection (`setup.ts:779,788`).
+
+- **R-017 (P1) — `akm setup --config/--from` silently drops five valid config
+  keys.** `ALLOWED_KEYS` (`setup.ts:1013-1027`) omits `index`, `search`,
+  `feedback`, `workflow`, `archiveRetentionDays` — all present in
+  `AkmConfigShape` — deleting them with only a stderr warn.
+
+- **R-018 (P1) — `akm curate --type` bypasses the entire curation algorithm.**
+  With an explicit type the result is `stashHits.slice(0, limit)` — no family
+  collapse, no intent nudges, no score floor (`curate.ts:255-262`). Two
+  qualitatively different products under one command name.
+
+- **R-019 (P1) — curate hard-caps registry results at 2 regardless of
+  `--limit`** (`curate.ts:264-265`), and the fallback path can issue up to 7
+  registry searches per invocation (`curate.ts:549-566`).
+
+- **R-020 (P1) — `akm show` drops the canonical `ref` from default and summary
+  output.** `showLocal` computes it, brief/summary builders include it, and the
+  shaper's `pickFields` allow-lists omit `"ref"` for human and summary shapes
+  (`output/shapes/helpers.ts:453-496`). Only `--shape agent` emits the one
+  identifier agents need for follow-up commands.
+
+- **R-021 (P1) — `--detail brief` behaves differently as a flag vs as config
+  default.** `showCommand` detects only the literal CLI token via
+  `getFlagValue("--detail")` to trigger `buildBriefResponse`
+  (`search-cli.ts:223-227`); config `output.detail: "brief"` reaches only the
+  shaper, which treats brief and normal identically. Same nominal level, two
+  payloads.
+
+- **R-022 (P1) — `akm index --dry-run` alone performs a full real index.** The
+  flag is only consulted inside the `--clean` branch (`indexer.ts:715-726`).
+
+- **R-023 (P1) — `akm index --background` claims to manage a PID file; none
+  exists.** The flag only suppresses the spinner and the final output
+  (`stash-cli.ts:95-99,127,157`) — the command still runs in the foreground and
+  prints nothing.
+
+- **R-024 (P1) — `akm graph update --source <bundle>` validates the name, then
+  extracts the primary stash anyway.** The validated result is discarded and
+  extraction always uses `sources[0]` (`graph.ts:529-538`,
+  `graph-extraction.ts:406`).
+
+- **R-025 (P1) — `akm config get <scalar>` returns secrets unredacted.**
+  `redactConfigValue` only redacts inside objects (`config-cli.ts:66`):
+  `akm config get embedding.apiKey` prints the literal value while
+  `akm config get embedding` redacts it. (Mitigated by write-time
+  sanitization, but the read surface is inconsistent.)
+
+- **R-026 (P1) — `akm env unset` argv workaround can silently drop keys.** The
+  positional filter removes any token equal to a global flag's *value*
+  (`env-cli.ts:474-482`), so unsetting a key literally named `json` while
+  `--format json` is set is a silent no-op; `--target` is wrongly included in
+  the global-flag list; the comment cites `cli.ts:1335` in a 666-line file.
+  > Status 2026-07-27: ✅ **fixed** (`0475870`) — the workaround is deleted
+  > outright. The root cause was citty parsing each command level against only
+  > its own declared args; `GLOBAL_OUTPUT_ARGS` now declares the global output
+  > flags on every leaf so their values are consumed by the parser, and keys
+  > literally named `json` unset correctly (verified end-to-end alongside the
+  > `sync --format json` case). See R-051's companion note.
+
+- **R-027 (P1) — `akm secret path`/`remove` can resolve to different files than
+  the read path for the same ref.** Reads use `findEnvSource` (all sources);
+  mutations use `resolveMutationTarget` (`core/env-secret-ref.ts:64-85` vs
+  `198-255`).
+
+- **R-028 (P1) — `akm import <url>`'s private-host allowance is gated on a
+  test-shaped predicate in production.** `allowPrivateHosts` defaults to
+  `shouldAllowPrivateWebsiteUrlForTests(source)` (`stash-cli.ts:256`,
+  `knowledge.ts:141-146`).
+
+- **R-029 (P1) — `akm backup` does not back up the stash.** Artifact set is
+  `config.json`, `state.db`, `workflow.db`, `index.db`
+  (`scripts/akm-migrate/migration-backup.ts:57-61`) — the markdown assets, env
+  files, and secrets are excluded. Additionally `--for` accepts only the literal
+  `"0.9.0"` (`backup-cli.ts:9-16`), and both `backup` and `migrate` hard-require
+  Bun on PATH under the supported Node install (`migration-tool.ts:21`). Rename
+  the command to match its migration-snapshot scope, or extend it to cover the
+  knowledge.
+  > Note (Q-14, ruled 2026-07-26): `backup` must receive a stability tier and
+  > either a cli.md section or an explicit internal listing — make the
+  > rename-vs-extend decision as part of that follow-through.
+  > Ruled 2026-07-27: **removed from the CLI** — neither renamed nor extended.
+  > `backup-cli.ts` deleted and the `backup` registration dropped; the
+  > capability remains at `akm-migrate backup` / `akm-migrate restore` (already
+  > present in that binary's surface). A cleaner backup story is deferred past
+  > 0.9.0. Migration guide + 0.9.0 release notes swept to the new spelling; the
+  > Q-14 tier question for `backup` is moot. ✅ landed same day.
+
+- **R-030 (P1) — `akm health` writes to the append-only event stream on every
+  run.** The state-db round-trip probe appends a `health_probe` event
+  (`health/metrics.ts:35-38`); CI polling accumulates rows indefinitely. Use a
+  transaction-rollback probe or a dedicated probe table.
+
+- **R-031 (P1) — `akm health --format html` overrides `--group-by`** (forces
+  `groupBy: "run"`, `cli.ts:341-360`) and runs the health computation twice with
+  a second window read — undocumented and inconsistent with the other formats.
+  > **Fixed on the base branch (`0475870`).** `akm health` no longer branches on
+  > `--format` anywhere: `--report` is now a data flag carrying runs/deltas/the
+  > pending-proposal queue in the envelope, the md/html renderers are pure
+  > functions of the result, `setHealthHtmlContext` is gone, and the html-only
+  > `--compare` was removed in favor of `--window-compare`. Breaking: bare
+  > `akm health --format html` renders the plain check generically — use
+  > `--report`. Verify and close.
+  > Follow-up in `453a0ba`: `--report` had been seeding `windowCompare` from
+  > `--since` unconditionally, so an absolute date/ISO/epoch `--since` reached a
+  > duration-only parser and threw, and an explicit `--windows` tripped the
+  > mutual-exclusivity guard. Precedence is now `--window-compare`, then a
+  > duration-valued `--since`, and nothing alongside `--windows`.
+
+- **R-032 (P1) — unknown-command handling is inconsistent with the exit-code
+  contract.** `akm totally-bogus` exits 1; `akm wiki list` prints top-level
+  usage and exits **0**; the CLI's own table says usage errors are exit 2.
+  Verified against the running CLI.
+
+- **R-033 (P1) — `akm feedback --tag` reads raw argv, including tokens after
+  `--`.** The declared citty arg is decorative; `parseAllFlagValues("--tag")`
+  scans the whole argv (`feedback-cli.ts:220,288`). Also `--applied-to` is a
+  silent no-op for non-lesson refs (`:397`).
+
+- **R-034 (P1) — feedback silently skips the ranking update for non-`user`
+  event sources.** With `AKM_EVENT_SOURCE` set to anything else — including
+  invalid values coerced to `"unknown"` — the usage event is recorded but the
+  utility score is untouched, with no output signal (`feedback-cli.ts:170`,
+  `usage-events.ts:31-35`).
+
+- **R-035 (P1) — the `AKM_NPM_REGISTRY` hint is false.** The env var only
+  widens the tarball-host allowlist (`resolve.ts:332-344`); metadata fetches are
+  hardcoded to `registry.npmjs.org` (`resolve.ts:375`), so installs from a
+  private mirror do not work despite the error hint saying they do
+  (`resolve.ts:322`).
+
+---
+
+## C. Trust and safety defaults (P1)
+
+- **R-036 (P1) — `akm setup` installs five cron/launchd/schtasks entries by
+  default** (hourly/4-hourly/nightly `akm improve` variants,
+  `commands/tasks/default-tasks.ts:51-92`), and embedded task templates add
+  `akm extract --auto` every 30 minutes. An OS-scheduler mutation deserves an
+  explicit, itemized opt-in step in the wizard and a flag in `--yes` mode.
+  > Ruled 2026-07-26 (Q-05/Q-14): `experimental.improveAutonomy` ships as
+  > STABILITY.md documents it, and `extract` is tiered Experimental. The
+  > scheduled `improve` entries must sit behind that off-by-default gate, and
+  > the embedded `akm extract --auto` template schedules an Experimental-tier
+  > command — implement the opt-in asked for here as the gate plus an explicit
+  > wizard step (and a flag in `--yes` mode).
+
+- **R-037 (P1) — `akm improve` commits and pushes the stash by default** for
+  git-backed stashes (`improve-cli.ts:145-154`). Combined with R-036 this means
+  a default setup schedules unattended LLM rewrites that push to a remote.
+  Default should be commit-only (or off) with push as explicit opt-in.
+  > **Rejected on the base branch (`84bba7a`, 2026-07-26)** — supersedes this
+  > item's recommendation and the earlier Q-05 note here. `sync.push` stays
+  > default-on and *outside* the autonomy gate: it publishes already-committed
+  > content to a remote configured for that purpose rather than mutating or
+  > deleting assets without review, and it already has two documented opt-outs
+  > (`sync.push: false`, `--no-push`). D8 gates five lanes — consolidate
+  > merge/delete/contradict, memory-cleanup and contradiction passes,
+  > memory-inference writes, and triage `applyMode: "promote"` — and `push`
+  > joins extract's session indexing as an ungated-by-design write. The R-036
+  > half (scheduling unattended runs) is unaffected and still stands.
+
+- **R-038 (P1) — `akm extract` mines other harnesses' private session
+  transcripts (claude-code JSONL, opencode storage) and sends content to the
+  configured LLM** (`improve/extract.ts`, `integrations/session-logs/`), with a
+  `--watch` mode that tails those directories indefinitely
+  (`extract-cli.ts:267-319`). Legitimate feature; needs first-run consent and
+  prominent disclosure given it reads data the user may not consider akm's.
+  > Ruled 2026-07-26 (Q-14): `extract` is tiered **Experimental** and must be
+  > documented (or explicitly listed internal) in cli.md. Land the first-run
+  > consent and prominent-disclosure requirements in that new STABILITY.md tier
+  > entry and reference section rather than as a standalone fix.
+
+- **R-039 (P1) — default `akm index` attempts an implicit ~130 MB embedding
+  model download.** With `semanticSearchMode: "auto"` and no endpoint,
+  `embedBatch` falls through to `@huggingface/transformers` →
+  `Xenova/bge-small-en-v1.5` (`llm/embedder.ts:158-176`). Failure downgrades
+  gracefully, but the download itself should be prompted.
+  > Ruled (owner ruling 9, X-RULING-9, `f04932f`): `semanticSearchMode` now
+  > defaults to `"off"` — a bare/headless install never attempts the
+  > download; the interactive `akm setup` wizard still pre-selects it on,
+  > with the download warning moved ahead of the prompt.
+
+- **R-040 (P1) — dynamic code loading from the stash.** Wiki snapshot fetchers
+  `import()` arbitrary `.ts`/`.js` from `<stashDir>/scripts/wiki-fetchers/`
+  (`sources/snapshot-fetchers/registry.ts:34-46`) — a code-execution surface
+  reachable from synced content. Should be gated by the same
+  third-party/first-party activation policy used for env keys. Related: the
+  built-in YouTube fetcher calls the private InnerTube API with a hardcoded key
+  impersonating the Android client (`snapshot-fetchers/youtube.ts:35-42`) —
+  fragile and worth an explicit support decision.
+
+- **R-041 (P1) — `akm graph export --out` writes anywhere with default 0644**
+  (`graph.ts:302-315`) while `akm env export` enforces 0600. Graph contents are
+  LLM-extracted from the user's knowledge; align the posture.
+
+---
+
+## D. Abstraction-seam gaps (P2) — where the agnosticism claims leak
+
+- **R-042 (P2) — harness result normalization is half-wired.** All harnesses
+  ship `result-extractor.ts` normalizers, but only the workflow native engine
+  consumes them (`workflows/exec/native-executor.ts:1259-1267`); `akm agent`,
+  `akm propose`, and reflect return raw harness stdout. Harness-agnosticism
+  currently holds only inside `workflow run`.
+
+- **R-043 (P2) — OKF is special-cased in `akm show`.** OKF-adapter entries
+  bypass the renderer registry for a hand-rolled markdown path
+  (`show.ts:369-370,545-586`). If format-agnosticism is the goal, OKF should go
+  through the same adapter/renderer seam as markdown assets.
+  > Ruled 2026-07-26 (Q-07): the parser half of this special-casing is settled
+  > — the ref-parser seam is fixed centrally so opaque conceptIds are accepted
+  > across graph, tasks, improve, proposals, the utility repo, and the indexer
+  > walk, removing `show`'s need to bypass `parseRefInput`. The
+  > renderer-registry half remains this item's ask and aligns with the ruling.
+  > **Largely fixed on the base branch (`453a0ba`).** `show`'s
+  > `indexedEntry?.adapterId === "okf"` branch became `usesIndexedProjection`
+  > (`read/show.ts:536-559`): OKF plus any indexed item whose type AKM does not
+  > place keeps its adapter's projection, so a `website` entry no longer comes
+  > back typed as AKM placement and a generic `file` no longer loses its
+  > content. OKF is still named explicitly — deliberately, since its `type` is
+  > open frontmatter and may collide with an AKM placement type — and
+  > `env`/`secret` stay pinned to the dotenv renderer so values are never
+  > dumped. What remains of this item is only that residual OKF name-check;
+  > the general seam now exists.
+
+- **R-044 (P2) — two disjoint secret systems; the toolkit doesn't dogfood its
+  own.** akm's LLM/embedding keys come from env vars or `$VAR` config refs
+  (`config.ts:437-444`) and cannot be supplied from `akm secret`. Letting config
+  reference `secrets/<name>` would close the loop and demonstrate the feature.
+  > Ruled 2026-07-26 (Q-08): slash spelling only, no colon alias — if config
+  > learns to reference managed secrets, the spelling must be the slash form
+  > `secrets/<name>` (e.g. `secrets/OPENAI_KEY`), not the `secret:NAME` form
+  > this item originally proposed.
+
+- **R-045 (P2) — the `instruction` asset type is half-registered.** It exists
+  in `KNOWN_TYPES`/`TYPE_PRESENTATION` but not `PLACEMENT_SPECS`
+  (`core/asset/asset-placement.ts:89-166` vs `core/recognition-util.ts:92-106`),
+  so it is invisible to `akm info`, unbrowsable via prefix queries, and its refs
+  don't round-trip. Register or remove it; add a compile-time exhaustiveness
+  check tying the two registries together.
+  > Ruled 2026-07-26 (Q-18): "register or remove" is settled — **register**.
+  > The two-registry split stays the core truth (`KNOWN_TYPES` = presentation
+  > vocabulary, `PLACEMENT_SPECS` = stash-resident subset), so the
+  > exhaustiveness check is a **subset** assertion (placement keys ⊆ known
+  > types), not equality. `instruction` gains a `PLACEMENT_SPECS` entry with an
+  > `instructions/` stash dir on the markdown spec, becoming creatable,
+  > browsable, and listed by `akm info` like knowledge; adapter-emitted
+  > `instruction` docs round-trip via the Q-07 opaque-conceptId fix. This is now
+  > mandated 0.9.0 feature work — **raise to P1**.
+
+- **R-046 (P2) — `--type` is unvalidated everywhere, and the help enumerates 11
+  of the 13 real types** (missing `fact`, `task`, `session`;
+  `search-cli.ts:41-43,125-127`). `--type bogus` silently returns zero hits.
+  Validate against `placementTypes()` and generate the help list from it.
+  > Note (Q-18, ruled 2026-07-26): `instruction` becomes a placement type,
+  > shifting the real-type count from 13 to 14 — a further reason to generate
+  > the help list and validation from `placementTypes()` rather than
+  > re-hardcoding.
+  > Status 2026-07-27: **superseded by the D6 decision** — the validation half
+  > of this item conflicts with a maintainer ruling this register missed.
+  > `type` is a free-form open string BY DESIGN (adapters emit `website`,
+  > `wiki-source`, OKF frontmatter types outside any placement list), so
+  > validating against `placementTypes()` would reject valid filters; D6 and
+  > `STABILITY.md`'s Stable-tier bullet both pin "deliberately not validated:
+  > an unrecognized type returns zero hits, not an error". The help half is
+  > already fixed: `search`/`curate` `--type` help now enumerates all 14
+  > built-ins **and states the set is open** (`search-cli.ts:43`). Nothing
+  > remains except keeping that string current — do not implement validation.
+
+- **R-047 (P2) — same concept, two flag names: `search --filter` vs
+  `show --scope`** for the identical `user=/agent=/run=/channel=` narrowing.
+  Pick one (keep the other as a hidden alias for one release).
+  > Ruled 2026-07-27: **unify on `--filter`, remove `--scope` with no alias.**
+  > ✅ landed same day: `show` declares `filter`, parses repeatable `--filter`
+  > through the same `parseScopeFilterFlags` helper as `search`; cli.md swept.
+  > The removed spelling fails loudly rather than silently un-narrowing —
+  > citty drops the unknown flag and its value lands in the positional slot,
+  > where `rejectExtraShowPositionals` raises exit 2 (pinned by a new CLI test
+  > in `scope-flags.test.ts`).
+
+- **R-048 (P2) — package identity: the npm description still says "package
+  manager".** Under the accepted toolkit framing this misstates the product to
+  its distribution channel and sets the wrong expectations for the verbs in §E.
+  Reposition the one-liner (`package.json:5`).
+
+---
+
+## E. Verb semantics and surface coherence (P2)
+
+- **R-049 (P2) — `update` / `upgrade` / `sync` are three unrelated operations
+  wearing package-manager names.** Refresh sources / self-update the akm binary
+  / git-commit-and-push the stash. Given the toolkit identity, consider
+  `akm self update` (or `self-upgrade`) and `akm stash sync` (or `save`) to
+  free the ecosystem-conventional meanings; `sync` still emits
+  `eventType: "save"` and `output("save", …)` from its retired name
+  (`sources-cli.ts:181-185`).
+
+- **R-050 (P2) — global flags that are mostly not global.** `--detail` is an
+  identity no-op for `init`/`index`/`info`/`import`/`remember` (and
+  brief==normal on `show`); `--format md|html` is accepted globally but valid
+  only for `health`; `--shape summary` only for `show`. Either scope the flags
+  to the commands that honor them in help output, or implement them uniformly.
+  > Ruled 2026-07-26 (Q-04): for `--format` the either/or is settled —
+  > implement basic support on every non-exempt command, with `text` and `md`
+  > collapsed into a single format, plus alignment of the persisted
+  > `output.format` schema and the `INVALID_FORMAT_VALUE` hint. Only the
+  > `--detail`/`--shape` halves of this item remain an open choice. Split the
+  > ruled `--format` work into its own item and **raise it to P1**: it is
+  > mandated Stable-tier contract work, not coherence debt.
+  > Status 2026-07-27: the "implement on every non-exempt command" half
+  > **landed** (D7: renderer registries, generic md/html fallbacks, declared
+  > exemptions in `format-exempt.ts`, `output.format` schema widened to six),
+  > but as SIX formats — the text/md collapse was not applied, and the
+  > `INVALID_FORMAT_VALUE` hint still lists four values (`errors.ts:111`).
+  > The Q-04 conflict in the drift register is the open decision; the hint
+  > fix is deferred until that call so it is corrected once, to the final set.
+
+- **R-051 (P2) — per-command `--format/--detail/--shape` declarations are
+  decorative.** Declared on `search`/`curate`/`show` but never read from
+  `args`; values come from the process-wide singleton (`search-cli.ts:63-64,
+  131-136`). Users see help entries for flags the handler ignores.
+  > **Reframed by the base branch (`0475870`).** The redundant declarations turn
+  > out to be load-bearing: citty parses each command level against only its own
+  > declared args, so a root-declared global was unknown at the leaf and its
+  > space-separated value fell through as a positional (`akm sync --format json`
+  > synced a bundle named "json"). `GLOBAL_OUTPUT_ARGS` now redeclares
+  > `--format`/`--detail`/`--shape`/`--output` on **every** leaf, parse-only,
+  > with the mode still read once from the invocation singleton
+  > (`cli/shared.ts:138-159`). The declarations are no longer decorative — this
+  > item is closed as fixed-by-design; only the help-text clarity ask remains.
+  > **Completed in `453a0ba`:** the first pass covered only `defineJsonCommand`
+  > leaves, so `improve`, `propose`, and `tasks run` (plain `defineCommand`)
+  > still had citty parse `--format` as a boolean and spill its value into the
+  > next positional — `improve --dry-run --format md` read "md" as the scope,
+  > `tasks run --format md nightly` lost the task id. Each leaf now declares
+  > the flags.
+
+- **R-052 (P2) — bash completions advertise wrong values.** `FLAG_VALUES`
+  offers `--detail … summary` (a `--shape` value that errors) and omits
+  `md`/`html` from `--format` (see the Q-04 note below); the table is keyed globally by flag name, so
+  `graph --source <TAB>` suggests search's `stash registry both`
+  (`commands/completions.ts:15-21`). The `completions` handler is also the only
+  one not wrapped in `runWithJsonErrors`, so a non-bash shell error surfaces as
+  `UNHANDLED_REJECTION`/exit 1 instead of a usage error/exit 2 (`cli.ts:449-452`).
+  > Ruled 2026-07-26 (Q-04): `text` and `md` collapse into a single format, so
+  > the accepted `--format` value set is changing — fix the completions table
+  > against the post-Q-04 set rather than adding `md`/`html` to today's list.
+
+- **R-053 (P2) — bare-group behavior is inconsistent three ways.**
+  `akm log`/`akm lessons` print help and exit 0; `akm backup`/`akm migrate`
+  throw usage errors (exit 2); `akm env`/`akm config`/`akm graph` run a default
+  action. Pick one convention.
+
+- **R-054 (P2) — `akm lessons` advertises "strength queries" that don't
+  exist.** The group description promises them (`observability-cli.ts:205`);
+  `lessonStrength` is written by feedback and read by ranking but not queryable
+  from any command. Implement `lessons strength <ref>` or fix the description.
+
+- **R-055 (P2) — reads are writes, undisclosed.** `search`/`show`/`curate`
+  append events, insert usage rows, and search bumps EMA utility scores —
+  running a search changes future rankings (`search.ts:393`). Legitimate design
+  for a learning index, but it should be stated on the command surface and
+  offer an opt-out (the internal `skipLogging` already exists).
+
+- **R-056 (P2) — `akm index` writes to `config.json`** (persisting detected
+  adapters via `mutateConfig`, `indexer.ts:600-622`). Surprising for an "build
+  the index" command; disclose or relocate to `add`/`setup`.
+
+- **R-057 (P2) — `akm info` omits the most basic facts.** No `stashDir`, no
+  `defaultBundle`, no per-type asset counts (`info.ts:64-78`); `searchModes`
+  reports semantic readiness from a cached status file, not a live probe; its
+  stats warning writes raw `process.stderr`, bypassing `--quiet`
+  (`info.ts:103`).
+
+- **R-058 (P2) — remove/update destructive-action asymmetry.** `akm remove`
+  prompts for confirmation; `akm update`, which can `rm -rf` the prior
+  materialized root (`installed-stashes.ts:421-428`), does not. Also removing a
+  plain git/website bundle leaves its mirror cache behind, and `akm clone` of an
+  unregistered origin downloads a full package into the cache with no bundle or
+  lock record (orphaned disk).
+
+- **R-059 (P2) — two parallel cache schemes for the same upstream.** Managed
+  installs key `getRegistryCacheDir()` by version/revision; plain git/website
+  mirrors key `getRegistryIndexCacheDir()` by URL hash — adding the same repo
+  both ways stores two copies.
+
+- **R-060 (P2) — `akm log` is still `akm events` internally.** Output shapes
+  `events-list`/`events-tail`, text headers, and the R-004 hint all use the old
+  name. Rename the shapes at the next schemaVersion bump.
+
+- **R-061 (P2) — argv is parsed in three layers with four workaround
+  patterns.** citty; the pre-citty `normalizeShowArgv` rewrite; the
+  `ParsedInvocation` raw-argv singleton for repeatable flags; plus ad-hoc
+  `process.argv.includes("--no-init")` and the `remember` positional-swallowing
+  heuristic that covers `--format`/`--detail` but not `--shape`/`--output`
+  (`remember.ts:303-370`). Consolidate on one parse or replace the framework —
+  each workaround has already produced user-visible bugs (R-026, R-033).
+  > Ruled 2026-07-26 (Q-03): `normalizeShowArgv` and the hidden `--akm*` flags
+  > it feeds are deleted with the show view modes, removing one of the four
+  > workaround patterns outright. Consolidate the remaining three; do not invest
+  > further in the pre-citty rewrite layer.
+  > Status 2026-07-27: two of the four are gone — `normalizeShowArgv` (Q-03)
+  > and the env-unset value filter (R-026, root-caused by
+  > `GLOBAL_OUTPUT_ARGS`). Remaining: the `ParsedInvocation` singleton (now
+  > load-bearing by design — the one-parse rule), ad-hoc
+  > `process.argv.includes` probes, and the `remember` positional-swallowing
+  > heuristic, which `GLOBAL_OUTPUT_ARGS` on the `remember` leaf may make
+  > deletable — verify against `remember.ts:303-370` before consolidating.
+
+- **R-062 (P2) — `--showSimilar` is the CLI's only camelCase flag**
+  (`remember-cli.ts:141-144`); everything else is kebab-case, and
+  `migrate apply` declares `dryRun` where the codebase convention is
+  `"dry-run"`.
+
+---
+
+## F. Cleanup batch (P3)
+
+- **R-063 (P3) — confirmed dead code.** `parseGithubShorthand` branch
+  (unreachable, see R-007); `injectIntoEnv` (`env.ts:115` — mutates
+  `process.env`, forbidden by its own module docstring); secret `listNames`
+  (`secret.ts:96`); `loadGraphMetaOnly` / `loadGraphEntitiesByPath`
+  (`graph-db.ts:343,403`); `parseConfigValue` shim and the unreachable
+  `toggleComponent` throw and dead `--list` flag (`config-cli.ts:44,129,136`);
+  `listStashes`/`SourceListResult` (`source-manage.ts:36-39`);
+  `resolveRegistries` on the search path (`registry-search.ts:35`); the
+  `semanticSearch` projection branch (`helpers.ts:290`); curate's
+  colon-grammar family regexes (`curate.ts:769,779`); the
+  `session-log-failures` advisory hardwired to pass (`checks.ts:464-482`);
+  `setup.taskSchedules` schema key nothing reads or writes.
+  > Note (Q-02, ruled 2026-07-26): curate's colon-grammar family regexes
+  > (`curate.ts:769,779`) are now part of the mandated colon-removal sweep —
+  > schedule their deletion with the Q-02 work, not as standalone cleanup.
+
+- **R-064 (P3) — dead fields threaded through live signatures.**
+  `IndexOptions.reEnrich` (flag removed, parameter still threaded three layers;
+  `stash-cli.ts:103-112`, `indexer.ts:179-183`); `IndexResponse.graphQuality`
+  (declared, never assigned); `acceptedActions` "always 0 since the 0.9.0
+  confidence-gate deletion" (`loop-stages.ts:746-750`); `durationMs` computed
+  then `void`-ed (`improve-cli.ts:359-360`); `SourceEntry.updatable` and
+  `.provider` set-but-never-read; `installedKitCount` (retired "Agent Kit
+  Manager" naming) still in the public JSON envelope of add/remove/update;
+  `workflow.db` still in the backup artifact set after the 0.9 state.db merge.
+
+- **R-065 (P3) — stale comments that assert the opposite of adjacent code.**
+  `init.ts:9` ("ensures ripgrep is available" — nothing uses ripgrep);
+  `info.ts:57-61` (claims to avoid the `getDbPath()` call it makes);
+  `graph-extraction.ts:34-37` (describes retired fs.writeFile storage);
+  `history.ts:11-15` (`events.jsonl` vs actual `state.db`); the four
+  `TODO(R2)` markers in `workflows/program/{parser,schema}.ts` and
+  `ir/compile.ts` describing gate loops / retry / isolation / schema validation
+  as unimplemented — all four are implemented in `native-executor.ts`;
+  `reflect.ts:6` / `distill.ts` / `consolidate.ts` headers documenting
+  `akm reflect` etc. as CLI commands that were never registered;
+  `metrics.ts:270-274` documenting a deleted metric; `setup.ts:776` (R-016).
+
+- **R-066 (P3) — duplicated logic.** Two secret-directory walkers
+  (`secret.ts:96-115` vs `secret-cli.ts:50-74`); `ACTIVE_RUN_WARN_MS` defined
+  twice (`health/types-result.ts:37`, `health/checks.ts:20`); the `--limit`
+  guard copy-pasted five times in `graph.ts`; `assertSetupSandbox` invoked
+  2–3× per setup path; `getEffectiveRegistries()` exists but `registry list`
+  re-implements it inline.
+
+- **R-067 (P3) — `process.exit()` mid-command bypasses cleanup.**
+  `env run`, `secret run` (`env-cli.ts:305`, `secret-cli.ts:257`), and
+  `runMigrationTool` exit directly, skipping the `disposeDispatchResources()`
+  finally in `cli.ts:663-665`.
+
+- **R-068 (P3) — misc small fixes.** `show lines` coerces `start` with
+  `Number` and `end` with `parseInt` (NaN accepted, `search-cli.ts:206-212`);
+  `init` never checks `git init`'s exit status (`init.ts:183-188`);
+  `.akm-include` referenced in seven comments but the real mechanism is
+  `package.json` `akm.include`; the `semver` npm package is a runtime
+  dependency imported nowhere in `src/` while a hand-rolled subset rejects
+  valid ranges (`registry/semver.ts:58-99`); `graphPath` in every graph
+  command's output is the index.db path (field name fossil,
+  `graph-db.ts:471`); graph read commands open/close index.db twice per
+  invocation; `--belief` is described as memory-only but filters any entry
+  with a `beliefState` (`db-search.ts:770-787`).
+  > Ruled 2026-07-26 (Q-03): drop the `show lines` coercion sub-item — the
+  > `lines` view mode and the `normalizeShowArgv`/`--akmStart`/`--akmEnd`
+  > plumbing it lives in are deleted per D2, with fragment refs as the
+  > successor. The remaining sub-items stand.
+  > Status 2026-07-27: D2 has landed, so the `show lines` sub-item is now moot
+  > in code, not just ruled away. The remaining sub-items were not
+  > individually re-verified.
+
+---
+
+## Explicitly reclassified as in-scope (no issue filed)
+
+Under the agent-toolkit identity, the following were reviewed and are **not**
+defects of scope, only subject to the coherence/safety issues above:
+`akm env`/`akm secret` (including run-injection and `${secret:}` interpolation),
+`akm agent` and the ten harness integrations, the workflow engine including the
+`brief`/`report` external-driver protocol, `akm tasks` and its three OS
+backends, the improve/proposal/collapse-detector loop, and the health
+observability surface.
+
+Also noted as genuinely strong and worth preserving: the journaled
+fs-transaction promotion/revert machinery, tar-extraction and website-crawl
+SSRF hardening, git-URL scheme allowlisting, the exact-path git staging in
+stash sync, the values-never-in-stdout secret discipline, and the uniform
+`{ok, error, code, hint}` error envelope.