# Docs–code drift register and intent questions — ruled 2026-07-26 (v0.9.0-rc.10)

Status: maintainer rulings recorded 2026-07-26 — all 19 questions ruled.
Re-verified 2026-07-27 against `2d2edc1` (code identical to `453a0ba`; the
delta is docs-only). That pass corrected three register entries that had
drifted from the tree — Q-12 (landed, not open), the R-004 companion item
(user-facing print already removed), and the Q-18 remediation sketch (the
suggested predicate overshoots — see the amended landmine note).
Note: items below cite `docs/agents/AGENTS.md` / `AGENTS.full.md`. Those files
were deleted during the 0.9.0 docs sweep; their still-true content now lives in
`src/assets/hints/cli-hints-full.md` / `cli-hints-short.md`, which is what
`akm hints` prints.
Companion to: `0.9.0-public-api-issue-backlog.md` (implementation-only findings).
This register covers the complement: places where the **documentation and the
code disagree**, and places where the **intended implementation is genuinely
unclear** because the project's own decision records conflict with shipped
behavior.

Method: three independent audits (README + guides; architecture/specs/agent
docs + STABILITY/AGENTS/SECURITY; docs/reference) compared documented claims
against `src/` with file:line verification, plus live CLI execution for the
highest-stakes items. Items verified by actually running the CLI are marked
**[verified live]**. Line references may drift; every item names the file and
observable behavior so it can be re-verified.

Reading order: Part 1 records the intent conflicts and now carries the
**maintainer rulings (2026-07-26)** that settle them — the rulings table is
the authoritative direction; the question bodies remain as the evidence
record. Parts 2–3 are mechanical now that Part 1 is decided. Part 4 records
false alarms and verified-clean surfaces so future audits don't re-litigate
them.

---

## Part 1 — Decision needed (now ruled): the intent conflicts

Each question cites both sides. "Docs-as-intent" means the fix is code work;
"code-as-intent" means the fix is doc work — but several of these have the
*decision record itself* (STABILITY.md, `0.9.0-decisions.md`, `ref.md`) on the
losing side, which is why a ruling was needed first.

### Maintainer rulings — 2026-07-26

Ruled by the maintainer in session review. Each ruling names the winning side
and the required follow-through; the question bodies below are kept as the
evidence record.

Until each follow-through lands, these rulings supersede conflicting statements
in the older records — `0.9.0-decisions.md` (notably D3's `mv` removal and D9's
`--auto-accept` wording), STABILITY.md (the `mv`-removal claim, the six-format
wording amended by Q-04, the missing tier entries), `ref.md`, and the
scaffolded stash assets such as `facts/conventions/organization.md`. Where any
of those contradicts this table, the table wins; treat the contradiction as
un-swept drift, not authority.

| Q | Ruling |
| --- | --- |
| Q-01 | Keep `akm mv`. Supersede D3; add an Experimental tier entry for `mv` to STABILITY.md; rewrite the scaffolded `facts/conventions/organization.md` fact and the other D3-side docs to teach the command. |
| Q-02 | Slash grammar only. Implement the decided slash form including `bundle//` enumeration; **remove the colon form entirely — no alias, no deprecation window**. Sweep `search --help`, `akm hints`, and the ref-prefix tests to slash. |
| Q-03 | Delete the `show` view modes per D2 (`SHOW_VIEW_MODES`, `normalizeShowArgv`, hidden `--akm*` flags). Fragment refs (D1) are the successor. |
| Q-04 | Implement basic support for all output formats on every non-exempt command, with `text` and `md` **collapsed into a single format**. Align the persisted `output.format` schema with the CLI's accepted set and fix the `INVALID_FORMAT_VALUE` hint. Follow-through detail: both `text` and `md` stay accepted as flag values resolving to the one collapsed renderer (amend here if a spelling is instead dropped); STABILITY.md's "all six formats" wording (`:70-77`) updates to the collapsed set; D7's exemption mechanism is in scope — exemptions must be declared and warned, never silent. Downstream: D-08's global `--format` table, the `INVALID_FORMAT_VALUE` hint, and completions (backlog R-052) update to the final accepted set. |
| Q-05 | Implement both gates (`experimental.workflowEngine`, `experimental.improveAutonomy`) as STABILITY.md documents them. |
| Q-06 | `show`-only is the intended 0.9.0 scope for fragment refs. State that scope in ref.md/D1; wider rollout is post-0.9.0. |
| Q-07 | Honor D11: fix the ref-parser seam centrally so opaque adapter conceptIds are accepted by the ref-consuming commands (graph, tasks, improve, proposals, utility repo, indexer walk). |
| Q-08 | Slash spelling only (`env/<name>`, `secrets/<name>`). Update every help/doc surface that teaches `env:`/`secret:`; **no colon alias**. |
| Q-09 | Keep the code's provider taxonomy (`filesystem`/`git`/`npm`/`website`); fix the docs that teach `local`/`managed`/`remote`. |
| Q-10 | `--rerank` was designed-then-dropped: remove the cli.md reference and the setup-wizard prose. |
| Q-11 | Keep flat `--name`; hierarchical placement goes through **`--path`, like other commands**. Document `--path` in cli.md and drop the "slashes in names" claim. **Doc-only work — verified 2026-07-26:** `workflow create` already declares `--path` (`workflow-cli.ts:204`), already routes it through the shared `normalizeCreateSubPath`/`combineCreatePath` helpers (`:227`) used by `knowledge`, `contribute`, and the env/secret create paths, and its `--name` help already reads "flat, no '/'; use --path for a subdirectory" (`:201`). Only `docs/reference/cli.md:574-577` is wrong. |
| Q-12 | Implement the STABILITY.md contract: parse `--auto-accept`, warn "deprecated and ignored" in 0.9, hard error in 0.10. Align D9/E4 wording. |
| Q-13 | Treat as a regression: restore the 7-day (static-index) and 24-hour (skills-sh) stale-fallback windows. |
| Q-14 | Adopt the convention: every registered command gets a tier and the reference either documents it or explicitly lists it internal. `extract`, `proposal drain`, and `improve canary` are tiered **Experimental**. Open follow-through: tiers for `lint`, `backup`, and the workflow exec/driver family (`run`/`brief`/`report`/`watch`/`abandon`) are still unassigned — record them when the STABILITY.md re-tier (Part 5, step 3) lands. |
| Q-15 | Code wins: fix the docs wording (`raw/**` is indexed as `wiki-source` documents, not pages). |
| Q-16 | Trim §4 to the five implemented contracts (`RankingContributor`, `SearchHitEnricher`, `ActionContributor`, `ProposalValidator`, `SessionLogHarness`); delete the seven unimplemented entries. §3.9's seam name updates to the shipped `RunnerSpec`/`executeRunner` (`runner-dispatch.ts`) so the doc describes reality throughout. |
| Q-17 | Do not keep the standalone brief: **consolidate** `runtime-boundary-design.md` into the other architecture docs, keeping only the still-necessary details; retire the file. Destination: fold the `bun:sqlite`/`Bun.*` import-boundary rule and the `database.ts`/`runtime.ts` export table into `architecture.md` (Module Boundaries / Tech Stack); drop the stale "Architect: investigate" checklists and the outdated 3-hard-import-files claim rather than carrying them over; remove the file's row from `docs/architecture/README.md` when retiring it. |
| Q-18 | Both halves. The two-registry split stays the core truth: `KNOWN_TYPES` is the presentation vocabulary, `PLACEMENT_SPECS` the stash-resident subset, and the exhaustiveness check asserts placement keys ⊆ known types (adapter-emitted `instruction` docs round-trip via the Q-07 opaque-conceptId fix). **And** the akm adapter gains `instruction` as a stash-resident asset type — a `PLACEMENT_SPECS` entry with an `instructions/` stash dir on the markdown spec — so instruction assets become creatable, browsable, and listed by `akm info` like knowledge. |
| Q-19 | Fix the resolver: `resolveSourcesForOrigin` must match install refs (`github:owner/repo`) so `//meta` and the `akm add` error hint work as documented. |

