@astrosheep/keiyaku 2.9.11 → 2.9.13

package/build/cli/commands/projection/history/handler.js

@@ -3,19 +3,63 @@ import { FlowError } from "../../../../flow-error.js";
 import { projectionHistoryJson, renderProjectionHistoryDetail, renderProjectionHistoryList } from "../../../render/projection-history.js";
 import { textResponse } from "../../../render/shared.js";
 import { projectDirectory } from "../../shared.js";
+const DEFAULT_HISTORY_LIMIT = 20;
+function page(entries, offset, requestedLimit) {
+    const limit = requestedLimit ?? DEFAULT_HISTORY_LIMIT;
+    const selected = entries.slice(offset, offset + limit);
+    const nextOffset = offset + selected.length < entries.length ? offset + selected.length : null;
+    return { entries: selected, pagination: { offset, limit, total: entries.length, nextOffset } };
+}
+function rawAvailability() {
+    return { retention: "unavailable", reason: "provider-raw-body-not-retained" };
+}
 export const handler = async (_stdin, flags, _signal, positional) => {
     const cwd = await projectDirectory(flags, "history");
     const [address] = positional;
+    const offset = flags.historyOffset ?? 0;
     if (!address) {
+        if (flags.historyRaw || flags.historyEntry !== undefined) {
+            throw new FlowError("INVALID_USAGE", "history --raw and --entry require one projection, alias, or artifact address");
+        }
         const runs = selectProjectionHistory(await readProjectionHistory(cwd), {
             filters: flags.taskFilters,
             sort: flags.taskSort,
             nowMs: Date.now(),
         });
-        return textResponse(flags.json ? projectionHistoryJson(runs) : renderProjectionHistoryList(runs));
+        const result = page(runs, offset, flags.historyLimit);
+        return textResponse(flags.json ? projectionHistoryJson(result) : renderProjectionHistoryList(result.entries, result.pagination));
+    }
+    if (flags.historyRaw && !flags.json) {
+        throw new FlowError("INVALID_USAGE", "history --raw requires --json");
+    }
+    if (flags.historyRaw && flags.historyEntry === undefined) {
+        throw new FlowError("INVALID_USAGE", "history --raw requires --entry N");
+    }
+    if (flags.historyEntry !== undefined && (flags.historyLimit !== undefined || offset !== 0)) {
+        throw new FlowError("INVALID_USAGE", "history --entry cannot be combined with --limit or --offset");
     }
     const detail = await readProjectionHistoryAddress(cwd, address);
     if (!detail)
         throw new FlowError("PROJECTION_HISTORY_NOT_FOUND", `history has no retained run for '${address}'`);
-    return textResponse(flags.json ? projectionHistoryJson(detail) : renderProjectionHistoryDetail(detail));
+    const addressedDetail = {
+        ...detail,
+        inputToken: address,
+        canonicalId: detail.id,
+    };
+    if (flags.historyEntry !== undefined) {
+        const entry = detail.activity?.retainedTimeline[flags.historyEntry];
+        if (!entry)
+            throw new FlowError("PROJECTION_HISTORY_NOT_FOUND", `history entry ${flags.historyEntry} is not retained for '${address}'`);
+        const response = {
+            id: addressedDetail.id,
+            inputToken: addressedDetail.inputToken,
+            canonicalId: detail.id,
+            ...(detail.alias ? { alias: detail.alias } : {}),
+            entry: { index: flags.historyEntry, event: entry, ...(flags.historyRaw ? { raw: rawAvailability() } : {}) },
+        };
+        return textResponse(flags.json ? projectionHistoryJson(response) : renderProjectionHistoryDetail(detail, response.entry));
+    }
+    return textResponse(flags.json
+        ? projectionHistoryJson(addressedDetail)
+        : renderProjectionHistoryDetail(detail));
 };

package/build/cli/commands/projection/history/meta.js

