akm-cli 0.9.8-beta.1 → 0.9.8-beta.3

package/dist/tasks/source/task-to-v3.js

@@ -112,6 +112,12 @@ function base(input) {
         ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
     };
 }
+/**
+ * #902: the one blocker with an unambiguous remedy. The sibling shell-safety
+ * reasons need a case-by-case judgement and stay reason-only.
+ */
+const ARGV_ARRAY_BLOCK_DETAIL = "Manual conversion required: an array `command:` has no safe v3 `run:` string. Rewrite it by hand as " +
+    "`run:` (string) plus `shell:` — see docs/migration/v0.9.1-to-v0.9.2.md for the full v2 to v4 field mapping.";
 function blocked(input, reason, detail) {
     return Object.freeze({ status: "blocked", ...base(input), reason, ...(detail ? { detail } : {}) });
 }
@@ -389,8 +395,10 @@ export function planLegacyTaskDataToV3(input, data) {
     catch (cause) {
         return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
     }
-    if (isReason(migrated))
-        return blocked(input, migrated);
+    if (isReason(migrated)) {
+        const detail = migrated === "argv-array-has-no-portable-shell-string" ? ARGV_ARRAY_BLOCK_DETAIL : undefined;
+        return blocked(input, migrated, detail);
+    }
     const after = Buffer.from(stringifyYaml(migrated), "utf8");
     try {
         parseTaskV3Yaml({

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -212,10 +212,24 @@ command: [node, scripts/release.js, "--exact value"]
 
 Shell-sensitive strings — assignments, shell builtins, reserved words, and
 similar constructs — are also blocked when translating them would invent
-shell semantics. The original bytes remain untouched. Author a v3 `run`
-string or a script/command asset deliberately, validate it, and rerun the
-preview. (This step still produces v3 output, which the second generation
-then carries the rest of the way to v4 in the same `akm migrate apply` run.)
+shell semantics. The original bytes remain untouched, and `akm migrate
+status`/`apply` names the block as `argv-array-has-no-portable-shell-string`
+(or a sibling shell-safety reason) rather than guessing: this is manual
+conversion, not a case the migrator can be re-run to fix. Rewrite the file
+by hand using this field mapping:
+
+| v2 | v4 |
+|---|---|
+| `command:` (array, argv style) | `run:` (string) plus `shell:` |
+| `timeoutMs:` | `timeout:` |
+| `enabled:` (document level) | removed — use `schedule:` as a list of `{cron, enabled}` entries |
+| `schedule:` (cron string) | still accepted as a bare string, or as the list form above |
+
+validate it, and rerun the preview. You can either write the replacement
+directly as `version: 4` (generation 1 then reports it `already-v4` and
+leaves it alone) or as a `version: 3` `run:` string, letting the second
+generation carry it the rest of the way to v4 in the same `akm migrate
+apply` run.
 
 ### Migrating task v3 to task source v4
 

package/docs/reference/cli.md

@@ -582,7 +582,7 @@ Subcommands:
 | `list` | List workflow runs (optionally filtered by `--ref`; `--active` shows only `status=active` runs, excluding `blocked`/`failed`/`completed`). Child workflow runs are excluded unless `--children` is passed |
 | `resume <run-id>` | Flip a `blocked` or `failed` run back to `active`. Completed runs cannot be resumed |
 | `abandon <run-id>` | Mark a run failed so it stops counting as active (`resume` can reopen it) |
-| `plan <ref>` | **Evolving.** Compile and freeze a workflow WITHOUT publishing a run: the canonical step graph, per-step frozen target kinds, task/child expansion, input bindings, source read set, and lowering notices — zero durable writes. Defaults to a human-readable summary; pass `--format json` for the full envelope |
+| `plan <ref>` | **Evolving.** Compile and freeze a workflow WITHOUT publishing a run: the canonical step graph, per-step frozen target kinds, task/child expansion, input bindings, source read set, and lowering notices — zero durable writes. Returns the full JSON envelope by default, like every other command; pass `--format text` for a human-readable summary |
 
 The public `workflow start`, `next`, and `complete` lifecycle was removed in
 0.9, along with the experimental `brief`/`report` external-driver protocol.

package/docs/reference/data-and-telemetry.md

@@ -60,6 +60,7 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 | `state.db` | Events, local usage telemetry, proposals, task history, improve run results, and workflow run state/history (the former `workflow.db` was folded in during the 0.9.0 cutover) | **No** — deletes event/usage logs, proposal queue, improve history, and workflow run history |
 | `logs.db` | Structured, high-volume task/run log lines (`{ts, task_id, run_id, stream, level, line}`), joined to `state.db`'s `task_history` rows by `task_id@started_at`. Kept separate from `state.db` because log lines are append-only and freely purgeable, unlike durable state | Yes — log lines are regenerable per run; deleting loses historical run output only |
 | `akm.lock` | Inter-process write lock | Yes — recreated automatically |
+| `backups/task-v3/`, `backups/task-v4/` | Copies of task files taken by `akm migrate apply` before it rewrites them, one timestamped directory per run; the five most recent per generation are kept (#897) | Yes — once the migrated tasks are verified |
 | `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
 
 Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.

package/docs/reference/tasks.md

@@ -325,6 +325,17 @@ for both generations combined. Resolve every blocked file manually, then
 preview again. Apply validates a complete replacement before writing and
 backs up each original immediately before replacement.
 
+Common v2 → v3 blocked reasons and what to do about each — these need a
+hand-authored replacement, not a re-run; see [the 0.9.1 to 0.9.2 migration
+guide](../migration/v0.9.1-to-v0.9.2.md#v2--v3-blocked-cases) for the full v2
+to v4 field mapping (`command:` array → `run:` + `shell:`, `timeoutMs:` →
+`timeout:`, document-level `enabled:` → per-`schedule:`-entry `enabled`):
+
+| Reason | Meaning | Fix |
+|---|---|---|
+| `argv-array-has-no-portable-shell-string` | The task's `command:` is an argv array; no single shell string is provably equivalent. | Rewrite the file by hand — a `run:` string plus `shell:` — using the field mapping above. |
+| `shell-quoting-changes-v2-whitespace-split-semantics`, `shell-operators-change-v2-literal-argv-semantics`, `shell-command-resolution-changes-v2-literal-argv-semantics` | The `command:` string contains quoting, shell operators, or a bare executable name whose v2 argv-exec behavior a v3 `run:` (host-shell) invocation cannot reproduce unambiguously. | Review the command's intended shell semantics and author the v3/v4 `run:`/`shell:` fields by hand. |
+
 Common v3 → v4 blocked reasons and what to do about each:
 
 | Reason | Meaning | Fix |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.8-beta.1",
+  "version": "0.9.8-beta.3",
   "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": [
@@ -77,14 +77,10 @@
     "test:integration": "bash scripts/test-integration.sh",
     "test:node-smoke": "bun scripts/node-smoke.ts",
     "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
-    "lint:isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
-    "lint:active-docs-terminology": "bun scripts/lint-active-docs-terminology.ts",
     "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-secret-resolver-boundary.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.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/",
     "format": "bunx biome format --write src/ tests/ scripts/",
     "prepublishOnly": "cp .github/README.npm.md README.md && bun run build",