akm-cli 0.9.0-rc.13 → 0.9.0-rc.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/CHANGELOG.md +117 -23
  2. package/dist/akm-migrate +3 -1
  3. package/dist/assets/hints/cli-hints-full.md +3 -4
  4. package/dist/assets/hints/cli-hints-short.md +5 -5
  5. package/dist/assets/workflows/workflow-template.md +4 -3
  6. package/dist/cli/invocation.js +3 -2
  7. package/dist/cli/retired-commands.js +3 -0
  8. package/dist/cli/unknown-flags.js +226 -0
  9. package/dist/cli.js +19 -35
  10. package/dist/commands/agent/contribute-cli.js +15 -3
  11. package/dist/commands/feedback-cli.js +6 -3
  12. package/dist/commands/improve/collapse-detector.js +2 -3
  13. package/dist/commands/lint/base-linter.js +4 -16
  14. package/dist/commands/lint/index.js +13 -13
  15. package/dist/commands/log.js +6 -1
  16. package/dist/commands/migration-tool.js +4 -5
  17. package/dist/commands/observability-cli.js +1 -1
  18. package/dist/commands/proposal/repository.js +5 -5
  19. package/dist/commands/read/knowledge.js +2 -0
  20. package/dist/commands/registry-cli.js +5 -3
  21. package/dist/commands/sources/add-cli.js +6 -6
  22. package/dist/commands/sources/self-update.js +30 -7
  23. package/dist/commands/sources/source-add.js +17 -2
  24. package/dist/commands/tasks/tasks.js +8 -3
  25. package/dist/commands/workflow-cli.js +142 -119
  26. package/dist/core/adapter/adapters/akm-lint.js +17 -13
  27. package/dist/core/adapter/adapters/akm-task-adapter.js +14 -11
  28. package/dist/core/asset/akm-markdown.js +41 -8
  29. package/dist/core/asset/frontmatter.js +22 -0
  30. package/dist/core/asset/resolve-ref.js +23 -3
  31. package/dist/core/common.js +45 -2
  32. package/dist/core/config/config-schema.js +8 -0
  33. package/dist/core/config/schema/experimental.js +5 -13
  34. package/dist/core/config/schema/sources-bundles.js +11 -0
  35. package/dist/core/config/schema/workflow.js +3 -1
  36. package/dist/core/errors.js +5 -0
  37. package/dist/core/logs-db.js +2 -1
  38. package/dist/core/parse.js +4 -1
  39. package/dist/core/state/migrations.js +11 -14
  40. package/dist/core/state-db.js +4 -6
  41. package/dist/core/subprocess.js +6 -4
  42. package/dist/core/type-presentation.js +1 -1
  43. package/dist/indexer/indexer.js +16 -1
  44. package/dist/indexer/search/search-source.js +1 -1
  45. package/dist/indexer/walk/matchers.js +3 -1
  46. package/dist/integrations/agent/config.js +2 -2
  47. package/dist/integrations/agent/detect.js +49 -19
  48. package/dist/integrations/agent/profiles.js +10 -0
  49. package/dist/integrations/agent/spawn.js +1 -2
  50. package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +7 -3
  51. package/dist/integrations/lockfile.js +11 -56
  52. package/dist/output/shapes/passthrough.js +0 -4
  53. package/dist/output/text/command-format.js +3 -3
  54. package/dist/output/text/helpers.js +1 -1
  55. package/dist/output/text/show-directives.js +4 -6
  56. package/dist/output/text/workflow-format.js +7 -62
  57. package/dist/output/text/workflow.js +1 -5
  58. package/dist/scripts/akm-migrate-node.js +58773 -0
  59. package/dist/scripts/akm-migrate.js +33976 -11391
  60. package/dist/setup/detect.js +40 -15
  61. package/dist/setup/setup.js +1 -1
  62. package/dist/sources/providers/git-stash.js +4 -2
  63. package/dist/sources/providers/website.js +5 -0
  64. package/dist/sources/snapshot-fetchers/bluesky.js +146 -0
  65. package/dist/sources/snapshot-fetchers/content-extract.js +370 -0
  66. package/dist/sources/snapshot-fetchers/fetcher-util.js +40 -0
  67. package/dist/sources/snapshot-fetchers/host-guard.js +199 -0
  68. package/dist/sources/snapshot-fetchers/registry.js +10 -1
  69. package/dist/sources/snapshot-fetchers/robots.js +348 -0
  70. package/dist/sources/snapshot-fetchers/rss.js +279 -0
  71. package/dist/sources/snapshot-fetchers/secret-seam.js +42 -0
  72. package/dist/sources/snapshot-fetchers/website-ingest.js +488 -257
  73. package/dist/sources/snapshot-fetchers/x.js +193 -0
  74. package/dist/storage/engines/sqlite-migrations.js +22 -107
  75. package/dist/tasks/runner.js +19 -16
  76. package/dist/tasks/schema.js +24 -1
  77. package/dist/workflows/exec/brief.js +1 -1
  78. package/dist/workflows/exec/frozen-judge.js +28 -2
  79. package/dist/workflows/exec/native-executor.js +18 -1
  80. package/dist/workflows/exec/report.js +11 -4
  81. package/dist/workflows/exec/run-workflow.js +103 -44
  82. package/dist/workflows/exec/step-work.js +19 -18
  83. package/dist/workflows/exec/unit-dispatch.js +4 -0
  84. package/dist/workflows/exec/workflow-engine-gate.js +11 -13
  85. package/dist/workflows/ir/compile.js +2 -2
  86. package/dist/workflows/ir/freeze.js +16 -8
  87. package/dist/workflows/ir/params.js +134 -10
  88. package/dist/workflows/ir/plan-hash.js +1 -1
  89. package/dist/workflows/ir/schema.js +6 -2
  90. package/dist/workflows/renderer.js +2 -2
  91. package/dist/workflows/runtime/checkin.js +3 -3
  92. package/dist/workflows/runtime/runs.js +50 -29
  93. package/dist/workflows/validate-summary.js +30 -14
  94. package/docs/migration/release-notes/0.9.0.md +31 -4
  95. package/docs/migration/v0.8-to-v0.9.md +69 -100
  96. package/docs/reference/data-and-telemetry.md +5 -5
  97. package/package.json +6 -2
  98. package/schemas/akm-config.json +24 -0
  99. package/schemas/akm-workflow.json +1 -1
  100. package/dist/workflows/cli.js +0 -33
