@rse/ase 1.0.7 → 2.0.0

package/dst/ase-task-format.js

@@ -0,0 +1,757 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import YAML from "yaml";
+import { nanoid } from "./ase-lib-hash.js";
+/*  the pre-defined task lifecycle models (see "project.task.lifecycle")  */
+export const taskLifecycles = {
+    solo: {
+        name: "solo",
+        states: ["OPEN", "SHELVED", "CLOSED", "CANCELLED"],
+        initial: "OPEN",
+        finished: ["CLOSED", "CANCELLED"],
+        activity: [],
+        transitions: {
+            OPEN: ["SHELVED", "CLOSED", "CANCELLED"],
+            SHELVED: ["OPEN", "CANCELLED"],
+            CLOSED: [],
+            CANCELLED: []
+        }
+    },
+    team: {
+        name: "team",
+        states: ["PLANNING", "SHELVED", "IMPLEMENTING", "STALLED", "IMPLEMENTED", "CANCELLED"],
+        initial: "PLANNING",
+        finished: ["IMPLEMENTED", "CANCELLED"],
+        activity: ["IMPLEMENTING"],
+        transitions: {
+            PLANNING: ["SHELVED", "IMPLEMENTING", "CANCELLED"],
+            SHELVED: ["PLANNING", "CANCELLED"],
+            IMPLEMENTING: ["PLANNING", "STALLED", "IMPLEMENTED", "CANCELLED"],
+            STALLED: ["IMPLEMENTING", "CANCELLED"],
+            IMPLEMENTED: [],
+            CANCELLED: []
+        }
+    },
+    enterprise: {
+        name: "enterprise",
+        states: [
+            "DRAFTED", "SHELVED", "PLANNING", "PLANNED", "STALLED", "IMPLEMENTING",
+            "IMPLEMENTED", "DECLINED", "QUALIFYING", "QUALIFIED", "DEFERRED", "INTEGRATING",
+            "INTEGRATED", "CANCELLED"
+        ],
+        initial: "DRAFTED",
+        finished: ["INTEGRATED", "CANCELLED"],
+        activity: ["PLANNING", "IMPLEMENTING", "QUALIFYING", "INTEGRATING"],
+        transitions: {
+            DRAFTED: ["SHELVED", "PLANNING", "CANCELLED"],
+            SHELVED: ["DRAFTED", "CANCELLED"],
+            PLANNING: ["DRAFTED", "SHELVED", "PLANNED", "CANCELLED"],
+            PLANNED: ["STALLED", "IMPLEMENTING", "CANCELLED"],
+            STALLED: ["PLANNED", "CANCELLED"],
+            IMPLEMENTING: ["DRAFTED", "PLANNED", "STALLED", "IMPLEMENTED", "CANCELLED"],
+            IMPLEMENTED: ["DECLINED", "QUALIFYING", "CANCELLED"],
+            DECLINED: ["IMPLEMENTED", "CANCELLED"],
+            QUALIFYING: ["DRAFTED", "PLANNED", "IMPLEMENTED", "DECLINED", "QUALIFIED", "CANCELLED"],
+            QUALIFIED: ["DEFERRED", "INTEGRATING", "CANCELLED"],
+            DEFERRED: ["QUALIFIED", "CANCELLED"],
+            INTEGRATING: ["DRAFTED", "PLANNED", "QUALIFIED", "DEFERRED", "INTEGRATED", "CANCELLED"],
+            INTEGRATED: [],
+            CANCELLED: []
+        }
+    }
+};
+/*  the effective lifecycle status of a header: its "Status" key
+    (upper-cased), or the initial state of the model if absent  */
+export const taskStatus = (header, lifecycle) => {
+    const status = header.Status;
+    if (typeof status === "string" && status.trim() !== "")
+        return status.trim().toUpperCase();
+    return lifecycle.initial;
+};
+/*  check a "Status" change against the task lifecycle model: returns
+    an error (else empty) if the changed status is not a state of the
+    model or not reachable from the old status via one or more transitions
+    (as one operation may perform several stages); an old status foreign
+    to the model may change to any state, to allow its correction  */
+export const checkStatus = (lifecycle, from, to) => {
+    if (to === from)
+        return "";
+    if (!lifecycle.states.includes(to))
+        return `status "${to}" is not a state of the "${lifecycle.name}" task lifecycle model ` +
+            `(expected one of: ${lifecycle.states.join(", ")})`;
+    if (!lifecycle.states.includes(from))
+        return "";
+    const seen = new Set([from]);
+    const queue = [from];
+    while (queue.length > 0) {
+        const state = queue.shift();
+        if (state === to)
+            return "";
+        for (const next of lifecycle.transitions[state] ?? [])
+            if (!seen.has(next)) {
+                seen.add(next);
+                queue.push(next);
+            }
+    }
+    return `status "${to}" is not reachable from status "${from}" in the "${lifecycle.name}" task lifecycle model`;
+};
+/*  the states of the task lifecycle models, each mapped onto its candidate
+    states in another model (tried after the state itself), where absent
+    states fall back to the initial (resp. first finished) state only  */
+const statusCandidates = {
+    PLANNING: ["OPEN"],
+    PLANNED: ["PLANNING", "OPEN"],
+    IMPLEMENTING: ["OPEN"],
+    STALLED: ["OPEN"],
+    DECLINED: ["IMPLEMENTING", "OPEN"],
+    IMPLEMENTED: ["INTEGRATED", "CLOSED"],
+    QUALIFYING: ["IMPLEMENTED", "CLOSED"],
+    QUALIFIED: ["IMPLEMENTED", "CLOSED"],
+    DEFERRED: ["IMPLEMENTED", "CLOSED"],
+    INTEGRATING: ["IMPLEMENTED", "CLOSED"],
+    INTEGRATED: ["IMPLEMENTED", "CLOSED"],
+    CLOSED: ["INTEGRATED", "IMPLEMENTED"]
+};
+/*  map a status from one task lifecycle model onto another: the first
+    candidate state present in the target model wins (for a finished
+    status only a finished one), else the initial (resp. first finished)
+    state; a status foreign to the source model is kept as-is  */
+export const mapStatus = (from, to, status) => {
+    if (!from.states.includes(status))
+        return status;
+    const finished = from.finished.includes(status);
+    const mapped = [status, ...(statusCandidates[status] ?? [])]
+        .find((state) => to.states.includes(state) && (!finished || to.finished.includes(state)));
+    return mapped ?? (finished ? to.finished[0] : to.initial);
+};
+/*  adapt a status onto a task lifecycle model: a state of the model is kept,
+    a state foreign to it is mapped onto it via the first model knowing the
+    state (see "mapStatus"), and a status unknown to all models falls back
+    to the initial state of the model  */
+export const adaptStatus = (lifecycle, status) => {
+    if (lifecycle.states.includes(status))
+        return status;
+    const source = Object.values(taskLifecycles).find((model) => model.states.includes(status));
+    return source !== undefined ? mapStatus(source, lifecycle, status) : lifecycle.initial;
+};
+/*  resolve an "include" and an "exclude" comma-separated lifecycle
+    state list into the effective state set a task plan has to be in
+    to be listed at all; the "none" sentinel and empty tokens are
+    silently dropped, the "finished" sentinel expands to the finished
+    states of the task lifecycle model, an empty "include" list means
+    all states, and the "exclude" list is applied after the "include" list  */
+export const resolveStates = (lifecycle, include, exclude) => {
+    const parse = (list) => list.split(",")
+        .map((token) => token.trim())
+        .filter((token) => token !== "" && token.toUpperCase() !== "NONE")
+        .flatMap((token) => {
+        const state = token.toUpperCase();
+        if (state === "FINISHED")
+            return lifecycle.finished;
+        if (!lifecycle.states.includes(state))
+            throw new Error(`invalid state "${token}" ` +
+                `(expected one of: ${lifecycle.states.join(", ")}, or "finished")`);
+        return [state];
+    });
+    const included = parse(include);
+    const excluded = parse(exclude);
+    const states = (included.length > 0 ? included : lifecycle.states)
+        .filter((state) => !excluded.includes(state));
+    if (states.length === 0)
+        throw new Error("\"include\" and \"exclude\" cancel out to an empty state set");
+    return states;
+};
+/*  the id pattern of projects and sessions, and the one of tasks
+    (additionally allowing "#", as in ids like "#42", but no leading "-" or "_")  */
+export const ID_RE = /^[A-Za-z0-9_-]+$/;
+export const TASK_ID_RE = /^[A-Za-z0-9#][A-Za-z0-9#_-]*$/;
+/*  the reserved task id of the default task of a session  */
+export const DEFAULT_TASK_ID = "default";
+/*  the task id scheme callbacks, each mapping the optional argument
+    <arg> of "<kind>[:<arg>]" onto the scheme or an error message  */
+const idSchemes = {
+    slug: (arg) => {
+        if (arg !== undefined && !/^\d+$/.test(arg))
+            return "word count has to be a number";
+        const words = arg !== undefined ? Number.parseInt(arg, 10) : 2;
+        if (words < 1 || words > 16)
+            return "word count has to be 1-16";
+        return { kind: "slug", words, match: `^[a-z][a-z0-9]*(?:-[a-z0-9]+){0,${words - 1}}(?:-[0-9]+)?$` };
+    },
+    seq: (arg) => {
+        const m = /^((?:[A-Za-z#][A-Za-z#_-]*)?)%(?:0(\d+))?d([A-Za-z#_-]*)$/.exec(arg ?? "%d");
+        if (m === null)
+            return "template has to contain exactly one \"%d\" or \"%0<width>d\" " +
+                "and otherwise only the characters [A-Za-z#_-] (but not start with \"-\" or \"_\")";
+        const width = m[2] !== undefined ? Number.parseInt(m[2], 10) : 0;
+        if (width > 16)
+            return "width has to be 0-16";
+        /*  prefix and suffix need no quoting, as [A-Za-z#_-] are no metacharacters  */
+        const match = `^${m[1]}([0-9]${width > 0 ? `{${width},}` : "+"})${m[3]}$`;
+        return { kind: "seq", prefix: m[1], width, suffix: m[3], match };
+    },
+    any: (arg) => {
+        if (arg !== undefined)
+            return "scheme takes no argument";
+        return { kind: "any", match: TASK_ID_RE.source };
+    }
+};
+/*  parse a task id scheme specification  */
+export const parseIdScheme = (spec) => {
+    const m = /^([a-z]+)(?::(.*))?$/.exec(spec);
+    const callback = m !== null && Object.hasOwn(idSchemes, m[1]) ? idSchemes[m[1]] : undefined;
+    if (m === null || callback === undefined)
+        throw new Error(`invalid task id scheme "${spec}" (expected "slug[:<words>]", "seq[:<template>]", or "any")`);
+    const scheme = callback(m[2]);
+    if (typeof scheme === "string")
+        throw new Error(`invalid task id scheme "${spec}" (${scheme})`);
+    return scheme;
+};
+/*  check a task id scheme specification: returns an error (else empty)  */
+export const checkIdScheme = (spec) => {
+    try {
+        parseIdScheme(spec);
+        return "";
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+};
+/*  derive a slug from a title: diacritics stripped (and "ß" expanded), lower-cased,
+    and the first <words> alphanumeric words, starting with the first word
+    beginning with a letter, joined with "-"  */
+export const slugify = (title, words) => {
+    const list = title.normalize("NFKD").replace(/\p{M}/gu, "").replace(/ß/g, "ss").toLowerCase()
+        .split(/[^a-z0-9]+/).filter((word) => word !== "");
+    const i = list.findIndex((word) => /^[a-z]/.test(word));
+    return i < 0 ? "" : list.slice(i, i + words).join("-");
+};
+/*  check whether a task id conforms to a task id scheme
+    (the reserved default task id always conforms)  */
+export const idConforms = (scheme, id) => id === DEFAULT_TASK_ID || new RegExp(scheme.match).test(id);
+/*  the warning (else empty) about a task id not conforming to a task id scheme  */
+export const idWarning = (spec, id) => idConforms(parseIdScheme(spec), id) ? "" :
+    `task id "${id}" does not conform to the task id scheme "${spec}" (see "project.task.idscheme")`;
+/*  the sequence number of a task id conforming to a "seq" task id scheme
+    (else 0, as for all ids under any other scheme or beyond the safe integer range)  */
+export const seqNumber = (scheme, id) => {
+    if (scheme.kind !== "seq")
+        return 0;
+    const n = Number.parseInt(new RegExp(scheme.match).exec(id)?.[1] ?? "0", 10);
+    return Number.isSafeInteger(n) ? n : 0;
+};
+/*  determine the next free task id of a task id scheme, given all existing
+    task ids: for "seq" the highest number of all conforming ids and of the
+    high-water mark "seqmark" (of the removed ids) plus one, for "slug" the slug
+    of the title, and for "any" the proposed id (sanitized, else the slug of the
+    title), where a taken slug or id gets a numeric suffix  */
+export const nextTaskId = (scheme, ids, title = "", proposal = "", seqmark = 0) => {
+    const taken = new Set([...ids, DEFAULT_TASK_ID]);
+    let base;
+    if (scheme.kind === "seq") {
+        const n = ids.reduce((max, id) => Math.max(max, seqNumber(scheme, id)), seqmark) + 1;
+        return `${scheme.prefix}${String(n).padStart(scheme.width, "0")}${scheme.suffix}`;
+    }
+    else if (scheme.kind === "slug")
+        base = slugify(title, scheme.words);
+    else
+        base = proposal.trim().replace(/\s+/g, "-").replace(/[^A-Za-z0-9#_-]/g, "").replace(/^[_-]+/, "") || slugify(title, 2);
+    if (base === "")
+        throw new Error(`task id scheme "${scheme.kind}" requires a ` +
+            (scheme.kind === "any" ? "proposed id or " : "") + "title with at least one word beginning with a letter");
+    let id = base;
+    for (let n = 2; taken.has(id); n++)
+        id = `${base}-${n}`;
+    return id;
+};
+/*  compare two task ids in natural order (numbers by their value)  */
+export const compareIds = (a, b) => a.localeCompare(b, "en", { numeric: true });
+/*  the task id of a task text: the value of the "Id:" key of its frontmatter,
+    or the empty string if absent  */
+export const taskTextId = (text) => {
+    const fm = /^---\r?\n([\s\S]*?\r?\n)---\r?\n/.exec(text);
+    return fm === null ? "" : (/^Id:[ \t]*(.*)$/m.exec(fm[1])?.[1].trim() ?? "");
+};
+/*  the fixed value of the "Type" frontmatter key  */
+export const TASK_TYPE = "text/vnd.ase.task";
+/*  the frontmatter keys of the task plan format in their canonical
+    order, the array-typed ones among them, and the attachment keys
+    in their canonical order (see "ase-format-task.md")  */
+const frontKeys = ["Type", "Id", "Created", "Modified", "Group", "Phase", "After", "Status", "Assignee", "Kind", "Effort", "Tags", "Source", "Changeset", "Target"];
+export const arrayKeys = ["After", "Tags"];
+const attachKeys = ["Type", "Desc", "Created", "Modified", "Data", "File"];
+/*  the legacy task plan header lines, each mapped onto the
+    frontmatter key which superseded it  */
+const legacy = [
+    { key: "Created", re: /^⎈[ \t]+Created:[ \t]*(.*)$/m },
+    { key: "Modified", re: /^⚙[ \t]+Modified:[ \t]*(.*)$/m },
+    { key: "Kind", re: /^☯[ \t]+Kind:[ \t]*(.*)$/m }
+];
+/*  the legacy lifecycle states of the pre-lifecycle-model task plan
+    format, each mapped onto its candidate states in the current models
+    (first candidate present in the configured model wins, otherwise
+    the initial state of the model is used)  */
+const legacyStates = {
+    DRAFTED: [],
+    REJECTED: [],
+    APPROVED: ["PLANNED", "PLANNING", "OPEN"],
+    DEFERRED: ["SHELVED"],
+    STARTED: ["IMPLEMENTING", "OPEN"],
+    BLOCKED: ["STALLED", "OPEN"],
+    COMPLETED: ["INTEGRATED", "IMPLEMENTED", "CLOSED"],
+    CANCELLED: ["CANCELLED"]
+};
+/*  migrate the legacy "Branch:" key (the branch the change set lands on, created
+    from HEAD on demand) into "Changeset:" (created from the source on demand),
+    where the legacy "current" (the checked-out branch) is the default "worktree":
+    returns the "Changeset:" value, or undefined if the key is to be dropped only  */
+export const migrateBranch = (branch) => branch !== "" && branch !== "current" ? `branch:${branch}` : undefined;
+/*  migrate the legacy "preflight" kind of an implementation draft attachment
+    into "draft" (in place)  */
+export const migrateAttachment = (att) => {
+    if (att.Type !== undefined && /^text\/x-diff\s*(?:;|$)/i.test(att.Type))
+        att.Type = att.Type.replace(/(;\s*kind\s*=\s*)("?)preflight\2(\s*(?:;|$))/i, "$1$2draft$2$3");
+    return att;
+};
+/*  render a single key line with a column-aligned key
+    (a key too long for the column keeps at least one separating space)  */
+const keyLine = (key, value) => {
+    if (!/^[A-Za-z]+$/.test(key) || /[\r\n]/.test(value))
+        throw new Error(`invalid key line for key "${key}" (key has to be alphabetic and value single-line)`);
+    return value === "" ? key + ":" : (key + ":").padEnd(Math.max(11, key.length + 2)) + value;
+};
+/*  the key line pattern of the frontmatter and attachment blocks
+    (value to be right-trimmed by the caller, avoiding regex backtracking)  */
+const keyLineRe = /^([A-Za-z]+):[ \t]*(.*)$/;
+/*  parse the frontmatter block of a plan text into its key/value pairs,
+    keeping any non-key lines for a verbatim pass-through, plus the
+    length of the block; returns null if the text carries no block  */
+const parseFront = (text) => {
+    const fm = /^---\r?\n([\s\S]*?\r?\n)---\r?\n/.exec(text);
+    if (fm === null)
+        return null;
+    const keys = new Map();
+    const other = [];
+    for (const line of fm[1].split(/\r?\n/)) {
+        const m = keyLineRe.exec(line);
+        if (m !== null)
+            keys.set(m[1], m[2].trimEnd());
+        else if (line !== "")
+            other.push(line);
+    }
+    return { keys, other, length: fm[0].length };
+};
+/*  order keys canonically, with any unknown keys trailing  */
+const orderKeys = (canonical, keys) => [...canonical.filter((key) => keys.includes(key)), ...keys.filter((key) => !canonical.includes(key))];
+/*  re-assemble a frontmatter block with the keys in canonical order
+    (unknown keys and non-key lines trailing) and the values re-aligned  */
+const assembleFront = (keys, other) => {
+    const front = orderKeys(frontKeys, [...keys.keys()]).map((key) => keyLine(key, keys.get(key)));
+    return `---\n${[...front, ...other].join("\n")}\n---\n`;
+};
+/*  normalize a legacy task plan text into the current Markdown frontmatter
+    shape, so every consumer sees a single plan shape only: a plan
+    carrying its metadata in the "#   TASK <id>: <title>" heading and
+    the "⎈"/"⚙"/"☯" glyph header lines is first lifted into a
+    frontmatter block; then the frontmatter block is migrated by
+    inserting the mandatory "Type:" key, mapping a legacy "Status:" value
+    onto the configured lifecycle model, rewriting the legacy "Properties:"
+    key into "Tags:", rewriting the legacy "Branch:" key into "Changeset:",
+    and re-ordering and re-aligning the keys; any content without a
+    frontmatter block or task heading is passed through verbatim; absent
+    optional keys are never materialized, as they read as their default
+    value  */
+export const normalizeTaskText = (id, text, lifecycle) => {
+    if (text === "")
+        return text;
+    /*  lift the heading and the glyph header lines into their frontmatter
+        keys, with the task id taken from the authoritative filename-derived id  */
+    if (!/^---\r?\n/.test(text)) {
+        const heading = /^#[ \t]+TASK(?:[ \t]+[A-Za-z0-9#][A-Za-z0-9#_-]*)?[ \t]*:[ \t]*(.*)$/m.exec(text);
+        if (heading === null)
+            return text;
+        let body = text.replace(heading[0], "");
+        const front = [keyLine("Id", id)];
+        for (const entry of legacy) {
+            const m = entry.re.exec(body);
+            if (m === null)
+                continue;
+            front.push(keyLine(entry.key, m[1].trim()));
+            body = body.replace(m[0], "");
+        }
+        text = `---\n${front.join("\n")}\n---\n\n` +
+            `#   TASK: ${heading[1].trim()}\n\n` +
+            body.replace(/^(?:[ \t]*\r?\n)+/, "");
+    }
+    /*  parse the frontmatter block into its key/value pairs  */
+    const fm = parseFront(text);
+    if (fm === null)
+        return text;
+    const keys = fm.keys;
+    /*  a plan is legacy if it lacks the mandatory "Type:" key (or still
+        carries the "Properties:" key), decided before "Type:" is inserted  */
+    const isLegacy = !keys.has("Type") || keys.has("Properties");
+    /*  insert the mandatory "Type:" key  */
+    if (!keys.has("Type"))
+        keys.set("Type", TASK_TYPE);
+    /*  map a legacy "Status:" value unconditionally onto the configured
+        lifecycle model, as legacy values like "DEFERRED" carry
+        a different meaning than their same-named current states  */
+    const status = keys.get("Status");
+    if (isLegacy && status !== undefined && Object.hasOwn(legacyStates, status)) {
+        const state = legacyStates[status].find((state) => lifecycle.states.includes(state));
+        keys.set("Status", state ?? lifecycle.initial);
+    }
+    /*  rewrite the legacy "Properties:" key into "Tags:", where the
+        legacy "grilled" property (a fully grilled plan) becomes one
+        "grilled:" tag per section and any other property a plain tag  */
+    const properties = keys.get("Properties");
+    if (properties !== undefined) {
+        keys.delete("Properties");
+        const tags = properties.split(",")
+            .map((token) => token.trim())
+            .filter((token) => token !== "" && token.toLowerCase() !== "none")
+            .flatMap((token) => token.toLowerCase() === "grilled" ?
+            ["grilled:specification", "grilled:design", "grilled:verification"] : [token]);
+        if (tags.length > 0)
+            keys.set("Tags", [keys.get("Tags") ?? "", ...tags].filter((tag) => tag !== "").join(", "));
+    }
+    /*  rewrite the legacy "Branch:" key into "Changeset:" (see migrateBranch)  */
+    const branch = keys.get("Branch");
+    if (branch !== undefined) {
+        keys.delete("Branch");
+        const changeset = migrateBranch(branch);
+        if (changeset !== undefined && !keys.has("Changeset"))
+            keys.set("Changeset", changeset);
+    }
+    /*  re-assemble the frontmatter block, followed by the untouched
+        remainder of the plan  */
+    return assembleFront(keys, fm.other) + text.slice(fm.length);
+};
+/*  track the fenced code block state across a body line: returns the
+    opening fence, or an empty string if outside any fenced code block  */
+export const fenceTrack = (fence, line) => {
+    const m = /^ {0,3}(`{3,}|~{3,})[ \t]*(.*)$/.exec(line);
+    if (m !== null && fence === "")
+        return m[1];
+    else if (m !== null && m[2] === "" && m[1][0] === fence[0] && m[1].length >= fence.length)
+        return "";
+    return fence;
+};
+/*  check whether a body survives a round-trip through the task plan text:
+    returns null, or the reason why the parser would misread it -- a "---"
+    line outside a fenced code block followed by a "Type:" line (read as an
+    attachment start) or an unclosed fenced code block (swallowing all attachments)  */
+export const bodyConflict = (body) => {
+    const lines = body.split(/\r?\n/);
+    let fence = "";
+    let open = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const prev = fence;
+        fence = fenceTrack(fence, lines[i]);
+        if (prev === "" && fence !== "")
+            open = i + 1;
+        if (lines[i] === "---" && fence === "" && /^Type:/.test(lines[i + 1] ?? ""))
+            return `line ${i + 1}: a "---" line followed by a "Type:" line would start an attachment`;
+    }
+    return fence !== "" ? `line ${open}: fenced code block is not closed` : null;
+};
+/*  parse a task plan text (after legacy normalization) into the JSON
+    task plan structure: the text is split into blocks at its "---"
+    lines, the first block yields the header (with "After" and "Tags"
+    split into arrays and "Id" taken from the authoritative id), the
+    second block the body (without its leading and trailing empty line),
+    and every further block an attachment (with a "Data: |4+" or "|4-" literal
+    block scalar de-indented and a legacy "preflight" diff kind migrated into
+    "draft"); a text without a closed frontmatter is taken as body;
+    a "---" line not starting a block stays part of the body  */
+export const parseTaskText = (id, text, lifecycle) => {
+    text = normalizeTaskText(id, text, lifecycle);
+    const lines = text.split(/\r?\n/);
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    const blocks = [];
+    let fence = "";
+    for (let i = 0; i < lines.length; i++) {
+        /*  track the fenced code blocks of the body  */
+        if (blocks.length >= 2)
+            fence = fenceTrack(fence, lines[i]);
+        /*  beyond the frontmatter, a "---" line starts a block only outside a
+            fenced code block and if followed by the mandatory "Type:" key of an
+            attachment -- else it is kept as body (lossless for legacy plans)  */
+        if (lines[i] === "---" && lines[0] === "---" && fence === ""
+            && (blocks.length < 2 || /^Type:/.test(lines[i + 1] ?? "")))
+            blocks.push([]);
+        else if (blocks.length > 0)
+            blocks[blocks.length - 1].push(lines[i]);
+    }
+    const header = {};
+    let body;
+    const attachment = [];
+    if (blocks.length < 2)
+        body = text;
+    else {
+        for (const line of blocks[0]) {
+            const m = keyLineRe.exec(line);
+            if (m === null)
+                continue;
+            header[m[1]] = arrayKeys.includes(m[1]) ?
+                m[2].split(",").map((token) => token.trim()).filter((token) => token !== "") :
+                m[2].trimEnd();
+        }
+        const bodyLines = blocks[1] ?? [];
+        if (bodyLines[0] === "")
+            bodyLines.shift();
+        while (bodyLines.length > 0 && bodyLines[bodyLines.length - 1] === "")
+            bodyLines.pop();
+        body = bodyLines.length > 0 ? `${bodyLines.join("\n")}\n` : "";
+        for (const block of blocks.slice(2)) {
+            /*  drop one trailing empty line of the block, as it separates the block
+                from the next one (written by formatTaskText only behind a block ending
+                with an empty line, but typically added by hand, too)  */
+            if (block.length > 0 && block[block.length - 1] === "")
+                block.pop();
+            const att = {};
+            for (let i = 0; i < block.length; i++) {
+                const m = keyLineRe.exec(block[i]);
+                if (m === null)
+                    continue;
+                if (m[1] === "Data" && m[2].startsWith("|")) {
+                    const data = [];
+                    while (i + 1 < block.length && (block[i + 1] === "" || block[i + 1].startsWith("    ")))
+                        data.push(block[++i].slice(4));
+                    /*  honor the "strip" chomping indicator of a "|4-" block scalar  */
+                    if (m[2].trimEnd().endsWith("-")) {
+                        while (data.length > 0 && data[data.length - 1] === "")
+                            data.pop();
+                        att.Data = data.join("\n");
+                    }
+                    else
+                        att.Data = `${data.join("\n")}\n`;
+                }
+                else
+                    att[m[1]] = m[2].trimEnd();
+            }
+            attachment.push(migrateAttachment(att));
+        }
+    }
+    header.Type ??= TASK_TYPE;
+    header.Id = id;
+    return { header, body, attachment };
+};
+/*  format the header of the JSON task plan structure into the key lines
+    of the task plan text (without the enclosing "---" lines): the keys in
+    canonical order (unknown keys trailing) with the array values comma-joined  */
+export const formatTaskHeader = (header) => {
+    const value = (v) => Array.isArray(v) ? v.join(", ") : v;
+    return orderKeys(frontKeys, Object.keys(header).filter((key) => header[key] !== undefined))
+        .map((key) => `${keyLine(key, value(header[key]))}\n`).join("");
+};
+/*  format the JSON task plan structure into the task plan text: the
+    header (see formatTaskHeader), the body enclosed in its leading and
+    trailing empty line, and every attachment as its own block with
+    "Data" rendered as a "|4+" (or, without trailing newline, "|4-")
+    literal block scalar, as an empty value if empty, or as the elision
+    marker itself if elided, and a block ending with an empty line (of its
+    "Data") followed by a separating empty line (see parseTaskText)  */
+export const formatTaskText = (plan) => {
+    let text = `---\n${formatTaskHeader(plan.header)}---\n\n`;
+    if (plan.body !== "")
+        text += plan.body.endsWith("\n") ? `${plan.body}\n` : `${plan.body}\n\n`;
+    for (const att of plan.attachment) {
+        const keys = orderKeys(attachKeys, Object.keys(att).filter((key) => att[key] !== undefined));
+        text += "---\n";
+        for (const key of keys) {
+            if (key === "Data" && (att.Data === "" || isElided(att.Data)))
+                text += `${keyLine("Data", att.Data)}\n`;
+            else if (key === "Data") {
+                const keep = att.Data.endsWith("\n");
+                const data = att.Data.split("\n");
+                if (keep)
+                    data.pop();
+                text += `${keyLine("Data", keep ? "|4+" : "|4-")}\n`;
+                for (const line of data)
+                    text += line === "" ? "\n" : `    ${line}\n`;
+            }
+            else
+                text += `${keyLine(key, att[key])}\n`;
+        }
+        if (text.endsWith("\n\n"))
+            text += "\n";
+    }
+    return text;
+};
+/*  the marker of an elided "Data" of an attachment, carrying its number of lines  */
+const elidedRe = /^\[elided: \d+ lines?\]$/;
+export const isElided = (data) => data !== undefined && elidedRe.test(data);
+/*  elide the non-empty "Data" of all attachments of a task plan, i.e., replace it
+    by a marker, so the plan can be passed through an LLM without its potentially
+    huge attachment payloads, and the marker be restored on saving (see restoreAttachments)  */
+export const elideAttachments = (plan) => ({
+    ...plan,
+    attachment: plan.attachment.map((att) => {
+        if (att.Data === undefined || att.Data === "" || isElided(att.Data))
+            return att;
+        const lines = att.Data.replace(/\n$/, "").split("\n").length;
+        return { ...att, Data: `[elided: ${lines} line${lines === 1 ? "" : "s"}]` };
+    })
+});
+/*  restore the elided "Data" of the attachments of a task plan from the stored plan:
+    each elided attachment takes the "Data" of the first not yet taken stored attachment
+    of the same "Type", preferably also of the same "Created" (so the attachments can be
+    reordered or removed meanwhile); throws if no stored attachment matches  */
+export const restoreAttachments = (plan, stored) => {
+    if (!plan.attachment.some((att) => isElided(att.Data)))
+        return plan;
+    const taken = new Set();
+    const take = (att, created) => (stored?.attachment ?? []).findIndex((s, i) => !taken.has(i) && s.Type === att.Type
+        && s.Data !== undefined && !isElided(s.Data) && (!created || s.Created === att.Created));
+    return {
+        ...plan,
+        attachment: plan.attachment.map((att) => {
+            if (!isElided(att.Data))
+                return att;
+            let i = take(att, true);
+            if (i < 0)
+                i = take(att, false);
+            if (i < 0)
+                throw new Error(`elided attachment of type "${att.Type ?? ""}" not found in the stored task plan ` +
+                    "(an elided attachment can only be kept, but not be created or copied)");
+            taken.add(i);
+            return { ...att, Data: stored.attachment[i].Data };
+        })
+    };
+};
+/*  the type of the usage attachment of a task plan, carrying its AI usage accounting,
+    which is owned by the task store: changed by bookings only, but never by any other save  */
+export const USAGE_TYPE = "application/yaml; kind=\"usage\"";
+/*  whether an attachment is the usage attachment of a task plan  */
+export const isUsage = (att) => (att.Type ?? "").trim() === USAGE_TYPE;
+/*  a task plan without its usage attachments  */
+export const withoutUsage = (plan) => plan.attachment.some(isUsage) ? { ...plan, attachment: plan.attachment.filter((att) => !isUsage(att)) } : plan;
+/*  keep the usage attachments of the stored plan in a task plan to be saved: each usage
+    attachment of the plan is replaced (in place) by the next stored one or else dropped,
+    and the remaining stored ones are appended, so no save can change them  */
+export const keepUsage = (plan, stored) => {
+    const kept = stored.attachment.filter(isUsage);
+    if (kept.length === 0 && !plan.attachment.some(isUsage))
+        return plan;
+    const attachment = [];
+    for (const att of plan.attachment) {
+        if (!isUsage(att))
+            attachment.push(att);
+        else if (kept.length > 0)
+            attachment.push(kept.shift());
+    }
+    return { ...plan, attachment: [...attachment, ...kept] };
+};
+/*  the amounts of the AI usage accounting of a task, as "<group>.<field>" of the YAML data of
+    its usage attachment: the AI request time, the human time, and the real (wall-clock) time
+    (in minutes), the cache read, cache write, (uncached) input, and output tokens, and the AI
+    and human costs (in USD)  */
+export const usageKeys = [
+    "time.ai", "time.hr", "time.real",
+    "token.cread", "token.cwrite", "token.input", "token.output",
+    "cost.ai", "cost.hr"
+];
+/*  parse the YAML data of a usage attachment into its amounts (leniently,
+    i.e., with unparsable data and non-numeric amounts taken as absent)  */
+export const usageOf = (data) => {
+    let doc;
+    try {
+        doc = YAML.parse(data);
+    }
+    catch {
+        doc = null;
+    }
+    const groups = (typeof doc === "object" && doc !== null ? doc : {});
+    const usage = {};
+    for (const key of usageKeys) {
+        const [group, field] = key.split(".");
+        const amount = Number(groups[group]?.[field]);
+        if (Number.isFinite(amount))
+            usage[key] = amount;
+    }
+    return usage;
+};
+/*  render the amounts of a usage attachment as its YAML data: one flow mapping per group  */
+export const usageData = (usage) => {
+    const groups = new Map();
+    for (const key of usageKeys) {
+        const [group, field] = key.split(".");
+        groups.set(group, [...(groups.get(group) ?? []), `${field}: ${String(usage[key] ?? 0)}`]);
+    }
+    return Array.from(groups, ([group, fields]) => `${(group + ":").padEnd(7)} { ${fields.join(", ")} }\n`).join("");
+};
+/*  the T-shirt sizes of the effort estimation of a task plan (its "Effort" key), in ascending order  */
+export const effortSizes = ["XS", "S", "M", "L", "XL"];
+/*  the default upper band bounds of the sizes "XS" to "L" (in human minutes,
+    see "project.task.effort.scale"), on a logarithmic scale of factor 4  */
+export const EFFORT_SCALE = "15,60,240,960";
+/*  parse the upper band bounds "<xs>,<s>,<m>,<l>" of the sizes "XS" to "L"
+    (strictly ascending positive human minutes), else throw  */
+export const parseEffortScale = (spec) => {
+    const bounds = spec.split(",").map((bound) => bound.trim());
+    if (bounds.length !== 4 || !bounds.every((bound) => /^\d+(?:\.\d+)?$/.test(bound)))
+        throw new Error(`invalid effort scale "${spec}" (expected four comma-separated numbers of minutes)`);
+    const scale = bounds.map((bound) => Number(bound));
+    if (!scale.every((bound, i) => bound > (i > 0 ? scale[i - 1] : 0)))
+        throw new Error(`invalid effort scale "${spec}" (expected strictly ascending positive bounds)`);
+    return scale;
+};
+/*  the representative human minutes of a size, for summing up efforts: the midpoint
+    of its band, where the open-ended "XL" counts twice the upper bound of "L"  */
+export const effortMinutes = (size, scale) => {
+    const i = effortSizes.indexOf(size);
+    return i < 4 ? ((i > 0 ? scale[i - 1] : 0) + scale[i]) / 2 : 2 * scale[3];
+};
+/*  parse the value "<size> [<hash>]" of an "Effort" key into its size and its
+    content hash (empty if not stamped yet), or null if malformed  */
+export const parseEffort = (value) => {
+    const m = /^(XS|S|M|L|XL)(?:[ \t]+([0-9A-Za-z]+))?$/.exec(value.trim());
+    return m === null ? null : { size: m[1], hash: m[2] ?? "" };
+};
+/*  the content hash of a task plan body, the "Effort" key is bound to: the body with
+    its bullet-points in the inert checkbox states "[-]" and "[>]" left out entirely, the
+    checkboxes of all other bullet-points left out, and all whitespace left out, so checkbox
+    state changes and re-wrapping keep the hash, while every other content change (including
+    cancelling or deferring a bullet-point) changes it  */
+export const effortHash = (body) => {
+    const content = [];
+    let inert = false;
+    for (const line of body.split(/\r?\n/)) {
+        const m = /^[-*+][ \t]+\[([ ?/xX>-])\]/.exec(line);
+        if (m !== null)
+            inert = m[1] === "-" || m[1] === ">";
+        else if (!/^[ \t]+\S/.test(line))
+            inert = false;
+        if (!inert)
+            content.push(line.replace(/^([ \t]*[-*+][ \t]+)\[[ ?/xX>-]\]/, "$1"));
+    }
+    return nanoid(`effort:${content.join("").replace(/\s+/g, "")}`);
+};
+/*  bind the "Effort" key of a task plan to its body (in place): a key without
+    content hash is stamped with the content hash of the body, while a malformed
+    or stale key (whose content hash differs from the one of the body) is dropped  */
+export const bindEffort = (plan) => {
+    const value = plan.header.Effort;
+    if (value === undefined)
+        return plan;
+    const effort = typeof value === "string" ? parseEffort(value) : null;
+    const hash = effortHash(plan.body);
+    if (effort !== null && effort.hash === "")
+        plan.header.Effort = `${effort.size} ${hash}`;
+    else if (effort === null || effort.hash !== hash)
+        Reflect.deleteProperty(plan.header, "Effort");
+    return plan;
+};
+/*  derive the title of a task plan from its body as defined by the
+    "Task titles" convention: the text following "TASK:" on the first
+    "#   TASK: <title>" heading line, or the empty string if absent  */
+export const taskTitle = (body) => {
+    const m = /^#[ \t]+TASK:[ \t]*(.*)$/m.exec(body);
+    return m === null ? "" : m[1].trim();
+};