akm-cli 0.9.29 → 0.9.31

package/docs/architecture/specs/0.9.0-docs-code-drift-register.md

@@ -0,0 +1,745 @@
+# 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).