### Implementation status against the base branch (`claude/0-9-0-release-review-bcjxxu` @ `453a0ba`)

Re-verified 2026-07-26 after merging the base branch. The questions below were
written against `a8464f2`; the base branch has since implemented part of the
ruling set. Status per ruling:

| Q | Status | Evidence |
| --- | --- | --- |
| Q-01 | **Landed** | `mv` retained and declared Experimental (`STABILITY.md:72`); D3 explicitly excluded from the removal list (`:345`). |
| Q-02 | **Landed** | `parseRefPrefixQuery` now takes conceptId-prefix/`bundle//` slash forms and no colon form (`fts-query.ts:88-100`). |
| Q-03 | **Landed** | `SHOW_VIEW_MODES` and `normalizeShowArgv` deleted; `#fragment` golden replaces the lines-view golden. |
| Q-04 | **Conflict — see below** | All six formats implemented with an exemption registry (`output/format-exempt.ts`, `cli/shared.ts:219-244`), but `text` and `md` are **separate** renderers. |
| Q-05 | **Partial** | `experimental.improveAutonomy` shipped (`config/schema/experimental.ts:29`, `improve/autonomy-gate.ts`, reported by `tasks doctor`), and `453a0ba` closed the two lanes that were still silently gated — `memoryCleanup` and `contradiction` have no `processes.<name>.enabled` flag, so `applyAutonomyGate` structurally could not see them and suppressed them with no warning, event, or doctor line (the exact silent no-op the contract forbids). It also moved the gate off the read-only `analyzeMemoryCleanup` onto `applyMemoryCleanup`, so review-first runs get their preview back. `experimental.workflowEngine` still has zero code. |
| Q-14 | **Partial** | The workflow exec/driver family is now tiered Experimental (`STABILITY.md:230-240`). `extract`, `proposal drain`, `improve canary`, `lint`, and `backup` still have no tier entry and no `cli.md` section. |
| Q-06 | Open | `parseRefInput` still rejects `#fragment` outright (`asset/resolve-ref.ts:257-262`); `show` still works only by bypassing it. Recommendation: the ruling makes this doc-only for 0.9.0 — add one "scope: `show` only in 0.9.0" sentence to `ref.md` § Fragments and D1's Status line; no code change. |
| Q-07 | **Renderer half advanced; parser half open** | `453a0ba` replaced `show`'s OKF-only branch with `usesIndexedProjection` (`read/show.ts:536-559`): OKF plus **any** indexed item whose type AKM does not place now keeps its adapter's projection. That is the format-agnostic direction D11 asked for, on the *render* seam. The *parser* seam is untouched — `parseRefInput` still throws when a conceptId has no known asset-type prefix (`resolve-ref.ts:265-271`), so graph, tasks, improve, proposals, the utility repo, and the indexer walk remain strict. |
| Q-08 | Open | Colon spellings still taught by `env-cli.ts:392,455`, `secret-cli.ts:95,160`, `prompts.ts:78`, `AGENTS.md:44`. |
| Q-09 | Code correct | `VALID_SOURCE_KINDS` unchanged (`sources/sources-cli.ts:34`) — the ruled direction; the doc sweep is outstanding. |
| Q-10 | Open | `curate --rerank` still advertised by the setup wizard (`connection.ts:365,424`); cli.md reference also unswept. Recommendation: two-line deletion in each file, no dependencies — batch with the Part 5 step-2 sweep. |
| Q-11 | Open | `cli.md:613-614` still claims slashes are supported in workflow names. |
| Q-12 | **Landed** (0.9 half) — the register had this wrong | `resolveScopeAfterRetiredAutoAccept` (`improve-cli.ts:103-117`, shipped `2a68c7a`) warns "--auto-accept was removed in 0.9 and is ignored", names the replacement (`proposal drain --promote` / triage `applyMode: "promote"`), announces the 0.10 hard error, and **drops the poisoned positional** — the space-separated form (`--auto-accept 90`) previously read `90` as the scope, matched nothing, and exited 0. Remaining: align D9/E4 wording (E4 still says the runtime "does not parse" the flag). |
| Q-13 | Open | No second stale window in the registry cache. Recommendation: add a per-provider `staleWindowMs` to `fetchCachedJson` (`registry-cache.ts:136-141`) and have `getRegistryIndexCache` return rows past TTL but inside the window with a `stale: true` marker — the doc'd 7d/24h numbers become the two providers' constants. Small, self-contained. |
| Q-15 | Open | `wikis.md:59-60` still says `raw/` is "never indexed as pages". |
| Q-16, Q-17 | Open | §4 still lists all twelve contracts; `runtime-boundary-design.md` still present. |
| Q-18 | Open — **and now has a landmine, see below** | `instruction` still absent from `PLACEMENT_SPECS`. |
| Q-19 | Open | `resolveSourcesForOrigin` still matches derived installation ids only (`registry/origin-resolve.ts:18-23`). Recommendation: also compare `origin` against each installation's install ref (`installations.ts:98-110` already derives it) — an additive `||` in the filter; land together with backlog R-007 so the `akm add` hint chain works end to end. |