@@ -2,23 +2,147 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /**
5
- * Run-parameter validation against the frozen plan's param schemas (reviewer
6
- * #12). A program can declare `params.files: { type: array }`; supplying
7
- * `--params '{"files":"not-an-array"}'` must be rejected at start rather than
8
- * silently flowing into a unit prompt. The schemas are frozen into the plan
9
- * ({@link WorkflowPlanGraph.paramSchemas}, program path only) so validation is
10
- * a pure function of the frozen plan and the supplied params — no live-asset
11
- * re-read.
5
+ * Run-parameter validation against the frozen plan's param schemas. A workflow
6
+ * can declare `params.files: { type: array }`; supplying a non-array through
7
+ * the exact-name `--files` flag must be rejected at start rather than silently
8
+ * flowing into a unit prompt. The schemas are frozen into the plan, so
9
+ * validation is a pure function of the frozen plan and supplied params.
12
10
  *
13
11
  * Uses the same bounded {@link validateJsonSchemaSubset} the engine applies to
14
- * unit output: undeclared params are permitted (the schema map only constrains
15
- * the params it names), and a workflow with no declared schemas (every Markdown
16
- * workflow, and programs without a `params:` block) validates trivially.
12
+ * unit output. Internal callers may validate partial parameter objects; the CLI
13
+ * separately rejects flags that do not exactly name declared parameters.
17
14
  *
18
15
  * Pure module: no IO, no engine imports.
19
16
  */
20
17
  import { UsageError } from "../../core/errors.js";
21
18
  import { validateJsonSchemaSubset } from "../../core/json-schema.js";
