akm-cli 0.9.1 → 0.9.2-alpha.2

package/docs/reference/workflow-schema.md

@@ -13,15 +13,75 @@ detail.
 - For operating a run day to day (`run`, `status`, `resume`, `abandon`), see
   [Running Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/run-workflows.md).
 
-## One format
+## Source formats and shared IR
 
-A workflow is an ordinary AKM markdown asset — the same envelope as every
-other type, OKF-conformant frontmatter plus a markdown body — whose
-frontmatter carries the entire orchestration graph (params, and how each step
-dispatches, fans out, routes, and gates) and whose body carries each step's
+Peer workflow sources include Markdown `.md` and GitHub-shaped YAML `.yml`.
+`.yaml` is not supported or recognized as a workflow source. Both adapters
+compile into the same strict source IR version 1 (`sourceIrVersion: 1`) before
+target resolution and durable freezing.
+
+The shipped `schemas/akm-workflow.json` frontmatter schema applies to and
+validates the Markdown source only. Markdown is not the sole or only workflow
+source; the GitHub-shaped YAML adapter has its own bounded parser and shares
+the source-IR decoder and semantic authorities.
+
+### Markdown source
+
+A Markdown workflow is an ordinary AKM asset — the same envelope as every
+other Markdown type, OKF-conformant frontmatter plus a body — whose
+frontmatter carries the orchestration graph (params, and how each step
+dispatches, fans out, routes, and gates). Its body carries each step's
 instructions and gate rubric under plain headings, joined to the frontmatter
-by step id. There is **one** format: no separate YAML "program" surface, no
-`.yaml`/`.yml` workflow files.
+by step id. The remainder of this page's frontmatter/body sections document
+that Markdown authoring format.
+
+## GitHub-shaped YAML subset
+
+A complete valid `on` plus `jobs` document is one workflow asset.
+It never creates a duplicate or second task asset. The root vocabulary is exactly
+`name`, `on`, and `jobs`:
+
+```yaml
+name: Local checks
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch: {}
+jobs:
+  checks:
+    runs-on: [self-hosted]
+    steps:
+      - id: lint
+        run: bun run lint
+      - id: review
+        uses: akm/command
+        with:
+          ref: commands/review
+```
+
+The accepted 0.9.2 subset is deliberately closed:
+
+- `on` accepts five-field `schedule` entries and an empty or null
+  `workflow_dispatch`; workflow_dispatch inputs are unsupported.
+- Service events are rejected.
+  A rejected service event creates no watcher and no polling daemon.
+- Each job requires exactly `runs-on: [self-hosted]`. `name`, `needs`, and
+  `steps` are the remaining job fields.
+- Each step requires `id` and exactly one `uses` or `run`; optional fields are
+  `name`, `with`, `env`, `shell`, and contained `working-directory`.
+- A `run` accepts only token-safe local command tokens.
+  Shell expansion and operators are unsupported and rejected, even when a host shell is named.
+- `uses` delegates to the task-v3 ref classifier. `akm/command`, command,
+  script, and task composition are local targets.
+  Local actions and Docker actions are unsupported and rejected (including `./` and `docker://`); remote actions are rejected
+  because acquisition is out of scope; nested workflows are unsupported.
+- GitHub expressions and contexts are unsupported and rejected anywhere in
+  the parsed tree.
+
+Multi-job documents are dependency-validated, indexed, and displayable, but
+cannot execute in 0.9.2 because the runtime boundary is single-job execution.
+The runtime refuses instead of flattening `needs` or fabricating job
+semantics.
 
 ## Frontmatter keys
 
@@ -668,7 +728,8 @@ stripped it — the same treatment an agent-harness child gets.
 
 Deliberately **not** on the list: credentials of any kind, cloud/CI variables,
 and the proxy family (`HTTP_PROXY` and friends — proxy URLs routinely embed
-credentials). Reach them with `pass_env:`, an `env:` binding, or `inherit_env:`.
+credentials). Reach a required value with an exact named `env:` binding, or
+name a non-secret per-machine variable with `pass_env:`.
 
 #### `pass_env:` — widen the allowlist by name
 
@@ -687,26 +748,16 @@ a committed *value*, so it cannot carry "whatever this build agent's
 Values passed through this way are **not** redacted from the command's output
 the way `env:` binding values are, so never list a credential here.
 
-#### `inherit_env:` — opt back into full inheritance
-
-```yaml
-    unit:
-      exec:
-        command: ["./scripts/deploy.sh"]
-        inherit_env: true
-```
+#### Durable v4 forbids `inherit_env`
 