@@ -1,9 +1,9 @@
 export const meta = {
     command: "history",
     summary: "Discover retained Akuma runs or inspect one run",
-    usage: ["keiyaku history [PROJECTION|ALIAS|ARTIFACT] [-C|--cwd DIR] [--filter EXPR] [--sort KEYS] [--json]"],
+    usage: ["keiyaku history [PROJECTION|ALIAS|ARTIFACT] [-C|--cwd DIR] [--limit COUNT] [--offset COUNT] [--entry N] [--raw --json] [--json]"],
     stdin: { mode: "argument" },
-    flags: ["cwd", "repo", "filter", "sort", "json"],
-    purpose: "Read retained projection history and the public response-file path without reading response content.",
+    flags: ["cwd", "repo", "limit", "offset", "entry", "raw", "json"],
+    purpose: "Read bounded retained projection history; raw provider bodies require --json --raw on one addressed entry.",
     completionRank: 15,
 };

package/build/cli/commands/projection/kill/handler.js

@@ -10,12 +10,11 @@ export const handler = async (_stdin, flags, signal, positional) => runProjectio
         throw new FlowError("EMPTY_PARAM", "kill requires a projection address");
     const projection = await resolveProjectionCommandTarget(ctx, projectionAddress, "kill");
     const result = killProjectionGeneration(projection.directory);
-    if (result.status === "already-closed") {
-        return buildKillAlreadyClosedResponse(projection.id);
-    }
     if (flags.timeoutMs === undefined) {
-        return buildKillAcceptedResponse(projection.id);
+        return result.status === "already-closed"
+            ? buildKillAlreadyClosedResponse(projection.id)
+            : buildKillAcceptedResponse(projection.id);
     }
-    // Accepted with --wait: no acceptance receipt or address preamble.
+    // --wait always replays ordinary wait, including already-terminal generations.
     return buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: projection.directory, timeoutMs: flags.timeoutMs, signal }), { alias: projection.alias });
 });

package/build/cli/commands/projection/kill/meta.js

@@ -1,11 +1,11 @@
 export const meta = {
     command: "kill",
-    summary: "Stop the current projection generation",
+    summary: "Stop a projection's active run",
     usage: [
         "keiyaku kill <projection-address> [--wait DURATION]",
         "keiyaku @addr kill <projection-address> [--wait DURATION]",
     ],
     stdin: { mode: "argument" },
     flags: ["cwd", "repo", "contract", "wait"],
-    purpose: "Terminate the current generation while keeping the projection identity and tell ledger.",
+    purpose: "Stop the active run while keeping the projection available for inspection and follow-up messages.",
 };

package/build/cli/commands/projection/status/handler.js

@@ -1,26 +1,42 @@
 import { readKanshiBoard } from "../../../../core/status/board.js";
 import { normalizeTargetRef } from "../../../../core/target-ref.js";
-import { isProjectionId } from "../../../../core/projection/index.js";
-import { FlowError } from "../../../../flow-error.js";
-import { renderProjectionFilteredStatus, renderStatusBoard } from "../../../render/status.js";
+import { buildStatusPayload, renderAkumaRosterStatus, renderProjectionFilteredStatus, renderStatusBoard, renderStatusJson, } from "../../../render/status.js";
 import { coreTextResponse } from "../../../render/shared.js";
 import { projectDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags, _signal, positional) => {
-    const [projectionId] = positional;
-    if (projectionId !== undefined && !isProjectionId(projectionId)) {
-        throw new FlowError("EMPTY_PARAM", `invalid projection id: ${projectionId}`);
-    }
+    const [projectionAddress] = positional;
     // Status is read-only and must open outside Git. projectDirectory still
     // honors --repo as a repository coordinate when the operator names one.
-    const cwd = flags.target === undefined
+    const cwd = flags.target === undefined && flags.contractId === undefined
         ? await projectDirectory(flags, "status")
-        : await repositoryDirectory(flags, "status target filtering");
+        : await repositoryDirectory(flags, flags.contractId === undefined ? "status target filtering" : "status commission filtering");
     const target = flags.target === undefined ? undefined : normalizeTargetRef(flags.target);
     const board = await readKanshiBoard(cwd, Date.now(), {
         ...(target === undefined ? {} : { target }),
-        ...(projectionId === undefined ? {} : { projectionId }),
+        ...(projectionAddress === undefined ? {} : { projectionAddress }),
+        ...(flags.akumaRoster ? {
+            roster: true,
+            ...(flags.historyLimit === undefined ? {} : { rosterLimit: flags.historyLimit }),
+            ...(flags.historyOffset === undefined ? {} : { rosterOffset: flags.historyOffset }),
+        } : {}),
+        ...(flags.contractId === undefined ? {} : {
+            commission: {
+                raw: flags.contractId,
+                source: flags.contractAddressSource ?? "explicit-flag",
+            },
+        }),
     });
-    if (projectionId === undefined)
-        return coreTextResponse(renderStatusBoard(board), board);
-    return coreTextResponse(renderProjectionFilteredStatus(board, projectionId), board);
+    const selectedProjection = projectionAddress === undefined ? undefined : board.projections?.rows[0];
+    const unknown = projectionAddress !== undefined
+        && (selectedProjection === undefined || selectedProjection.state === "lost" || selectedProjection.state === "unknown");
+    const payload = buildStatusPayload(board);
+    if (flags.json)
+        return { ...coreTextResponse(renderStatusJson(payload), payload), ...(unknown ? { exitCode: 4 } : {}) };
+    if (projectionAddress === undefined) {
+        return coreTextResponse(flags.akumaRoster ? renderAkumaRosterStatus(board) : renderStatusBoard(board), payload);
+    }
+    return {
+        ...coreTextResponse(renderProjectionFilteredStatus(board, projectionAddress), payload),
+        ...(unknown ? { exitCode: 4 } : {}),
+    };
 };

