akm-cli 0.8.0-rc2 → 0.8.0

package/dist/commands/tasks.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * `akm tasks` — register, inspect, run, and remove scheduled task assets.
  *
@@ -7,7 +10,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
+import { stringify as yamlStringify } from "yaml";
 import { resolveAssetPathFromName } from "../core/asset-spec";
 import { isWithin, resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
@@ -21,10 +24,16 @@ import { resolveAkmInvocation } from "../tasks/resolveAkmBin";
 import { exitCodeForStatus, readTaskHistory, runTask } from "../tasks/runner";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../tasks/schedule";
 import { validateTaskDocument } from "../tasks/validator";
+import { resolveImproveProfile } from "./improve-profiles";
 export async function akmTasksAdd(input) {
     const id = normaliseTaskId(input.id);
-    if ((input.workflow && input.prompt) || (!input.workflow && !input.prompt)) {
-        throw new UsageError("Pass exactly one of --workflow <ref> or --prompt <inline|asset-ref|./file.md>.", "INVALID_FLAG_VALUE");
+    const hasCommand = input.command !== undefined &&
+        input.command !== null &&
+        !(typeof input.command === "string" && input.command.trim() === "") &&
+        !(Array.isArray(input.command) && input.command.length === 0);
+    const targetCount = [Boolean(input.workflow), Boolean(input.prompt), hasCommand].filter(Boolean).length;
+    if (targetCount !== 1) {
+        throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <asset-ref|./file.md|text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
     }
     // Validate the schedule for the active backend before writing anything.
     const backend = backendNameForPlatform();
@@ -39,20 +48,23 @@ export async function akmTasksAdd(input) {
     if (fs.existsSync(assetPath) && !input.force) {
         throw new UsageError(`Task "${id}" already exists. Pass --force to overwrite, or use \`akm tasks remove ${id}\` first.`, "RESOURCE_ALREADY_EXISTS");
     }
-    const markdown = renderTaskMarkdown({
+    const yaml = renderTaskYaml({
         id,
         schedule: input.schedule,
         workflow: input.workflow,
         prompt: input.prompt,
+        command: input.command,
         profile: input.profile,
         params: input.params,
+        name: input.name,
         description: input.description,
+        when_to_use: input.when_to_use,
         tags: input.tags,
         enabled: input.disabled !== true,
     });
-    const task = parseTaskDocument({ markdown, filePath: assetPath, id });
+    const task = parseTaskDocument({ yaml, filePath: assetPath, id });
     await validateTaskDocument(task, { backend, stashDir });
-    fs.writeFileSync(assetPath, markdown.endsWith("\n") ? markdown : `${markdown}\n`, "utf8");
+    fs.writeFileSync(assetPath, yaml.endsWith("\n") ? yaml : `${yaml}\n`, "utf8");
     // Install in the OS scheduler. If install fails after the file was written,
     // delete the file so the on-disk state never claims a task is registered
     // when it isn't.
@@ -80,19 +92,58 @@ export async function akmTasksAdd(input) {
         target: task.target,
     };
 }
+/**
+ * Emit a single grouped stderr warning for legacy `.md` task files in the
+ * tasks directory. 0.8.0 requires task definitions to be pure `.yml`; any
+ * leftover `.md` files from 0.7.x would otherwise be silently skipped, which
+ * makes scheduled tasks vanish without operator notice. We do NOT auto-migrate
+ * — that is a separate workstream — but operators must see the affected files.
+ *
+ * `seen` is module-level so the warning is emitted at most once per process,
+ * even when both `akm tasks list` and `akm tasks sync` are invoked in the same
+ * akm run.
+ */
+const warnedLegacyMdDirs = new Set();
+function warnLegacyMdTaskFiles(typeRoot) {
+    if (warnedLegacyMdDirs.has(typeRoot))
+        return;
+    let mdFiles;
+    try {
+        mdFiles = fs.readdirSync(typeRoot).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return;
+    }
+    if (mdFiles.length === 0)
+        return;
+    warnedLegacyMdDirs.add(typeRoot);
+    const affected = mdFiles.map((f) => `tasks/${f}`).join(", ");
+    process.stderr.write(`WARNING: ${mdFiles.length} task file(s) use the legacy .md format and were ignored.\n` +
+        `         AKM 0.8.0 requires tasks as pure .yml. See docs/migration/v0.7-to-v0.8.md#task-definition-files-mdfrontmatter--yml.\n` +
+        `         Affected: ${affected}\n`);
+}
+/**
+ * Reset the legacy `.md` task warning de-duplication state. Test-only escape
+ * hatch — production code should never call this.
+ */
+export function _resetLegacyMdTaskWarningStateForTests() {
+    warnedLegacyMdDirs.clear();
+}
 export async function akmTasksList() {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "tasks");
     if (!fs.existsSync(typeRoot))
         return { tasks: [] };
-    const files = fs.readdirSync(typeRoot).filter((f) => f.endsWith(".md"));
+    const entries = fs.readdirSync(typeRoot);
+    warnLegacyMdTaskFiles(typeRoot);
+    const files = entries.filter((f) => f.endsWith(".yml"));
     const tasks = [];
     for (const file of files) {
-        const id = file.slice(0, -3);
+        const id = file.slice(0, -4);
         const filePath = path.join(typeRoot, file);
         let task;
         try {
-            task = parseTaskDocument({ markdown: fs.readFileSync(filePath, "utf8"), filePath, id });
+            task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
         }
         catch {
             continue; // skip malformed files; `akm tasks show <id>` will surface the error
@@ -104,7 +155,9 @@ export async function akmTasksList() {
             schedule: task.schedule,
             enabled: task.enabled,
             target: task.target,
+            name: task.name,
             description: task.description,
+            when_to_use: task.when_to_use,
             tags: task.tags,
         });
     }
@@ -113,9 +166,12 @@ export async function akmTasksList() {
 export async function akmTasksShow(id) {
     const normalised = normaliseTaskId(id);
     const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    if (fs.existsSync(typeRoot))
+        warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
     const task = parseTaskDocument({
-        markdown: fs.readFileSync(filePath, "utf8"),
+        yaml: fs.readFileSync(filePath, "utf8"),
         filePath,
         id: normalised,
     });
@@ -128,13 +184,18 @@ export async function akmTasksShow(id) {
         cron: translateToCron(spec),
         enabled: task.enabled,
         target: task.target,
+        name: task.name,
         description: task.description,
+        when_to_use: task.when_to_use,
         tags: task.tags,
     };
 }
 export async function akmTasksRemove(id) {
     const normalised = normaliseTaskId(id);
     const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    if (fs.existsSync(typeRoot))
+        warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
     const sched = selectBackend();
     try {
@@ -148,24 +209,31 @@ export async function akmTasksRemove(id) {
 export async function akmTasksSetEnabled(id, enabled) {
     const normalised = normaliseTaskId(id);
     const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    if (fs.existsSync(typeRoot))
+        warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
-    const markdown = fs.readFileSync(filePath, "utf8");
-    const updated = setEnabledInMarkdown(markdown, enabled);
+    const yaml = fs.readFileSync(filePath, "utf8");
+    const updated = setEnabledInYaml(yaml, enabled);
     fs.writeFileSync(filePath, updated, "utf8");
     const sched = selectBackend();
     try {
         await sched.setEnabled(normalised, enabled);
     }
     catch (err) {
-        // Roll the file back so the markdown source-of-truth and the OS
+        // Roll the file back so the YAML source-of-truth and the OS
         // scheduler don't diverge silently when the backend call fails.
-        fs.writeFileSync(filePath, markdown, "utf8");
+        fs.writeFileSync(filePath, yaml, "utf8");
         throw err;
     }
     return { id: normalised, enabled, backend: sched.name };
 }
 export async function akmTasksRun(id) {
     const normalised = normaliseTaskId(id);
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    if (fs.existsSync(typeRoot))
+        warnLegacyMdTaskFiles(typeRoot);
     const result = await runTask(normalised);
     return {
         ok: result.status === "completed" || result.status === "disabled",
@@ -176,6 +244,10 @@ export async function akmTasksRun(id) {
 export async function akmTasksHistory(input) {
     const limit = input.limit !== undefined && input.limit > 0 ? input.limit : 50;
     const id = input.id ? normaliseTaskId(input.id) : undefined;
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    if (fs.existsSync(typeRoot))
+        warnLegacyMdTaskFiles(typeRoot);
     return { rows: readTaskHistory({ id, limit }) };
 }
 /**
@@ -187,11 +259,13 @@ export async function akmTasksHistory(input) {
 export async function akmTasksSync() {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "tasks");
+    if (fs.existsSync(typeRoot))
+        warnLegacyMdTaskFiles(typeRoot);
     const fileIds = fs.existsSync(typeRoot)
         ? fs
             .readdirSync(typeRoot)
-            .filter((f) => f.endsWith(".md"))
-            .map((f) => f.slice(0, -3))
+            .filter((f) => f.endsWith(".yml"))
+            .map((f) => f.slice(0, -4))
         : [];
     const sched = selectBackend();
     const backend = backendNameForPlatform();
@@ -200,10 +274,10 @@ export async function akmTasksSync() {
     const unchanged = [];
     const skipped = [];
     for (const id of fileIds) {
-        const filePath = path.join(typeRoot, `${id}.md`);
+        const filePath = path.join(typeRoot, `${id}.yml`);
         let task;
         try {
-            task = parseTaskDocument({ markdown: fs.readFileSync(filePath, "utf8"), filePath, id });
+            task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
         }
         catch (err) {
             skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
@@ -243,10 +317,32 @@ export async function akmTasksDoctor() {
     catch (err) {
         warnings.push(err instanceof Error ? err.message : String(err));
     }
+    try {
+        const stashDir = resolveStashDir();
+        const typeRoot = path.join(stashDir, "tasks");
+        if (fs.existsSync(typeRoot))
+            warnLegacyMdTaskFiles(typeRoot);
+    }
+    catch {
+        // doctor must never fail on stash-resolution; the warning is best-effort
+    }
     const backend = backendNameForPlatform();
     const config = loadConfig();
-    const defaultProfile = config.agent?.default;
-    const profiles = listAgentProfileNames(config.agent);
+    // v2: prefer profiles.agent / defaults.agent; fall back to legacy agent.default
+    const defaultProfile = config.defaults?.agent;
+    const profiles = config.profiles?.agent ? Object.keys(config.profiles.agent) : listAgentProfileNames(config);
+    // §6.1: surface the effective triage settings for the default improve
+    // profile. The struct is a fixed shape, so this is a deliberate addition.
+    const improveProfileName = typeof config.defaults?.improve === "string" ? config.defaults.improve : "default";
+    const triage = resolveImproveProfile(config.defaults?.improve, config).processes?.triage;
+    const improveTriage = triage
+        ? {
+            defaultProfile: improveProfileName,
+            enabled: triage.enabled === true,
+            applyMode: triage.applyMode ?? "queue",
+            policy: triage.policy ?? "personal-stash",
+        }
+        : undefined;
     return {
         backend,
         akm: invocation,
@@ -255,12 +351,15 @@ export async function akmTasksDoctor() {
         agent: { defaultProfile, available: profiles },
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
+        ...(improveTriage ? { improveTriage } : {}),
     };
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
 const VALID_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 function normaliseTaskId(raw) {
-    const id = raw.trim().replace(/\.md$/, "");
+    // Accept both .yml and .md suffixes from users so muscle memory from the
+    // pre-0.8.0 markdown task format doesn't produce a confusing "task not found".
+    const id = raw.trim().replace(/\.(yml|md)$/, "");
     if (!id) {
         throw new UsageError("Task id must be non-empty.", "MISSING_REQUIRED_ARGUMENT");
     }
@@ -269,63 +368,35 @@ function normaliseTaskId(raw) {
     }
     return id;
 }
-function renderTaskMarkdown(input) {
-    const lines = ["---"];
-    lines.push(`schedule: ${yamlQuote(input.schedule)}`);
+function renderTaskYaml(input) {
+    const obj = { schedule: input.schedule };
     if (input.workflow) {
-        lines.push(`workflow: ${yamlQuote(input.workflow)}`);
+        obj.workflow = input.workflow;
         if (input.params) {
-            const parsed = parseJsonObjectArg(input.params);
-            lines.push("params:");
-            for (const [k, v] of Object.entries(parsed)) {
-                lines.push(`  ${k}: ${yamlScalarValue(v)}`);
-            }
+            obj.params = parseJsonObjectArg(input.params);
         }
     }
     else if (input.prompt) {
-        if (looksLikeAssetRef(input.prompt) || isFilePath(input.prompt) || input.prompt === "inline") {
-            lines.push(`prompt: ${yamlQuote(input.prompt)}`);
-        }
-        else {
-            lines.push(`prompt: inline`);
-        }
+        obj.prompt = input.prompt;
         if (input.profile)
-            lines.push(`profile: ${yamlQuote(input.profile)}`);
+            obj.profile = input.profile;
     }
-    lines.push(`enabled: ${input.enabled}`);
-    if (input.description)
-        lines.push(`description: ${yamlQuote(input.description)}`);
-    if (input.tags && input.tags.length > 0) {
-        lines.push(`tags: [${input.tags.map((t) => yamlQuote(t)).join(", ")}]`);
+    else if (input.command !== undefined) {
+        // Emit a string when given a string, an array when given an array. The
+        // parser accepts both forms; preserving the caller's shape keeps the YAML
+        // ergonomic for humans editing the file later.
+        obj.command = input.command;
     }
-    lines.push("---", "");
-    if (input.workflow) {
-        lines.push(`# Task: ${humanise(input.id)}`, "");
-    }
-    else if (input.prompt) {
-        if (looksLikeAssetRef(input.prompt) || isFilePath(input.prompt) || input.prompt === "inline") {
-            lines.push(`# Task: ${humanise(input.id)}`, "");
-        }
-        else {
-            // Raw inline prompt — use the body itself.
-            lines.push(input.prompt.trim(), "");
-        }
-    }
-    return lines.join("\n");
-}
-function yamlQuote(value) {
-    if (/^[A-Za-z_][A-Za-z0-9_.\-/:]*$/.test(value))
-        return value;
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-function yamlScalarValue(v) {
-    if (typeof v === "string")
-        return yamlQuote(v);
-    if (typeof v === "number" || typeof v === "boolean")
-        return String(v);
-    if (v === null)
-        return "null";
-    return JSON.stringify(v);
+    obj.enabled = input.enabled;
+    if (input.name)
+        obj.name = input.name;
+    if (input.description)
+        obj.description = input.description;
+    if (input.when_to_use)
+        obj.when_to_use = input.when_to_use;
+    if (input.tags && input.tags.length > 0)
+        obj.tags = input.tags;
+    return yamlStringify(obj);
 }
 function parseJsonObjectArg(raw) {
     let parsed;
@@ -340,31 +411,26 @@ function parseJsonObjectArg(raw) {
     }
     return parsed;
 }
-function looksLikeAssetRef(s) {
-    return /^[a-z][a-z0-9_-]*:[^\s]/i.test(s) && !s.startsWith("./") && !s.startsWith("/");
-}
-function isFilePath(s) {
-    return s.startsWith("./") || s.startsWith("../") || path.isAbsolute(s);
-}
-function humanise(id) {
-    return id.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-}
 /**
- * Toggle the `enabled:` value in a task markdown's frontmatter without doing
- * a round-trip through the parser+renderer (which would lose comments and
- * formatting choices). Inserts the key right before the closing `---` if
- * absent.
+ * Toggle the `enabled:` value in a task YAML file in-place without a full
+ * parse/render round-trip (which would reformat the file). Appends the key
+ * if absent.
+ *
+ * Preserves inline comments (e.g. `enabled: true # important`) and uses
+ * case-sensitive matching (YAML keys are case-sensitive).
  */
-export function setEnabledInMarkdown(markdown, enabled) {
-    const m = markdown.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r\n|\r|\n|$))([\s\S]*)$/);
-    if (!m) {
-        throw new UsageError("Task markdown is missing frontmatter; cannot toggle enabled.", "INVALID_FLAG_VALUE");
+export function setEnabledInYaml(yaml, enabled) {
+    // Match: key prefix (group 1), value (group 2), optional trailing comment (group 3)
+    const pattern = /^(enabled:\s*)([^\s#\r\n][^\r\n]*?)(\s*(?:#[^\r\n]*))?$/m;
+    if (pattern.test(yaml)) {
+        return yaml.replace(pattern, `$1${enabled}$3`);
+    }
+    // Handle the case where enabled: has no value yet (bare key)
+    const simplePattern = /^(enabled:)\s*$/m;
+    if (simplePattern.test(yaml)) {
+        return yaml.replace(simplePattern, `$1 ${enabled}`);
     }
-    const [, openFence, fmBody, closeFence, body] = m;
-    const replaced = fmBody.match(/(^|\r?\n)enabled:\s*[^\r\n]*/i)
-        ? fmBody.replace(/(^|\r?\n)enabled:\s*[^\r\n]*/i, `$1enabled: ${enabled}`)
-        : `${fmBody}\nenabled: ${enabled}`;
-    return `${openFence}${replaced}${closeFence}${body}`;
+    return `${yaml.trimEnd()}\nenabled: ${enabled}\n`;
 }
 // Re-exported so tests can verify the validator path directly.
 // Re-export error classes consumed by callers that want to instanceof-check.
@@ -375,11 +441,11 @@ export { ConfigError, exitCodeForStatus, NotFoundError, parseTaskDocument, Usage
 // user passes a ref, we accept the bare name part too.
 export function parseTaskRef(input) {
     if (input.includes(":")) {
-        const ref = parseAssetRef(input);
-        if (ref.type !== "task") {
+        const [typePart, ...rest] = input.split(":");
+        if (typePart !== "task" || rest.length === 0) {
             throw new UsageError(`Expected a task id or task:<id> ref, got "${input}".`, "INVALID_FLAG_VALUE");
         }
-        return { id: normaliseTaskId(ref.name) };
+        return { id: normaliseTaskId(rest.join(":")) };
     }
     return { id: normaliseTaskId(input) };
 }

package/dist/commands/url-checker.js

@@ -1,3 +1,6 @@
+// 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/.
 const URL_RE = /https?:\/\/[^\s"'<>)\]]+/g;
 const TIMEOUT_MS = 5000;
 const MAX_URLS = 20;

package/dist/core/action-contributors.js

@@ -1,3 +1,6 @@
+// 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-registry";
 function registryActionContributor(registry) {
     return {

package/dist/core/asset-ref.js

@@ -1,6 +1,13 @@
+// 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 path from "node:path";
 import { isAssetType } from "./common";
 import { UsageError } from "./errors";
+/** Accepted spelling aliases mapping to a canonical asset type. */
+const TYPE_ALIASES = {
+    environment: "env",
+};
 // ── Construction ────────────────────────────────────────────────────────────
 /**
  * Build a ref string from components.
@@ -46,12 +53,16 @@ export function parseAssetRef(ref) {
     }
     const rawType = body.slice(0, colon);
     const rawName = body.slice(colon + 1);
-    if (!isAssetType(rawType)) {
+    // Type aliases: `environment:` is an accepted spelling of the canonical
+    // `env:` type. (`vault:` remains its own deprecated type so the frozen
+    // `vaults/` copy keeps resolving through the 0.8.x window.)
+    const resolvedType = TYPE_ALIASES[rawType] ?? rawType;
+    if (!isAssetType(resolvedType)) {
         throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");
     }
     validateName(rawName);
     const name = normalizeName(rawName);
-    return { type: rawType, name, origin: origin || undefined };
+    return { type: resolvedType, name, origin: origin || undefined };
 }
 // ── Validation ──────────────────────────────────────────────────────────────
 function validateName(name) {

package/dist/core/asset-registry.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Central registry for asset type renderer and action builder maps.
  *
@@ -21,9 +24,11 @@ export const TYPE_TO_RENDERER = {
     lesson: "lesson-md",
     memory: "memory-md",
     workflow: "workflow-md",
+    env: "env-file",
     vault: "vault-env",
+    secret: "secret-file",
     wiki: "wiki-md",
-    task: "task-md",
+    task: "task-yaml",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -35,7 +40,9 @@ export const ACTION_BUILDERS = {
     lesson: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
     memory: (ref) => `akm show ${ref} -> recall context`,
     workflow: (ref) => buildWorkflowAction(ref),
-    vault: (ref) => `akm show ${ref} -> inspect keys; source "$(akm vault path ${ref})" -> load values; akm vault run ${ref} -- <command> -> run with injected env`,
+    env: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (the agent-safe path — values never reach stdout). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
+    vault: (ref) => `DEPRECATED (use env): akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with injected env`,
+    secret: (ref) => `akm show ${ref} -> name only (value never shown); akm secret path ${ref} -> file path; akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
     task: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
 };

package/dist/core/asset-serialize.js

@@ -0,0 +1,88 @@
+// 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/.
+/**
+ * Canonical asset-on-disk serialization.
+ *
+ * Before this module, 9+ call sites across `src/` independently reimplemented
+ * `yamlStringify(fm).trimEnd() + "---\n…\n---\n\n${body}"` to assemble a
+ * Markdown asset. The reimplementations drifted (different body normalization,
+ * different separator newlines, different trailing-newline policy), which is
+ * exactly the kind of silent format-shift the proposal-quality validators end
+ * up chasing downstream. This file is the single point of truth for
+ * "what does a well-formed AKM asset look like on disk".
+ *
+ * Two helpers are exported:
+ *   - `serializeFrontmatter(fm)` — YAML for the frontmatter block only, with
+ *     no `---` fences and no trailing newline. Single home for quoting style,
+ *     field-order policy, and trailing-whitespace rules.
+ *   - `assembleAsset(fm, body)` — frontmatter wrapped in `---` fences with a
+ *     blank line between the closing fence and the body, and exactly one
+ *     trailing `\n`. Single home for body normalization and the file-shape
+ *     contract.
+ *
+ * Contract (must hold for the dedup to be safe):
+ *   - Idempotent: `parseFrontmatter(assembleAsset(fm, body))` re-assembled
+ *     reproduces the same bytes.
+ *   - Field order: insertion order of `fm` is preserved (the caller controls
+ *     ordering; the helper never reorders).
+ *   - Quoting: `yaml.stringify` defaults — no custom quoting logic.
+ *   - Trailing newline: exactly one `\n` at end of output.
+ *   - Body normalization: leading newlines are stripped (`/^\n+/`). This
+ *     collapses the assorted `body.replace(/^\n+/, "")` /
+ *     `body.startsWith("\n") ? "" : "\n" + body` / bare `${body}` patterns
+ *     onto the most aggressive existing normalizer.
+ */
+import { stringify as yamlStringify } from "yaml";
+/**
+ * Serialize a frontmatter object to its on-disk YAML form, without `---`
+ * fences and without a trailing newline.
+ *
+ * Two calls with the same input produce byte-identical output. Field order is
+ * preserved from the input object's insertion order — callers control
+ * ordering, the helper never reorders.
+ */
+export function serializeFrontmatter(frontmatter) {
+    return yamlStringify(frontmatter).trimEnd();
+}
+/**
+ * Assemble a complete asset file string from a frontmatter object and a body.
+ *
+ * Output shape: `---\n<yaml>\n---\n\n<body>\n` where:
+ *   - `<yaml>` is `serializeFrontmatter(frontmatter)`.
+ *   - `<body>` has any leading `\n` characters stripped.
+ *   - Exactly one `\n` terminates the file.
+ *
+ * Idempotent under round-trip through the project's `parseFrontmatter`.
+ */
+export function assembleAsset(frontmatter, body) {
+    return assembleAssetFromString(serializeFrontmatter(frontmatter), body);
+}
+/**
+ * Same fence/body assembly as `assembleAsset` but takes a pre-serialized
+ * frontmatter string. Use this when a caller needs its own frontmatter
+ * serializer (e.g. defensive single-line flattening for untrusted LLM
+ * output, or JSON.stringify-per-value for guaranteed-quoted scalars) while
+ * still sharing the canonical fence-and-body template.
+ *
+ * The `serializedFm` argument must already match `serializeFrontmatter`'s
+ * contract: no `---` fences, no trailing newline. Trailing whitespace is
+ * trimmed defensively.
+ *
+ * Output contract — identical to `assembleAsset`:
+ *   - `---\n<serializedFm>\n---\n\n<body>\n`
+ *   - body has leading `\n` characters stripped
+ *   - exactly one `\n` terminates the file
+ *
+ * This helper is the single point of truth for the fence-and-body template.
+ * Three command surfaces (`reflect`, `distill`, `consolidate`) call it
+ * directly because their inputs are pre-validated LLM payloads where the
+ * full `yamlStringify` may emit shapes (`|`-block scalars, anchors) that
+ * the project's hand-rolled `parseFrontmatter` subset parser cannot read.
+ */
+export function assembleAssetFromString(serializedFm, body) {
+    const yaml = serializedFm.replace(/\s+$/, "");
+    const normalizedBody = body.replace(/^\n+/, "");
+    const withTrailingNewline = normalizedBody.endsWith("\n") ? normalizedBody : `${normalizedBody}\n`;
+    return `---\n${yaml}\n---\n\n${withTrailingNewline}`;
+}