akm-cli 0.9.31 → 0.10.261002-beta

package/docs/reference/workflows.md

@@ -1,14 +1,13 @@
 # Workflows
 
-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
+A workflow is a multi-step procedure authored as AKM Markdown. `akm workflow run`
+compiles the source 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
-> external-driver protocol.
+> **`akm workflow run` is Experimental (see `STABILITY.md`), ungated, and the only
+> execution surface.** It is the canonical start/resume/execute command; there is
+> no separate external-driver protocol.
 
 Workflows are one of the execution surfaces AKM directly orchestrates: AKM
 retrieves every supported capability type, but a workflow's declared steps —
@@ -29,10 +28,10 @@ split by what you're doing:
   models, and engine-selection troubleshooting.
 - **[Workflow Schema](../reference/workflow-schema.md)** — the exhaustive,
   authoritative reference: every frontmatter key, the bare-reference grammar,
-  routing, failure policy, gates, and budget ceilings, with exact syntax.
+  failure policy, gates, and budget ceilings, with exact syntax.
 - **[Architecture: The Workflow Engine](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md)**
   — how a frozen plan actually executes: persistence, the run lease, dispatch,
-  worktree isolation, concurrency limits, and resume-without-replay.
+  concurrency limits, and resume-without-replay.
 
 For task- or schedule-driven workflow runs — an `akm task` bound to
 `uses: workflows/<ref>` and reconciled with the OS scheduler — see
@@ -40,29 +39,23 @@ For task- or schedule-driven workflow runs — an `akm task` bound to
 
 ## 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