package/build/cli/commands/projection/status/meta.js

@@ -1,9 +1,20 @@
 export const meta = {
     command: "status",
     summary: "Show the Kanshi board",
-    usage: ["keiyaku status [PROJECTION] [-C|--cwd DIR] [--repo DIR] [--target REF]"],
+    usage: [
+        "keiyaku status [PROJECTION|ALIAS] [-C|--cwd DIR] [--repo DIR] [--target REF]",
+        "keiyaku status --akuma [PROJECTION|ALIAS] [--limit COUNT] [--offset COUNT] [-C|--cwd DIR] [--repo DIR]",
+        "keiyaku status --contract ADDR [-C|--cwd DIR] [--repo DIR] [--target REF]",
+        "keiyaku @addr status [-C|--cwd DIR] [--repo DIR] [--target REF]",
+    ],
     stdin: { mode: "argument" },
-    flags: ["cwd", "repo", "target"],
-    purpose: "Read the Kanshi board or filter it to one projection without mutation.",
+    flags: ["cwd", "repo", "contract", "target", "akuma", "limit", "offset", "json"],
+    flagUsages: {
+        akuma: "--akuma",
+    },
+    flagDescriptions: {
+        akuma: "Show the complete Akuma projection roster; optionally address one projection or alias.",
+    },
+    purpose: "Read the Kanshi board or filter it to one projection or commission without mutation.",
     completionRank: 14,
 };

package/build/cli/commands/projection/tell/handler.js

@@ -1,8 +1,8 @@
 import { FlowError } from "../../../../flow-error.js";
-import { assertTellEffortSupported, interruptProjectionGeneration, tellProjection, writeInboxTell } from "../../../../core/projection/index.js";
+import { assertTellEffortSupported, interruptProjectionGeneration, readProjectionAlias, tellProjection, writeInboxTell } from "../../../../core/projection/index.js";
 import { waitForProjection } from "../../../../core/projection/index.js";
 import { prependAddressReceipt } from "../../../render/address.js";
-import { buildSilentTellResponse } from "../../../render/tell.js";
+import { buildTellAcceptedResponse } from "../../../render/tell.js";
 import { buildWaitResponse } from "../../../render/wait.js";
 import { resolveProjectionCommandTarget, runProjectionCommand, } from "../shared.js";
 export const handler = async (body, flags, signal, positional) => runProjectionCommand(flags, "tell", async (ctx) => {
@@ -23,6 +23,10 @@ export const handler = async (body, flags, signal, positional) => runProjectionC
         await tellProjection(projection.directory, projection.id, flags.effort);
     }
     if (flags.timeoutMs === undefined)
-        return buildSilentTellResponse();
-    return prependAddressReceipt(buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: projection.directory, timeoutMs: flags.timeoutMs, signal }), { alias: projection.alias }), ctx.address, { projectionId: projection.id, projectionAlias: projection.alias });
+        return buildTellAcceptedResponse(projection.id, projectionAddress, projection.alias);
+    const alias = projection.alias
+        && await readProjectionAlias(ctx.address?.repo.stableRoot ?? ctx.cwd, projection.alias) === projection.id
+        ? projection.alias
+        : undefined;
+    return prependAddressReceipt(buildWaitResponse(projection.id, await waitForProjection({ projectionDirectory: projection.directory, timeoutMs: flags.timeoutMs, signal }), { alias, inputToken: projectionAddress }), ctx.address, { projectionId: projection.id, projectionAlias: alias });
 });