19
+ import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
20
+ /**
21
+ * Materialize exact-name CLI parameter flags against the plan being frozen for
22
+ * the run. The CLI deliberately carries raw values to this boundary so type
23
+ * coercion cannot race or drift from the persisted plan's schemas.
24
+ */
25
+ export function materializeWorkflowParameterFlags(plan, flags) {
26
+ if (flags.length === 0)
27
+ return {};
28
+ const declared = new Set(plan.params ?? Object.keys(plan.paramSchemas ?? {}));
29
+ const grouped = new Map();
30
+ for (const flag of flags) {
31
+ if (!PROGRAM_PARAM_NAME_PATTERN.test(flag.name) || !declared.has(flag.name)) {
32
+ const available = [...declared]
33
+ .sort()
34
+ .map((name) => `--${name}`)
35
+ .join(", ");
36
+ throw new UsageError(`Unknown workflow parameter "--${flag.name}". Parameter flags must exactly match a declared workflow parameter.`, "UNKNOWN_FLAG", available ? `Declared parameters: ${available}.` : "This workflow declares no parameters.");
37
+ }
38
+ const values = grouped.get(flag.name) ?? [];
39
+ values.push(flag.value);
40
+ grouped.set(flag.name, values);
41
+ }
42
+ const entries = [];
43
+ for (const [name, values] of grouped) {
44
+ const schema = plan.paramSchemas?.[name];
45
+ entries.push([name, materializeFlagValues(name, values, schema)]);
46
+ }
47
+ const params = Object.fromEntries(entries);
48
+ const errors = validateWorkflowParams(plan, params);
49
+ if (errors.length > 0) {
50
+ throw new UsageError(`Workflow parameter flags do not satisfy the workflow's declared schemas:\n${errors.map((error) => ` - ${error}`).join("\n")}`, "INVALID_FLAG_VALUE");
51
+ }
52
+ return params;
53
+ }
54
+ function materializeFlagValues(name, values, schema) {
55
+ const types = schemaTypes(schema);
56
+ if (types.includes("array")) {
57
+ if (values.length === 1 && typeof values[0] === "string" && values[0].trim().startsWith("[")) {
58
+ const parsed = parseJsonFlag(name, values[0]);
59
+ if (!Array.isArray(parsed))
60
+ throw invalidParameter(name, "must be a JSON array");
61
+ return parsed;
62
+ }
63
+ const itemSchema = isRecord(schema?.items) ? schema.items : undefined;
64
+ return values.map((value) => coerceFlagValue(name, value, itemSchema));
65
+ }
66
+ if (values.length > 1) {
67
+ throw invalidParameter(name, "was provided more than once but is not declared as an array");
68
+ }
69
+ return coerceFlagValue(name, values[0], schema);
70
+ }
71
+ function coerceFlagValue(name, raw, schema) {
72
+ const types = schemaTypes(schema);
73
+ if (types.length === 0)
74
+ return raw;
75
+ if (typeof raw === "boolean") {
76
+ if (types.includes("boolean"))
77
+ return raw;
78
+ if (types.includes("string"))
79
+ return String(raw);
80
+ throw invalidParameter(name, `requires a value of type ${types.join(" | ")}`);
81
+ }
82
+ // A union that permits strings keeps the user's exact text. This prevents a
83
+ // value such as "001" from being silently converted to a number.
84
+ if (types.includes("string"))
85
+ return raw;
86
+ for (const type of types) {
87
+ switch (type) {
88
+ case "boolean":
89
+ if (raw === "true")
90
+ return true;
91
+ if (raw === "false")
92
+ return false;
93
+ break;
94
+ case "number": {
95
+ const value = Number(raw);
96
+ if (raw.trim() !== "" && Number.isFinite(value))
97
+ return value;
98
+ break;
99
+ }
100
+ case "integer": {
101
+ const value = Number(raw);
102
+ if (raw.trim() !== "" && Number.isSafeInteger(value))
103
+ return value;
104
+ break;
105
+ }
106
+ case "null":
107
+ if (raw === "null")
108
+ return null;
109
+ break;
110
+ case "object": {
111
+ const parsed = parseJsonFlag(name, raw);
112
+ if (isRecord(parsed))
113
+ return parsed;
114
+ break;
115
+ }
116
+ case "array": {
117
+ const parsed = parseJsonFlag(name, raw);
118
+ if (Array.isArray(parsed))
119
+ return parsed;
120
+ break;
121
+ }
122
+ }
123
+ }
124
+ throw invalidParameter(name, `must be ${types.join(" | ")}; received ${JSON.stringify(raw)}`);
125
+ }
126
+ function schemaTypes(schema) {
127
+ const declared = schema?.type;
128
+ if (typeof declared === "string")
129
+ return [declared];
130
+ return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
131
+ }
132
+ function parseJsonFlag(name, raw) {
133
+ try {
134
+ return JSON.parse(raw);
135
+ }
136
+ catch {
137
+ throw invalidParameter(name, "must contain valid JSON");
138
+ }
139
+ }
140
+ function invalidParameter(name, message) {
141
+ return new UsageError(`Workflow parameter "--${name}" ${message}.`, "INVALID_FLAG_VALUE");
142
+ }
143
+ function isRecord(value) {
144
+ return typeof value === "object" && value !== null && !Array.isArray(value);
145
+ }
22
146
  /**
23
147
  * Validate a run's supplied params against the plan's frozen param schemas.
24
148
  * Returns a flat list of human-readable, path-prefixed error strings (empty =
@@ -4,7 +4,7 @@
4
4
  /**
5
5
  * Plan hashing for the frozen-plan contract (redesign addendum, R1).
6
6
  *
7
- * `workflow start` persists `plan_json` + `plan_hash` on the run row
7
+ * `workflow run` persists `plan_json` + `plan_hash` on the run row
8
8
  * (migration 006); every later invocation executes that snapshot. The hash is
9
9
  * the sha256 (hex) of the plan's CANONICAL JSON — object keys recursively
10
10
  * sorted — so two structurally-equal plans hash identically regardless of key
@@ -110,8 +110,12 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
110
110
  assertUnitEngineCompatibility(step.root, engines);
111
111
  if (step.gate.judge) {
112
112
  const judge = engines[step.gate.judge.engine];
113
- if (!judge || judge.kind !== "llm")
114
- fail(`gate ${step.gate.id} must reference an LLM engine`);
113
+ if (!judge)
114
+ fail(`gate ${step.gate.id} references an unavailable engine`);
115
+ if (judge.kind === "llm" && step.gate.judge.model === null)
116
+ fail(`LLM gate ${step.gate.id} has no exact model`);
117
+ if (judge.kind === "agent" && step.gate.judge.llm !== undefined)
118
+ fail(`agent gate ${step.gate.id} cannot carry LLM invocation settings`);
115
119
  }
116
120
  }
117
121
  return plan;
@@ -16,7 +16,7 @@ function shellQuote(value) {
16
16
  return `'${value.replace(/'/g, `'\\''`)}'`;
17
17
  }
18
18
  export function buildWorkflowAction(ref) {
19
- return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
19
+ return `Start or resume execution with \`akm workflow run ${shellQuote(ref)}\`.`;
20
20
  }
21
21
  function deriveName(ctx) {
22
22
  const metaName = ctx.matchResult.meta?.name;
@@ -117,7 +117,7 @@ export const workflowMdRenderer = {
117
117
  buildShowResponse(ctx) {
118
118
  const name = deriveName(ctx);
119
119
  const doc = loadDocument(ctx);
120
- // WI-8.5b (display flip): the `akm workflow next <ref>` action is DISPLAY
120
+ // WI-8.5b (display flip): the `akm workflow run <ref>` action is DISPLAY
121
121
  // output — its spelling follows the D-R5 display rule (`displayRef`). A
122
122
  // primary/default-bundle workflow renders the SHORT conceptId
123
123
  // (`workflows/<name>`); a named source qualifies it as
@@ -9,7 +9,7 @@
9
9
  * reconciles #506 (file/command-loop signal) with #501 (background thread) in
10
10
  * favour of the former. There is intentionally NO timer or resident process
11
11
  * here. Arming a check-in writes a timestamp (`checkin_armed_at`) on the run
12
- * row; the next time the agent polls the engine via `workflow next`/`status`,
12
+ * row; the next time the agent polls the engine via `workflow run`/`status`,
13
13
  * {@link evaluateCheckin} is called to decide — purely from timestamps — whether
14
14
  * the run looks stalled and a strong `continue` directive should be surfaced
15
15
  * through the normal command output.
@@ -48,8 +48,8 @@ export function evaluateCheckin(run, now = Date.now(), stallMs = CHECKIN_STALL_M
48
48
  return {
49
49
  signal: "continue",
50
50
  directive: "CONTINUE: this workflow run has stalled with no progress. Resume immediately — " +
51
- "re-read the current step's instructions, finish the outstanding work, then call " +
52
- "`akm workflow complete` with a summary. Do not stop until the step is complete.",
51
+ "inspect its status, then call `akm workflow run` with the run id to finish the outstanding work. " +
52
+ "Do not stop until the run reaches a terminal state or reports a verification rejection.",
53
53
  idleMs,
54
54
  agentHarness: run.agentHarness ?? null,
55
55
  agentSessionId: run.agentSessionId ?? null,
@@ -4,7 +4,7 @@
4
4
  import { randomUUID } from "node:crypto";
5
5
  import { parseBundleRef } from "../../core/asset/asset-ref.js";
6
6
  import { loadConfig } from "../../core/config/config.js";
7
- import { NotFoundError, UsageError } from "../../core/errors.js";
7
+ import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
8
8
  import { appendEvent } from "../../core/events.js";
9
9
  import { warn } from "../../core/warn.js";
10
10
  import { insertEventOnce } from "../../storage/repositories/events-repository.js";
@@ -14,7 +14,7 @@ import { frozenSummaryJudge } from "../exec/frozen-judge.js";
14
14
  import { detectSecretShapedParams } from "../exec/param-secrets.js";
15
15
  import { collectWorkflowWarnings } from "../ir/compile.js";
16
16
  import { compileResolveFreezeWorkflow } from "../ir/freeze.js";
17
- import { validateWorkflowParams } from "../ir/params.js";
17
+ import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
18
18
  import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
19
19
  import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "../ir/schema.js";
20
20
  import { validateStepSummary } from "../validate-summary.js";
@@ -71,20 +71,26 @@ export async function startWorkflowRun(ref, params = {}, options) {
71
71
  // later invocation executes this snapshot — the asset file is never re-read
72
72
  // for an in-flight run; re-planning is an explicit new run.
73
73
  const plan = decodeWorkflowPlanV3(compileResolveFreezeWorkflow(asset, loadConfig()).plan);
74
+ if (options?.parameterFlags?.length && Object.keys(params).length > 0) {
75
+ throw new UsageError("Workflow parameters must use either an object or per-parameter flags, not both.");
76
+ }
77
+ const effectiveParams = options?.parameterFlags?.length
78
+ ? materializeWorkflowParameterFlags(plan, options.parameterFlags)
79
+ : params;
74
80
  // Non-fatal WARNINGS: untyped-step and undeclared-param advisories surface
75
81
  // as `warn()` lines at start (stderr, consistent with the repo's other
76
82
  // author-facing warnings) without blocking the run.
77
83
  for (const w of collectWorkflowWarnings(asset.document)) {
78
- warn(`workflow start: ${asset.path}:${w.line} — ${w.message}`);
84
+ warn(`workflow run: ${asset.path}:${w.line} — ${w.message}`);
79
85
  }
80
- // Reviewer #12: validate supplied `--params` against the frozen param
86
+ // Reviewer #12: validate supplied parameters against the frozen param
81
87
  // schemas BEFORE creating the run, so a type-mismatched param (e.g. a string
82
88
  // for a `{ type: array }` param) is rejected with actionable errors instead
83
89
  // of flowing silently into a unit prompt. Programs without declared param
84
90
  // schemas (and every Markdown workflow) validate trivially.
85
- const paramErrors = validateWorkflowParams(plan, params);
91
+ const paramErrors = validateWorkflowParams(plan, effectiveParams);
86
92
  if (paramErrors.length > 0) {
87
- throw new UsageError(`Cannot start ${asset.ref}: the supplied --params do not satisfy the workflow's declared parameter schemas:\n` +
93
+ throw new UsageError(`Cannot start ${asset.ref}: the supplied parameters do not satisfy the workflow's declared schemas:\n` +
88
94
  paramErrors.map((e) => ` - ${e}`).join("\n"), "INVALID_JSON_ARGUMENT");
89
95
  }
90
96
  const planJson = canonicalPlanJson(plan);
@@ -105,8 +111,8 @@ export async function startWorkflowRun(ref, params = {}, options) {
105
111
  // Concurrency guard (#485): if an active run already exists in this
106
112
  // (workflow_ref, scope_key) pair, refuse to create a parallel run unless
107
113
  // `force: true` is set. Previously every call inserted unconditionally,
108
- // so two terminals running `akm workflow start <ref>` left two runs
109
- // racing; `akm workflow next` then non-deterministically picked one. The
114
+ // so two terminals starting the same workflow could leave two runs racing.
115
+ // The
110
116
  // active-alias query and all inserts now share this immediate transaction.
111
117
  // #506: arm a file-signal check-in (a timestamp, NOT a background thread —
112
118
  // per the workflow-agent check-in ADR) so a stalled run can be
@@ -117,7 +123,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
117
123
  const existing = repo.findActiveRunForScope(workflowRefs, scopeKey);
118
124
  if (existing) {
119
125
  throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
120
- `Use 'akm workflow next ${asset.ref}' to resume it, 'akm workflow abandon ${existing.id}' to give up on it, or pass --force to start a parallel run.`, "RESOURCE_ALREADY_EXISTS");
126
+ `Use 'akm workflow run ${asset.ref}' to resume it or 'akm workflow abandon ${existing.id}' to give up on it.`, "RESOURCE_ALREADY_EXISTS");
121
127
  }
122
128
  }
123
129
  repo.insertRun({
@@ -126,7 +132,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
126
132
  scopeKey,
127
133
  workflowEntryId,
128
134
  workflowTitle: asset.title,
129
- paramsJson: JSON.stringify(params),
135
+ paramsJson: JSON.stringify(effectiveParams),
130
136
  currentStepId,
131
137
  createdAt: now,
132
138
  updatedAt: now,
@@ -151,7 +157,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
151
157
  // without breaking the driver protocol). Surface a loud, best-effort warning
152
158
  // when a param LOOKS like a credential so the author moves it to an env
153
159
  // binding. Advisory only — never blocks the start.
154
- const secretWarnings = detectSecretShapedParams(params);
160
+ const secretWarnings = detectSecretShapedParams(effectiveParams);
155
161
  if (secretWarnings.length > 0)
156
162
  result.warnings = [...(result.warnings ?? []), ...secretWarnings];
157
163
  // 07 P1-B: emit only the run id + status — NOT the raw workflowTitle (which
@@ -230,9 +236,9 @@ export async function listWorkflowRuns(input) {
230
236
  .map(toWorkflowRunSummary),
231
237
  }));
232
238
  }
233
- export async function getNextWorkflowStep(specifier, params) {
239
+ export async function getNextWorkflowStep(specifier, params, options) {
234
240
  return withWorkflowRunsRepo(async (repo) => {
235
- const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
241
+ const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags);
236
242
  const steps = readWorkflowRunSteps(repo, run.id);
237
243
  const plan = requireExecutableWorkflowPlan(run);
238
244
  assertWorkflowSpineMatchesPlan(plan, run, steps);
@@ -387,15 +393,20 @@ export async function completeWorkflowStep(input) {
387
393
  if (input.status === "completed" && !summary) {
388
394
  throw new UsageError(`Completing step "${input.stepId}" requires a --summary describing the work done.`, "MISSING_REQUIRED_ARGUMENT");
389
395
  }
390
- // #506: validation gate — judge the summary against the step's
391
- // completionCriteria via the configured LLM. Fail-open when no criteria or no
392
- // judge. Only a well-formed `complete: false` blocks completion.
396
+ // #506: validation gate — a criteria-bearing step must have a frozen judge
397
+ // and receive an affirmative verdict before it can advance.
393
398
  if (input.status === "completed" && summary) {
394
399
  const criteria = preflight.stepPlan.gate.criteria;
400
+ if (input.signal?.aborted)
401
+ throw interruptionReason(input.signal);
395
402
  const judge = input.summaryJudge === undefined
396
- ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge)
403
+ ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge, input.signal)
397
404
  : input.summaryJudge;
398
- const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined);
405
+ if (criteria.length > 0 && !judge) {
406
+ throw new ConfigError(`Workflow run ${input.runId} has completion criteria for step "${input.stepId}" but its frozen plan has no judge. ` +
407
+ "Set workflow.judgeEngine, abandon this run, and create a new one with `akm workflow run <ref>`.", "INVALID_CONFIG_FILE");
408
+ }
409
+ const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined, input.signal);
399
410
  if (!verdict.complete) {
400
411
  // Re-arm the check-in so a subsequent stall is still nudged, but leave the
401
412
  // step pending and return corrective feedback instead of completing.
@@ -411,6 +422,8 @@ export async function completeWorkflowStep(input) {
411
422
  };
412
423
  }
413
424
  }
425
+ if (input.signal?.aborted)
426
+ throw interruptionReason(input.signal);
414
427
  return withWorkflowRunsRepo((repo) => {
415
428
  let updatedRun;
416
429
  let refreshedSteps = [];
@@ -436,6 +449,8 @@ export async function completeWorkflowStep(input) {
436
449
  if (run.current_step_id !== existing.step_id) {
437
450
  throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
438
451
  }
452
+ if (input.signal?.aborted)
453
+ throw interruptionReason(input.signal);
439
454
  const completedAt = new Date().toISOString();
440
455
  repo.updateStepCompletion({
441
456
  status: input.status,
@@ -485,11 +500,12 @@ export async function completeWorkflowStep(input) {
485
500
  return detail;
486
501
  });
487
502
  }
488
- async function resolveRunSpecifier(repo, specifier, params) {
503
+ async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
504
+ const hasParameters = (params && Object.keys(params).length > 0) || (parameterFlags?.length ?? 0) > 0;
489
505
  const explicitRun = repo.getRunById(specifier);
490
506
  if (explicitRun) {
491
- if (params && Object.keys(params).length > 0) {
492
- throw new UsageError(`--params can only be used when starting a new run from a workflow ref, not with an existing run id ("${specifier}")`);
507
+ if (hasParameters) {
508
+ throw new UsageError(`Workflow parameter flags can only be used when starting a new run, not with existing run id "${specifier}".`);
493
509
  }
494
510
  return { run: explicitRun, autoStarted: false };
495
511
  }
@@ -504,8 +520,8 @@ async function resolveRunSpecifier(repo, specifier, params) {
504
520
  }
505
521
  catch (error) {
506
522
  if (detached) {
507
- if (params && Object.keys(params).length > 0) {
508
- throw new UsageError(`--params can only be set on a new run; ${specifier} already has an active run`);
523
+ if (hasParameters) {
524
+ throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active.`);
509
525
  }
510
526
  return { run: detached, autoStarted: false };
511
527
  }
@@ -516,14 +532,19 @@ async function resolveRunSpecifier(repo, specifier, params) {
516
532
  }
517
533
  const active = repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
518
534
  if (active) {
519
- if (params && Object.keys(params).length > 0) {
520
- throw new UsageError(`--params can only be set on a new run; ${ref} already has an active run`);
535
+ if (hasParameters) {
536
+ throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active.`);
521
537
  }
522
538
  return { run: active, autoStarted: false };
523
539
  }
524
- const started = await startWorkflowRun(ref, params ?? {});
540
+ const started = await startWorkflowRun(ref, params ?? {}, {
541
+ ...(parameterFlags !== undefined ? { parameterFlags } : {}),
542
+ });
525
543
  return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
526
544
  }
545
+ function interruptionReason(signal) {
546
+ return signal.reason instanceof Error ? signal.reason : new Error("Workflow run interrupted.");
547
+ }
527
548
  async function canonicalizeWorkflowSpecifier(specifier) {
528
549
  return canonicalizeWorkflowRefInput(specifier);
529
550
  }
@@ -592,7 +613,7 @@ function readWorkflowRunSteps(repo, runId) {
592
613
  }
593
614
  function buildWorkflowRunDetail(run, steps) {
594
615
  // Review M1: `workflow status` (and every other detail-shaped response) now
595
- // evaluates the check-in, not just `workflow next`. Pure timestamp check —
616
+ // evaluates the check-in, not just `workflow run`. Pure timestamp check —
596
617
  // no background thread (see checkin.ts).
597
618
  const checkin = evaluateCheckin({
598
619
  status: run.status,
@@ -630,7 +651,7 @@ function toWorkflowRunSummary(run) {
630
651
  planIrVersion: plan.irVersion,
631
652
  executionSupport: plan.support,
632
653
  // Surface the engine lease (holder id + expiry — never workflow-authored
633
- // content) so `workflow next`/`status` show who is driving the run.
654
+ // content) so `workflow run`/`status` show who is driving the run.
634
655
  ...(run.engine_lease_holder && run.engine_lease_until
635
656
  ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
636
657
  : {}),
@@ -639,7 +660,7 @@ function toWorkflowRunSummary(run) {
639
660
  /**
640
661
  * Single-driver enforcement (R2 run lease): while a LIVE (unexpired) engine
641
662
  * lease is held, only the holding engine may advance the gate spine. Manual
642
- * `akm workflow complete` (no `leaseHolder`) — or a stale engine invocation
663
+ * A call with no `leaseHolder` — or a stale engine invocation
643
664
  * whose lease was claimed by another — is refused with the holder + expiry.
644
665
  * An EXPIRED lease never blocks: the engine that held it is presumed dead.
645
666
  */
