akm-cli 0.10.261012-beta → 0.10.261013-beta

package/docs/guides/bundles.md

@@ -80,8 +80,8 @@ back out of `sourceAdded`/`installed`. Without `--name`, akm derives one
 a `-<hash>` suffix only on a collision — that forgiving fallback applies
 solely to a derived name, never to an explicit `--name`.
 
-Git credentials must be symbolic references: `$VAR`, `${VAR}`, or
-`secret://name`. AKM resolves the reference only at the Git subprocess boundary
+Git credentials must be symbolic references: `$VAR`, `${VAR}`, or an akm ref
+such as `${secrets/gitea_token}`. AKM resolves the reference only at the Git subprocess boundary
 and sends it as an HTTPS bearer header; it does not put the token in the remote
 URL or `config.json`.
 
@@ -136,8 +136,10 @@ Valid `--kind` values are the four bundle providers: `filesystem`, `git`,
 ## akm bundle update / akm bundle remove
 
 `akm bundle update` refreshes git, npm, and website bundles. Each candidate is
-staged outside its active root, audited for dangerous environment keys, and
-only then published and indexed. `akm bundle remove` disconnects a bundle and
+staged outside its active root and only then published and indexed. Installing
+a bundle is the trust decision: neither `add` nor `update` inspects its `env/`
+files, so a bundle that sets `PATH` in an env file installs and refreshes
+unattended with no flag. `akm bundle remove` disconnects a bundle and
 re-indexes without it.
 
 Bundle refresh is deliberately explicit: Git bundles do not poll upstream on
@@ -152,7 +154,6 @@ akm bundle update @scope/bundle          # One managed bundle
 akm bundle update --all                 # All managed bundles
 akm bundle update --all --force         # Force fresh download even if version unchanged
 akm bundle update --all --skip-if-locked # Scheduled refresh: exit 0 on DB contention
-akm bundle update @scope/bundle --allow-dangerous-env-keys  # Approve reviewed dangerous env keys
 
 # Remove
 akm bundle remove @scope/bundle          # By npm id
@@ -161,12 +162,16 @@ akm bundle remove ~/.claude/skills      # By path
 akm bundle remove my-provider           # By name
 ```
 
-Dangerous keys prompt in a terminal (default: No) and block non-interactive
-updates unless `--allow-dangerous-env-keys` is explicit. `--yes` is a deprecated
-no-op on update; it never approves security findings.
-For `--all`, blocked and failed bundles are reported separately and later
-bundles continue. A rejected or failed bundle keeps its prior bytes, lock/config
-state, and search-index generation.
+A read-only git or npm bundle whose upstream revision is unchanged is not
+fetched or replaced again (`--force` fetches it anyway), so a task or workflow
+running from it keeps its directory. When the revision does change, the
+previous revision directory is kept and older ones are removed.
+
+`--allow-dangerous-env-keys` and `--yes` are deprecated no-ops on update,
+accepted through 0.10 so existing scripts keep working.
+For `--all`, failed bundles are reported separately and later bundles continue.
+A failed bundle keeps its prior bytes, lock/config state, and search-index
+generation.
 
 Private bundles that intentionally version every file under `env/` and
 `secrets/` can place this documented marker anywhere in their root

package/docs/guides/claude-code-vs-akm-workflows.md

@@ -6,7 +6,7 @@ subagents, runs them concurrently, and reports back before the session ends.
 AKM workflows are a different thing: a portable procedure that any supported
 agent harness can run, with durable state, retries, gates, and resume built
 in. A workflow source is Markdown `.md`, lowered to source IR version 1. Every run freezes the durable plan
-v4 family's executable `irVersion: 5` before execution; pre-`irVersion`-5
+v4 family's executable `irVersion: 7` before execution; pre-`irVersion`-5
 stored plans are rejected.
 Neither replaces the other — they solve different problems, and the right
 choice depends on whether the work is a one-off inside a session or a

package/docs/guides/run-workflows.md

@@ -12,15 +12,23 @@ see [Scheduling](scheduling.md).
 
 ## Start or continue a run
 
-`akm workflow run <run-id|workflows/ref>` starts or continues a persisted run
-and executes it until completion, failure, verification rejection,
-interruption, or an explicit invocation limit. Run state is scoped to the
-current project directory (nearest `.akm/config.json`, git root, bundle root,
-or current directory), so the same workflow can run independently in separate
-projects.
+`akm workflow run <workflows/ref>` always starts a new persisted run, and
+`akm workflow run <run-id>` continues that exact run. Either way it executes
+until completion, failure, verification rejection, interruption, or an
+explicit invocation limit. A run is identified by its run id and a workflow by
+its ref; the directory you run from never matters, so `akm workflow list` and
+`akm workflow status` show the same runs from anywhere.
+
+If other runs of the same ref are still active, a start says so in one
+warning that names their ids and the `akm workflow run <id>` /
+`akm workflow abandon <id>` commands. Starting is never refused.
+`akm workflow resume <id>` is only for a blocked or failed run: it re-activates
+the run so `akm workflow run <id>` can continue it.
+`--new` is a deprecated no-op (a ref always starts a new run), kept through
+0.10 so existing scripts keep working.
 
 Every new run/start compiles source IR v1 and freezes the durable plan v4
-family's current executable format (`irVersion: 5`) before publishing the run.
+family's current executable format (`irVersion: 7`) before publishing the run.
 A workflow ref is a Markdown `.md` source.
 
 ```sh
