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

package/dist/commands/workflow-cli.js

@@ -7,35 +7,37 @@
  * args/output shape are byte-identical. Handlers whose body is a plain
  * `runWithJsonErrors(...) + output(...)` are migrated to `defineJsonCommand`,
  * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
- * form. `workflow template` keeps a plain `defineCommand` because it writes the
- * template straight to stdout with no JSON envelope. The private helpers
- * `looksLikeWorkflowRunId` and `resolveWorkflowFilePath` move with the family.
+ * form.
+ *
+ * 0.9.0 CLI overhaul (S5): `workflow template` is dropped — `workflow create
+ * --print` prints the same content without writing. `workflow validate` is
+ * dropped — `akm lint --type workflows` covers structural validation.
+ * `workflow watch` is dropped — poll `akm log --since '@offset:<id>' --run
+ * <run-id>` instead. Workflows are markdown-only (workflow-format-
+ * unification) — `workflow create <name>.yaml` is a usage error.
  */
-import { defineCommand } from "citty";
-import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
+import { getParsedInvocation } from "../cli/invocation.js";
+import { getStringArg } from "../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
 import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
-import { resolveSourceEntries } from "../indexer/search/search-source.js";
-import { hasBooleanFlag } from "../output/context.js";
-import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
-import { resolveAssetPath } from "../sources/resolve.js";
-import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
-import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "../workflows/cli.js";
-import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
+import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
+import { parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES } from "../workflows/cli.js";
+import { requireWorkflowEngineEnabled } from "../workflows/exec/workflow-engine-gate.js";
+import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStartCommand = defineJsonCommand({
     meta: {
         name: "start",
         description: "Start a new workflow run in the current working scope",
     },
     args: {
-        ref: { type: "positional", description: "Workflow ref (workflow:<name>)", required: true },
+        ref: { type: "positional", description: "Workflow ref (workflows/<name>)", required: true },
         params: { type: "string", description: "Workflow parameters as a JSON object" },
         force: {
             type: "boolean",
-            description: "Allow a parallel run when an active run already exists in this scope (#485)",
+            description: "Allow a parallel run when an active run already exists in this scope",
             default: false,
         },
     },
@@ -57,45 +59,17 @@ const workflowNextCommand = defineJsonCommand({
     },
     async run({ args }) {
         // `--dry-run` is intentionally NOT a declared arg (so it stays out of
-        // --help). The guard reads it straight from process.argv so existing
-        // callers still get a clear, actionable error instead of a generic
-        // "unknown flag" from citty.
-        if (hasBooleanFlag(process.argv, "--dry-run")) {
+        // --help). The guard reads it straight from the invocation singleton so
+        // existing callers still get a clear, actionable error instead of a
+        // generic "unknown flag" from citty.
+        if (getParsedInvocation().hasFlag("--dry-run")) {
             throw new UsageError("`akm workflow next` does not support --dry-run. Remove the flag to start or resume a run.", "INVALID_FLAG_VALUE");
         }
         const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
-        // If the target looks like a UUID-style run id (no `:` and matches the
-        // run-id shape), short-circuit with a structured WORKFLOW_NOT_FOUND
-        // error before parseAssetRef gets to throw an unhelpful ref-parse error.
-        if (looksLikeWorkflowRunId(args.target)) {
-            const { hasWorkflowRun } = await import("../workflows/runtime/runs.js");
-            if (!(await hasWorkflowRun(args.target))) {
-                throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
-            }
-        }
         const result = await getNextWorkflowStep(args.target, parsedParams);
         output("workflow-next", result);
     },
 });
-/**
- * Heuristic: a workflow run id is a UUID-shaped or hex-id-shaped string with
- * no `:` separator (refs always contain a colon: `workflow:<name>` or
- * `<origin>//workflow:<name>`). When this matches we can give a much better
- * error than parseAssetRef's "Invalid asset type" failure.
- */
-function looksLikeWorkflowRunId(target) {
-    if (target.includes(":"))
-        return false;
-    if (target.includes("/"))
-        return false;
-    // UUID v4-ish: 8-4-4-4-12 hex digits separated by dashes.
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target))
-        return true;
-    // Bare hex/alphanumeric run ids of >=8 chars (covers shortened ids).
-    if (/^[0-9a-z][0-9a-z_-]{7,}$/i.test(target) && /[0-9]/.test(target))
-        return true;
-    return false;
-}
 const workflowCompleteCommand = defineJsonCommand({
     meta: {
         name: "complete",
@@ -139,35 +113,37 @@ const workflowStatusCommand = defineJsonCommand({
         description: "Show full workflow run state for review or resume; workflow refs resolve within the current scope",
     },
     args: {
-        target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
+        target: { type: "positional", description: "Workflow run id or workflow ref (workflows/<name>)", required: true },
+        units: {
+            type: "boolean",
+            description: "Also list per-unit rows from the run journal (unit id, status, failure_reason, and any result/error " +
+                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
+            default: false,
+        },
     },
     async run({ args }) {
         const target = args.target;
-        // Check if target looks like a workflow ref
-        const parsed = (() => {
-            try {
-                return parseAssetRef(target);
-            }
-            catch {
-                return null;
-            }
-        })();
-        if (parsed?.type === "workflow") {
-            const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-            const { runs } = await listWorkflowRuns({ workflowRef: ref });
-            if (runs.length === 0) {
-                throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            }
-            const mostRecent = runs[0];
-            if (!mostRecent)
-                throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            const result = await getWorkflowStatus(mostRecent.id);
+        const includeUnits = args.units === true;
+        if (await hasWorkflowRun(target)) {
+            const result = await getWorkflowStatus(target, { includeUnits });
             output("workflow-status", result);
+            return;
         }
-        else {
-            const result = await getWorkflowStatus(target);
-            output("workflow-status", result);
+        let runs;
+        try {
+            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
         }
+        catch (error) {
+            if (!target.includes(":") && !target.includes("/")) {
+                throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
+            }
+            throw error;
+        }
+        const mostRecent = runs[0];
+        if (!mostRecent)
+            throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
+        const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
+        output("workflow-status", result);
     },
 });
 const workflowListCommand = defineJsonCommand({
@@ -187,19 +163,22 @@ const workflowListCommand = defineJsonCommand({
 const workflowCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
-        description: "Create a workflow markdown document in the working stash",
+        description: "Create a workflow (markdown document) in the working bundle",
     },
     args: {
         name: {
             type: "positional",
-            description: "Workflow name (flat, no '/'; use --path for a subdirectory)",
+            description: "Workflow name (flat, no '/'; use --path for a subdirectory).",
             required: true,
         },
         path: {
             type: "string",
             description: "Relative subdirectory under workflows/ to place the workflow in (e.g. 'release'). The filename comes from the name.",
         },
-        from: { type: "string", description: "Import and validate markdown from an existing file" },
+        from: {
+            type: "string",
+            description: "Import and validate content from an existing file",
+        },
         force: {
             type: "boolean",
             description: "Overwrite an existing workflow (requires --from or --reset)",
@@ -210,6 +189,11 @@ const workflowCreateCommand = defineJsonCommand({
             description: "Explicitly replace an existing workflow with a fresh template (use with --force)",
             default: false,
         },
+        print: {
+            type: "boolean",
+            description: "Print the RAW template that would be written to stdout without creating anything — pipe it to a file as a starter document",
+            default: false,
+        },
     },
     async run({ args }) {
         // `name` is flat; subdirectory placement is `--path`'s job.
@@ -219,6 +203,14 @@ const workflowCreateCommand = defineJsonCommand({
         if (!namePattern.test(effectiveName)) {
             throw new UsageError("Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, dots, underscores, and slashes.");
         }
+        assertWorkflowMarkdownName(effectiveName);
+        if (args.print) {
+            // Raw document, not an envelope — the retired `workflow template` was
+            // format-exempt for the same reason: `--print > starter.md` must yield
+            // a usable starter file, not `{ok,template,kind}` JSON.
+            process.stdout.write(getWorkflowTemplate());
+            return;
+        }
         if (args.force && !args.from && !args.reset) {
             throw new UsageError("Refusing to overwrite with template: pass --from <file> to replace content, or --reset to explicitly replace with a fresh template.");
         }
@@ -234,61 +226,180 @@ const workflowCreateCommand = defineJsonCommand({
         output("workflow-create", { ok: true, ...result });
     },
 });
-const workflowTemplateCommand = defineCommand({
+const workflowRunCommand = defineJsonCommand({
     meta: {
-        name: "template",
-        description: "Print a valid workflow markdown template",
+        name: "run",
+        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: execute a workflow's steps with the native " +
+            "engine — akm dispatches each step's units (fan-out, schema output) to the configured runner and advances " +
+            "the run through the normal completion gates",
     },
-    run() {
-        process.stdout.write(getWorkflowTemplate());
+    args: {
+        target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
+        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
+        "max-steps": { type: "string", description: "Stop after executing this many steps" },
+    },
+    async run({ args }) {
+        requireWorkflowEngineEnabled(loadConfig(), "run");
+        const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
+        const rawMaxSteps = getStringArg(args, "max-steps");
+        let maxSteps;
+        if (rawMaxSteps !== undefined) {
+            maxSteps = Number.parseInt(rawMaxSteps, 10);
+            if (!/^\d+$/.test(rawMaxSteps) || maxSteps <= 0) {
+                throw new UsageError(`--max-steps must be a positive integer, got "${rawMaxSteps}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        const result = await runWorkflowSteps({
+            target: args.target,
+            ...(args.params ? { params: parseWorkflowJsonObject(args.params, "--params") } : {}),
+            ...(maxSteps !== undefined ? { maxSteps } : {}),
+        });
+        output("workflow-run", result);
     },
 });
-const workflowValidateCommand = defineJsonCommand({
+const workflowBriefCommand = defineJsonCommand({
     meta: {
-        name: "validate",
-        description: "Validate a workflow markdown file or ref and print any errors",
+        name: "brief",
+        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: describe a run's active step as an executable " +
+            "work-list for ANY agent session (the harness-neutral driver protocol) — read-only, takes no engine lease, " +
+            "mutates nothing; prints per-unit instructions, output schema, env binding names, and the exact " +
+            "`akm workflow report` command lines",
     },
     args: {
         target: {
             type: "positional",
-            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md",
+            description: "Workflow run id (or a workflow ref with an active run)",
             required: true,
         },
     },
     async run({ args }) {
-        const filePath = await resolveWorkflowFilePath(args.target);
-        const { parse } = validateWorkflowSource(filePath);
-        if (parse.ok) {
-            output("workflow-validate", {
-                ok: true,
-                path: filePath,
-                title: parse.document.title,
-                stepCount: parse.document.steps.length,
+        requireWorkflowEngineEnabled(loadConfig(), "brief");
+        const { buildWorkflowBrief } = await import("../workflows/exec/brief.js");
+        const result = await buildWorkflowBrief(args.target);
+        output("workflow-brief", result);
+    },
+});
+const WORKFLOW_REPORT_STATES = ["completed", "failed", "running"];
+const workflowReportCommand = defineJsonCommand({
+    meta: {
+        name: "report",
+        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: report a unit's result back into a run (the " +
+            "mutating half of the harness-neutral driver protocol) — ingested through the SAME shared step semantics " +
+            "the engine uses. --status running claims/" +
+            "heartbeats a unit; completed/failed records it and, when the step's work-list is fully terminal, runs the " +
+            "engine's completion path (reducer, artifact + schema validation, gate). --settle (no --unit) advances a run " +
+            "parked on a route-only/empty step. Refused while a live engine lease exists",
+    },
+    args: {
+        target: {
+            type: "positional",
+            description: "Workflow run id (or a workflow ref with an active run)",
+            required: true,
+        },
+        unit: {
+            type: "string",
+            description: "Content-derived unit id from `akm workflow brief` (copy it verbatim). Omit with --settle.",
+        },
+        settle: {
+            type: "boolean",
+            description: "Advance/finalize a run whose active step has NO unit left to report: a non-dispatching step (params-based route, empty fan-out, all-unresolvable) OR a fully-terminal step still needing finalization (every unit ran but the gate never judged — e.g. after resuming a required-gate block). Runs the deterministic completion path. Mutually exclusive with --unit; refused when the step still has genuinely pending units",
+            default: false,
+        },
+        "expect-step": {
+            type: "string",
+            description: "Guard: the step id you briefed against. Refuses the report if the run's active step has since moved (from the `brief` report/settle command line)",
+        },
+        status: { type: "string", description: `Unit status: ${WORKFLOW_REPORT_STATES.join(", ")}` },
+        result: { type: "string", description: "Result payload (JSON for a schema unit, else text). completed only." },
+        "result-file": { type: "string", description: "Read the result payload from this file instead of --result/stdin" },
+        tokens: { type: "string", description: "Tokens spent on this unit (counts against a declared budget)" },
+        "session-id": { type: "string", description: "Harness-native session id revealed while executing the unit" },
+        "failure-reason": { type: "string", description: "Structured failure vocabulary for a --status failed report" },
+        note: { type: "string", description: "Short progress note for a --status running heartbeat (not persisted)" },
+        rerun: {
+            type: "boolean",
+            description: "Re-run an already-FAILED unit: record a NEW attempt (re-applies budget) instead of refusing a differing re-report",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        requireWorkflowEngineEnabled(loadConfig(), "report");
+        // --settle: the unit-less verb that advances a run parked on a
+        // non-dispatching step. Mutually exclusive with the per-unit report flags.
+        if (args.settle === true) {
+            if (getStringArg(args, "unit") !== undefined || getStringArg(args, "status") !== undefined) {
+                throw new UsageError("--settle advances a route-only/empty step and takes no --unit or --status. Drop them, or report a " +
+                    "specific unit with `--unit <id> --status <state>` instead.", "INVALID_FLAG_VALUE");
+            }
+            const { settleWorkflowSpine } = await import("../workflows/exec/report.js");
+            const result = await settleWorkflowSpine({
+                target: args.target,
+                ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
             });
+            output("workflow-report", result);
             return;
         }
-        throw new UsageError(formatWorkflowErrors(filePath, parse.errors));
-    },
-});
-async function resolveWorkflowFilePath(target) {
-    if (!target.startsWith("workflow:"))
-        return target;
-    const parsed = parseAssetRef(target);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${target}".`);
-    }
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    for (const source of searchSources) {
-        try {
-            return await resolveAssetPath(source.path, "workflow", parsed.name);
+        const status = args.status;
+        if (!status) {
+            throw new UsageError("--status is required (completed | failed | running), or pass --settle to advance a non-dispatching step.", "MISSING_REQUIRED_ARGUMENT");
         }
-        catch {
-            /* try next source */
+        if (!WORKFLOW_REPORT_STATES.includes(status)) {
+            throw new UsageError(`Invalid --status "${status}". Expected one of: ${WORKFLOW_REPORT_STATES.join(", ")}.`, "INVALID_FLAG_VALUE");
         }
-    }
-    throw new UsageError(`Workflow not found for ref: workflow:${parsed.name}`);
+        const unitId = getStringArg(args, "unit");
+        if (!unitId) {
+            throw new UsageError("--unit is required (the content-derived unit id from `akm workflow brief`), or pass --settle for a route-only/empty step.", "MISSING_REQUIRED_ARGUMENT");
+        }
+        let tokens;
+        const rawTokens = getStringArg(args, "tokens");
+        if (rawTokens !== undefined) {
+            tokens = Number.parseInt(rawTokens, 10);
+            if (!/^\d+$/.test(rawTokens)) {
+                throw new UsageError(`--tokens must be a non-negative integer, got "${rawTokens}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        // Result payload precedence: --result, then --result-file, then stdin
+        // (completed/failed only; a running heartbeat carries no result).
+        let resultRaw;
+        if (status !== "running") {
+            const resultFile = getStringArg(args, "result-file");
+            if (args.result !== undefined && resultFile !== undefined) {
+                throw new UsageError("Pass at most one of --result or --result-file.", "INVALID_FLAG_VALUE");
+            }
+            if (args.result !== undefined) {
+                resultRaw = String(args.result);
+            }
+            else if (resultFile !== undefined) {
+                const fs = await import("node:fs");
+                resultRaw = fs.readFileSync(resultFile, "utf8");
+            }
+            else if (!process.stdin.isTTY) {
+                resultRaw = await readStdin();
+            }
+        }
+        const { reportWorkflowUnit } = await import("../workflows/exec/report.js");
+        const result = await reportWorkflowUnit({
+            target: args.target,
+            unitId,
+            status: status,
+            ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
+            ...(resultRaw !== undefined ? { resultRaw } : {}),
+            ...(tokens !== undefined ? { tokens } : {}),
+            ...(args.rerun === true ? { rerun: true } : {}),
+            ...(getStringArg(args, "session-id") !== undefined ? { sessionId: getStringArg(args, "session-id") } : {}),
+            ...(getStringArg(args, "failure-reason") !== undefined
+                ? { failureReason: getStringArg(args, "failure-reason") }
+                : {}),
+            ...(getStringArg(args, "note") !== undefined ? { note: getStringArg(args, "note") } : {}),
+        });
+        output("workflow-report", result);
+    },
+});
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
 }
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
@@ -316,7 +427,7 @@ const workflowResumeCommand = defineJsonCommand({
         output("workflow-resume", result);
     },
 });
-export const workflowCommand = defineCommand({
+export const workflowCommand = defineGroupCommand({
     meta: {
         name: "workflow",
         description: "Author, inspect, and execute step-by-step workflow assets",
@@ -328,16 +439,16 @@ export const workflowCommand = defineCommand({
         status: workflowStatusCommand,
         list: workflowListCommand,
         create: workflowCreateCommand,
-        template: workflowTemplateCommand,
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
-        validate: workflowValidateCommand,
-    },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasWorkflowSubcommand(args))
-                return;
-            output("workflow-list", await listWorkflowRuns({ activeOnly: true }));
-        });
-    },
+        run: workflowRunCommand,
+        brief: workflowBriefCommand,
+        report: workflowReportCommand,
+    },
+    // No `defaultRun`: bare `akm workflow` is a usage error (exit 2), the
+    // canonical bare-group behavior — owner ruling 12. Run `akm workflow list
+    // --active` for what the bare form used to print. This group was previously
+    // hand-rolled on `defineCommand` with its own `hasWorkflowSubcommand` guard,
+    // which duplicated the subcommand names in a second hand-maintained set;
+    // `defineGroupCommand` derives the guard from `subCommands` directly.
 });

package/dist/core/action-contributors.js

@@ -1,7 +1,7 @@
 // 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/.
-import { defaultRendererRegistry } from "./asset/asset-registry.js";
+import { defaultRendererRegistry } from "./type-presentation.js";
 function registryActionContributor(registry) {
     return {
         name: "registry-action-contributor",

package/dist/core/activation-policy.js

@@ -0,0 +1,49 @@
+// 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/.
+/**
+ * Decide whether injecting an env with the given dangerous keys is allowed,
+ * warned, or blocked. Third-party (registry-installed) stashes hard-block;
+ * first-party stashes warn. See rule 1 above.
+ *
+ * @param dangerousKeys The subset of injected keys flagged as process-hijacking
+ *   (already filtered by the caller via `isDangerousEnvKey`).
+ * @param thirdParty `true` when the env's source is a third-party stash — i.e.
+ *   its origin carries a `registryId`.
+ */
+export function decideDangerousEnvInjection(input) {
+    if (input.dangerousKeys.length === 0)
+        return "allow";
+    return input.thirdParty ? "block" : "warn";
+}
+/**
+ * Decide the baseline install stance for a freshly-installed stash's
+ * dangerous-key scan. The interactive confirm / rollback UX is applied by the
+ * caller on top of the `"gate"` stance — this predicate only fixes the policy.
+ * See rule 2 above.
+ */
+export function decideDangerousKeyInstall(input) {
+    if (!input.findingsPresent)
+        return "allow";
+    return input.allowInsecure ? "warn-allow" : "gate";
+}
+// ── Rule 3: task activation (tasks/runner.ts) ────────────────────────────────
+/**
+ * Whether a scheduler-generated task invocation must be skipped because the
+ * task is not activated (its `enabled:` is false). Manual (non-scheduled) runs
+ * are always dispatched — installing a task grants nothing until enabled, but
+ * the operator may still run it by hand for catch-up / testing. See rule 3.
+ */
+export function shouldSkipUnactivatedTask(input) {
+    return !input.enabled && input.scheduled;
+}
+// ── Rule 4: write activation (search-source.ts, installations.ts) ────────────
+/**
+ * Whether a resolved source is write-activated. Only the primary stash and
+ * sources explicitly marked `writable: true` are writable; registry-cached
+ * (installed, read-only) sources are never written in place because
+ * `akm update` overwrites them. See rule 4 above.
+ */
+export function isSourceWriteActivated(source) {
+    return source.writable === true;
+}