+Markdown `.md` is the one workflow source format; it preserves AKM's full prose,
+gates, maps, typed artifacts, and exec vocabulary. New starts resolve source
 owners and executable targets, then freeze durable plan `irVersion` 5. A
 stored plan is read back as it is: one frozen at another `irVersion` that
 still decodes runs, and one this akm cannot decode is abandoned by
 `akm workflow run` with a message naming how to start a new run. See
 [Architecture: The Workflow Engine](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md#resume-skips-completed-units).
 
-A step can compose another workflow as a child — directly
-(`uses: workflows/<ref>`) or through a task whose own target is a workflow
-(`uses: tasks/<ref>`) — frozen completely into the parent's plan before the
-parent run is published. See
+A step can run another workflow as a child (`unit: { workflow: workflows/<ref> }`,
+**Experimental**) — frozen completely into the parent's plan before the parent
+run is published. See
 [Workflow Schema: Child workflows](../reference/workflow-schema.md#child-workflows)
-for both forms and their limits. Running a step that composes a child
+for the form and its limits. Running a step that composes a child
 workflow drives that child to completion (or as far as it gets) with the
 same engine the parent uses, then maps the child's final status onto the
-composing step: a completed child promotes its declared `outputs:` (or
-`{runId, status}` when it declares none) as the step's own output and the
-parent continues; a failed child fails the step and the run; a blocked
+composing step: a completed child's last step output becomes the step's own
+output and the parent continues; a failed child fails the step and the run; a blocked
 child blocks the composing step and the run, with recovery notes naming the
 exact `akm workflow resume`/`akm workflow run` sequence. `akm workflow
 status` on a run that composes children renders a `children:` tree showing
@@ -72,16 +65,6 @@ for the full status mapping and the blocked-child recovery flow, and
 [Running Workflows: Child runs](https://github.com/itlackey/akm/blob/main/docs/guides/run-workflows.md#child-runs) for a
 walkthrough.
 
-## Workflow outputs
-
-A workflow may declare a run-level export in its Markdown frontmatter —
-`outputs: {<name>: {from: steps.<id>.output(.<segment>)*, schema?}}`, up to
-64 entries — resolved once, from persisted step evidence, at run
-completion. A run with no `outputs:` declaration exports `{runId, status}`
-instead; a composing parent step promotes a completed child's `outputs:`
-(or that same `{runId, status}` fallback) as its own step output — see
-[Workflow Schema: Workflow outputs](../reference/workflow-schema.md#workflow-outputs).
-
 ## Inspecting a workflow without running it
 
 `akm workflow plan <ref>` compiles, resolves, and freezes a workflow exactly
@@ -93,23 +76,12 @@ actually do — including which child workflows it would compose — before
 committing to a run. See
 [CLI reference: workflow plan](cli.md#workflow-plan).
 
-## 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,
-service events, and arbitrary hosted runners remain outside 0.9.2.
-**Multi-job YAML is rejected outright** — `jobs:` must contain exactly one
-job; a document with zero, two, or more jobs fails to compile at all (it is
-not "indexed but not executed" — it never becomes a valid workflow). Split a
-multi-job source into single-job workflows and compose them with a
-child-workflow step instead. AKM neither fetches remote actions nor creates
-event watchers or polling daemons.
-
-These full GitHub semantics, actions, service events, and runner behaviors are
-explicit 0.9.3-or-later work.
+## Removed in 0.10
 
-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.
+The GitHub-shaped YAML workflow format (`.yml` with `name`/`on`/`jobs`), `route`
+steps, `unit.isolation: worktree`, and top-level `outputs:` were removed in 0.10;
+see the CHANGELOG. A task that runs a workflow (`uses: workflows/<name>`, or a
+`run:` that calls `akm workflow run`) is unaffected.
 
 ## See also
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.31",
+  "version": "0.10.261002-beta",
   "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": [
@@ -18,7 +18,6 @@
     "commands",
     "claude-code",
     "opencode",
-    "mcp",
     "ai-coding-assistant",
     "agent-skills",
     "skill-management",
@@ -36,6 +35,7 @@
   "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.",
+    "@opencode/client@2.0.26": "Exact pin. The OpenCode 2 wire client (OpenCode.make + session.create/prompt/wait/interrupt, event.subscribe, permission.reply) used by src/integrations/harnesses/opencode-sdk/v2-adapter.ts, the default adapter. It is an HTTP client for a private `opencode serve` child akm spawns; it does not install the opencode binary and must never pull in `opencode-ai` or `@opencode/cli`. Re-run the gated real-binary test (AKM_OPENCODE_V2_BIN) before bumping.",
     "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.",
     "@huggingface/transformers@4.2.0": "Exact semantic-search dependency pin. Re-run the real-model semantic gate before changing it."
   },
@@ -59,6 +59,15 @@
     "docs/plans/0.9.2-agent-command-workflow-plan.md",
     "schemas"
   ],
+  "exports": {
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "bun": "./dist/api.js",
+      "default": "./dist/api-node.mjs"
+    },
+    "./package.json": "./package.json",
+    "./dist/*": "./dist/*"
+  },
   "bin": {
     "akm": "dist/akm",
     "akm-migrate": "dist/akm-migrate"
@@ -111,6 +120,7 @@
     "@clack/prompts": "^1.3.0",
     "@huggingface/transformers": "4.2.0",
     "@opencode-ai/sdk": "1.2.20",
+    "@opencode/client": "2.0.26",
     "citty": "^0.2.2",
     "dotenv": "^17.4.2",
     "fast-xml-parser": "^5.10.1",

package/schemas/akm-config.json

@@ -808,15 +808,6 @@
                         },
                         "additionalProperties": true
                       },
-                      "lowValueFilter": {
-                        "type": "object",
-                        "properties": {
-                          "enabled": {
-                            "type": "boolean"
-                          }
-                        },
-                        "additionalProperties": true
-                      },
                       "defectFilter": {
                         "type": "object",
                         "properties": {
@@ -911,10 +902,6 @@
                           "minLength": 1
                         }
                       },
-                      "limit": {
-                        "type": "integer",
-                        "exclusiveMinimum": 0
-                      },
                       "qualityGate": {
                         "type": "object",
                         "properties": {
@@ -990,15 +977,6 @@
                           }
                         },
                         "additionalProperties": true
-                      },
-                      "fidelityCheck": {
-                        "type": "object",
-                        "properties": {
-                          "enabled": {
-                            "type": "boolean"
-                          }
-                        },
-                        "additionalProperties": true
                       }
                     },
                     "additionalProperties": true
@@ -1071,32 +1049,10 @@
                         "type": "integer",
                         "exclusiveMinimum": 0
                       },
-                      "minPoolSize": {
-                        "type": "integer",
-                        "minimum": 0
-                      },
                       "maxChunkSize": {
                         "type": "integer",
                         "minimum": 1,
                         "maximum": 50
-                      },
-                      "p90ChunkSecondsDefault": {
-                        "type": "number",
-                        "exclusiveMinimum": 0
-                      },
-                      "antiCollapse": {
-                        "type": "object",
-                        "properties": {
-                          "enabled": {
-                            "type": "boolean"
-                          },
-                          "randomClusterFraction": {
-                            "type": "number",
-                            "minimum": 0,
-                            "maximum": 1
-                          }
-                        },
-                        "additionalProperties": true
                       }
                     },
                     "additionalProperties": true