@@ -9,10 +9,9 @@
9
9
  * demonstrates each criterion is met, and returns either a pass or structured
10
10
  * corrective feedback steering the agent on what to finish/fix.
11
11
  *
12
- * The LLM call is injected (`judge`) so the gate is unit-testable without a
13
- * live endpoint, and the whole gate is fail-open: when no criteria exist or no
14
- * judge is available the step completes as before (per the workflow-agent
15
- * check-in ADR).
12
+ * The judge call is injected so the gate is unit-testable without a live
13
+ * endpoint. A declared gate is fail-closed: only a well-formed affirmative
14
+ * verdict advances the step.
16
15
  *
17
16
  * @module workflows/validate-summary
18
17
  */
@@ -36,31 +35,45 @@ function buildUserPrompt(input) {
36
35
  /**
37
36
  * Run the summary-validation gate.
38
37
  *
39
- * Fail-open contract:
40
- * - no criteria → `{ complete: true, skipped: true }`
41
- * - no judge → `{ complete: true, skipped: true }`
42
- * - judge throws / returns unparseable → `{ complete: true, skipped: true }`
43
- *
44
- * Only a well-formed `complete: false` verdict blocks completion.
38
+ * No criteria skips verification. A missing, failing, or malformed judge is a
39
+ * rejection: declared criteria are never silently bypassed.
45
40
  */
46
- export async function validateStepSummary(input, judge) {
41
+ export async function validateStepSummary(input, judge, signal) {
47
42
  const criteria = input.completionCriteria.filter((c) => c.trim().length > 0);
48
43
  if (criteria.length === 0) {
49
44
  return { complete: true, missing: [], skipped: true };
50
45
  }
51
46
  if (!judge) {
52
- return { complete: true, missing: [], skipped: true };
47
+ return {
48
+ complete: false,
49
+ missing: criteria,
50
+ feedback: "This step declares completion criteria but no verification judge is available.",
51
+ };
53
52
  }
54
53
  let raw;
55
54
  try {
55
+ if (signal?.aborted)
56
+ throw interruptionReason(signal);
56
57
  raw = await judge({ system: JUDGE_SYSTEM, user: buildUserPrompt({ ...input, completionCriteria: criteria }) });
58
+ if (signal?.aborted)
59
+ throw interruptionReason(signal);
57
60
  }
58
61
  catch {
59
- return { complete: true, missing: [], skipped: true };
62
+ if (signal?.aborted)
63
+ throw interruptionReason(signal);
64
+ return {
65
+ complete: false,
66
+ missing: criteria,
67
+ feedback: "The verification judge failed. Retry after fixing the verifier configuration or service.",
68
+ };
60
69
  }
61
70
  const parsed = parseJsonResponse(raw);
62
71
  if (!parsed || typeof parsed.complete !== "boolean") {
63
- return { complete: true, missing: [], skipped: true };
72
+ return {
73
+ complete: false,
74
+ missing: criteria,
75
+ feedback: "The verification judge returned a malformed verdict instead of the required JSON result.",
76
+ };
64
77
  }
65
78
  if (parsed.complete) {
66
79
  return { complete: true, missing: [] };
@@ -74,3 +87,6 @@ export async function validateStepSummary(input, judge) {
74
87
  "Finish the outstanding work and resubmit with a summary that addresses each criterion.";
75
88
  return { complete: false, missing, feedback };
76
89
  }
90
+ function interruptionReason(signal) {
91
+ return signal.reason instanceof Error ? signal.reason : new Error("Workflow verification interrupted.");
92
+ }
@@ -81,10 +81,37 @@ Primary public command family for 0.9.0:
81
81
 
82
82
  ## Release validation
83
83
 
84
- Release validation passed on 2026-07-31. `bun run release:check` verified the
85
- packed npm installation, Node fallback and Bun launcher paths, migration and
86
- task execution from published 0.8.14, the Linux standalone scheduler artifact,
87
- 2,953 unit tests, 5,061 integration tests, and all seven Docker install targets.
84
+ Release validation was repeated on 2026-07-31. An isolated manual pass covered
85
+ 114 first-run, CLI, indexing, search/show, output-format, strict-flag,
86
+ tools-only agent classification, multi-bundle write/lint, workflow, task,
87
+ llm-wiki, env/secret, feedback/log, config/migration, health, upgrade, and
88
+ registry checks with no failures. `bun run release:check` verified the packed
89
+ npm installation, Node fallback and Bun launcher paths, migration and task
90
+ execution from published 0.8.14, the Linux standalone scheduler artifact,
91
+ 3,003 unit tests, 5,071 integration tests, and all seven Docker install targets.
92
+ The gated semantic-search suite passed 9 tests; Node 24 passed all 9 fallback
93
+ smoke steps and 25 compatibility tests.
94
+
95
+ The post-release checklist audit added a separate 125-check deterministic pass
96
+ for cross-bundle identity, write fidelity, output destinations, lint/task
97
+ behavior, env secrecy, durable log cursors, workflow transitions, proposal
98
+ dry-runs, setup recovery, fresh health initialization, and source-install
99
+ safety. It passed 125/125 on Linux. The current branch also passed
100
+ `bun run check` (3,005 unit and 5,072 integration tests) and `bun run build`.
101
+
102
+ A container-isolated follow-up passed 188 destructive crash/recovery checks,
103
+ including real `SIGKILL` windows across proposal, workflow, and lock journals,
104
+ plus deterministic interruption replay across phase-free migration sentinels.
105
+ The container also passed `release:check --skip-docker`, the seven-image
106
+ Docker install matrix, 9 semantic-search tests, all 9 Node 22 smoke steps, all
107
+ 25 Node compatibility tests, and the offline full gate (3,005 unit and 5,070
108
+ integration tests). This pass exposed and fixed host-scheduler and co-located
109
+ Node/Bun assumptions in three tests; no production behavior changed.
110
+
111
+ Live credential-backed agent/LLM calls and native macOS/Windows execution were
112
+ not run from this Linux host. Their deterministic paths remain covered by the
113
+ full unit/integration suite; release artifacts still require their normal
114
+ platform CI/release checks.
88
115
 
89
116
  Required upgrade checks:
90
117