# 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.