package/build/cli/commands/projection/tell/meta.js

@@ -6,7 +6,7 @@ export const meta = {
         mode: "argument",
         selector: { kind: "positional", index: 1, required: true, rejectBlank: true },
     },
-    flags: ["cwd", "repo", "contract", "effort", "interrupt", "wait"],
+    flags: ["cwd", "repo", "contract", "effort", "interrupt", "wait", "json"],
     purpose: "Write intent to the mailbox; --interrupt terminates the active turn before successor wake.",
     completionRank: 3,
 };

package/build/cli/commands/projection/wait/handler.js

@@ -1,30 +1,50 @@
-import { projectionDirAtCoordinate, resolveProjectionCoordinate, snapshotCommissionProjectionIdsAtCoordinate, waitForProjection, waitForProjectionSet, } from "../../../../core/projection/index.js";
+import { projectionDirAtCoordinate, projectionAliasRootAtCoordinate, readProjectionAliasAtRoot, resolveProjectionCoordinate, snapshotCommissionProjectionIdsAtCoordinate, waitForProjection, waitForProjectionSet, } from "../../../../core/projection/index.js";
 import { FlowError } from "../../../../flow-error.js";
-import { prependAddressReceipt } from "../../../render/address.js";
 import { buildProjectionWaitSetResponse, buildWaitResponse } from "../../../render/wait.js";
-import { resolveProjectionCommandAddress, resolveProjectionCommandTarget, runProjectionCommand, } from "../shared.js";
+import { resolveProjectionCommandAddress, runProjectionCommand, } from "../shared.js";
 import { WAIT_SET_SELECTION_ERROR } from "./meta.js";