**Q-04 conflict — RESOLVED 2026-07-27: keep six formats.** The maintainer
amended the ruling to accept D7 as shipped: six distinct formats (`text` for
terminal rendering, `md` for document artifacts) plus the exemption registry.
The collapse is off the table. Follow-through landed the same day: the
`INVALID_FORMAT_VALUE` hint (`errors.ts:111`) and bash completions
(`completions.ts`) now carry the six-value set, completions dropped the bogus
`--detail summary` value and gained `--shape`, and the per-command `--format`
help strings on search/curate/show were updated. Q-04's original follow-through
detail in the rulings table is superseded by this note; STABILITY.md's
six-format wording stands as-is. Related same-day rulings: **R-029** —
`akm backup` is removed from the CLI (the capability lives at
`akm-migrate backup`/`restore`, which already existed; migration docs swept);
**R-047** — the scope-narrowing axis unifies on `--filter` for both `search`
and `show`, `--scope` removed with **no alias** (the old spelling now fails
loudly via the extra-positional guard, pinned by test). The paragraph below is
kept as the evidence record.

Original conflict note: The ruling recorded above says
"collapse `text` and `md` into a single format". The base branch instead landed
D7 as *six distinct* formats: `md` gained a renderer registry plus a generic
markdown fallback, explicitly so that "no command emits JSON under `--format
md` any more" (`cli/shared.ts:234-241`). It also built the exemption registry
D7 asked for (`format-exempt.ts`), which the ruling wanted. So the shipped work
satisfies the ruling's first half and contradicts its second. Either the
collapse is applied on top of D7 (deleting one of the two renderer paths), or
the ruling is amended to accept six formats. Until that is decided, the Q-04
follow-through detail recorded in the table above is provisional.

**Q-18 now collides with `usesIndexedProjection` — sequence the work.** `453a0ba`
made `show` decide between the adapter's indexed projection and the AKM matcher
by asking `!placementTypes().includes(entry.type)` (`read/show.ts:557`). Today
`instruction` is not a placement type, so adapter-emitted `CLAUDE.md`/`AGENTS.md`
items (claude/opencode adapters, `tool-dir-shared.ts:110-112`) take the
projection and render with their indexed content — the behavior that commit was
written to restore. The moment Q-18's ruling lands and `instruction` joins
`PLACEMENT_SPECS`, that predicate flips to `false` for those items and `show`
starts re-deriving them through `recognizeMatch`, reintroducing for `instruction`
exactly the regression `453a0ba` fixed for `website`/`file`. Implementing Q-18
therefore requires widening the predicate at the same time.

**Amended 2026-07-27 — the sketch above overshoots.** Gating on
`entry.adapterId !== "akm"` would change behavior for four other adapters:
`agent-skills`, `akm-task`, `akm-workflow`, and `llm-wiki` all publish
`document.content` AND emit AKM-placed types (`skill`, `task`, `workflow`,
`knowledge`) whose items deliberately render through AKM's bespoke type
renderers today (a skill keeps its run-command action, a task its schedule
view). Flipping them to the generic projection is a second regression wearing
the fix's clothes. The correct shape is an explicit ownership signal rather
than either inference: when `instruction` joins `PLACEMENT_SPECS`, either (a)
route `instruction`-typed items from the `claude`/`opencode` adapters to the
projection by adapter id — a two-member allowlist, honest about being one — or
(b) add an adapter-declared `ownsPresentation` marker on the indexed document
and let `usesIndexedProjection` read it. (b) is the durable fix; (a) is
acceptable 0.9.0 scope. Either way, land a guard test pinning
instruction-item `show` output BEFORE the `PLACEMENT_SPECS` change, so the
flip fails a test instead of shipping silently. **Ruled 2026-07-27: option
(b), the `ownsPresentation` marker** — adapters stamp presentation ownership
on the documents they index and `usesIndexedProjection` reads the stamp;
`index.db` being a regenerable cache, the schema addition needs only a
reindex. Implement the marker together with (or before) the
`PLACEMENT_SPECS.instruction` entry, guard test first. This remains the concrete cost
of the two-registry split: placement is now load-bearing for rendering, not
just for storage.

### Q-01 — `akm mv`: decided removed, fully shipped. Which wins?

- **Removed, per:** `0.9.0-decisions.md` D3 (`:67-117`), `STABILITY.md:60-62`,
  `ref.md:259-286`, `architecture.md:110-111`, `docs/agents/AGENTS.full.md:215`,
  `stash-conventions-code-spec.md:189-195`, and the **scaffolded stash asset**
  `facts/conventions/organization.md` ("A rename is delete plus create. There
  is no command that preserves an asset's identity or learned state").
- **Shipped, per:** `src/cli.ts:98,529`; `src/commands/mv-cli.ts` (1,300+ LOC)
  whose header states it re-keys the index row, usage_events history, and
  state.db salience rows **in place** — the exact inverse of D3's contract —
  and `docs/reference/cli.md:888-921` documenting it as live. `mv-cli.ts`
  self-labels "Experimental — see STABILITY.md", but STABILITY.md has no `mv`
  tier entry. D3's cleanup item (delete the `mv` fs-txn kind) is also
  unexecuted (`MV_TXN_KIND`, `mv-cli.ts:300`).
- **Cost of ambiguity:** agents reading the shipped conventions fact avoid the
  safe command and hand-roll the dangerous procedure it automates.

### Q-02 — Ref-prefix browse grammar: slash (decided) vs colon (implemented)

- **Decided grammar (slash), per:** D4, `STABILITY.md:50-52` (**Stable tier**),
  `ref.md:159-186`, `docs/guides/concepts.md:237-253` ("that spelling is
  gone"), `docs/reference/cli.md:338,344`, and `akm hints` output
  (`akm search "memories/projectA/"`).
- **Implemented grammar (colon), per:** `parseRefPrefixQuery`
  (`src/indexer/search/fts-query.ts:85-102`) accepts exactly
  `<singular-type>:` / `<singular-type>:<prefix>/`; no-colon queries return
  `null` and fall through to keyword FTS. Bundle enumeration (`bundle//`) has
  **no code path**. `search --help` (`search-cli.ts:36`) documents the colon
  form; tests pin it (`tests/integration/search-ref-prefix.test.ts:160,184,348`).
- **[verified live]** `akm search "memories/"` → keyword search (returned an
  unrelated fact); `akm search "memory:"` → actual type enumeration.
- Note: `akm hints` shows BOTH spellings (`"memories/projectA/"` and
  `"knowledge:"`) — the tool's own agent guidance is internally split.

### Q-03 — `akm show` view modes: decided deleted, still live and advertised

- **Deleted, per:** D2 (`0.9.0-decisions.md:44-63`), `ref.md:144-157` — the
  positional `toc|section|lines|frontmatter|full` grammar, `normalizeShowArgv`,
  and the hidden `--akmView/--akmHeading/--akmStart/--akmEnd` flags.