@@ -1161,19 +1117,6 @@
                       "minPendingCount": {
                         "type": "integer",
                         "minimum": 0
-                      },
-                      "cls": {
-                        "type": "object",
-                        "properties": {
-                          "enabled": {
-                            "type": "boolean"
-                          },
-                          "adjacentCount": {
-                            "type": "integer",
-                            "minimum": 1
-                          }
-                        },
-                        "additionalProperties": true
                       }
                     },
                     "additionalProperties": true
@@ -1540,10 +1483,6 @@
                       "maxPerRun": {
                         "type": "integer",
                         "exclusiveMinimum": 0
-                      },
-                      "limit": {
-                        "type": "integer",
-                        "exclusiveMinimum": 0
                       }
                     },
                     "additionalProperties": true
@@ -1585,16 +1524,7 @@
         },
         "salience": {
           "type": "object",
-          "properties": {
-            "outcomeWeightEnabled": {
-              "type": "boolean"
-            },
-            "salienceThreshold": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 1
-            }
-          },
+          "properties": {},
           "additionalProperties": true
         },
         "stateGc": {
@@ -2484,15 +2414,6 @@
                             },
                             "additionalProperties": true
                           },
-                          "lowValueFilter": {
-                            "type": "object",
-                            "properties": {
-                              "enabled": {
-                                "type": "boolean"
-                              }
-                            },
-                            "additionalProperties": true
-                          },
                           "defectFilter": {
                             "type": "object",
                             "properties": {
@@ -2587,10 +2508,6 @@
                               "minLength": 1
                             }
                           },
-                          "limit": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          },
                           "qualityGate": {
                             "type": "object",
                             "properties": {
@@ -2666,15 +2583,6 @@
                               }
                             },
                             "additionalProperties": true
-                          },
-                          "fidelityCheck": {
-                            "type": "object",
-                            "properties": {
-                              "enabled": {
-                                "type": "boolean"
-                              }
-                            },
-                            "additionalProperties": true
                           }
                         },
                         "additionalProperties": true
@@ -2747,32 +2655,10 @@
                             "type": "integer",
                             "exclusiveMinimum": 0
                           },
-                          "minPoolSize": {
-                            "type": "integer",
-                            "minimum": 0
-                          },
                           "maxChunkSize": {
                             "type": "integer",
                             "minimum": 1,
                             "maximum": 50
-                          },
-                          "p90ChunkSecondsDefault": {
-                            "type": "number",
-                            "exclusiveMinimum": 0
-                          },
-                          "antiCollapse": {
-                            "type": "object",
-                            "properties": {
-                              "enabled": {
-                                "type": "boolean"
-                              },
-                              "randomClusterFraction": {
-                                "type": "number",
-                                "minimum": 0,
-                                "maximum": 1
-                              }
-                            },
-                            "additionalProperties": true
                           }
                         },
                         "additionalProperties": true
@@ -2837,19 +2723,6 @@
                           "minPendingCount": {
                             "type": "integer",
                             "minimum": 0
-                          },
-                          "cls": {
-                            "type": "object",
-                            "properties": {
-                              "enabled": {
-                                "type": "boolean"
-                              },
-                              "adjacentCount": {
-                                "type": "integer",
-                                "minimum": 1
-                              }
-                            },
-                            "additionalProperties": true
                           }
                         },
                         "additionalProperties": true
@@ -3216,10 +3089,6 @@
                           "maxPerRun": {
                             "type": "integer",
                             "exclusiveMinimum": 0
-                          },
-                          "limit": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
                           }
                         },
                         "additionalProperties": true
@@ -3261,16 +3130,7 @@
             },
             "salience": {
               "type": "object",
-              "properties": {
-                "outcomeWeightEnabled": {
-                  "type": "boolean"
-                },
-                "salienceThreshold": {
-                  "type": "number",
-                  "minimum": 0,
-                  "maximum": 1
-                }
-              },
+              "properties": {},
               "additionalProperties": true
             },
             "stateGc": {
@@ -3623,15 +3483,6 @@
           },
           "additionalProperties": true
         },
-        "lowValueFilter": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean"
-            }
-          },
-          "additionalProperties": true
-        },
         "defectFilter": {
           "type": "object",
           "properties": {
@@ -3675,42 +3526,11 @@
           },
           "additionalProperties": true
         },
-        "fidelityCheck": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean"
-            }
-          },
-          "additionalProperties": true
-        },
-        "minPoolSize": {
-          "type": "integer",
-          "minimum": 0
-        },
         "maxChunkSize": {
           "type": "integer",
           "minimum": 1,
           "maximum": 50
         },