@@ -29,6 +37,9 @@ akm workflow run workflows/review --changed_files a.ts --changed_files b.ts
 akm workflow run <run-id> --max-retries 2 --timeout 10m
 ```
 
+Parameters are accepted on every ref start. They cannot be combined with a run
+id, which already has its parameters.
+
 Parameter flags must come after the target and exactly match declared
 `params` keys. Values are coerced through each parameter's JSON Schema:
 repeat an array flag, pass an object or whole array as JSON, and use a bare
@@ -58,7 +69,7 @@ and evidence — for a given run ID or workflow ref.
 ```sh
 akm workflow status <run-id>
 akm workflow status workflows/ship-release
-# When given a ref, resolves to the most-recently-updated run in the current scope
+# When given a ref, shows the most recently updated run of that ref
 ```
 
 Use this to inspect where a run is after a context window break, or to verify
@@ -151,12 +162,13 @@ A child run id always works directly, listed or not — `akm workflow status
 <childRunId>`, `resume`, `abandon`, and `run` all operate on it exactly like
 any other run.
 
-## List runs in scope
+## List runs
 
-`akm workflow list` shows workflow runs in the current scope.
+`akm workflow list` shows every workflow run on this host, most recently
+updated first. `--all-scopes` is a deprecated no-op, kept through 0.10.
 
 ```sh
-akm workflow list              # All runs in this scope (any status)
+akm workflow list              # All runs (any status)
 akm workflow list --active     # Only status=active (executable) runs
 akm workflow list --ref workflows/ship-release  # Runs for a specific workflow
 ```
@@ -190,7 +202,7 @@ completed are skipped, not re-run (see
 A resume consumes the frozen plan and journaled attempts; it does not re-read
 configuration or the index, and reads the authored workflow only to warn once
 when it changed since the run was frozen (the run continues on the frozen
-plan; `akm workflow run <ref> --new` picks up the edit). A stored plan this akm
+plan; `akm workflow run <ref>` starts a new run that picks up the edit). A stored plan this akm
 cannot decode is abandoned with a message naming how to start a new run.
 
 ## Abandon a run
@@ -249,7 +261,7 @@ treat package dependencies**:
 - **Audit before run** for any workflow that touches secrets, deploys to
   production, or writes outside the project tree. Read the `env:` bindings a
   workflow declares, and read its `exec.pass_env` lines.
-  The durable v4 family (`irVersion: 5`) rejects `inherit_env`. Authors must
+  The durable v4 family (`irVersion: 7`) rejects `inherit_env`. Authors must
   use exact named bindings and `pass_env` names.
 - **Pin known-good versions** when adding workflow sources from a registry
   or git remote (`akm bundle add github:owner/repo#v1.2.3`), and update

package/docs/guides/scheduling.md

@@ -61,7 +61,7 @@ different checkout or package. Editing definitions and running ordinary `akm
 task sync` preserves that captured runtime.
 
 A scheduled fire re-reads the guarded current source and creates a fresh
-durable-v4-family freeze at executable `irVersion: 5`.
+durable-v4-family freeze at executable `irVersion: 7`.
 Scheduler sync/validation evidence is not an executable snapshot and is never reused as the later run plan.
 
 ## A scheduled `akm improve` covers one bundle

package/docs/maintainers/README.md

@@ -8,9 +8,8 @@ actually improve it, and the current state of the `curate` implementation.
   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.
+- [Release Checklist](release-checklist.md) — the branch model and the steps to
+  cut, release and install akm and its plugins.
 - [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).

package/docs/maintainers/release-checklist.md

@@ -1,135 +1,82 @@
 # 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 monthly release number, `0.10.YYMMNN` (see step 4):
