akm-cli 0.9.30 → 0.10.26101001-alpha

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,132 @@
+# 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. From
+   0.10 the version is a daily build, `0.10.YYMMDDNN` (see step 4):
+   `bun scripts/release-version.ts next` prints the next free one for today
+   (UTC). Commit it in `package.json` and cut the CHANGELOG as
+   `## [0.10.YYMMDDNN] - YYYY-MM-DD`. A prerelease stage is not committed: it is
+   chosen when the Release workflow runs, and a stage of a build is covered by
+   that build's CHANGELOG section.
+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.
+
+0.10 and later use daily builds, `0.10.YYMMDDNN`: `YY` the UTC year, `MM` the
+month, `DD` the day and `NN` the build that day (`01` to `99`), two digits each
+(see [`STABILITY.md`](../../STABILITY.md)). The first build on 2026-10-10 is
+`0.10.26101001`. `bun scripts/release-version.ts next` takes `NN` as one above
+the highest build already on npm for today's UTC date (`npm view akm-cli
+versions`), so numbering follows what was published, not what was committed.
+
+The workflow has two inputs:
+
+- `version`: the version committed in `package.json`, as before. The workflow
+  rejects a malformed one (`scripts/release-version.ts`, tested in
+  `tests/release-version.test.ts`): two digits each for `YY`, `MM`, `DD`, `NN`, a
+  real calendar date, `NN` 01 to 99. For 0.9 and older it is the `X.Y.Z` as
+  before.
+- `stage`: `none` publishes the build itself to the npm `latest` tag and as a
+  GitHub release. `alpha`, `beta` or `rc` publishes `<version>-<stage>` to
+  `next` as a GitHub prerelease (no `.N`: the build number already differs per
+  build). Promote one build by running the workflow again with the same
+  `version` and the next stage, then with `none`. The order is
+  `-alpha` < `-beta` < `-rc` < the build.
+
+`bun scripts/release-version.ts validate <version>` checks a version by hand.

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

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.2.0
+# akm v0.2.0 migration notes
 
 - Asset refs are user-facing `type:name` values; do not rely on URI-style refs.
 - The old fixed asset-type union was replaced by an extensible asset type system.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.3.0
+# akm v0.3.0 migration notes
 
 - The old `stash` and `kit` command groups were folded into the top-level CLI.
 - Use `akm add`, `akm list`, and `akm remove` instead of the older split command surfaces.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.5.0
+# akm v0.5.0 migration notes
 
 - New top-level surfaces: `akm wiki …`, `akm workflow …`, `akm vault …`, and `akm save`.
 - If you tried the unreleased single-wiki LLM prototype, move to the new `akm wiki …` workflow.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.6.0
+# akm v0.6.0 migration notes
 
 This release ships the v1 architecture refactor on top of the earlier 0.6
 terminology cut (`kit` → `stash` in the registry wire format). The CLI

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.0
+# akm v0.7.0 migration notes
 
 0.7.0 is the last pre-1.0 ship in the v1 cycle. It introduces the
 proposal queue, agent reflection commands, the `lesson` asset type, the

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.3
+# akm v0.7.3 migration notes
 
 0.7.3 includes stability improvements, security hardening, and UX refinements. Key changes include:
 
@@ -13,4 +13,4 @@ Migration notes for akm v0.7.3
 - **`.stash.json` no longer drives incremental stale detection** — editing `.stash.json` alone no longer forces directories to rescan during incremental indexing.
 - **One-shot URL ingest for `akm import` and `akm wiki stash`** — both commands now accept a single HTTP/HTTPS URL in addition to file paths and stdin. `akm import <url>` fetches the exact page, converts it to markdown, and writes it into `knowledge/` using a URL-path-derived default name. `akm wiki stash <wiki> <url>` fetches the exact page, converts it to markdown, and writes it into `wikis/<wiki>/raw/`. Neither command registers a persistent website source or crawls linked pages.
 
-For stash authors on the 0.7.x pre-release line: `.stash.json` remains supported for compatibility in this release, but it is deprecated and will be removed in v0.8.0. That timeline is intentional: during this aggressive pre-release phase-out window, compatibility shims do not stay around until 1.0 unless they still earn their cost. Prefer frontmatter for markdown assets and structured code comments for scripts, and migrate any remaining `.stash.json` metadata before taking the 0.8 upgrade.
+For stash authors on the 0.7.x pre-release line: `.stash.json` remains supported for compatibility in this release, but it is deprecated and will be removed in v0.8.0. That timeline is intentional: during this aggressive pre-release phase-out window, compatibility shims do not stay around until 1.0 unless they still earn their cost. Prefer frontmatter for markdown assets and structured code comments for scripts, and migrate any remaining `.stash.json` metadata before taking the 0.8 upgrade.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.4
+# akm v0.7.4 migration notes
 
 This is a patch release that fixes the publish process. No functional changes from v0.7.3.
 

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.5
+# akm v0.7.5 migration notes
 
 0.7.5 is a patch release that rolls up all changes shipped on `main` after v0.7.4.
 

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.8.0
+# akm v0.8.0 migration notes
 
 This release combines the 0.8.0 CLI/storage break with the final improve-owned
 maintenance migration work that landed before release validation closed.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.0
+# akm v0.9.0 migration notes
 
 These notes apply to the 0.9.0 release candidates and final release. If you
 were already running a 0.9.0 beta, align scripts, prompts, and stash layout

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.14
+# akm v0.9.14 migration notes
 
 The derived `index.db` generation changes from v22 to v23 to support lexical
 Markdown fragments. On the first normal read after upgrade, akm detects that

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.15
+# akm v0.9.15 migration notes
 
 `RUN_LEASE_HELD` (a workflow run-lease refusal) and the new
 `STATE_DB_CONTENDED` (state.db write contention) now exit 75 (`EX_TEMPFAIL`)

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.16
+# akm v0.9.16 migration notes
 
 Scheduled execution is now authorized by host-local config and bound to the
 specific source installed under a bundle id. Existing

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.17
+# akm v0.9.17 migration notes
 
 Run this after upgrading:
 

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.19
+# akm v0.9.19 migration notes
 
 Nothing has to run after upgrading from 0.9.18: 0.9.19 adds no config keys,
 changes no index layout, adds no state.db migration and leaves scheduler rows

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.2
+# akm v0.9.2 migration notes
 
 Exact-prefix additive `state.db` upgrades remain automatic. The released
 historical migration 018 is classified separately because it removes retired

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

@@ -7,40 +7,36 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
-- [0.9.19](0.9.19.md) — `akm improve` planning only the bundle it writes to
-  (a scheduled run needs one `--bundle` run per other bundle),
-  `akm proposal reopen` and the retire-proposal diff, consolidate's coverage
-  check and content-driven hold on decided promotions, distill's grounding
-  check, and what a downgrade to 0.9.18 undoes
-- [0.9.17](0.9.17.md) — consolidate's retire proposals and continuity check,
-  promotions archiving their source memory, declared links replacing the LLM
-  entity graph, index layout 26, scheduler rows carrying their own context,
-  and `akm improve` scoped to what retrieval actually returns
-- [0.9.16](0.9.16.md) — source-bound scheduler grants, local execution
-  authority, config inheritance's portable-data boundary, and split unsafe
-  overrides
-- [0.9.15](0.9.15.md) — exit-code 75 for lease/state.db contention,
-  `--require-engines` scheduled task templates, `--no-probe` cli-version
-  skip, thinking-control wire forms, embedding re-embed safety and
-  cross-rebuild vector salvage, launcher signal forwarding, a default
-  per-document embedding cap, and `extends` config inheritance
-- [0.9.14](0.9.14.md) — index v22-to-v23 derived-cache rebuild, lexical
-  fragments, and collapse-detector canary re-minting
-- [0.9.2](0.9.2.md) — task source v4 migration, workflow source IR v1 and
-  durable-v4-family `irVersion: 5`, command diagnostics, and strategy judgment
-  migration
+- [0.9.19](0.9.19.md) — Bundle-scoped improve planning, proposal reopen, and consolidate/distill guardrails.
+- [0.9.17](0.9.17.md) — Retire proposals, declared links replacing the LLM entity graph, and scoped improve planning.
+- [0.9.16](0.9.16.md) — Source-bound scheduler grants, local execution authority, and split unsafe overrides.
+- [0.9.15](0.9.15.md) — Lease/state.db contention exit code 75, scheduled-task engine requirements, and safer launchers.
+- [0.9.14](0.9.14.md) — Index v22→v23 derived-cache rebuild, lexical fragments, and collapse-detector canaries.
+- [0.9.2](0.9.2.md) — Task source v4 migration, workflow source IR v1, and durable-v4-family `irVersion: 5`.
+- [0.9.0](0.9.0.md) — 0.9 release-candidate and final-release migration notes.
+- [0.8.0](0.8.0.md) — CLI/storage break, improve-owned graph pipeline, config v2, and task assets.
+- [0.7.5](0.7.5.md) — Patch rollup for everything shipped on `main` after v0.7.4.
+- [0.7.4](0.7.4.md) — Publish-process-only patch release with no functional change from 0.7.3.
+- [0.7.3](0.7.3.md) — Stability improvements, security hardening, and UX refinements.
+- [0.7.0](0.7.0.md) — Last v1-cycle pre-1.0 release with the proposal queue and improve-loop groundwork.
+- [0.6.0](0.6.0.md) — v1 architecture refactor, stash rename cleanup, and sandbox/setup guidance.
+- [0.5.0](0.5.0.md) — Wiki, workflow, vault, and save command additions before the 0.6 architecture cut.
+- [0.3.0](0.3.0.md) — Fold the old `stash` and `kit` command groups into the top-level CLI.
+- [0.2.0](0.2.0.md) — User-facing `type:name` refs and early bundle conventions.
+- [0.1.0](0.1.0.md) — Rebrand from Agent-i-Kit to akm.
+- [0.0.13](0.0.13.md) — Initial public release.
 
 ## Adding notes for a new release
 
 1. Create `<version>.md` in this directory (e.g. `0.7.0.md`).
-2. Write plain text — the content is printed verbatim. Start the body
-   with a line like `Migration notes for akm v0.7.0`, then list the
-   automatic migrations, manual actions, publisher changes, etc.
-3. The file ships with the published package via `package.json` →
-   `files[]` and is resolved at runtime from either `src/` or `dist/`,
-   so no code change is required.
+2. Start the file with `# akm v<version> migration notes`, then list the
+   automatic migrations, manual actions, publisher changes, and any longform
+   guide links the terminal user may need.
+3. The file ships with the published package via `package.json` → `files[]`
+   and is resolved at runtime from either `src/` or `dist/`, so no code
+   change is required.
 4. Link to the longform guide in the last paragraph if one exists.
 
-Keep each note self-contained: it should tell a user everything they
-need to upgrade without requiring them to open a browser (the longform
-guide link is the last resort, not the first).
+Keep each note self-contained: it should tell a user everything they need to
+upgrade without requiring them to open a browser (the longform guide link is
+the last resort, not the first).