-`inherit_env: true` gives the command akm's **entire** environment, verbatim —
-what it would see if you had typed it yourself in the shell that ran
-`akm workflow run`. Reach for it when a command genuinely needs the
-caller's whole environment (a wrapper script, a toolchain with many ambient
-variables) and enumerating names would be a losing game. Prefer `pass_env:` or
-`env:` bindings when you can, because those keep what the command can see
-visible in the frontmatter diff.
+Every new workflow start freezes a durable v4 plan. V4 rejects
+`inherit_env: true` and any other request for whole-process inheritance; use
+exact named environment bindings and `pass_env:` instead. Both mechanisms are
+dispatch-significant, keep the visible environment surface bounded, and form
+part of the unit's input hash.
 
-Both keys are **dispatch-significant**: they change what the command can see,
-so both are part of the unit's input hash. Changing either re-dispatches the
-unit rather than reusing a journaled row produced under the other scope.
+The historical `inherit_env` spelling is unsupported. Pre-v4 stored plans are
+rejected; they are never upgraded or replayed through a second runtime.
 
 ### What `akm show` reports for an exec step
 
@@ -727,8 +778,7 @@ happens. Field presence is the discriminator, the same way `fanOut` marks a
     "exec": {
       "command": ["bun", "run", "test:unit"],
       "cwd": "packages/core",
-      "passEnv": ["CARGO_HOME"],
-      "inheritEnv": true
+      "passEnv": ["CARGO_HOME"]
     }
   }
 }
@@ -741,8 +791,9 @@ happens. Field presence is the discriminator, the same way `fanOut` marks a
   of it is resolved from your environment, from a secret ref, or from a prior
   step's output. Every byte is already visible in the workflow file (and stored
   verbatim in `plan_json`) — which is also why you never inline a secret there.
-- `cwd`, `passEnv` and `inheritEnv` appear only when the unit declares them.
-  `passEnv` is a list of variable **names**; no value is ever projected.
+- `cwd` and `passEnv` appear only when the unit declares them. `passEnv` is a
+  list of variable **names**; no value is ever projected. New v4 plans never
+  carry `inheritEnv`.
 - `timeoutMs` is still reported, because an exec unit really does inherit
   `defaults.timeout` — that number is true for it.
 
@@ -987,23 +1038,23 @@ budget means starting a new run.
 ## Model references
 
 Reference semantic aliases in `model:` fields instead of exact model ids so a
-workflow stays harness-agnostic. Recommended vocabulary (convention, not
-hardcoded) via the config-root `modelAliases` key:
+workflow stays harness-agnostic. Aliases are defined only in the installed and
+optional user `models.json` files:
 
 ```jsonc
 {
-  "modelAliases": {
-    "fast":     { "llm": "claude-haiku-4-5", "*": "claude-haiku-4-5" },
-    "balanced": { "llm": "claude-sonnet-4-6", "*": "claude-sonnet-4-6" },
-    "deep":     { "claude": "claude-fable-5", "opencode": "opencode/claude-fable-5", "*": "claude-fable-5" }
+  "version": 1,
+  "aliases": {
+    "fast": { "claude": "claude-haiku-4-5", "opencode": "opencode/claude-haiku-4-5" },
+    "balanced": { "claude": "claude-sonnet-4-6", "opencode": "opencode/claude-sonnet-4-6" },
+    "reasoning": { "claude": "claude-opus-4-7", "opencode": "opencode/claude-opus-4-7" }
   }
 }
 ```
 
-For an LLM engine, resolution checks its engine-name column, then `llm`, then
-`*`. Agent engines check their harness platform and then `*`. The built-in
-aliases `fable`, `opus`, `sonnet`, and `haiku` resolve per platform with no
-config. See the [Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-engines-and-models)
+Resolution checks the selected engine name or canonical harness column. A
+known alias without that column fails rather than guessing a provider model;
+an unknown string is treated as an exact model selector. See the [Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-engines-and-models)
 for guidance on which tier to pick per step.
 
 ## See also

package/docs/reference/workflows.md

@@ -1,9 +1,10 @@
 # Workflows
 
-A workflow is a structured markdown document that defines a multi-step
-procedure. `akm workflow run` compiles it to a frozen plan, persists run and
-unit state, dispatches its work, verifies declared gates, and can resume after
-an interruption without replaying completed units.
+A workflow is a multi-step procedure authored as either AKM Markdown or the
+bounded GitHub-shaped YAML subset. `akm workflow run` compiles either peer
+source format through source IR v1, freezes a durable plan, persists run and
+unit state, dispatches work, verifies declared gates, and can resume after an
+interruption without replaying completed units.
 
 > **`akm workflow run` is Stable, ungated, and the only execution surface.**
 > It is the canonical start/resume/execute command; there is no separate
