akm-cli 0.8.7 → 0.8.14

package/dist/workflows/{runs.js → runtime/runs.js}

@@ -3,61 +3,76 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import { parseAssetRef } from "../core/asset-ref";
-import { loadConfig } from "../core/config";
-import { NotFoundError, UsageError } from "../core/errors";
-import { appendEvent } from "../core/events";
-import { getDbPath } from "../core/paths";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
-import { resolveSourceEntries } from "../indexer/search-source";
-import { resolveSourcesForOrigin } from "../registry/origin-resolve";
-import { resolveAssetPath } from "../sources/resolve";
-import { formatWorkflowErrors } from "./authoring";
-import { closeWorkflowDatabase, openWorkflowDatabase } from "./db";
-import { parseWorkflow } from "./parser";
-import { getCurrentWorkflowScopeKey } from "./scope-key";
-async function withWorkflowDb(fn) {
-    const db = openWorkflowDatabase();
-    try {
-        return await Promise.resolve(fn(db));
-    }
-    finally {
-        closeWorkflowDatabase(db);
-    }
-}
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { getDbPath } from "../../core/paths.js";
+import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
+import { formatWorkflowErrors } from "../authoring/authoring.js";
+import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
+import { parseWorkflow } from "../parser.js";
+import { validateStepSummary } from "../validate-summary.js";
+import { resolveAgentIdentity } from "./agent-identity.js";
+import { evaluateCheckin } from "./checkin.js";
 export async function startWorkflowRun(ref, params = {}, options) {
     const asset = await loadWorkflowAsset(ref);
-    return withWorkflowDb(async (db) => {
+    return withWorkflowRunsRepo(async (repo) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
         const currentStepId = asset.steps[0]?.id ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
+        // Capture the agent harness + session driving this run. Explicit options
+        // win; otherwise fall back to best-effort environment detection. This is
+        // identity-only — no background thread or timer is started here.
+        const detected = resolveAgentIdentity();
+        const agentHarness = options?.agentHarness !== undefined ? options.agentHarness : detected.harness;
+        const agentSessionId = options?.agentSessionId !== undefined ? options.agentSessionId : detected.sessionId;
         // Concurrency guard (#485): if an active run already exists in this
         // (workflow_ref, scope_key) pair, refuse to create a parallel run unless
         // `force: true` is set. Previously every call inserted unconditionally,
         // so two terminals running `akm workflow start <ref>` left two runs
         // racing; `akm workflow next` then non-deterministically picked one.
         if (!options?.force) {
-            const existing = db
-                .prepare("SELECT id, current_step_id FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
-                .get(asset.ref, scopeKey);
+            const existing = repo.findActiveRunForScope(asset.ref, scopeKey);
             if (existing) {
                 throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
                     `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");
             }
         }
-        db.transaction(() => {
-            db.prepare(`INSERT INTO workflow_runs (
-          id, workflow_ref, scope_key, workflow_entry_id, workflow_title, status, params_json, current_step_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`).run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
-            const insertStep = db.prepare(`INSERT INTO workflow_run_steps (
-          run_id, step_id, step_title, instructions, completion_json, sequence_index, status
-        ) VALUES (?, ?, ?, ?, ?, ?, 'pending')`);
-            for (const step of asset.steps) {
-                insertStep.run(runId, step.id, step.title, step.instructions, step.completionCriteria ? JSON.stringify(step.completionCriteria) : null, step.sequenceIndex ?? 0);
-            }
-        })();
+        // #506: arm a file-signal check-in (a timestamp, NOT a background thread —
+        // see docs/technical/workflow-agent-checkin-adr.md) so a stalled run can be
+        // re-targeted with a `continue` directive. The agent harness + session id
+        // are already resolved above (agentHarness/agentSessionId, from #501).
+        repo.transaction(() => {
+            repo.insertRun({
+                id: runId,
+                workflowRef: asset.ref,
+                scopeKey,
+                workflowEntryId,
+                workflowTitle: asset.title,
+                paramsJson: JSON.stringify(params),
+                currentStepId,
+                createdAt: now,
+                updatedAt: now,
+                agentHarness,
+                agentSessionId,
+                checkinArmedAt: now,
+            });
+            repo.insertSteps(asset.steps.map((step) => ({
+                runId,
+                stepId: step.id,
+                stepTitle: step.title,
+                instructions: step.instructions,
+                completionJson: step.completionCriteria ? JSON.stringify(step.completionCriteria) : null,
+                sequenceIndex: step.sequenceIndex ?? 0,
+            })));
+        });
         const result = await getWorkflowStatus(runId);
         appendEvent({
             eventType: "workflow_started",
@@ -68,49 +83,49 @@ export async function startWorkflowRun(ref, params = {}, options) {
     });
 }
 export async function getWorkflowStatus(runId) {
-    return withWorkflowDb((db) => {
-        const run = readWorkflowRun(db, runId);
-        const steps = readWorkflowRunSteps(db, run.id);
+    return withWorkflowRunsRepo((repo) => {
+        const run = readWorkflowRun(repo, runId);
+        const steps = readWorkflowRunSteps(repo, run.id);
         return buildWorkflowRunDetail(run, steps);
     });
 }
 export async function hasWorkflowRun(runId) {
-    return withWorkflowDb((db) => {
-        const row = db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
-        return !!row;
-    });
+    return withWorkflowRunsRepo((repo) => repo.hasRun(runId));
 }
 export async function listWorkflowRuns(input) {
-    return withWorkflowDb((db) => {
-        const filters = [];
-        const params = [];
+    return withWorkflowRunsRepo((repo) => {
         const scopeKey = getCurrentWorkflowScopeKey();
-        filters.push("scope_key = ?");
-        params.push(scopeKey);
+        let workflowRef;
         if (input?.workflowRef) {
             const parsed = parseAssetRef(input.workflowRef);
             if (parsed.type !== "workflow") {
                 throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${input.workflowRef}".`);
             }
-            filters.push("workflow_ref = ?");
-            params.push(`${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`);
+            workflowRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
         }
-        if (input?.activeOnly) {
-            filters.push("status IN ('active', 'blocked')");
-        }
-        const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
-        const rows = db
-            .prepare(`SELECT * FROM workflow_runs ${where} ORDER BY updated_at DESC, created_at DESC`)
-            .all(...params);
+        const rows = repo.listRuns({
+            scopeKey,
+            ...(workflowRef ? { workflowRef } : {}),
+            ...(input?.activeOnly ? { activeOnly: true } : {}),
+        });
         return { runs: rows.map(toWorkflowRunSummary) };
     });
 }
 export async function getNextWorkflowStep(specifier, params) {
-    return withWorkflowDb(async (db) => {
-        const { run, autoStarted } = await resolveRunSpecifier(db, specifier, params);
-        const steps = readWorkflowRunSteps(db, run.id);
+    return withWorkflowRunsRepo(async (repo) => {
+        const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
+        const steps = readWorkflowRunSteps(repo, run.id);
         const currentStep = resolveCurrentStep(run, steps);
         const done = run.status === "completed" ? true : undefined;
+        // #506: surface a check-in directive through the normal command output when
+        // the run looks stalled. Pure timestamp evaluation — no background thread.
+        const checkin = evaluateCheckin({
+            status: run.status,
+            updatedAt: run.updated_at,
+            checkinArmedAt: run.checkin_armed_at,
+            agentHarness: run.agent_harness,
+            agentSessionId: run.agent_session_id,
+        }) ?? undefined;
         return {
             run: toWorkflowRunSummary(run),
             workflow: {
@@ -121,47 +136,90 @@ export async function getNextWorkflowStep(specifier, params) {
             step: currentStep ? toWorkflowRunStepState(currentStep) : null,
             ...(done ? { done } : {}),
             ...(autoStarted ? { autoStarted } : {}),
+            ...(checkin ? { checkin } : {}),
         };
     });
 }
 export async function resumeWorkflowRun(runId) {
-    return withWorkflowDb((db) => {
-        const run = readWorkflowRun(db, runId);
+    return withWorkflowRunsRepo((repo) => {
+        const run = readWorkflowRun(repo, runId);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
-            const steps = readWorkflowRunSteps(db, run.id);
+            const steps = readWorkflowRunSteps(repo, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
         // it can be reclassified (completed, failed, skipped) after resuming.
         const now = new Date().toISOString();
-        db.transaction(() => {
+        repo.transaction(() => {
             if (run.current_step_id) {
-                db.prepare(`UPDATE workflow_run_steps
-             SET status = 'pending', notes = NULL, evidence_json = NULL, completed_at = NULL
-             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`).run(run.id, run.current_step_id);
+                repo.reopenStepsForResume(run.id, run.current_step_id);
             }
-            db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
-        })();
+            repo.markRunActive(run.id, now);
+        });
         const updated = { ...run, status: "active", updated_at: now };
-        const steps = readWorkflowRunSteps(db, run.id);
+        const steps = readWorkflowRunSteps(repo, run.id);
         return buildWorkflowRunDetail(updated, steps);
     });
 }
 export async function completeWorkflowStep(input) {
-    return withWorkflowDb((db) => {
+    // Read the step (read-only) up front so the LLM validation gate runs OUTSIDE
+    // the write transaction — a slow/hung LLM must never hold a db write lock.
+    const preflight = await withWorkflowRunsRepo((repo) => {
+        const run = readWorkflowRun(repo, input.runId);
+        if (run.status !== "active") {
+            throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
+        }
+        const existing = repo.getStep(run.id, input.stepId);
+        if (!existing) {
+            throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
+        }
+        if (existing.status !== "pending") {
+            throw new UsageError(`Step "${input.stepId}" is already ${existing.status} in workflow run ${run.id}.`);
+        }
+        if (run.current_step_id !== existing.step_id) {
+            throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
+        }
+        return { existing };
+    });
+    const summary = input.summary?.trim();
+    // #506: completing a step requires a summary of the work done.
+    if (input.status === "completed" && !summary) {
+        throw new UsageError(`Completing step "${input.stepId}" requires a --summary describing the work done.`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    // #506: validation gate — judge the summary against the step's
+    // completionCriteria via the configured LLM. Fail-open when no criteria or no
+    // judge. Only a well-formed `complete: false` blocks completion.
+    if (input.status === "completed" && summary) {
+        const criteria = parseJsonArray(preflight.existing.completion_json) ?? [];
+        const judge = input.summaryJudge === undefined ? buildDefaultSummaryJudge() : input.summaryJudge;
+        const verdict = await validateStepSummary({ stepTitle: preflight.existing.step_title, completionCriteria: criteria, summary }, judge ?? undefined);
+        if (!verdict.complete) {
+            // Re-arm the check-in so a subsequent stall is still nudged, but leave the
+            // step pending and return corrective feedback instead of completing.
+            await withWorkflowRunsRepo((repo) => {
+                repo.rearmCheckin(input.runId, new Date().toISOString());
+            });
+            return {
+                ok: false,
+                runId: input.runId,
+                stepId: input.stepId,
+                missing: verdict.missing,
+                feedback: verdict.feedback ?? "The summary does not satisfy the step's completion criteria.",
+            };
+        }
+    }
+    return withWorkflowRunsRepo((repo) => {
         let updatedRun;
         let refreshedSteps = [];
-        db.transaction(() => {
-            const run = readWorkflowRun(db, input.runId);
+        repo.transaction(() => {
+            const run = readWorkflowRun(repo, input.runId);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
-            const existing = db
-                .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? AND step_id = ?")
-                .get(run.id, input.stepId);
+            const existing = repo.getStep(run.id, input.stepId);
             if (!existing) {
                 throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
             }
@@ -172,22 +230,36 @@ export async function completeWorkflowStep(input) {
                 throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
             }
             const completedAt = new Date().toISOString();
-            db.prepare(`UPDATE workflow_run_steps
-           SET status = ?, notes = ?, evidence_json = ?, completed_at = ?
-           WHERE run_id = ? AND step_id = ?`).run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
-            refreshedSteps = readWorkflowRunSteps(db, run.id);
+            repo.updateStepCompletion({
+                status: input.status,
+                notes: input.notes?.trim() || null,
+                evidenceJson: input.evidence ? JSON.stringify(input.evidence) : null,
+                summary: summary || null,
+                completedAt,
+                runId: run.id,
+                stepId: input.stepId,
+            });
+            refreshedSteps = readWorkflowRunSteps(repo, run.id);
             const state = deriveRunState(refreshedSteps);
-            db.prepare(`UPDATE workflow_runs
-           SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?
-           WHERE id = ?`).run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
+            // Re-arm the check-in on every state change: a healthy, progressing run
+            // keeps pushing the stall window forward so the directive never fires.
+            repo.updateRunState({
+                status: state.status,
+                currentStepId: state.currentStepId,
+                updatedAt: completedAt,
+                completedAt: state.completedAt,
+                checkinArmedAt: completedAt,
+                runId: run.id,
+            });
             updatedRun = {
                 ...run,
                 status: state.status,
                 current_step_id: state.currentStepId,
                 updated_at: completedAt,
                 completed_at: state.completedAt,
+                checkin_armed_at: completedAt,
             };
-        })();
+        });
         const detail = buildWorkflowRunDetail(updatedRun, refreshedSteps);
         appendEvent({
             eventType: "workflow_step_completed",
@@ -200,8 +272,8 @@ export async function completeWorkflowStep(input) {
         return detail;
     });
 }
-async function resolveRunSpecifier(db, specifier, params) {
-    const explicitRun = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(specifier);
+async function resolveRunSpecifier(repo, specifier, params) {
+    const explicitRun = repo.getRunById(specifier);
     if (explicitRun) {
         if (params && Object.keys(params).length > 0) {
             throw new UsageError(`--params can only be used when starting a new run from a workflow ref, not with an existing run id ("${specifier}")`);
@@ -217,9 +289,7 @@ async function resolveRunSpecifier(db, specifier, params) {
     }
     const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
     const scopeKey = getCurrentWorkflowScopeKey();
-    const active = db
-        .prepare("SELECT * FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
-        .get(ref, scopeKey);
+    const active = repo.getActiveRunRowForScope(ref, scopeKey);
     if (active) {
         if (params && Object.keys(params).length > 0) {
             throw new UsageError(`--params can only be set on a new run; ${ref} already has an active run`);
@@ -227,7 +297,7 @@ async function resolveRunSpecifier(db, specifier, params) {
         return { run: active, autoStarted: false };
     }
     const started = await startWorkflowRun(ref, params ?? {});
-    return { run: readWorkflowRun(db, started.run.id), autoStarted: true };
+    return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
 }
 async function loadWorkflowAsset(ref) {
     const parsed = parseAssetRef(ref);
@@ -338,17 +408,15 @@ function resolveWorkflowEntryId(sourcePath, ref) {
         closeDatabase(db);
     }
 }
-function readWorkflowRun(db, runId) {
-    const run = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId);
+function readWorkflowRun(repo, runId) {
+    const run = repo.getRunById(runId);
     if (!run) {
         throw new NotFoundError(`Workflow run "${runId}" not found.`, "WORKFLOW_NOT_FOUND");
     }
     return run;
 }
-function readWorkflowRunSteps(db, runId) {
-    return db
-        .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? ORDER BY sequence_index ASC")
-        .all(runId);
+function readWorkflowRunSteps(repo, runId) {
+    return repo.getStepsForRun(runId);
 }
 function buildWorkflowRunDetail(run, steps) {
     return {
@@ -373,6 +441,8 @@ function toWorkflowRunSummary(run) {
         updatedAt: run.updated_at,
         completedAt: run.completed_at,
         params: parseJsonObject(run.params_json),
+        agentHarness: run.agent_harness ?? null,
+        agentSessionId: run.agent_session_id ?? null,
     };
 }
 function toWorkflowRunStepState(step) {
@@ -385,6 +455,7 @@ function toWorkflowRunStepState(step) {
         status: step.status,
         notes: step.notes ?? undefined,
         evidence: parseJsonObject(step.evidence_json),
+        summary: step.summary ?? undefined,
         completedAt: step.completed_at,
     };
 }
@@ -414,6 +485,33 @@ function deriveRunState(steps) {
         .at(-1);
     return { status: "completed", currentStepId: null, completedAt: completedAt ?? null };
 }
+/**
+/**
+ * Build the default summary-validation judge from the configured LLM, or return
+ * `null` when no LLM is configured (gate is then skipped — fail-open). Lazily
+ * imports the client/config so the workflow engine has no hard LLM dependency.
+ */
+function buildDefaultSummaryJudge() {
+    let llm;
+    try {
+        const config = loadConfig();
+        const { getDefaultLlmConfig } = require("../../core/config/config");
+        llm = getDefaultLlmConfig(config);
+    }
+    catch {
+        return null;
+    }
+    if (!llm)
+        return null;
+    const resolved = llm;
+    return async ({ system, user }) => {
+        const { chatCompletion } = require("../../llm/client");
+        return chatCompletion(resolved, [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ]);
+    };
+}
 function parseJsonObject(value) {
     if (!value)
         return undefined;
@@ -443,10 +541,8 @@ function parseJsonArray(value) {
     return undefined;
 }
 export async function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
-    return withWorkflowDb((db) => {
-        const row = db
-            .query("SELECT id, current_step_id, workflow_ref FROM workflow_runs WHERE scope_key = ? AND status IN ('active', 'blocked') ORDER BY updated_at DESC LIMIT 1")
-            .get(scopeKey);
+    return withWorkflowRunsRepo((repo) => {
+        const row = repo.findActiveOrBlockedRunForScope(scopeKey);
         if (!row)
             return null;
         return { runId: row.id, stepId: row.current_step_id, workflowRef: row.workflow_ref };

package/dist/workflows/validate-summary.js

@@ -0,0 +1,82 @@
+// 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/.
+/**
+ * Summary-validation gate for workflow step/workflow completion (#506).
+ *
+ * Takes a step's `completionCriteria` and the summary of work the agent claims
+ * to have done, asks the configured LLM to judge whether the summary
+ * demonstrates each criterion is met, and returns either a pass or structured
+ * corrective feedback steering the agent on what to finish/fix.
+ *
+ * The LLM call is injected (`judge`) so the gate is unit-testable without a
+ * live endpoint, and the whole gate is fail-open: when no criteria exist or no
+ * judge is available the step completes as before. See
+ * docs/technical/workflow-agent-checkin-adr.md.
+ *
+ * @module workflows/validate-summary
+ */
+import { parseJsonResponse } from "../core/parse.js";
+const JUDGE_SYSTEM = "You are a strict completion auditor for a software workflow engine. " +
+    "Given a step's completion criteria and a summary of the work an agent claims to have done, " +
+    "judge whether the summary provides concrete evidence that EVERY criterion is satisfied. " +
+    "Be skeptical: vague, hand-wavy, or unsubstantiated claims do NOT satisfy a criterion. " +
+    'Respond with ONLY a JSON object: {"complete": boolean, "missing": string[], "feedback": string}. ' +
+    '"missing" lists the exact criteria that are not yet satisfied; "feedback" is a short directive ' +
+    "telling the agent what to finish or fix. No prose, no markdown fences.";
+function buildUserPrompt(input) {
+    const criteria = input.completionCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+    return [
+        `Step: ${input.stepTitle}`,
+        "",
+        "Completion criteria:",
+        criteria,
+        "",
+        "Agent's summary of work done:",
+        input.summary.trim(),
+        "",
+        "Return the JSON verdict now.",
+    ].join("\n");
+}
+/**
+ * Run the summary-validation gate.
+ *
+ * Fail-open contract:
+ *  - no criteria → `{ complete: true, skipped: true }`
+ *  - no judge → `{ complete: true, skipped: true }`
+ *  - judge throws / returns unparseable → `{ complete: true, skipped: true }`
+ *
+ * Only a well-formed `complete: false` verdict blocks completion.
+ */
+export async function validateStepSummary(input, judge) {
+    const criteria = input.completionCriteria.filter((c) => c.trim().length > 0);
+    if (criteria.length === 0) {
+        return { complete: true, missing: [], skipped: true };
+    }
+    if (!judge) {
+        return { complete: true, missing: [], skipped: true };
+    }
+    let raw;
+    try {
+        raw = await judge({ system: JUDGE_SYSTEM, user: buildUserPrompt({ ...input, completionCriteria: criteria }) });
+    }
+    catch {
+        // LLM unreachable / errored — fail open so offline use keeps working.
+        return { complete: true, missing: [], skipped: true };
+    }
+    const parsed = parseJsonResponse(raw);
+    if (!parsed || typeof parsed.complete !== "boolean") {
+        return { complete: true, missing: [], skipped: true };
+    }
+    if (parsed.complete) {
+        return { complete: true, missing: [] };
+    }
+    const missing = Array.isArray(parsed.missing)
+        ? parsed.missing.filter((m) => typeof m === "string" && m.trim().length > 0)
+        : [];
+    const feedback = typeof parsed.feedback === "string" && parsed.feedback.trim().length > 0
+        ? parsed.feedback.trim()
+        : "The summary does not yet demonstrate every completion criterion is met. " +
+            "Finish the outstanding work and resubmit with a summary that addresses each criterion.";
+    return { complete: false, missing, feedback };
+}

package/docs/README.md

@@ -31,7 +31,7 @@
 
 ## Operations
 
-- Analyzing `akm improve` runs -- use [`akm health`](../src/commands/health.ts) (0.8.0+): `--since`, `--detail per-run`, `--window-compare`, `--windows`. See [health-command-enhancements.md](technical/health-command-enhancements.md).
+- Analyzing `akm improve` runs -- use [`akm health`](../src/commands/health.ts) (0.8.0+): `--since`, `--group-by run`, `--window-compare`, `--windows`. See [health-command-enhancements.md](technical/health-command-enhancements.md).
 
 ## Internals
 

package/docs/data-and-telemetry.md

@@ -76,7 +76,7 @@ Override: set `AKM_STASH_DIR` (or configure `stashDir` in `config.json`).
 
 ### 1. Events Table
 
-An append-only log of every mutating action you perform with AKM. Events are stored locally for self-improvement (the improve loop uses them to surface usage patterns) and for inspection via `akm events`.
+An append-only log of every mutating action you perform with AKM. Events are stored locally for self-improvement (the improve loop uses them to surface usage patterns) and for inspection via `akm log`.
 
 **What is recorded:**
 - `event_type` — what action was taken (see full list below)
@@ -101,7 +101,7 @@ An append-only log of every mutating action you perform with AKM. Events are sto
 | `update` | `akm update [source]` | `ref` |
 | `remember` | `akm remember <text>` | `ref` |
 | `import` | `akm import <file>` | `ref` |
-| `save` | `akm save <ref>` | `ref` |
+| `save` | `akm sync` | `ref` |
 | `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
 | `search` | `akm search <query>` | `query`, `source`, `signal` |
 | `curate` | `akm curate <prompt>` | `query`, `source` |
@@ -154,16 +154,16 @@ A record of scheduled task runs (from `akm tasks`):
 
 ```sh
 # List recent events
-akm events list
+akm log list
 
 # Stream live events (tail)
-akm events tail
+akm log tail
 
 # Filter by type
-akm events list --type search --limit 20
+akm log list --type search --limit 20
 
 # Filter by asset ref
-akm events list --ref skill:code-review
+akm log list --ref skill:code-review
 ```
 
 ### Inspect proposals