+async function refreshWaitAddresses(result, coordinate) {
+    const aliasRoot = projectionAliasRootAtCoordinate(coordinate);
+    return {
+        ...result,
+        results: await Promise.all(result.results.map(async (member) => {
+            const { alias: admittedAlias, inputToken: admittedToken, ...rest } = member;
+            const alias = admittedAlias && await readProjectionAliasAtRoot(aliasRoot, admittedAlias) === member.id
+                ? admittedAlias
+                : undefined;
+            const inputToken = admittedToken === admittedAlias && alias === undefined
+                ? member.id
+                : admittedToken;
+            return {
+                ...rest,
+                ...(inputToken ? { inputToken } : {}),
+                ...(alias ? { alias } : {}),
+            };
+        })),
+    };
+}
 export const handler = async (_stdin, flags, signal, positional) => runProjectionCommand(flags, "wait", async (ctx) => {
+    const coordinate = ctx.address
+        ? {
+            physicalRoot: ctx.address.repo.stableRoot,
+            authority: { kind: "repository", stableRoot: ctx.address.repo.stableRoot },
+        }
+        : await resolveProjectionCoordinate(ctx.cwd);
     // Selection modes only govern admitted sets with more than one explicit member.
     if (positional.length === 1) {
-        const projection = await resolveProjectionCommandTarget(ctx, positional[0], "wait");
-        return prependAddressReceipt(buildWaitResponse(projection.id, await waitForProjection({
+        const projection = await resolveProjectionCommandAddress(ctx, positional[0], "wait", coordinate);
+        const result = await waitForProjection({
             projectionDirectory: projection.directory,
             timeoutMs: flags.timeoutMs,
             signal,
-        }), { alias: projection.alias }), ctx.address, { projectionId: projection.id, projectionAlias: projection.alias });
+        });
+        const alias = projection.alias
+            && await readProjectionAliasAtRoot(projectionAliasRootAtCoordinate(coordinate), projection.alias) === projection.id
+            ? projection.alias
+            : undefined;
+        return buildWaitResponse(projection.id, result, { alias, inputToken: positional[0] });
     }
     const selected = new Map();
-    let coordinate;
-    if (ctx.address) {
-        coordinate = {
-            physicalRoot: ctx.address.repo.stableRoot,
-            authority: { kind: "repository", stableRoot: ctx.address.repo.stableRoot },
-        };
-    }
-    else {
-        coordinate = await resolveProjectionCoordinate(ctx.cwd);
-    }
     if (positional.length === 0) {
         if (ctx.address?.binding.kind === "commission") {
             for (const id of await snapshotCommissionProjectionIdsAtCoordinate(coordinate, ctx.address.binding.commissionId)) {
@@ -36,20 +56,25 @@ export const handler = async (_stdin, flags, signal, positional) => runProjectio
         // Resolve in argument order so multiple bad coordinates have one stable failure.
         for (const projectionAddress of positional) {
             const projection = await resolveProjectionCommandAddress(ctx, projectionAddress, "wait", coordinate);
-            selected.set(projection.id, { id: projection.id, projectionDirectory: projection.directory });
+            selected.set(projection.id, {
+                id: projection.id,
+                projectionDirectory: projection.directory,
+                inputToken: projectionAddress,
+                ...(projection.alias ? { alias: projection.alias } : {}),
+            });
         }
     }
-    const projections = [...selected.values()].sort((left, right) => left.id.localeCompare(right.id));
+    const projections = [...selected.values()];
     if (projections.length === 0) {
         throw new FlowError("EMPTY_PARAM", "wait commission snapshot contains no projections");
     }
     if (!flags.any && !flags.all) {
         throw new FlowError("EMPTY_PARAM", WAIT_SET_SELECTION_ERROR);
     }
-    return prependAddressReceipt(buildProjectionWaitSetResponse(await waitForProjectionSet({
+    return buildProjectionWaitSetResponse(await refreshWaitAddresses(await waitForProjectionSet({
         projections,
         selection: flags.any ? "any" : "all",
         timeoutMs: flags.timeoutMs,
         signal,
-    })), ctx.address);
+    }), coordinate));
 });

package/build/cli/commands/projection/wait/meta.js

@@ -8,7 +8,7 @@ export const meta = {
         "keiyaku @addr wait [<projection-address>...] (--any|--all) [--timeout DURATION]",
     ],
     stdin: { mode: "argument" },
-    flags: ["cwd", "repo", "contract", "timeout", "any", "all"],
+    flags: ["cwd", "repo", "contract", "timeout", "any", "all", "json"],
     flagDescriptions: {
         all: "For a projection set, return only after every admitted member reaches a terminal state.",
     },

package/build/cli/commands/shared.js

@@ -39,7 +39,7 @@ export function buildCallInput(content, flags, mode = "call", platform = process
         ...(mode === "call" && flags.alias !== undefined ? { alias: assertProjectionAlias(flags.alias) } : {}),
     };
 }
-export function revivePrompt(stdin) {
+export function forkPrompt(stdin) {
     return stdin.trim() ? stdin : "Continue from the previous response.";
 }
 export function effectiveDirectory(flags, platform = process.platform) {
@@ -54,7 +54,7 @@ export async function repositoryDirectory(flags, operation) {
             const asTyped = flags.contractAddressSource === "at-address"
                 ? `@${flags.contractId}`
                 : `--contract ${flags.contractId}`;
-            throw new AddressResolutionError("EMPTY_PARAM", `${asTyped} is a commission address, but ${candidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
+            throw new AddressResolutionError("UNKNOWN_ADDRESS", `${asTyped} is a commission address, but ${candidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
                 repo: { kind: "user" },
                 workdir: effectiveDirectory(flags),
                 spelling: {

package/build/cli/commands/system/catalog.js

@@ -1,7 +1,9 @@
 import { meta as guideMeta } from "./guide/meta.js";
 import { meta as completionMeta } from "./completion/meta.js";
 import { meta as dumpEnvMeta } from "./dump-env/meta.js";
+import { meta as verificationMeta } from "../verification/meta.js";
 export const systemCatalog = [
+    { meta: verificationMeta, load: async () => await import("../verification/handler.js") },
     { meta: guideMeta, load: () => import("./guide/handler.js") },
     { meta: completionMeta, load: () => import("./completion/handler.js") },
     { meta: dumpEnvMeta, load: () => import("./dump-env/handler.js") },

package/build/cli/commands/task/add/handler.js

@@ -1,22 +1,38 @@
-import { createTask, openTaskMutationContext, resolveTaskCreator, } from "../../../../core/task/index.js";
+import { createTask, openTaskMutationContext, parseTaskCreationDocument, resolveTaskCreator, } from "../../../../core/task/index.js";
+import { FlowError } from "../../../../flow-error.js";
 import { renderTaskMutationRow } from "../../../render/task.js";
 import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-import { parseTaskAddInput } from "../shared.js";
-export const handler = async (stdin, flags, signal) => {
-    const input = parseTaskAddInput(stdin);
-    const cwd = effectiveDirectory(flags);
+import { taskCommandDirectory } from "../shared.js";
+function hasCreationFlags(flags) {
+    return flags.taskPri !== undefined
+        || flags.taskNeeds !== undefined
+        || flags.taskParent !== undefined
+        || flags.taskFrom !== undefined
+        || flags.taskSupersedes !== undefined
+        || flags.taskRelatesTo !== undefined;
+}
+export const handler = async (stdin, flags, signal, positional) => {
+    const fromStdin = positional[0] === "-";
+    if (fromStdin && hasCreationFlags(flags)) {
+        throw new FlowError("INVALID_USAGE", "task add accepts either a stdin task document or creation flags, not both");
+    }
+    const input = fromStdin
+        ? parseTaskCreationDocument({ path: "stdin", text: stdin })
+        : { title: stdin };
+    const cwd = await taskCommandDirectory(flags);
     const context = await openTaskMutationContext(cwd, signal);
     const task = await createTask(context.repository, {
         ...input,
         namespace: context.namespace,
         creator: await resolveTaskCreator(cwd),
-        ...(flags.taskPri === undefined ? {} : { pri: flags.taskPri }),
-        needs: flags.taskNeeds ?? [],
-        parent: flags.taskParent ?? null,
-        from: flags.taskFrom ?? [],
-        supersedes: flags.taskSupersedes ?? [],
-        relatesTo: flags.taskRelatesTo ?? [],
+        ...(fromStdin ? {} : {
+            ...(flags.taskPri === undefined ? {} : { pri: flags.taskPri }),
+            needs: flags.taskNeeds ?? [],
+            parent: flags.taskParent ?? null,
+            from: flags.taskFrom ?? [],
+            supersedes: flags.taskSupersedes ?? [],
+            relatesTo: flags.taskRelatesTo ?? [],
+        }),
     }, { now: () => new Date() });
     return textResponse(renderTaskMutationRow(task));
 };

package/build/cli/commands/task/add/meta.js

@@ -1,19 +1,31 @@
-const TASK_ADD_USAGE_PREFIX = "keiyaku task add [-C|--cwd DIR] [--needs COORDINATE]... [--parent COORDINATE] [--from COORDINATE]... [--supersedes COORDINATE]... [--relates-to COORDINATE]... [--pri 0-3]";
+const TASK_ADD_USAGE_PREFIX = "keiyaku task add [-C|--cwd DIR] [--contract ADDR]";
+const TASK_ADD_CREATION_FLAGS = "[--needs COORDINATE]... [--parent COORDINATE] [--from COORDINATE]... [--supersedes COORDINATE]... [--relates-to COORDINATE]... [--pri 0-3]";
+export const TASK_ADD_INPUT_SHAPE_ERROR = "task add accepts exactly one <TITLE|->; use `keiyaku task add \"title\"` or `keiyaku task add - < task.md`";
 export const meta = {
     command: "task add",
     summary: "Add a task",
     usage: [
-        `${TASK_ADD_USAGE_PREFIX} <BODY>`,
+        `${TASK_ADD_USAGE_PREFIX} ${TASK_ADD_CREATION_FLAGS} <TITLE>`,
         `${TASK_ADD_USAGE_PREFIX} - < task.md`,
     ],
     stdin: {
         mode: "argument",
         selector: { kind: "positional", index: 0, required: true, rejectBlank: true },
     },
-    flags: ["cwd", "needs", "parent", "from", "supersedes", "relates-to", "pri"],
-    purpose: "Create a lightweight task from a title and optional body.",
+    flags: ["cwd", "contract", "needs", "parent", "from", "supersedes", "relates-to", "pri"],
+    purpose: "Create a lightweight task from a title or one canonical task document.",
+    input: [
+        "---",
+        "title: Extract task parser",
+        "pri: 1",
+        "needs:",
+        "  - task-model",
+        "---",
+        "Markdown body.",
+    ],
     notes: [
-        "<BODY> and literal - are mutually exclusive body selectors. Use literal - with stdin for multiline prose.",
-        "Only literal - reads stdin; unselected piped bytes are ignored and never change a literal <BODY>.",
+        "Literal - reads one canonical task document. It may declare title, pri, needs, parent, from, supersedes, relatesTo, and Markdown body.",
+        "Creation-owned fields (id, state, timestamps, creator, startedAt, contractId) are rejected. Stdin documents and creation flags are mutually exclusive.",
+        "Only literal - reads stdin; unselected piped bytes are ignored and never change a literal <TITLE>.",
     ],
 };

package/build/cli/commands/task/catalog.js

@@ -1,5 +1,6 @@
 import { meta as taskMeta } from "./task/meta.js";
 import { meta as addMeta } from "./add/meta.js";
+import { meta as composeMeta } from "./compose/meta.js";
 import { meta as showMeta } from "./show/meta.js";
 import { meta as lsMeta } from "./ls/meta.js";
 import { meta as logMeta } from "./log/meta.js";
@@ -8,12 +9,14 @@ import { meta as stopMeta } from "./stop/meta.js";
 import { meta as holdMeta } from "./hold/meta.js";
 import { meta as resumeMeta } from "./resume/meta.js";
 import { meta as doneMeta } from "./done/meta.js";
+import { meta as noteMeta } from "./note/meta.js";
 import { meta as dropMeta } from "./drop/meta.js";
 import { meta as updateMeta } from "./update/meta.js";
 import { meta as doctorMeta } from "./doctor/meta.js";
 export const taskCatalog = [
     { meta: taskMeta, load: () => import("./task/handler.js") },
     { meta: addMeta, load: () => import("./add/handler.js") },
+    { meta: composeMeta, load: () => import("./compose/handler.js") },
     { meta: showMeta, load: () => import("./show/handler.js") },
     { meta: lsMeta, load: () => import("./ls/handler.js") },
     { meta: logMeta, load: () => import("./log/handler.js") },
@@ -22,6 +25,7 @@ export const taskCatalog = [
     { meta: holdMeta, load: () => import("./hold/handler.js") },
     { meta: resumeMeta, load: () => import("./resume/handler.js") },
     { meta: doneMeta, load: () => import("./done/handler.js") },
+    { meta: noteMeta, load: () => import("./note/handler.js") },
     { meta: dropMeta, load: () => import("./drop/handler.js") },
     { meta: updateMeta, load: () => import("./update/handler.js") },
     { meta: doctorMeta, load: () => import("./doctor/handler.js") },

package/build/cli/commands/task/compose/handler.js

@@ -0,0 +1,18 @@
+import { composeTasks, openTaskMutationContext, planTaskComposition, resolveTaskCreator, } from "../../../../core/task/index.js";
+import { renderTaskComposition, renderTaskCompositionJson } from "../../../render/task.js";
+import { textResponse } from "../../../render/shared.js";
+import { taskCommandDirectory } from "../shared.js";
+export const handler = async (stdin, flags, signal) => {
+    const cwd = await taskCommandDirectory(flags);
+    const context = await openTaskMutationContext(cwd, signal);
+    const input = {
+        sketch: stdin,
+        creator: await resolveTaskCreator(cwd),
+        namespace: context.namespace,
+        now: () => new Date(),
+    };
+    const plan = flags.check
+        ? planTaskComposition(await context.repository.read(), input)
+        : await composeTasks(context.repository, input);
+    return textResponse(flags.json ? renderTaskCompositionJson(plan, Boolean(flags.check)) : renderTaskComposition(plan, Boolean(flags.check)));
+};

package/build/cli/commands/task/compose/meta.js

@@ -0,0 +1,10 @@
+export const meta = {
+    command: "task compose",
+    summary: "Atomically compose tasks from a tree sketch",
+    usage: ["keiyaku task compose [-C|--cwd DIR] [--contract ADDR] [--check] - < sketch.md"],
+    stdin: { mode: "document", selector: { kind: "positional", index: 0, required: true, rejectBlank: true } },
+    flags: ["cwd", "contract", "check", "json"],
+    purpose: "Atomically create and rewire tasks from one validated tree sketch.",
+    input: ["Each task line is two-space indented + title or @COORDINATE, followed by whitespace-separated parent=, needs=@a,@b, supersedes=@c, or relates=@d declarations. Bare prose is allowed only in a nested + task body."],
+    notes: ["Nesting assigns parent. Top-level references preserve their parent; parent= clears it. Omitted relation declarations preserve their current complete set, while an explicit empty declaration clears that set."],
+};

package/build/cli/commands/task/doctor/handler.js

@@ -1,4 +1,3 @@
 import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-import { renderTaskDoctor } from "../shared.js";
-export const handler = async (_stdin, flags) => textResponse(await renderTaskDoctor(effectiveDirectory(flags)));
+import { renderTaskDoctor, taskCommandDirectory } from "../shared.js";
+export const handler = async (_stdin, flags) => textResponse(await renderTaskDoctor(await taskCommandDirectory(flags)));

package/build/cli/commands/task/doctor/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task doctor",
     summary: "Diagnose the task board",
-    usage: ["keiyaku task doctor [-C|--cwd DIR]"],
+    usage: ["keiyaku task doctor [-C|--cwd DIR] [--contract ADDR]"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Report task state counts, supported board diseases, and lock state without repair.",
 };

package/build/cli/commands/task/done/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task done",
     summary: "Complete a task",
-    usage: ["keiyaku task done [-C|--cwd DIR] [COORDINATE]"],
+    usage: ["keiyaku task done [-C|--cwd DIR] [--contract ADDR] [COORDINATE]"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Complete an open or in-progress task.",
 };

package/build/cli/commands/task/drop/handler.js

@@ -1,3 +1,8 @@
-import { dropTask } from "../../../../core/task/index.js";
+import { dropTask, dropTaskWithNote, resolveTaskCreator } from "../../../../core/task/index.js";
 import { runTaskMutationCommand } from "../shared.js";
-export const handler = async (_stdin, flags, _signal, positional) => runTaskMutationCommand(flags, (repository) => dropTask(repository, positional[0]));
+export const handler = async (_stdin, flags, _signal, positional) => runTaskMutationCommand(flags, async (repository, cwd) => flags.taskNote === undefined
+    ? dropTask(repository, positional[0])
+    : dropTaskWithNote(repository, positional[0], {
+        actor: await resolveTaskCreator(cwd),
+        text: flags.taskNote,
+    }));

package/build/cli/commands/task/drop/meta.js

@@ -1,8 +1,11 @@
 export const meta = {
     command: "task drop",
     summary: "Drop a task",
-    usage: ["keiyaku task drop [-C|--cwd DIR] COORDINATE"],
-    stdin: { mode: "argument" },
-    flags: ["cwd"],
+    usage: ["keiyaku task drop [-C|--cwd DIR] [--contract ADDR] COORDINATE [--note TEXT|-]"],
+    stdin: {
+        mode: "argument",
+        selector: { kind: "flag", names: ["taskNote"], required: false, rejectBlank: true },
+    },
+    flags: ["cwd", "contract", "note"],
     purpose: "Abandon an open or in-progress task.",
 };

package/build/cli/commands/task/hold/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task hold",
     summary: "Put a task on hold",
-    usage: ["keiyaku task hold [-C|--cwd DIR] COORDINATE"],
+    usage: ["keiyaku task hold [-C|--cwd DIR] [--contract ADDR] COORDINATE"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Move an open or in-progress task to on hold.",
 };

package/build/cli/commands/task/log/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task log",
     summary: "Show one task's Git history",
-    usage: ["keiyaku task log [-C|--cwd DIR] COORDINATE"],
+    usage: ["keiyaku task log [-C|--cwd DIR] [--contract ADDR] COORDINATE"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Read the current checkout branch's task micro-commit history.",
 };

package/build/cli/commands/task/ls/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task ls",
     summary: "List tasks",
-    usage: ["keiyaku task ls [-C|--cwd DIR] [--all|--done] [--filter EXPR] [--sort KEYS] [--json]"],
+    usage: ["keiyaku task ls [-C|--cwd DIR] [--contract ADDR] [--all|--done] [--filter EXPR] [--sort KEYS] [--json]"],
     stdin: { mode: "argument" },
-    flags: ["cwd", "all", "done", "filter", "sort", "json"],
+    flags: ["cwd", "contract", "all", "done", "filter", "sort", "json"],
     purpose: "List tasks from the working-tree board.",
 };