akm-cli 0.9.7 → 0.9.8-beta.2

package/dist/workflows/parser.js

@@ -33,7 +33,7 @@
 import { LineCounter, parseDocument } from "yaml";
 import { parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { parseMarkdownToc } from "../core/asset/markdown.js";
-import { isContainedRelativePath } from "../core/common.js";
+import { isContainedRelativePath, isRecord } from "../core/common.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { checkJsonSchemaDefinition, JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS } from "../core/json-schema.js";
 import { parseReference } from "./program/expressions.js";
@@ -165,7 +165,7 @@ export function parseWorkflow(markdown, source) {
     };
     if (root === null || root === undefined)
         root = {};
-    if (!isPlainRecord(root)) {
+    if (!isRecord(root)) {
         return {
             ok: false,
             errors: [{ line: 2, message: `Workflow frontmatter must be a YAML mapping (key: value pairs).` }],
@@ -355,7 +355,7 @@ function checkEnvelopeFields(ctx, root, fmEndLine) {
             checkActorStamp(ctx, root.verified, ["verified"], `"verified"`);
         }
     }
-    if (root.provenance !== undefined && !isPlainRecord(root.provenance)) {
+    if (root.provenance !== undefined && !isRecord(root.provenance)) {
         ctx.err(["provenance"], `Workflow frontmatter "provenance" must be a mapping.`);
     }
     if (root.status !== undefined && (typeof root.status !== "string" || !LIFECYCLE_STATUSES.has(root.status))) {
@@ -368,7 +368,7 @@ function checkEnvelopeFields(ctx, root, fmEndLine) {
 function checkActorStamp(ctx, value, path, label) {
     if (value === undefined)
         return;
-    if (!isPlainRecord(value)) {
+    if (!isRecord(value)) {
         ctx.err(path, `Workflow frontmatter ${label} must be a mapping with a non-empty "by".`);
         return;
     }
@@ -402,7 +402,7 @@ function checkXrefs(ctx, value, fmEndLine) {
 function parseParams(ctx, raw) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(["params"], `"params" must be a mapping of param name to a JSON Schema object (e.g. changed_files: { type: array }).`);
         return undefined;
     }
@@ -412,7 +412,7 @@ function parseParams(ctx, raw) {
             ctx.err(["params", paramName], `Param name "${paramName}" is invalid. Use letters, digits, and underscores, starting with a letter or underscore, so "params.${paramName}" can address it.`);
             continue;
         }
-        if (!isPlainRecord(value)) {
+        if (!isRecord(value)) {
             ctx.err(["params", paramName], `Param "${paramName}" must be a JSON Schema object (e.g. { type: string }).`);
             continue;
         }
@@ -441,7 +441,7 @@ function parseParams(ctx, raw) {
 function parseOutputs(ctx, raw) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(["outputs"], `"outputs" must be a mapping of output name to { from, schema? } (e.g. report: { from: steps.summarize.output }).`);
         return undefined;
     }
@@ -453,7 +453,7 @@ function parseOutputs(ctx, raw) {
                 `underscore, so "steps.<child>.output.${outputName}" can address it.`);
             continue;
         }
-        if (!isPlainRecord(value)) {
+        if (!isRecord(value)) {
             ctx.err(path, `Output "${outputName}" must be a mapping with "from" (and optional "schema").`);
             continue;
         }
@@ -474,7 +474,7 @@ function parseOutputs(ctx, raw) {
         }
         const entry = { from: value.from };
         if (value.schema !== undefined) {
-            if (!isPlainRecord(value.schema)) {
+            if (!isRecord(value.schema)) {
                 ctx.err([...path, "schema"], `Output "${outputName}" "schema" must be a JSON Schema object.`);
             }
             else {
@@ -493,7 +493,7 @@ function parseDefaults(ctx, raw) {
     if (raw === undefined)
         return undefined;
     const path = ["defaults"];
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `"defaults" must be a mapping with any of: ${DEFAULTS_KEYS.join(", ")}.`);
         return undefined;
     }
@@ -525,7 +525,7 @@ function parseBudget(ctx, raw) {
     if (raw === undefined)
         return undefined;
     const path = ["budget"];
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `"budget" must be a mapping with any of: ${BUDGET_KEYS.join(", ")}.`);
         return undefined;
     }
@@ -558,7 +558,7 @@ function parseSteps(ctx, raw) {
     // (including ones that fail their own validation).
     const idIndex = new Map();
     raw.forEach((rawStep, index) => {
-        if (isPlainRecord(rawStep) && typeof rawStep.id === "string" && !idIndex.has(rawStep.id)) {
+        if (isRecord(rawStep) && typeof rawStep.id === "string" && !idIndex.has(rawStep.id)) {
             idIndex.set(rawStep.id, index);
         }
     });
@@ -567,7 +567,7 @@ function parseSteps(ctx, raw) {
     const routeChecks = [];
     raw.forEach((rawStep, index) => {
         const path = ["steps", index];
-        if (!isPlainRecord(rawStep)) {
+        if (!isRecord(rawStep)) {
             ctx.err(path, `Step ${index + 1} must be a mapping with an "id".`);
             return;
         }
@@ -655,7 +655,7 @@ function parseSteps(ctx, raw) {
 // Step blocks
 // ---------------------------------------------------------------------------
 function parseUnit(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "unit" must be a mapping (a dispatch-override bag).`);
         return undefined;
     }
@@ -733,7 +733,7 @@ function parseUnit(ctx, raw, path, stepLabel) {
  * keeps that decision visible in the frontmatter diff.
  */
 function parseExec(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "exec" must be a mapping with a "command" argv list.`);
         return undefined;
     }
@@ -832,7 +832,7 @@ function parseExecCwd(ctx, raw, path, stepLabel) {
     return value;
 }
 function parseMap(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "map" must be a mapping with an "over" key.`);
         return undefined;
     }
@@ -866,7 +866,7 @@ function parseMap(ctx, raw, path, stepLabel) {
     return map;
 }
 function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "route" must be a mapping with "input" and "when" keys.`);
         return undefined;
     }
@@ -888,7 +888,7 @@ function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
         const seenMatches = new Map();
         raw.when.forEach((branch, i) => {
             const branchPath = [...whenPath, i];
-            if (!isPlainRecord(branch)) {
+            if (!isRecord(branch)) {
                 ctx.err(branchPath, `${stepLabel} "when[${i}]" must be a mapping: { match, step }.`);
                 return;
             }
@@ -967,7 +967,7 @@ function parseInputs(ctx, raw, path, stepLabel) {
     return out.length > 0 ? out : undefined;
 }
 function parseGate(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "gate" must be a mapping with any of: ${GATE_KEYS.join(", ")}.`);
         return undefined;
     }
@@ -1009,7 +1009,7 @@ function parseEngineName(ctx, raw, path, label) {
 function parseRetry(ctx, raw, path, stepLabel) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "retry" must be a mapping: { max: <n>, on: [<failure_reason>, …] }.`);
         return undefined;
     }
@@ -1092,7 +1092,7 @@ function parseEnumField(ctx, raw, path, label, allowed) {
 function parseLlmOverrides(ctx, raw, path, label) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${label} must be a mapping of LLM invocation overrides.`);
         return undefined;
     }
@@ -1127,7 +1127,7 @@ function parseLlmOverrides(ctx, raw, path, label) {
             ctx.err([...path, "supports_json_schema"], `${label}.supports_json_schema must be a boolean.`);
     }
     if (raw.extra_params !== undefined) {
-        if (!isPlainRecord(raw.extra_params)) {
+        if (!isRecord(raw.extra_params)) {
             ctx.err([...path, "extra_params"], `${label}.extra_params must be a JSON object.`);
         }
         else {
@@ -1168,7 +1168,7 @@ function parseLlmOverrides(ctx, raw, path, label) {
 function parseSchemaObject(ctx, raw, path, label) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${label} must be a JSON Schema object (e.g. { type: object, properties: { … } }).`);
         return undefined;
     }
@@ -1212,9 +1212,6 @@ function checkUnknownKeys(ctx, obj, path, allowed, label) {
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
-function isPlainRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function describeError(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }

package/dist/workflows/source-files.js

@@ -12,20 +12,21 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { compareCodePoints, toPosix } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../core/recognition-util.js";
 export class WorkflowSourceRejectionError extends UsageError {
     sourcePaths;
     constructor(message, code, sourcePaths) {
         super(message, code);
-        this.sourcePaths = [...sourcePaths].sort(comparePaths);
+        this.sourcePaths = [...sourcePaths].sort(compareCodePoints);
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
     canonicalName;
     constructor(canonicalName, sourcePaths) {
-        const sorted = [...sourcePaths].sort(comparePaths);
+        const sorted = [...sourcePaths].sort(compareCodePoints);
         super(`Workflow "${canonicalName}" resolves to multiple workflow source files: ${sorted.join(", ")}. ` +
             "A canonical workflow ref must be owned by exactly one recognized .md or .yml source; remove or rename the duplicate.", "RESOURCE_ALREADY_EXISTS", sorted);
         this.name = "WorkflowSourceCollisionError";
@@ -36,8 +37,8 @@ export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
 export class WorkflowSourceDomainError extends WorkflowSourceRejectionError {
     canonicalName;
     constructor(canonicalName, sourcePaths, issues, collidingSourcePaths) {
-        const sortedPaths = [...sourcePaths].sort(comparePaths);
-        const sortedCollisions = [...collidingSourcePaths].sort(comparePaths);
+        const sortedPaths = [...sourcePaths].sort(compareCodePoints);
+        const sortedCollisions = [...collidingSourcePaths].sort(compareCodePoints);
         const code = issues.some((issue) => issue.code === "PATH_ESCAPE_VIOLATION")
             ? "PATH_ESCAPE_VIOLATION"
             : "WORKFLOW_SOURCE_INVALID";
@@ -169,7 +170,7 @@ export function listWorkflowSourceFiles(sourceRoot, adapterId, name) {
             extensionlessStem: entry.name.slice(0, -extension.length),
         });
     }
-    candidates.sort((left, right) => comparePaths(left.relativePath, right.relativePath));
+    candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
     const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
     if (issues.length > 0) {
         throw workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues);
@@ -229,9 +230,9 @@ export function resolveWorkflowSourceDomains(sourceRoot, adapterId, sourcePaths)
         candidatesByName.set(canonicalName, domain);
     }
     const resolutions = [];
-    for (const canonicalName of [...candidatesByName.keys()].sort(comparePaths)) {
+    for (const canonicalName of [...candidatesByName.keys()].sort(compareCodePoints)) {
         const candidates = candidatesByName.get(canonicalName) ?? [];
-        candidates.sort((left, right) => comparePaths(left.relativePath, right.relativePath));
+        candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
         const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
         const sourcePaths = candidates.map((candidate) => candidate.relativePath);
         if (issues.length > 0) {
@@ -365,9 +366,3 @@ function isWithinResolved(candidate, root) {
     const relative = path.relative(root, path.resolve(candidate));
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
-function toPosix(value) {
-    return value.replaceAll("\\", "/");
-}
-function comparePaths(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}

package/dist/workflows/source-ir/schema.js

@@ -10,12 +10,12 @@
  */
 import { types as utilTypes } from "node:util";
 import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { compareCodePoints, wellFormedUnicode } from "../../core/common.js";
 import { validateExtraParams } from "../../core/extra-params.js";
 import { checkJsonSchemaDefinition } from "../../core/json-schema.js";
 import { parseReference } from "../program/expressions.js";
 import { PROGRAM_RETRY_REASONS } from "../program/schema.js";
 import { jsonBytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
-import { compareWorkflowSourceCodePoints } from "./compare.js";
 import { canonicalizeWorkflowCron, canonicalizeWorkflowRun, canonicalizeWorkflowWorkingDirectory, classifyWorkflowStepUses, rejectNulInArgv, validateWorkflowBuiltinCommand, WorkflowSourceSemanticError, } from "./semantics.js";
 export const WORKFLOW_SOURCE_IR_VERSION = 1;
 export const WORKFLOW_SOURCE_IR_MAX_BYTES = 2 * 1024 * 1024;
@@ -269,9 +269,6 @@ function validateStep(value, jobId, index, stepIds, options) {
     extensions(step.extensions, `step ${id} extensions`);
     span(step.source, `step ${id} source`);
 }
-function compareCodePoints(left, right) {
-    return compareWorkflowSourceCodePoints(left, right);
-}
 function validateExec(value, location, options) {
     if (value === undefined)
         return;
@@ -692,21 +689,6 @@ function countJsonBytes(state, token) {
     if (state.bytes > WORKFLOW_SOURCE_IR_MAX_BYTES)
         fail("source IR exceeds the byte limit");
 }
-function wellFormedUnicode(value) {
-    for (let index = 0; index < value.length; index++) {
-        const code = value.charCodeAt(index);
-        if (code >= 0xd800 && code <= 0xdbff) {
-            const next = value.charCodeAt(index + 1);
-            if (!(next >= 0xdc00 && next <= 0xdfff))
-                return false;
-            index++;
-        }
-        else if (code >= 0xdc00 && code <= 0xdfff) {
-            return false;
-        }
-    }
-    return true;
-}
 function record(value, location) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         fail(`${location} must be an object`);

package/docs/migration/v0.9.0-troubleshooting.md

@@ -24,7 +24,17 @@ before that migration and tells you to run:
 akm upgrade --force
 ```
 
-Only a successful executable upgrade admits migration 018. Immediately before
+Where akm cannot reinstall itself — a container that ships the CLI globally,
+an unprivileged runtime user — that command fails at its install step
+(`EACCES` on the global module directory) before it ever reaches the
+migration. Use the install-free route instead:
+
+```sh
+akm upgrade --state-only
+```
+
+Both admit migration 018 and both take the same verified safety copy described
+below; `--state-only` simply skips the executable replacement. Immediately before
 the migration, AKM takes a SQLite writer-exclusion lock, rechecks the exact
 ledger, and writes a consistent SQLite snapshot beside the database as
 `state.db.pre-018-drop-dead-lane-schema.<UTC-digits>.<UUID>.bak`. The randomized
@@ -41,7 +51,7 @@ general storage migrator.
 
 An existing database with no applied migration IDs is never treated as a fresh
 install, whether its `schema_migrations` table is absent or empty. Ordinary
-commands reject it without writing. The explicit `akm upgrade --force` path
+commands reject it without writing. The explicit `akm upgrade --force` (or `--state-only`) path
 takes and verifies a descriptor-bound snapshot named
 `state.db.pre-001-initial-schema.<UTC-digits>.<UUID>.bak` before it creates the
 ledger or applies any migration from 001 through 022. A truly new database is

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.
@@ -1022,12 +1022,14 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 akm upgrade              # Download and replace the running binary
 akm upgrade --check      # Check for updates without installing
 akm upgrade --force      # Force upgrade even if already on latest
+akm upgrade --state-only # Apply pending state.db migrations; install nothing
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--check` | Check for updates without installing |
 | `--force` | Force upgrade even if on latest version |
+| `--state-only` | Apply pending `state.db` migrations without installing a new akm. For installs that cannot rewrite their own binary — a container shipping akm globally, an unprivileged runtime user — where the install step would fail `EACCES` before the migration could run. Takes the same verified safety copy as `--force`; it changes who may request the migration, not what it does. |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
 
 Checksum verification is not optional and has no flag. If a release's

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/docs/reference/workflow-schema.md

@@ -572,6 +572,30 @@ that declares an `output` schema is unaffected — an empty response is not
 valid JSON, so it fails as a parse error and can never satisfy a schema as a
 silent `null`.
 
+### When a step declares no `output:` schema
+
+A step-level `output:` schema is **optional**, and omitting it is a supported
+mode, not a deficiency. The step artifact is then exactly the value described
+above — the unit's result for a solo step, the collected array for a `map`
+step — carried untyped and never validated.
+
+The shape is stable either way: it does not depend on whether a schema is
+present, and it does not vary between a live run and a resume. `steps.<id>.output`
+resolves the same in both cases, so downstream references work with or without
+a schema.
+
+What a schema adds is **enforcement**, not shape. With one, the promoted
+artifact is checked against it and the step fails on mismatch; without one, a
+downstream reference to a field the artifact happens not to carry surfaces at
+resolution time instead (`steps.X.output is not an object — cannot resolve
+property "y"`). Declare `output:` when you want that mismatch caught at the
+producing step rather than at the consuming one.
+
+akm does not warn about a missing step `output:` schema. It briefly did, and
+the advisory was removed: it fired on essentially every step, could not be
+enforced (advisories never reach `--fail-on-flagged`), and flagged a state
+that is legitimate.
+
 ## Workflow outputs
 
 A workflow can declare a run-level export: the values a **completed run**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.7",
+  "version": "0.9.8-beta.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": [
@@ -77,17 +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",
-    "test:time": "bun scripts/test-timing-report.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",
-    "lint:devto-posts": "bun scripts/lint-devto-posts.ts",
-    "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-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": "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: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",

package/dist/workflows/source-ir/compare.js

@@ -1,17 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Locale-independent code-point ordering, shared by the workflow source-IR
- * lane (job `needs` canonicalization) and `akm lint` (name sorting).
- *
- * Split out of the deleted `source-ir/ordering.ts` (P4 §3.3, docs/plans/specs/
- * p4-deletions-closeout.md): that file's other export,
- * `canonicalTopologicalJobs`, existed only to order MULTIPLE ready jobs —
- * moot once the adapter confines a workflow source to exactly one job. This
- * comparator has an unrelated consumer (`src/commands/lint/index.ts`) and
- * survives on its own.
- */
-export function compareWorkflowSourceCodePoints(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}