@@ -23,7 +24,7 @@ split by what you're doing:
   events. Includes the trust model for running a workflow sourced from
   someone else's bundle.
 - **[Author's Guide: Writing Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md)** —
-  writing and testing a workflow definition: the markdown structure, a
+  writing and testing a workflow definition: choosing a source format, the Markdown structure, a
   minimal complete example, common authoring mistakes, choosing engines and
   models, and engine-selection troubleshooting.
 - **[Workflow Schema](../reference/workflow-schema.md)** — the exhaustive,
@@ -34,9 +35,35 @@ split by what you're doing:
   worktree isolation, concurrency limits, and resume-without-replay.
 
 For task- or schedule-driven workflow runs — an `akm task` bound to
-`--workflow <ref>` and reconciled with the OS scheduler — see
+`uses: workflows/<ref>` and reconciled with the OS scheduler — see
 [Scheduling](https://github.com/itlackey/akm/blob/main/docs/guides/scheduling.md).
 
+## Source formats and execution versions
+
+Markdown `.md` and GitHub-shaped YAML `.yml` are peer source formats. The
+Markdown adapter preserves AKM's full prose, gates, maps, routes, typed
+artifacts, and exec vocabulary. The YAML adapter accepts the documented local
+`name`/`on`/`jobs` subset. `.yaml` is not a workflow source.
+
+Both adapters produce strict source IR version 1. New starts resolve source
+owners and executable targets, then freeze durable plan v4. Only v4 plans
+execute; pre-v4 rows are rejected and must be replaced by a new run.
+
+## Unsupported boundary and 0.9.3
+
+The 0.9.2 GitHub-shaped adapter is a local interoperability seam, not GitHub
+Actions. Full GitHub expressions and contexts, local/Docker/remote actions,
+nested workflows, service events, arbitrary hosted runners, and multi-job
+runtime execution remain outside 0.9.2. Valid multi-job sources can be indexed
+and displayed, but the 0.9.2 runtime executes a single job only.
+
+These full GitHub semantics, actions, service events, and runner behaviors are
+explicit 0.9.3-or-later work. AKM neither fetches remote actions nor creates
+event watchers or polling daemons in the meantime.
+
+Version 0.9.3 may extend full GitHub expressions and contexts, actions,
+service events, and runners; none of those capabilities is implied by 0.9.2.
+
 ## See also
 
 - [Discover and Load](https://github.com/itlackey/akm/blob/main/docs/guides/discover-and-load.md) — find available

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.1",
+  "version": "0.9.2-alpha.2",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [
@@ -36,7 +36,8 @@
   "license": "MPL-2.0",
   "pinNotes": {
     "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for.",
-    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so every Node akm supports installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift."
+    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so akm's supported Node 24 line installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
+    "@huggingface/transformers@4.2.0": "Exact semantic-search dependency pin. Re-run the real-model semantic gate before changing it."
   },
   "files": [
     "dist",
@@ -49,11 +50,13 @@
     "docs/migration/v0.7-to-v0.8.md",
     "docs/migration/v0.8-to-v0.9.md",
     "docs/migration/v0.9.0-troubleshooting.md",
+    "docs/migration/v0.9.1-to-v0.9.2.md",
     "docs/reference/bundle-types.md",
     "docs/reference/cli.md",
     "docs/reference/configuration.md",
     "docs/reference/data-and-telemetry.md",
     "docs/reference/supported-formats.md",
+    "docs/reference/tasks.md",
     "docs/reference/workflow-schema.md",
     "docs/reference/workflows.md",
     "schemas"
@@ -63,7 +66,7 @@
     "akm-migrate": "dist/akm-migrate"
   },
   "scripts": {
-    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=24;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 24.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -82,7 +85,7 @@
     "lint:devto-posts:fix": "bun scripts/lint-devto-posts.ts --fix",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
-    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-test-ref-literals.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check && bun scripts/lint-active-docs-terminology.ts",
+    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-execution-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check && bun scripts/lint-active-docs-terminology.ts",
     "lint:runtime-boundary": "bun scripts/lint-runtime-boundary.ts",
     "lint:tests-isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:fix": "bunx biome check --write src/ tests/ scripts/",
@@ -100,21 +103,22 @@
     "@types/node": "^22.19.17",
     "@types/semver": "^7.5.8",
     "@types/turndown": "^5.0.6",
+    "ajv": "8.20.0",
     "bun-types": "^1.3.13",
     "cmd-shim": "9.0.2",
     "typescript": "^5.9.3",
     "zod-to-json-schema": "^3.23.0"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "^4.2.0",
     "better-sqlite3": "12.11.1",
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",
+    "@huggingface/transformers": "4.2.0",
     "@opencode-ai/sdk": "1.2.20",
     "citty": "^0.2.2",
     "dotenv": "^17.4.2",