- **Live, per:** `show.ts:672` (`SHOW_VIEW_MODES`), `show.ts:695-766`
  (`normalizeShowArgv`), invoked pre-citty at `src/cli.ts:605`; the view modes
  are the headline example in `show --help` and in `akm hints`.

### Q-04 — `--format` universality: a Stable-tier contract with no implementation

- **Contract, per:** D7, `STABILITY.md:70-77`: all six formats on every
  non-exempt command; exemptions "declared, documented, and warned about
  rather than silent".
- **Code:** `html` throws for every command except `health`
  (`src/cli/shared.ts:208-215`; health intercept `src/cli.ts:341`); `md`
  silently returns the JSON envelope except for health (`shared.ts:201-207`);
  `text` falls back to `JSON.stringify` where no renderer is registered
  (`shared.ts:196-199`); no exemption registry exists (0 hits for
  `FORMAT_EXEMPT`). `USAGE_HINTS.INVALID_FORMAT_VALUE`
  (`src/core/errors.ts:111`) lists only four of the six accepted values.
- **Related asymmetry:** persisted `output.format` schema accepts only
  `json|yaml|text` (`src/core/config/schema/output.ts:15`) while the CLI flag
  accepts six — a saved `md` preference is silently dropped.

### Q-05 — `experimental.workflowEngine` / `experimental.improveAutonomy`: documented gates, zero code

