akm-cli 0.9.30 → 0.9.31

package/docs/guides/wikis.md

@@ -0,0 +1,81 @@
+# LLM Wikis
+
+akm supports [Andrej Karpathy's LLM
+Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+pattern: a markdown-based knowledge base that an LLM agent maintains
+together with a human, on a filesystem it can read and write directly,
+with no special SDK.
+
+**As of 0.9.0 an LLM wiki is a bundle format, not an akm asset type.**
+The `akm wiki` command family was removed with the 0.9.0 bundle-adapter
+architecture; recognition moved into the first-class LLM Wiki adapter.
+
+## The design
+
+A wiki is a directory. Full stop.
+
+```
+<wiki-root>/
+  schema.md                  rulebook the agent reads first
+  index.md                   catalog of pages, regenerable
+  log.md                     append-only activity log
+  raw/                       immutable ingested sources (never edit)
+  pages/<page>.md            agent-authored pages
+  pages/<topic>/<page>.md    optional nesting
+```
+
+Three layers, from Karpathy's gist:
+
+- **Raw sources** (`raw/`) — what you ingest. Articles, papers,
+  transcripts, notes. Immutable.
+- **Wiki pages** (`pages/<page>.md`, optionally nested) — what the agent
+  writes. Summaries, entity pages, concept pages, FAQs. Cross-referenced
+  via `xrefs:` frontmatter; provenance recorded via `sources:`
+  frontmatter pointing at the cited raw files.
+- **Schema** (`schema.md`) — the per-wiki configuration: voice, page
+  kinds, contradiction policy, any conventions the agent should follow.
+  akm never touches it.
+
+### Principle — akm surfaces, the agent writes
+
+Karpathy's workflow is a conversation between a human, an agent, and a
+filesystem. akm is not that agent. Page writes — create, append, xref,
+log — all use the agent's native `Read` / `Write` / `Edit` tools. akm's
+job is recognition and discovery: it mounts the wiki, indexes the pages,
+and makes them searchable alongside every other asset.
+
+No LLM calls are made anywhere in the wiki surface. No network access.
+
+## How akm sees a wiki (0.9.0)
+
+The LLM Wiki adapter recognizes a wiki **deterministically at install
+time**: a bundle component whose root holds a `schema.md` plus a
+`pages/` directory is mounted as an `llm-wiki` component. From there:
+
+- `pages/**.md` are indexed as searchable documents; each page's ref is
+  `bundle//conceptId`, where the conceptId is the root-relative path
+  minus `.md` (a page at `pages/attention.md` in bundle `research-wiki`
+  is `research-wiki//pages/attention`).
+- `raw/**.md` **are** indexed — as first-class, addressable, searchable
+  `wiki-source` documents (not `page`-type items; a ref looks like
+  `bundle//raw/<slug>`), so citations resolve and raw content is
+  discoverable by search too.
+- `schema.md`, `index.md`, and `log.md` are structural and are never
+  indexed as a concept.
+- `xrefs:` frontmatter becomes cross-reference edges; `sources:`
+  frontmatter becomes citation edges back to raw files.
+
+## Working with a wiki
+
+```sh
+akm bundle add github:team/research-wiki        # install a wiki bundle (or point at a local dir)
+akm search "attention"                   # pages rank alongside all other indexed content
+akm show research-wiki//pages/attention  # read a page by ref
+akm show research-wiki//pages/attention#history
+```
+
+To build a new wiki, create the directory shape above by hand (or have
+your agent do it — `schema.md` plus an empty `pages/` is enough for
+recognition), then add it as a bundle. Ingesting raw sources, writing
+pages, and maintaining `index.md`/`log.md` are the agent's job, guided
+by `schema.md`.

package/docs/maintainers/README.md

@@ -0,0 +1,19 @@
+# Maintainer Docs
+
+This is maintainer/contributor documentation, not user-facing. It covers how
+to work on `akm` itself — running it from source, measuring whether changes
+actually improve it, and the current state of the `curate` implementation.
+
+- [Local Development](local-development.md) — the explicit launcher for each
+  kind of contributor check (live source, built launcher, packed-package
+  acceptance, global checkout install) and the verification commands to run
+  before pushing.
+- [Release Checklist](release-checklist.md) — local release validation, exact
+  candidate-SHA semantic/Docker/native-scheduler gates, and the evidence links
+  required before publication.
+- [akm-eval](https://github.com/itlackey/akm-eval) — the evals and benchmarks
+  that measure whether `akm improve` and retrieval changes are actually
+  working. The old in-repo toolkit is retired: see [eval.md](eval.md).
+- [Curate Workmap](curate-workmap.md) — the current `akm curate` contract,
+  where its implementation diverges from intended behavior, and the
+  highest-value next fixes.

package/docs/maintainers/curate-workmap.md

@@ -0,0 +1,336 @@
+# Curate Workmap
+
+> **Implementation note (added later, verified against `src/commands/read/curate.ts`):**
+> much of the "Preferred direction" / "Next Fix Candidates" work below has
+> already shipped. `curateSearchResults` now selects via `selectCuratedStashHits`
+> (score-first ranking through `annotateCurateHit`/`compareCurateHits`/
+> `passesCurateScoreFloor`, not "take the first hit per type"),
+> `collapseCurateFamilies`/`preferBroadRootRepresentative`/`getCurateFamily`
+> implement the asset-family root/child collapsing this document recommends,
+> `shouldRunCurateFallback` triggers fallback on a weak result set (not only
+> on zero hits, reversing the "Fallback Search Behavior" section below), and
+> `appendCurateSupportRef`/`mergeCurateSupportRefs` attach graph-derived
+> support refs (the "Graph Leverage" recommendation). The `orderCuratedTypes`
+> function this document's "Execution Path" section names no longer exists —
+> regex-based type reordering was replaced by the scoring pipeline above. The
+> "Current Behavior" / "Current Curate Contract" sections below were accurate
+> at the time they were written but are now describing the PRE-fix state in
+> several places; re-verify against the functions above before trusting any
+> specific "current behavior" claim in this document. Not fully re-audited
+> line by line — this note flags the drift rather than rewriting the
+> analysis.
+
+## When To Read This
+
+Read this before changing `akm curate` ranking, fallback, follow-up generation, or agent-facing output.
+
+This page is the shortest path to understanding:
+- how `akm curate` currently works
+- which tests pin that behavior
+- where the current implementation diverges from intended product behavior
+- what fix direction has the strongest support from recent review
+
+## Debate Outcome
+
+Recent multi-agent review converged on the same conclusion:
+
+- `curate` should be relevance-first, not diversity-first
+- search ranking should remain the backbone of the shortlist
+- type diversity should be a soft preference for later slots, not a hard override
+- fallback search should run when the initial result set is weak or noisy, not only when it is empty
+- `followUp` should become more action-aware over time, but ranking/fallback correctness comes first
+
+Recommended fix order:
+
+1. Make curate selection score-first and diversity-second.
+2. Relax fallback suppression so one weak phrase hit does not block token fallback.
+3. Revisit follow-up generation after ranking quality improves.
+
+Additional debate outcome:
+
+- simple type-aware reranking is useful only as a thin post-search correction layer
+- root-vs-derived asset families should usually be collapsed to one representative in the top-level shortlist
+- graph data is better suited for attached support refs or navigation hints than for primary reranking in the first iteration
+
+## Current Curate Contract
+
+- CLI entry lives in `src/commands/read/search-cli.ts`.
+- Public entry point is `akmCurate()` in `src/commands/read/curate.ts`.
+- Default curated limit is `4`.
+- Default search source is `stash`.
+- Curate fetches more search hits than it returns: `limit * 4`, minimum `12`.
+- `--type <type>` bypasses diversification and returns top hits of that type.
+- Default multi-type curate currently keeps one best hit per type, then reorders types using regex heuristics.
+- Registry hits only fill leftover slots and are capped at `2`.
+- Bundle items are enriched via `akmShowUnified()` best-effort.
+- Bundle `followUp` is always `akm show <ref>` today.
+- Curate logs both a summary event and per-item retrieval rows for bundle refs.
+
+## Execution Path
+
+Read these first:
+
+- `src/commands/read/search-cli.ts`
+- `src/commands/read/curate.ts`
+- `src/output/shapes/curate.ts`
+- `src/output/text/helpers.ts`
+- `src/commands/read/search.ts`
+- `src/commands/read/show.ts`
+
+Key functions in `src/commands/read/curate.ts` (current names; `orderCuratedTypes()`
+no longer exists — see the implementation note above):
+
+- `akmCurate()`
+- `searchForCuration()`
+- `deriveCurateFallbackQueries()`
+- `mergeCurateSearchResponses()`
+- `curateSearchResults()`
+- `selectCuratedStashHits()` / `annotateCurateHit()` / `compareCurateHits()` / `passesCurateScoreFloor()`
+- `collapseCurateFamilies()` / `preferBroadRootRepresentative()` / `getCurateFamily()`
+- `shouldRunCurateFallback()`
+- `appendCurateSupportRef()` / `mergeCurateSupportRefs()`
+- `enrichCuratedStashHit()`
+
+## Ranking And Selection Rules
+
+Current behavior:
+
+- Search returns scored, ordered hits.
+- Curate then discards most of that ordering by taking the first hit per type.
+- Those per-type winners are reordered using query regex boosts such as `deploy`, `review`, `guide`, `agent`, and `memory`.
+- This can promote obviously lower-score items above much stronger hits.
+
+Why this is a problem:
+
+- search already has strong ranking tests and should remain the primary relevance signal
+- current curate can surface irrelevant filler to satisfy type variety
+- users experience curate as a flagship shortlist, so wrong top results damage trust more than low variety does
+
+Preferred direction:
+
+- preserve top-ranked overall hits first
+- allow diversity only when alternatives are close in score and plausibly relevant
+- keep explicit `--type` behavior unchanged
+
+Small type-aware corrections that are considered in-bounds:
+
+- prefer runnable `script` / concrete `command` over similarly scored `memory` for execution-heavy queries
+- prefer `workflow` / `skill` over adjacent explanation docs for multi-step task queries
+- include `agent` mainly for explicit delegation / persona / prompt-building queries
+- keep `memory` for recall/context queries, not as generic filler
+
+Corrections that are currently considered too risky:
+
+- hard one-per-type quotas
+- large hand-authored type matrices
+- LLM reranking
+- blanket demotion of `memory` or `agent` as types
+
+## Asset Families
+
+Curate should think in terms of asset families, not just isolated types.
+
+Practical examples in this repo:
+
+- `skills/docker-homelab`
+- `knowledge/skills/docker-homelab/references/compose`
+
+Desired behavior:
+
+- broad query like `docker homelab` -> prefer the root asset
+- narrow query like `docker compose reference` -> prefer the child reference page
+- if both are useful, attach the weaker sibling as support instead of spending two top-level slots by default
+
+This should start as an explicit structural heuristic, not semantic lineage inference.
+
+## Fallback Search Behavior
+
+Current behavior:
+
+- `searchForCuration()` only runs fallback token searches when the initial query returns zero hits
+- if the initial query returns even one weak or irrelevant hit, fallback does not run
+- fallback token extraction removes filler words, dedupes tokens, drops tokens shorter than 3 chars, and caps the set at 6
+- fallback is also skipped when normalization leaves only one usable token
+
+Why this is a problem:
+
+- one weak phrase hit can block much better token hits
+- prompt-style queries like `the docker` do not get the obvious one-token fallback
+- meaningful short tokens such as `ai`, `ci`, `cd`, `go`, `js`, or `ts` are lost today
+
+Preferred direction:
+
+- suppress fallback only when the initial result set is actually strong enough
+- allow one-token fallback when that token is clearly the meaningful residue of a prompt-style query
+- preserve a narrow allowlist of meaningful short tokens
+
+## Enrichment And Follow-Up Fields
+
+Current behavior:
+
+- curate enriches bundle hits by calling `akmShowUnified({ ref })`
+- if show fails, enrichment silently degrades to raw search-hit data
+- bundle follow-up remains `akm show <ref>` even for runnable scripts with a concrete `run`
+- registry follow-up uses the registry action, usually `akm bundle add ...`
+
+Product implication:
+
+- output is inspect-first, not act-first
+- this is acceptable for now, but becomes more visible once result quality improves
+
+For agent consumers, the desired optimization order is:
+
+- actionability
+- relevance
+- low duplication / root-asset preference
+- navigability
+- type diversity
+
+## Output Shape And Formatting
+
+Read:
+
+- `src/output/shapes/curate.ts`
+- `src/output/text/helpers.ts`
+
+Important details:
+
+- `curate` has a dedicated output shaper now
+- `brief` still keeps `followUp` and `reason`
+- `--shape agent` trims fields down for agent use
+- `--shape summary` is rejected on `curate`
+- text output prints fixed `Next steps:` guidance that assumes `akm show <ref>` is the next action
+
+## Telemetry And Retrieval Signal
+
+Read:
+
+- `src/commands/read/curate.ts`
+- `tests/integration/get-retrieval-counts.test.ts`
+
+Important detail:
+
+- curate writes per-item `usage_events` rows for bundle refs so curated items count as retrieval signal
+
+This means ranking changes do not just affect UX. They also affect downstream improvement-loop evidence.
+
+## Graph Leverage
+
+> **Retired (0.9.17-alpha.9):** the LLM entity graph this section recommends
+> leveraging is gone — `graph-extraction`, `graph_meta`/`graph_files`/
+> `graph_file_entities`/`graph_file_relations`, and `akm show`'s `related`
+> block it fed are all deleted. It was already superseded before that: #935
+> (0.9.17-alpha.8) added the first-class asset->asset edge table this section
+> says doesn't exist (`asset_links`, declared links), and curate's support
+> refs (`buildCurateSupportRefs` in `src/commands/read/curate.ts`) come from
+> declared links now, not graph data — the implementation note at the top of
+> this document already flags that rename. Kept below for historical context
+> only; do not implement against it.
+
+Existing graph signal:
+
+- there is no first-class asset->asset edge table
+- asset relatedness is already derivable via shared-entity overlap
+- `listRelatedPathsForFile()` in `src/indexer/graph/graph-boost.ts` returns related assets with `ref`, `type`, `sharedEntities`, and `relationCount`
+- `akm show` already exposes a lightweight `related` block using that signal
+
+Limits:
+
+- graph coverage depends on graph extraction having run
+- graph is thin or absent on cold bundles
+- graph quality is uneven and generic entities can over-connect assets
+- graph coverage is strongest for `knowledge` / `memory` and should not be assumed for every asset family
+
+Recommended first graph-aware use in curate:
+
+- do not use graph as a primary reranker yet
+- use graph to attach 1-2 support refs or navigation hints to a top-level curated result
+- prefer hints like `see also`, `related`, or `inspect next` over full graph payloads
+- keep full graph exploration in `akm show`'s `related` block
+
+What not to do yet:
+
+- no graph-only reranking
+- no graph-required curate path
+- no full graph dumps in curate output
+- no semantic asset-lineage inference from sparse graph data
+
+## Tests That Pin Behavior
+
+Start with these:
+
+- `tests/integration/curate-command.test.ts`
+- `tests/curate-logic.test.ts`
+- `tests/integration/curate-search-for-curation.test.ts`
+
+What they cover:
+
+- CLI JSON/text output
+- shape/detail behavior
+- usage logging
+- fallback token derivation
+- merge semantics
+- type ordering
+- diversification logic
+- registry filler cap
+- blank query rejection
+- default limit
+- phrase-hit fallback suppression
+- current quality baselines showing irrelevant filler
+
+Search-ranking baselines that curate should respect:
+
+- `tests/integration/db-scoring.test.ts` (no `tests/commands/search.test.ts` exists in the current tree; this is the closest surviving search-scoring baseline, not a confirmed direct successor)
+- `tests/integration/ranking-regression.test.ts`
+
+## Known Gaps / Mismatches
+
+- `docs/guides/discover-and-load.md` currently says curate prefers one strong match per type; that wording is too strong if curate becomes relevance-first.
+- `docs/reference/cli.md` documents `--type`, `--limit`, and `--source`, but does not currently explain the effective `--detail` and `--shape` behavior alongside curate.
+- Some historical AKM refs about curate output shaping are stale because curate now has a dedicated shape implementation.
+
+## Safe Edit Checklist
+
+Before editing curate:
+
+1. Read the three curate-focused test files.
+2. Read `src/commands/read/curate.ts` top to bottom.
+3. Confirm whether you are changing:
+   - post-search selection
+   - fallback triggering
+   - fallback token extraction
+   - output contract
+   - telemetry side effects
+4. Keep CLI surface and output-shape tests passing unless you intentionally change the public contract.
+5. If you improve ranking quality, convert current characterization tests that encode bad behavior into regression tests for the new intended behavior.
+
+## Useful AKM Queries And Refs
+
+Queries:
+
+```sh
+akm search "curate rerank"
+akm search "curate output shape"
+akm search "search discovery curate"
+akm search "curate telemetry usage_events"
+akm search "curate fallback query"
+akm search "curate quality baseline"
+```
+
+Historical context refs:
+
+- `memories/curate-weak-for-ui-test-audit.derived`
+- `knowledge/curate-command-flags-inert`
+
+Note: `knowledge/curate-command-flags-inert` is historical context only. It describes an older output-shaping limitation that is no longer current now that `src/output/shapes/curate.ts` exists.
+
+## Next Fix Candidates
+
+Highest-value next changes:
+
+1. Replace hard one-per-type selection with score-first shortlist selection plus optional soft diversity.
+2. Replace empty-only fallback triggering with weak-result fallback triggering.
+3. Add simple family-aware root/child collapsing for obvious structural bundles.
+4. Add regression tests asserting that docker-specific curate queries stop surfacing unrelated `commands/release-manager` filler.
+5. Attach lightweight related-asset hints using existing graph data after ranking quality is fixed.
+6. Revisit `followUp` generation after ranking quality is fixed.

package/docs/maintainers/eval.md

@@ -0,0 +1,3 @@
+# akm-eval — retired from this repository
+
+The `scripts/akm-eval/` toolkit has left akm: its code is kept, to read and not to run, in [`retired/akm-scripts-akm-eval/`](https://github.com/itlackey/akm-eval/tree/main/retired/akm-scripts-akm-eval) of [itlackey/akm-eval](https://github.com/itlackey/akm-eval), where [`reports/retired-evals.md`](https://github.com/itlackey/akm-eval/blob/main/reports/retired-evals.md) says what each retired eval asked, found and why it ended. It is also in this repository's history, at commit `f57a7fd44b37` and in the tag `v0.9.27-alpha.1`.

package/docs/maintainers/local-development.md

@@ -0,0 +1,108 @@
+# Local Development
+
+Use an explicit launcher for each kind of contributor check. This keeps live
+source, build output, packed-package behavior, and the machine-wide `akm`
+installation from being mistaken for one another.
+
+The npm package requires Node.js >= 22 and npm. A working Bun >= 1.0 is optional
+for the installed launcher and remains the repository's primary development and
+test runtime. The standalone binaries are runtime-free.
+
+## Live Source
+
+Run the working tree directly for the normal edit-test loop:
+
+```bash
+bun src/cli.ts search "deploy"
+bun src/cli.ts task doctor
+```
+
+This executes current uncommitted source. Tests that spawn the CLI should use
+the same explicit `bun src/cli.ts` form with the repository as their working
+directory rather than resolving `akm` from `PATH`.
+
+## Built Launcher
+
+Build first, then invoke the package launcher from `dist/`:
+
+```bash
+bun run build
+node dist/akm search "deploy"
+node dist/akm task doctor
+```
+
+This checks generated imports, copied assets, and launcher behavior while still
+keeping the invocation tied to this checkout. `node dist/akm` is portable across
+Windows, macOS, and Linux; on POSIX systems the executable `./dist/akm` form is
+also available.
+
+## Isolated Package Acceptance
+
+Run the repository's package acceptance command. It builds and packs the package,
+installs it under an isolated temporary prefix, and exercises that installed
+launcher without replacing the machine's global `akm`:
+
+```bash
+bun run test:package
+```
+
+The command builds, packs, installs under a temporary npm prefix, and checks the
+installed launchers. It does not run setup or test application-state isolation.
+
+## Intentional Global Checkout Install
+
+Only install the checkout globally when you deliberately want the machine-wide
+`akm` command to resolve to this checkout's package:
+
+```bash
+bun run build:install
+command -v akm
+akm --version
+```
+
+This replaces the globally resolved package and can affect agents, shells, and
+scheduled tasks that invoke `akm`. Re-run `akm task sync --rebind` only when you
+intend existing scheduler entries to capture the new installed runtime, then
+verify with `akm task doctor`.
+
+## Transitional Machine-Local Wrapper
+
+Some development machines still have a historical machine-local wrapper. Leave
+that file untouched, but treat it as transitional: do not document wrapper
+modes, depend on it in tests, or use it to choose between source and package
+behavior. Invoke `bun src/cli.ts`, `node dist/akm`, or `bun run test:package`
+explicitly instead.
+
+## Inspecting a Live Database
+
+`state.db`, `logs.db`, and `index.db` are WAL-mode SQLite databases that akm
+(or a scheduled task) may be writing at any moment. Open a live one only with
+`sqlite3 -readonly`:
+
+```bash
+sqlite3 -readonly ~/.local/share/akm/state.db "PRAGMA integrity_check;"
+sqlite3 -readonly ~/.local/share/akm/state.db ".backup /tmp/state-snapshot.db"
+```
+
+Do not open a live akm database with a plain (read-write) `sqlite3`
+connection, even just to run `.backup`. Through 0.9.17 an akm process could
+silently lose its SQLite file locks (copying the database file inside a
+process that holds it open drops them). An older `sqlite3` (< 3.51, and
+Python's `sqlite3` module on many hosts) opened read-write at that moment
+sees no other reader, takes an exclusive lock when it closes, and deletes the
+`-wal`/`-shm` files akm is still using: that produced a `state.db` with
+colliding rowids and stale index entries. `-readonly` avoids the whole class
+of risk by never taking a write connection.
+
+## Verification
+
+Use focused tests while iterating, then the repository gates before pushing:
+
+```bash
+bun test tests/<focused-file>.test.ts
+bun run check:changed
+bun run check
+```
+
+For eval scripts that accept `AKM_BIN`, point it at the exact launcher under
+test rather than relying on `PATH`.

package/docs/maintainers/release-checklist.md

@@ -0,0 +1,103 @@
+# Release Checklist
+
+Use this checklist for every release candidate. Local release validation and
+scheduled CI are useful inputs, but neither substitutes for a successful gated
+run of the exact commit that will be published.
+
+## 1. Freeze the candidate
+
+1. Finish the version, changelog, migration-note, and release-PR changes.
+2. Record `git rev-parse HEAD`. This is the full 40-character release-candidate SHA.
+3. Run `bun run release:check` locally. If Docker is unavailable, run
+   `./tests/release-check.sh --skip-docker` and rely on the gated Docker job
+   below for the container matrix.
+
+Any commit added after this point creates a new candidate and invalidates the
+gated evidence collected for the previous SHA.
+
+## 2. Collect exact-SHA gated evidence
+
+GitHub only offers a scheduled or manually dispatched workflow after its file
+exists on the default branch. When validating the commit that first introduces
+or changes this workflow, create a unique lightweight candidate tag at the
+recorded SHA:
+
+```sh
+candidate_sha="$(git rev-parse HEAD)"
+candidate_short_sha="$(git rev-parse --short=12 HEAD)"
+candidate_version="$(node -p 'require("./package.json").version')"
+candidate_tag="gated-ci/candidate-${candidate_version}-${candidate_short_sha}"
+git tag "$candidate_tag" "$candidate_sha"
+git push origin "refs/tags/$candidate_tag"
+```
+
+Verify that the tag target is the exact candidate commit recorded in step 1.
+The `gated-ci/candidate-*` trigger runs every gated suite from the workflow in
+that tagged commit. The resolver checks that the checkout equals the immutable
+event SHA, and the final evidence job records both that SHA and the tag ref.
+Never force-move or reuse a candidate tag; a changed commit needs a new tag and
+a new run.
+
+After **Gated CI** exists on the default branch, manual dispatch is an
+equivalent exact-SHA path. From the repository's Actions page, choose **Run
+workflow** and supply:
+
+- `candidate_sha`: the full 40-character SHA recorded above, never a branch or
+  tag name.
+
+Every suite runs; there is no suite selector.
+
+The manual request rejects abbreviated SHAs and checks out that immutable
+commit for every gate. Wait for all of these stable checks to succeed on either
+candidate path:
+
+- `Gated / Semantic Search`
+- `Gated / Docker Install`
+- `Gated / Native Scheduler / Linux`
+- `Gated / Native Scheduler / macOS`
+- `Gated / Native Scheduler / Windows`
+- `Gated / Release Candidate Evidence`
+
+The final evidence job records the requested and resolved SHA, the trigger ref,
+each suite's result, and a run link in the workflow summary. A weekly run is
+drift detection, not release evidence, because it may cover a different
+commit.
+
+Manual and tagged candidate runs are cache restore-only. Only a successful
+scheduled run of the workflow on the repository's default branch may save the
+HuggingFace model cache; its key identifies both the embedding model and the
+source/lock inputs. This prevents candidate-controlled workflow code from
+publishing cache entries while still avoiding repeated model downloads.
+
+Copy the successful run URL (for example,
+`https://github.com/itlackey/akm/actions/runs/<run-id>`) and the exact candidate
+SHA into both the release PR and its milestone/parent tracker. Do not publish
+from a candidate whose evidence link names a different SHA, whose final
+evidence job is skipped, or whose run was re-run after the candidate changed.
+
+## 3. Gated CI does not run on pull requests
+
+Gated CI runs on three triggers only: the weekly schedule, an exact-SHA
+`workflow_dispatch`, and a `gated-ci/candidate-*` tag. All three run every
+suite.
+
+There used to be a `Gated / Detect Changed Paths` job that also ran these on
+PRs, selecting suites by regex-matching the diff against path lists. It was
+deleted in 0.9.8: the patterns had gone stale — they still named test files a
+reorganisation had moved or deleted, so it was silently under-selecting suites
+and nobody noticed. A build-policing job that quietly stops policing is worse
+than no job, because its green status is read as coverage.
+
+Nothing about release evidence changes. Step 2 was always the requirement, and
+it never went through the PR path.
+
+The candidate-tag trigger is reserved for release evidence and workflow
+rollout: it always runs `all`, because a tag-push workflow is the path available
+before the workflow file reaches the default branch.
+
+## 4. Publish
+
+After the exact-SHA gated run and local release check are green, trigger the
+Release workflow with the version already committed in `package.json`. Keep the
+candidate SHA and Gated CI run URL in the release record so the published
+artifact's validation can be audited later.

package/docs/migration/README.md

@@ -9,5 +9,5 @@ Upgrade guides and per-release migration notes.
 - [v0.9.19 release note](release-notes/0.9.19.md) -- `akm improve` scoped to the bundle it writes to (scheduled runs need one `--bundle` run per other bundle), `akm proposal reopen` and the retire-proposal diff, and fewer repeat consolidate promotions
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
-- [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes
-- [Release notes](release-notes/) -- The short per-release notes `akm help migrate <version>` prints (bundled with the npm package)
+- [v0.5 -> v0.6 migration guide](v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes
+- [Release notes index](release-notes/README.md) -- The short per-release notes `akm help migrate <version>` prints, with links to every bundled note

package/docs/migration/release-notes/0.0.13.md

@@ -1,4 +1,4 @@
-Migration notes for akm v0.0.13
+# akm v0.0.13 migration notes
 
 - Initial public release.
 - No migration steps are required for earlier akm versions.

package/docs/migration/release-notes/0.1.0.md

@@ -1,4 +1,4 @@
-Migration notes for akm v0.1.0
+# akm v0.1.0 migration notes
 
 - The package and project were rebranded from Agent-i-Kit to akm.
 - Update package references from `agent-i-kit` to `akm-cli`.