-   `bun scripts/release-version.ts next` prints the next free one for this
-   month (UTC). Every release, whatever its stage, takes the next number.
-   Commit it in `package.json` and cut the CHANGELOG as
-   `## [0.10.YYMMNN] - YYYY-MM-DD`. A prerelease stage is not committed: it is
-   chosen when the Release workflow runs, and the release's CHANGELOG section
-   covers it.
-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:
+`main` is the stable line (npm `latest`). The next version is developed on a
+release branch, `release/<version>` (npm `next`), which merges to `main` when
+it becomes stable. A fix for stable lands on `main` and is cherry-picked onto
+the release branch when that branch needs it.
+
+## 1. Cut the version
+
+On the branch you release from (`main` for stable, the release branch for
+next):
+
+1. Set the version: `npm pkg set version=<version>`. From 0.10,
+   `bun scripts/release-version.ts next` prints the next free one (see
+   [Versions](#versions)).
+2. Cut the changelog: add `## [<version>] - <YYYY-MM-DD>` (UTC date) directly
+   under `## [Unreleased]`, so the unreleased entries become this release's
+   section. CI fails the release commit when the newest section does not name
+   the `package.json` version (`tests/workflow-release.test.ts`).
+3. Add a migration note if the release needs one (see
+   [CONTRIBUTING](https://github.com/itlackey/akm/blob/main/.github/CONTRIBUTING.md#shipping-a-release--migration-notes)).
+4. Commit `release: <version>`, push it to the branch, and let CI run on it.
+
+## 2. Release akm
+
+```sh
+gh workflow run release.yml --ref <branch> -f version=<version> [-f stage=alpha|beta|rc]
+```
+
+The Release workflow, on the pushed commit:
+
+1. runs Gated CI: semantic search with real embeddings, the Docker install
+   matrix, and the native schedulers on Linux, macOS and Windows;
+2. requires CI to have passed on the same commit (it does not run lint, the
+   typecheck or the test suites again);
+3. runs `tests/release-check.sh --skip-docker`: the packaged artifact's bin
+   targets and migrator, package acceptance, and the upgrade rehearsal against
+   the packed tarball;
+4. builds the package and standalone binaries, publishes to npm (`latest` for
+   a stable version, `next` for a prerelease) and creates the GitHub release.
+
+If a job fails on a flake, rerun the failed jobs. If the fix needs a code
+change, commit it and release that commit. npm can take several minutes to show
+a new version: check `npm view akm-cli@<tag> version` before upgrading.
+
+## 3. Release the plugins
 
 ```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"
+gh workflow run release.yml --repo itlackey/akm-plugins --ref <plugins branch> -f akm_version=<published akm version>
 ```
 
-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.
+Plugins match akm's major.minor and keep their own patch numbers; each plugin
+release's notes name the akm version it requires. A plugin-only fix is released
+the same way, with the akm version already published. The Claude marketplace
+reads the plugins repository's `main`, so stable plugin releases come from
+`main`.
+
+## 4. Upgrade
+
+`akm upgrade` (stable) or `akm upgrade --next` (prerelease) updates akm and the
+installed plugins.
+
+## Gated CI on its own
+
+Gated CI also runs weekly on `main` to catch drift, and on demand from the
+Actions tab on any ref. Only the weekly run saves the Hugging Face model cache.
+
+## Versions
 
 0.10 and later use monthly release numbers, `0.10.YYMMNN`: `YY` the UTC year,
 `MM` the month and `NN` the release in that month (`01` to `99`), two digits
-each (see [`STABILITY.md`](../../STABILITY.md)). The first release of 2026-10 is
-`0.10.261001`. `bun scripts/release-version.ts next` takes `NN` as one above the
-highest release already on npm for this UTC month, with or without a stage
-(`npm view akm-cli versions`), so numbering follows what was published, not
-what was committed. The retired 8-digit daily builds (`0.10.26101001-alpha` to
-`0.10.26101202-alpha`) are not counted.
-
-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`, `NN`, a
-  month 01 to 12, `NN` 01 to 99; the old 8-digit daily form is rejected. For
-  0.9 and older it is the `X.Y.Z` as before.
-- `stage`: `none` publishes `<version>` 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`: every release has its own number). There is no
-  promoting one build through stages: the next release, at any stage, commits
-  the next number (`0.10.261001-alpha`, then `0.10.261002-beta`, then
-  `0.10.261003`).
-
-`bun scripts/release-version.ts validate <version>` checks a version by hand.
+each (see [`STABILITY.md`](../../STABILITY.md)). `bun scripts/release-version.ts
+next` takes `NN` as one above the highest release already on npm for this UTC
+month, with or without a stage, and `bun scripts/release-version.ts validate
+<version>` checks one by hand. The retired 8-digit daily builds
+(`0.10.26101001-alpha` to `0.10.26101202-alpha`) are not counted. 0.9 and older
+use `X.Y.Z`.
+
+The `stage` input is not committed: `none` (the default) publishes `<version>`
+to `latest`; `alpha`, `beta` or `rc` publishes `<version>-<stage>` to `next` as
+a GitHub prerelease. Every release, at any stage, takes the next number; a
+build is not promoted through stages.

package/docs/migration/v0.9-to-v0.10.md

@@ -48,7 +48,11 @@ akm workflow list --active
   `script` target (both came from features 0.10 removed) cannot be decoded in
   0.10; `akm workflow run` abandons it. A run whose plan has `unit.isolation`
   still decodes and runs in the engine's working directory. Let active runs
-  finish, or abandon them on purpose, before you upgrade.
+  finish, or abandon them on purpose, before you upgrade. In 0.10
+  `akm workflow run <ref>` always starts a new run (`akm workflow run <run-id>`
+  continues one; `resume` only re-activates a blocked or failed one), runs are no longer scoped
+  to a directory, and 0.9.15 does not see runs 0.10 started on the same
+  `state.db`. `--new` and `--all-scopes` are accepted and do nothing.
 - **Quit OpenCode.** `akm upgrade` skips (reports `deferred`) a plugin update
   while an OpenCode process runs. See [Plugins](#plugins).