-        "p90ChunkSecondsDefault": {
-          "type": "number",
-          "exclusiveMinimum": 0
-        },
-        "antiCollapse": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean"
-            },
-            "randomClusterFraction": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 1
-            }
-          },
-          "additionalProperties": true
-        },
         "minPendingCount": {
           "type": "integer",
           "minimum": 0
@@ -4040,15 +3860,6 @@
                   },
                   "additionalProperties": true
                 },
-                "lowValueFilter": {
-                  "type": "object",
-                  "properties": {
-                    "enabled": {
-                      "type": "boolean"
-                    }
-                  },
-                  "additionalProperties": true
-                },
                 "defectFilter": {
                   "type": "object",
                   "properties": {
@@ -4143,10 +3954,6 @@
                     "minLength": 1
                   }
                 },
-                "limit": {
-                  "type": "integer",
-                  "exclusiveMinimum": 0
-                },
                 "qualityGate": {
                   "type": "object",
                   "properties": {
@@ -4222,15 +4029,6 @@
                     }
                   },
                   "additionalProperties": true
-                },
-                "fidelityCheck": {
-                  "type": "object",
-                  "properties": {
-                    "enabled": {
-                      "type": "boolean"
-                    }
-                  },
-                  "additionalProperties": true
                 }
               },
               "additionalProperties": true
@@ -4303,32 +4101,10 @@
                   "type": "integer",
                   "exclusiveMinimum": 0
                 },
-                "minPoolSize": {
-                  "type": "integer",
-                  "minimum": 0
-                },
                 "maxChunkSize": {
                   "type": "integer",
                   "minimum": 1,
                   "maximum": 50
-                },
-                "p90ChunkSecondsDefault": {
-                  "type": "number",
-                  "exclusiveMinimum": 0
-                },
-                "antiCollapse": {
-                  "type": "object",
-                  "properties": {
-                    "enabled": {
-                      "type": "boolean"
-                    },
-                    "randomClusterFraction": {
-                      "type": "number",
-                      "minimum": 0,
-                      "maximum": 1
-                    }
-                  },
-                  "additionalProperties": true
                 }
               },
               "additionalProperties": true
@@ -4393,19 +4169,6 @@
                 "minPendingCount": {
                   "type": "integer",
                   "minimum": 0
-                },
-                "cls": {
-                  "type": "object",
-                  "properties": {
-                    "enabled": {
-                      "type": "boolean"
-                    },
-                    "adjacentCount": {
-                      "type": "integer",
-                      "minimum": 1
-                    }
-                  },
-                  "additionalProperties": true
                 }
               },
               "additionalProperties": true
@@ -4772,10 +4535,6 @@
                 "maxPerRun": {
                   "type": "integer",
                   "exclusiveMinimum": 0
-                },
-                "limit": {
-                  "type": "integer",
-                  "exclusiveMinimum": 0
                 }
               },
               "additionalProperties": true

package/schemas/akm-task.json

@@ -196,7 +196,7 @@
       "additionalProperties": { "$ref": "#/definitions/jsonValue" }
     },
     "taskInputName": {
-      "description": "One `inputs:` declaration key. Matches the identifier pattern AND excludes every name `akm task run` reserves for its own flags (src/tasks/task-run-reserved-flags.ts's TASK_RUN_RESERVED_FLAG_NAMES — the union of TASK_RUN_VALUE_FLAGS, TASK_RUN_BOOLEAN_FLAGS, and TASK_RUN_SELF_DIAGNOSED_FLAGS) — declaring an input under one of these names is rejected at parse time (TASK_SOURCE_INVALID, parseInputDeclarations) because the CLI would always treat the flag as its own, never as this input's. `no-quiet`/`no-verbose` are citty's negations of the `quiet`/`verbose` booleans and are listed for completeness even though the identifier pattern already excludes any hyphenated name.",
+      "description": "One `inputs:` declaration key. Matches the identifier pattern AND excludes every name `akm task run` reserves for its own flags (src/tasks/task-run-reserved-flags.ts's TASK_RUN_RESERVED_FLAG_NAMES — the union of TASK_RUN_VALUE_FLAGS and TASK_RUN_BOOLEAN_FLAGS) — declaring an input under one of these names is rejected at parse time (TASK_SOURCE_INVALID, parseInputDeclarations) because the CLI would always treat the flag as its own, never as this input's. `no-quiet`/`no-verbose` are citty's negations of the `quiet`/`verbose` booleans and are listed for completeness even though the identifier pattern already excludes any hyphenated name.",
       "type": "string",
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
       "not": {
@@ -211,8 +211,7 @@
           "verbose",
           "help",
           "no-quiet",
-          "no-verbose",
-          "target"
+          "no-verbose"
         ]
       }
     },