- **Contract, per:** `STABILITY.md:192-218` (gate table; "a gated lane never
  degrades into a silent no-op"), D8 (`0.9.0-decisions.md:226`),
  `0.9.0-release-surface-review.md:438,517,522`.
- **Code:** zero occurrences of `experimental` / `workflowEngine` /
  `improveAutonomy` in `src/` or `schemas/akm-config.json`; `akm workflow run`
  (`workflow-cli.ts:331`) is ungated. Because the top-level schema is
  `.passthrough()`, setting the keys is accepted and inert — precisely the
  silent no-op the contract forbids.
- **Question:** are the gates still intended for 0.9.0 final, or is the
  STABILITY.md section to be dropped?

### Q-06 — Fragment refs (`#fragment`): implemented for `show` only

- D1 (`0.9.0-decisions.md:19-40`) and `ref.md:111-142` declare the fragment
  production resolved. `parseRefInput` still throws `INVALID_FLAG_VALUE` on
  any fragment (`resolve-ref.ts:255-264`; docblock: "No input boundary
  consumes an export fragment"). `show` works by bypassing it
  (`show.ts:312,370,390-397`).
- **Question:** is "show only" the intended scope of D1, or an incomplete
  rollout across the other ref-consuming commands?

### Q-07 — Opaque adapter conceptIds (the OKF/format-agnostic promise)

- **Contract, per:** `okf-support.md:42-45` (item 5) and D11
  (`0.9.0-decisions.md:302-313`): `okfbundle//tables/customers` must be
  accepted by "show and other applicable ref-consuming commands"; the
  leading-segment (known type dir) requirement "is therefore an OKF support
  bug". `ref.md:33-37,84-86`: conceptIds are opaque paths.
- **Code:** `typeNameFromConceptId` requires a known stash subdir and
  `parseRefInput` throws otherwise (`resolve-ref.ts:230-236,265-271`). Only
  `show` bypasses. Still routed through the strict parser: graph
  (`graph.ts:634`), tasks (`validator.ts:46,76`, `runner.ts:361,578`), improve
  (`improve.ts:460`), proposals repo (`proposals-repository.ts:62`), utility
  repo (`index-utility-repository.ts:163`), indexer walk
  (`path-resolver.ts:25`).
- **Question:** which commands are "applicable"? This is the single biggest
  blocker to the stated agent/harness/format-agnostic direction.

### Q-08 — env/secret ref spelling: `env/prod` vs `env:prod`

- **Code canonical:** `env/<name>`, `secrets/<name>`; bare names auto-qualify
  (`src/core/env-secret-ref.ts:55-62,128`).
- **Colon spellings taught by:** `secret --help` example
  `akm secret path secret:deploy-key` (`secret-cli.ts:95`), `env set/unset`
  help (`env-cli.ts:392,455`), the vault-removal signpost itself ("use `env:`
  … or `secret:`", `env-secret-ref.ts:49`), `docs/agents/AGENTS.md:44-45`,
  and `docs/migration/v0.8-to-v0.9.md` (TL;DR `akm env run env:<name>`;
  "entries surface under `env:`").
- **[verified live]** `akm secret path secret:deploy-key` → `Secret not
  found: secrets/secret:deploy-key`; `akm env path env:prod` → `Env not
  found: env/env:prod`; slash and bare forms work.
- **Question:** should the colon forms be accepted as aliases (they are the
  spelling every help surface teaches), or should every emitter be swept to
  the slash form?

### Q-09 — `akm list --kind`: conceptual vs provider taxonomy

- **Docs:** `local | managed | remote` used consistently
  (`docs/guides/sources-registries.md:52-56`, `docs/reference/cli.md:754-764`,
  registry.md prose).
- **Code:** `VALID_SOURCE_KINDS = filesystem|git|npm|website`
  (`sources-cli.ts:36-47`); every documented example exits 2.
- Both taxonomies are coherent (the lock-backed "managed" distinction exists
  in code as a *behavioral* split — see backlog R-015). Which is the intended
  user-facing axis?

### Q-10 — `curate --rerank`: two independent references, zero implementation

- Referenced by `docs/reference/cli.md:129` **and** live setup-wizard prose
  (`src/setup/steps/connection.ts:365,424`). No such flag exists
  (`search-cli.ts:119-137`). Designed-then-dropped, or specced-never-built?
- **Resolved (0.9.15, #951):** the setup-wizard reference is already gone;
  the remaining `--rerank` / "curate reranks by intent" claims
  (`docs/reference/cli.md`, `docs/guides/getting-started.md`,
  `docs/guides/discover-and-load.md`, and the `curate` command description
  in `search-cli.ts`) were deleted rather than implemented — no `--rerank`
  flag or reranking behavior exists in `akm curate`. A `rerank` engine kind
  (the lab's cross-encoder endpoint from the same fleet review) is real
  feature work, not a doc fix, and is deferred to its own issue.

### Q-11 — `workflow create` hierarchical names

- `docs/reference/cli.md:574-577`: "Forward slashes are supported for
  hierarchical names (e.g. `release/ship`)."
- Code: `assertFlatAssetName` rejects any `/` in `--name`
  (`workflow-cli.ts:226`, `asset-create.ts:44-51`) — yet the post-combine
  validation regex explicitly permits `/` (`workflow-cli.ts:228-229`), and
  `--path` (undocumented in cli.md) reintroduces it. The regex permitting `/`
  suggests the flat guard may be the later, unintended restriction.

### Q-12 — `--auto-accept` removal contract: two docs, two contracts, code matches neither

- D9 / `0.9.0-release-surface-review.md` E4: the strict 0.9 runtime "does not
  parse" the flag (implies hard failure). `STABILITY.md:114-116`: "deprecated
  and ignored; becomes a hard error in 0.10."
- Code: no such arg is declared and no deprecation warning exists — citty
  silently drops it. Neither doc's signposting reaches the user.

### Q-13 — Registry stale-fallback windows: doc'd tiers may be a code regression

- `docs/reference/registry.md:325,345`: static-index has a "7-day stale
  fallback"; skills-sh "up to 24 hours" on network failure.
- Code: no second window exists — `getRegistryIndexCache` returns `undefined`
  past TTL (`registry-index-cache-repository.ts:80`); the stale branch in
  `fetchCachedJson` (`registry-cache.ts:136-141`) can only fire within TTL.
  The numbers are too specific to be invented, and the cache helper was
  extracted with a "behaviour-preserving extraction" note (`:95-97`) —
  possibly lost functionality rather than doc fiction.

### Q-14 — What is public surface? (the undocumented command families)

`akm lint`, `akm extract`, `akm backup`, `akm proposal drain`,
`akm improve canary`, and the workflow exec/driver family
(`run/brief/report/watch/abandon`) have **no section in
`docs/reference/cli.md`** (which calls itself authoritative), and STABILITY.md
assigns them no tier. Only `mv` is marked Experimental anywhere. Deliberate
hiding vs. doc debt is undecidable — and it matters for a 1.0 contract
freeze. A convention is needed: every registered command gets a tier
(stable/experimental/internal) and the reference either documents it or
explicitly lists it as internal.

### Q-15 — Wiki `raw/**` indexing vs "never indexed"

`docs/guides/wikis.md:60` (and adapter prose elsewhere) say `raw/` is
structural and "never indexed as pages". The llm-wiki adapter indexes
`raw/**.md` as first-class searchable documents with `type: "wiki-source"`
(`llm-wiki-adapter.ts:82-83,271,291` — "First-class addressable +
searchable"). Literally consistent ("not *pages*"), practically misleading.
Intended behavior or over-indexing?

### Q-16 — `functional-contract-patterns.md` §4: aspiration or contract?

7 of 12 "Recommended Contracts" have no implementation (`PathResolver`,
`MatchContributor`, `MetadataContributor`, `LintContributor`,
`ImproveContributor`, `IndexPostProcessor`, `AgentRunner`); §3.9 states the
`AgentRunner` seam as a *rule*, but the actual seam is
`RunnerSpec`/`executeRunner` (`runner-dispatch.ts`). Mark the doc as
aspirational, or reconcile the seam names.

### Q-17 — `runtime-boundary-design.md`: shipped, amended, or superseded?

Still written as an open brief with unchecked "Architect: investigate" boxes
(`:32-37,69-73,104-106,132-140`), yet both target files exist and are complete
(`src/storage/database.ts`, `src/runtime.ts` — all 11 tabled exports present).
Its "3 hard-import files" no longer match the tree. Originally flagged as
needing a status banner; ruled instead (see the rulings table): consolidate the
still-necessary details into the other architecture docs and retire the file.

### Q-18 — The `instruction` asset type: half-registered

Present in `KNOWN_TYPES`/`TYPE_PRESENTATION` (renderer + action builder),
absent from `PLACEMENT_SPECS` — so it is invisible to `akm info`, unbrowsable,
and its refs don't round-trip (`recognition-util.ts:92-106` vs
`asset-placement.ts:89-166`). Register fully or remove; either way, add a
compile-time exhaustiveness check tying the two registries together.

### Q-19 — Install-ref meta resolution: aspirational error message

`concepts.md:343` documents `akm show github:owner/repo//meta`, and
`showStashMeta`'s own error says "Run: akm add ${metaRef.origin}"
(`show.ts:149`) — but `resolveSourcesForOrigin` matches derived installation
ids that can never equal `github:owner/repo` (`origin-resolve.ts:18-23`,
`installations.ts:98-110`). Either the resolver lost install-ref support or
the doc + error message are aspirational.

---

## Part 2 — Verified drift register (docs describe behavior the code doesn't have)

### 2.1 STABILITY.md (contract-tier claims)

- **D-01** ✅ **Fixed** (D4 landed): slash enumeration incl. `bundle//` is the
  implementation; the colon form is gone. Was: listed Stable; not implemented.
- **D-02** ✅ **Fixed as six formats** (D7 landed): registries + generic
  md/html fallbacks + declared exemptions. NOTE the Q-04 collapse ruling is
  still unresolved against this — see the Q-04 conflict note.
- **D-03** ✅ **Fixed** (Q-01 landed): STABILITY.md now carries the
  Experimental `mv` entry and no removal claim.
- **D-04** Proposal status vocabulary wrong: doc says
  `accepted/pending/proposed/rejected/archived` (`STABILITY.md:145-147`);
  actual `ProposalStatus = pending|accepted|rejected|reverted`
  (`proposal-types.ts:157`, `proposal-cli.ts:55`). `proposed` is an entry
  *quality*, `archived` is not a status, `reverted` is documented nowhere.
- **D-05** ✅ **Fixed** (Q-12 landed, `2a68c7a`): warn-and-ignore implemented
  incl. the scope-poisoning drop; see the corrected Q-12 status row.

### 2.2 Root `AGENTS.md` (contributor guidance)

- **D-06** Instructs configuring `llm.maxTokens` / `llm.timeoutMs` /
  `llm.concurrency` in config.json (`AGENTS.md:46-48`) — a top-level `llm`
  key is **hard-rejected** at load with exit 78
  (`config-schema.ts:157-165`: "llm is retired in 0.9").
  `docs/architecture/internals/indexing.md:6,78-89` repeats the retired keys,
  as does a stale comment at `indexer.ts:1601`.
- **D-07** Error envelope documented as `{ok:false, error, code}`; code also
  emits `hint` (`cli/shared.ts:93`). Exit-code table omits 4 (health warn,
  `cli.ts:583`) and 70 (INTERNAL, `shared.ts:45`); same omission in
  `docs/agents/AGENTS.md:60-67`.

### 2.3 `docs/reference/cli.md`

- **D-08** ◐ **Partial**: the global `--format` table now lists all six values
  (`cli.md:18`, updated with D7); the `--output` global-flag row is **still
  missing**. Remaining work: one table row. (Value set may shrink again if the
  Q-04 collapse is chosen.)
- **D-09** `init` dir list stale: missing `tasks/`, `sessions/`, `facts/`
  (13 dirs via `stashDirNames()`, `init.ts:126`, `asset-placement.ts:203`).
  Note: Q-18's ruling adds an `instructions/` placement dir (13 → 14) — sweep
  this item and D-46 after that change lands, regenerating from
  `stashDirNames()` rather than re-hardcoding.
- **D-10** `akm.llm` indexing claim uses the retired key (see D-06).
- **D-11** ◐ **Partial**: `--report` and `--window-compare` are now documented
  (health redesign, `0475870`) and `--compare` no longer exists to document;
  `--group-by` and `--windows` still have no table row.
- **D-12** search: `--shape summary` described as a silent no-op alias of
  brief (`cli.md:365,395`); code rejects it at startup and in the shape
  registry (`cli.ts:632-634`, `shapes.ts:94-107`). cli.md:47-51 states the
  correct behavior — the doc contradicts itself.
- **D-13** search `--type` list incomplete (missing `task`, `session`,
  `fact`); undocumented flags `--belief` (table), `--no-project-context`,
  `--include-sessions`. Shape-source pointer cites `src/output/shapes.ts` for
  functions that live in `src/output/shapes/helpers.ts:342,385`.
- **D-14** show: `path`/`editable` are always projected, not `--detail full`
  additions (`helpers.ts:492-495`); only `schemaVersion`/`editHint` are
  full-only.
- **D-15** workflow: 5 of 14 subcommands undocumented (`run`, `brief`,
  `report`, `watch`, `abandon`); `complete --summary` (required, gate-validated,
  `workflow-cli.ts:112-132`) undocumented; `start --force`, `status --units`,
  `complete --evidence` undocumented; hierarchical-name claim false (Q-11).
- **D-16** add: dangerous-env-key block exits **1**, not 2
  (`add-cli.ts:200,221,355`); key list "23 total" vs 41 literals + 2 pattern
  families (`env-key-rules.ts:35-109`); scan is top-level `env/*.env` only,
  not "every file" (`add-cli.ts:87`).
- **D-17** list: `--kind` values wrong — all four documented examples exit 2
  (Q-09). `remove --yes/-y` undocumented.
- **D-18** feedback/history/log: missing `--failure-mode`, repeatable `--tag`
  (`feedback-cli.ts:212-222`); `history --include-proposals`,
  `--accept-rate-by-source` (`sources-cli.ts:307-320`); `log --include-tags`,
  `--exclude-tags` (`observability-cli.ts:53-60`).
- **D-19** registry: "four subcommands" (five exist; the doc itself documents
  five); `registry remove --yes` undocumented.
- **D-20** config: `validate`, `show`, `enable`, `disable` subcommands and
  `--silent` undocumented (`config-cli.ts:138-260`) — `validate` is
  load-bearing (startup bypass allowlist, `cli.ts:575`) and `enable`/`disable`
  are referenced by registry.md:347.
- **D-21** env: subcommand table omits `set`/`unset` (both registered,
  `env-cli.ts:509-510`); `create --sensitive/--path/--target` never in a flag
  table.
- **D-22** improve: `archiveRetentionDays` documented as `improve.*` with
  default 30 — actually **top-level** with default **90**
  (`config-schema.ts:149`, `repository.ts:1054`); `--skip-if-locked`,
  `--sync/--no-sync`, `--push/--no-push` undocumented; `improve canary
  [--refresh]` entirely undocumented (`improve-cli.ts:49,96,160-163`).
- **D-23** proposal: `drain` verb undocumented while cli.md:1991 asserts a
  six-verb grammar (`proposal-cli.ts:339-383`, 8 flags); bulk
  `--max-diff-lines`/`--older-than`/`--dry-run` undocumented.
- **D-24** tasks: `tasks_invoked`/`tasks_completed` events do not exist —
  task runs write the `task_history` table, surfaced by `akm tasks history`,
  not `akm log` (`runner.ts:24`, `task-history-repository.ts:112,162`);
  `tasks add --disabled/--force/--rebind` and `init`'s CI skip undocumented.
- **D-25** `akm lint`, `akm extract`, `akm backup` have no cli.md section at
  all (Q-14).
- **D-26** Cross-reference anchors into configuration.md don't exist
  (`#defaultwritetarget`, `#memory-scope`, `#graph-boost-search-tuning`).
- **D-27** agent/propose: `agent --cwd`, `propose --path` undocumented.

### 2.4 `docs/reference/configuration.md`

- **D-28** 11 of 18 real top-level keys undocumented: `bundles`,
  `defaultBundle`, `defaultWriteTarget`, `search`, `feedback`,
  `archiveRetentionDays`, `output`, `semanticSearchMode`, `embedding`,
  `registries`, `setup` (`config-schema.ts:120-153`). Several are
  load-bearing for the CLI reference's own flows.
- **D-29** Environment table missing `AKM_DATA_DIR`, `AKM_CACHE_DIR`,
  `AKM_STATE_DIR`, `XDG_*`, `AKM_VERBOSE`, `AKM_DEBUG`,
  `AKM_DISABLE_PROJECT_CONTEXT`.
- **D-30** ✅ **Fixed** (D7): `output.format` schema widened to all six values
  (`schema/output.ts`), schema regenerated. A saved `md` preference now works.
  (Re-shrinks if the Q-04 collapse is chosen — keep in the Q-04 blast radius.)

### 2.5 `docs/reference/registry.md`

- **D-31** Teaches retired `config.installed` (`:219-221`) and `sources[]`
  (`:316-317`) — both hard-rejected (`config-schema.ts:184-192`). Should be
  `bundles`.
- **D-32** Lists retired `wiki` asset type (`:431`); cites
  `src/core/asset/asset-spec.ts` as "the authority" — file does not exist.
- **D-33** `build-index` "scans the current directory" — it does not; it fans
  out to manual entries + npm keyword search + GitHub topic search
  (`build-index.ts:99-112`). Its command meta also says "v2" while emitting
  `version: 3` (`registry-cli.ts:133`, `build-index.ts:112`).
- **D-34** Stale-fallback windows don't exist (Q-13). Cache layout shape
  wrong (`provider-utils.ts:83-99`; no `<timestamp>-<random>` component).

### 2.6 `docs/reference/data-and-telemetry.md`

- **D-35** `logs.db` missing from the data-directory table — a third durable
  database (`logs-db.ts:6,55-60`); the "safe to delete" guidance is
  incomplete. (roadmap.md:39-41 names it correctly.)
- **D-36** Maps events to nonexistent commands: `akm distill` (no such
  command), `akm lint --repair` (flag is `--fix`);
  `workflow_step_completed/updated` attributed to `workflow next` — emitted
  by `complete` (`runs.ts:707-719`).
- **D-37** "Full event type list" (~33 rows) vs ≥53 emitted types; missing
  include `improve_invoked` (which cli.md:234 relies on), `llm_usage`, `mv`
  (documented at cli.md:965!), `env_access`, `secret_access`,
  `workflow_unit_*`, `collapse_detector_alert`, and ~15 more.
- **D-38** `akm log list --limit 20` — `log list` has no `--limit`
  (`observability-cli.ts:46-61`); only `tail --max-events`.
- **D-39** Retired `stashDir` config override taught (`:71`); still says
  "0.8.0" (`:237`); lists `wikis` as a stash dir (`:68`).

### 2.7 `docs/reference/akm-eval.md`

- **D-40** "Three runner types" — nine exist (`scripts/akm-eval/src/types.ts:7-16`);
  `reflect-quality` and `planner-waste` never mentioned though both ship
  runners and cases. `improve-smoke` case count "8" — 12 case files ship.
  Cites `src/core/proposals.ts` (does not exist).

### 2.8 `docs/guides/*`

- **D-41** concepts.md: prefix-grammar claims (Q-02); `wikis/` as a stash
  type dir (no `wiki` placement spec; llm-wiki probe is bundle-root
  `schema.md`+`pages/`, `llm-wiki-adapter.ts:429-436`); `akm mv` removal
  claim (Q-01); belief filter "default current for memory search" — default
  is `all` everywhere (`search-cli.ts:62`, `search.ts:166`).
- **D-42** search-discovery.md: `ref` availability stated backwards — present
  at `brief` (the default), absent at `normal`, per the REC-03 comment
  (`helpers.ts:366-379`).
- **D-43** sources-registries.md: `--kind local|managed|remote` examples all
  exit 2 (Q-09).
- **D-44** knowledge-management.md: `remember --name ops/prod-secrets`
  rejected by the flat-name guard (`remember-cli.ts:151`,
  `asset-create.ts:44-51`) — correct form is `--path ops --name prod-secrets`;
  "akm does not edit entries" contradicted by `env set`/`unset` (and by the
  same doc 17 lines later); secrets documented under `env/` — they live in
  `secrets/` (`asset-placement.ts:135-140`).
- **D-45** improvement-loop.md: `feedback --negative` without `--reason`
  fails (`requireReason` defaults true, `feedback-cli.ts:271-283`);
  `log list --since 7d` unsupported (strict ISO parser, `time.ts:86-108`;
  shorthand is health-only); "there is no auto-accept threshold" — false: the
  doc-recommended `proactive-maintenance` strategy ships
  `applyMode:"promote", maxAcceptsPerRun:100`
  (`assets/improve-strategies/proactive-maintenance.json`,
  `improve.ts:804-830`), and `proposal drain --apply` is a second promote
  surface.
- **D-46** getting-started.md: setup dir list includes `wikis/` (never
  created) and omits `tasks/`, `sessions/`, `facts/`.
- **D-47** agent-integration.md: `akm show "npm:@scope/pkg//…"` /
  `"github:owner/repo//…"` rejected by the bundle-slug charset
  (`asset-ref.ts:65,156-161`); concepts.md:214-215 correctly restricts
  install refs to `add`/`clone` — the two guides contradict each other.
- **D-48** stash-makers.md: `dangerous-vault-key` issue code stale (actual
  `dangerous-env-key`, `env-key-rules.ts:175`); "and 20 others" undercounts
  (41 + patterns); `wikis/` layout again.
- **D-49** claude-code-vs-akm-workflows.md Parts B–E describe the pre-engine
  world: "akm does not execute workflow steps" / "strictly sequential" /
  "no workers" / "two tables" / "a workflow is a document, not a program" —
  overtaken by `workflow run`'s native executor, fan-out scheduler with
  concurrency caps, worktree isolation, `workflow_run_units` + migrations
  004/005, and YAML v2 programs. Part F lists `watch` (NDJSON stream) and
  fan-out as future work; both shipped. Subcommand list missing five verbs.
- **D-50** `.github/README.npm.md`: "community skills from skills.sh in a
  single query" — the skills.sh registry ships `enabled: false`
  (`config.ts:109-112`). README asset-type tables list 12 types, omitting
  `session` (concepts.md says thirteen).

### 2.9 `docs/architecture/*` (architecture.md + internals)

- **D-51** Dead files/symbols cited as authoritative:
  `src/core/asset/asset-spec.ts` + re-export shims `src/core/asset-spec.ts`,
  `src/core/asset-ref.ts`, `src/core/config.ts` (architecture.md:34,451-453);
  `TYPE_DIRS` (storage-locations.md:445); `parseAssetRef`
  (improve-workflow.md:199); `akmManifest()` (search.md:217-222);
  fact-asset-type.md implementation table — 5 of 9 rows dead.
- **D-52** `RegistryProvider` documented with `searchKits/searchAssets/getKit/
  canHandle` (architecture.md:279-287); the real contract is a single
  `search()` (`registry/providers/types.ts:35-45`).
- **D-53** storage-locations.md documents on-disk proposal stores
  (`.akm/proposals/<uuid>/`, archive dirs) and `.akm/graph.json` — proposals
  are a `state.db` table ("archival is a status flip",
  `proposal/repository.ts:16-24`); graph lives in `index.db` tables; 0 refs
  to graph.json in `src/`. `backupExistingConfig` attributed to paths.ts —
  lives in `config-io.ts:111`.
- **D-54** indexing.md table inventory: 6 tables documented, 14+ created
  (`index-schema.ts` — adds `index_dir_state`, `llm_enrichment_cache`,
  `registry_index_cache`, `utility_scores_scoped`, `graph_*`). The former FTS
  dirty queue was removed when entry mutations took ownership of their FTS
  projection.
- **D-55** architecture.md: `wiki` listed as built-in type mapped to `wikis/`
  (retired; `recognition-util.ts:80-106`); `pushOnCommit` "deprecated" —
  actually hard-rejected (`sources-bundles.ts:31-35`); `renderers.ts`
  "replaced" — still exists and self-registers (592+ lines); static-index
  described as v2-only (code reads v2/v3).
- **D-56** akm-0.9.0-bundle-adapter-spec.md: `akm bundle rename` cited as
  first-class — the `bundle` group was removed by D5; the 7 optional facet
  methods (§2) are deliberately deferred in code
  (`bundle-adapter.ts:113-120` "DEFERRED … FLAGGED for maintainer") with no
  status marker in the spec.
- **D-57** fresh-host-rebuild-runbook.md: retired `stashDir` key
  (`:26-27`).

### 2.10 `docs/agents/*` (the agent-facing docs)

- **D-58** AGENTS.full.md documents the removed `akm wiki` family in full
  (`:50,64,67,131-163`) — `list|create|show|pages|search|stash|lint|ingest|
  remove`, `--type wiki`, `--wiki`, `show wiki:<name>`, wiki exit codes.
  AGENTS.md repeats `wiki list/stash/ingest` (`:21-24,46`).
  stash-conventions-code-spec.md cites `src/wiki/wiki.ts` (no such dir).
  Note the migration guide records the *intent*: the family was deliberately
  removed in 0.9.0 in favor of the `llm-wiki` bundle format — these docs and
  the shipped hints corpus (backlog R-001) were never swept.
- **D-59** AGENTS.md teaches `env run env:<name>` / `secret run
  secret:<name>` — both 404 (Q-08) **[verified live]**.
- **D-60** AGENTS.full.md `akm search "knowledge:"` works only because the
  retired colon grammar is still the implementation (Q-02); AGENTS.md:107
  omits the `reverted` proposal status.
- **D-61** agent-install.md: `stashDir`/`sources` listed as valid
  `setup --config` keys and `akm config get stashDir` shown — both
  hard-rejected/unresolvable (`config-schema.ts:181-189,382`).

### 2.11 `docs/migration/v0.8-to-v0.9.md`

- **D-62** Verification snippet `akm info --format=json | jq -r .stashDir`
  fails — `InfoResponse` has no `stashDir` field (`info.ts:64-78`)
  **[verified live]**.
- **D-63** TL;DR teaches `akm env run env:<name> -- <command>` (404s, Q-08);
  "entries surface under `env:`" uses the retired spelling.

### 2.12 In-CLI doc surfaces (shipped assets, help text)

Tracked in the backlog (R-001..R-006, R-052) and repeated here for
completeness because they are documentation in the product's own voice:
`akm hints` documents the removed wiki family and drifts by install method;
`show --format text` renders `type:name` feedback commands; `feedback` help
contradicts the immediate EMA update; a hint references `akm events list`;
the scaffolded conventions fact contradicts `akm mv`; bash completions
advertise `--detail summary` and omit `md/html`.

---

## Part 3 — Code that still emits the retired `type:name` grammar

The grammar decision (`STABILITY.md:42`, `ref.md:106`, D-R3 "nowhere after
the flip") is violated by live **output**, not just docs:

- **E-01** `formatRefForMessage()` returns `origin//type:name`
  (`write-source.ts:1148-1158`) — used in **git commit subjects**
  (`knowledge.ts:786`), env/secret boundary commits
  (`env-secret-ref.ts:273`), and write errors (`write-source.ts:317,343`).
- **E-02** `sources/resolve.ts:46,58,67,82` — "Stash asset not found for
  ref: ${type}:${name}".
- **E-03** `show.ts:393` — "Fragments are not supported for
  ${displayType}:${displayName}".
- **E-04** `mv-cli.ts:1052,1064,1080` — error text renders
  `${source.type}:${source.name}`.
- **E-05** The `show` APPLY footer (`show-directives.ts:26,57,75,87`) —
  backlog R-002.
- **E-06** env/secret help examples and the vault signpost (Q-08).
- **E-07** ◐ **Partial** (re-verified 2026-07-27): the `search --help` and
  `akm hints` prefix examples were swept to slash with D4. Survivors:
  `sources-cli.ts:213` clone example (`npm:@scope/pkg//script:deploy.sh`),
  five `skill:akm-dream` examples in `proposal-cli.ts` (`:98,178,271,304` +
  one), and `init.ts:152`'s `memory:…` reference. All are one-line help-string
  edits — batch into the Part 5 step-2 sweep.

---

## Part 4 — False alarms and verified-clean surfaces

Recorded so future audits don't re-litigate.

- **`migrate apply --dry-run` is NOT broken.** The arg is declared camelCase
  (`dryRun`, `migrate-cli.ts:28`), and an audit flagged that citty might not
  bind `--dry-run` to it — a real apply masquerading as a dry run.
  **[verified live]**: citty auto-camelizes; `--dry-run` binds to both
  `args.dryRun` and `args["dry-run"]`. However, this disproves the comment at
  `src/output/context.ts:87-93` ("citty does not auto-camelise hyphenated arg
  keys") — the codebase's quoted-kebab arg convention rests on a false
  premise, worth a note where that comment lives.
- **Verified clean:** `docs/reference/roadmap.md` (no shipped-but-absent or
  future-but-present items) and `docs/reference/wiki-snapshot-fetchers.md`
  (every claim matches `snapshot-fetchers/registry.ts`, `types.ts`,
  `website-ingest.ts`).
- **Verified exact:** the model-alias table in agent-integration.md matches
  `model-aliases.ts:45-76` byte-for-byte; storage paths, search/curate
  defaults and limits, website crawl caps (50 pages / depth 3 / 12h),
  `tasks` subcommands incl. `--rebind`, `env run --clean`,
  `secret run <ref> <VAR> -- cmd`, completions XDG install path,
  `history` oldest-first ordering, "installation is not activation"
  (`activation-policy.ts`), and workflow `complete --summary` gating all
  check out against code.
- **Stale code comment that misled the audit itself:**
  `llm-wiki-adapter.ts:63-64` claims the adapter barrel is test-only;
  `core/adapter/registry.ts:33` imports it in production. The adapter is
  live; the comment is wrong.

---

## Part 5 — Suggested triage order

1. **Rulings — done 2026-07-26** (all 19; see the Part 1 table). They decided
   whether ~40% of Part 2 is doc work or code work. Of the execute-first trio,
   **Q-02 has landed** (slash enumeration incl. `bundle//`, colon form gone);
   Q-07's renderer half landed (`usesIndexedProjection`) with the parser half
   open; Q-08 is untouched. Q-08 and Q-07's parser seam are now the
   highest-leverage remaining code items.
2. **Sweep the agent-copy-paste surfaces** (Part 3 + §2.10/2.12): everything
   an agent will paste from — hints, help examples, error messages, the show
   footer, AGENTS.md — should speak one grammar.
3. **Re-tier STABILITY.md** so nothing marked Stable is unimplemented and
   every registered command has a tier (Q-14).
4. **Mechanical doc sweep** for the remainder of Part 2, ideally with a CI
   check that executes every fenced `akm …` example in docs/ against a
   scratch stash (the `--kind`, `--since 7d`, `remember --name a/b`, and
   colon-spelling failures would all have been caught by running the docs).