@astrosheep/keiyaku 2.9.12 → 2.9.13

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) {

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

@@ -9,6 +9,7 @@ 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";
@@ -24,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

@@ -1,9 +1,9 @@
 import { composeTasks, openTaskMutationContext, planTaskComposition, resolveTaskCreator, } from "../../../../core/task/index.js";
 import { renderTaskComposition, renderTaskCompositionJson } from "../../../render/task.js";
 import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
+import { taskCommandDirectory } from "../shared.js";
 export const handler = async (stdin, flags, signal) => {
-    const cwd = effectiveDirectory(flags);
+    const cwd = await taskCommandDirectory(flags);
     const context = await openTaskMutationContext(cwd, signal);
     const input = {
         sketch: stdin,

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

@@ -1,9 +1,9 @@
 export const meta = {
     command: "task compose",
     summary: "Atomically compose tasks from a tree sketch",
-    usage: ["keiyaku task compose [-C|--cwd DIR] [--check] - < sketch.md"],
+    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", "check", "json"],
+    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.",
 };

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

@@ -0,0 +1,6 @@
+import { appendTaskNote, resolveTaskCreator } from "../../../../core/task/index.js";
+import { runTaskMutationCommand } from "../shared.js";
+export const handler = async (stdin, flags, _signal, positional) => runTaskMutationCommand(flags, async (repository, cwd) => appendTaskNote(repository, positional[0], {
+    actor: await resolveTaskCreator(cwd),
+    text: stdin,
+}));

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

@@ -0,0 +1,11 @@
+export const meta = {
+    command: "task note",
+    summary: "Append an immutable task note",
+    usage: ["keiyaku task note [-C|--cwd DIR] [--contract ADDR] COORDINATE TEXT|-"],
+    stdin: {
+        mode: "argument",
+        selector: { kind: "positional", index: 1, required: true, rejectBlank: true },
+    },
+    flags: ["cwd", "contract"],
+    purpose: "Record an append-only task journal fact.",
+};

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

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

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

@@ -1,30 +1,44 @@
 import { FlowError } from "../../../flow-error.js";
+import { attachAddressCarrier, resolveExplicitContractAddressFromRead } from "../../../core/addressing.js";
+import { readRepositoryLifecycle } from "../../../core/repository-ledger/read-model.js";
+import { findRegisteredContractWorktreePathFromModel, stableRepoRoot } from "../../../core/worktree-path.js";
 import { openTaskCommandRepository, parseTaskDocument, readTaskDoctor, taskCoordinateFromSourcePath, } from "../../../core/task/index.js";
 import { deriveTaskDisplay, renderTaskList, renderTaskMutationRow, } from "../../render/task.js";
 import { textResponse } from "../../render/shared.js";
 import { effectiveDirectory } from "../shared.js";
-/** Open the task command repository for flags.cwd and run the verb. */
-export async function withTaskCommandRepository(flags, run) {
+/** Resolve --contract to its one ledger-owned checkout before task access. */
+export async function taskCommandDirectory(flags) {
     const cwd = effectiveDirectory(flags);
+    if (flags.contractId === undefined)
+        return cwd;
+    const stableRoot = await stableRepoRoot(cwd);
+    const admitted = resolveExplicitContractAddressFromRead({
+        read: await readRepositoryLifecycle(stableRoot),
+        stableRoot,
+        workdir: cwd,
+        raw: flags.contractId,
+        source: flags.contractAddressSource ?? "explicit-flag",
+    });
+    const worktree = admitted.model.resources.worktree;
+    const lifecycle = admitted.model.phase;
+    if (!worktree || worktree.state !== "held") {
+        throw attachAddressCarrier(new FlowError("CONTRACT_WORKSPACE_UNAVAILABLE", `contract ${admitted.model.contract} has no materialized workspace for task commands (${lifecycle})`, { facts: { kind: "task_contract_workspace", contractId: admitted.model.contract, lifecycle, reason: "not-materialized" } }), admitted.address);
+    }
+    const registered = await findRegisteredContractWorktreePathFromModel(stableRoot, admitted.model);
+    if (!registered) {
+        throw attachAddressCarrier(new FlowError("CONTRACT_WORKSPACE_UNAVAILABLE", `contract ${admitted.model.contract} worktree is not a verified ledger-owned materialized checkout`, { facts: { kind: "task_contract_workspace", contractId: admitted.model.contract, lifecycle, reason: "unregistered" } }), admitted.address);
+    }
+    return registered;
+}
+/** Open the selected task command repository and run the verb. */
+export async function withTaskCommandRepository(flags, run) {
+    const cwd = await taskCommandDirectory(flags);
     return run(await openTaskCommandRepository(cwd), cwd);
 }
 /** Shared shell: open repository → mutate → renderTaskMutationRow receipt. */
 export async function runTaskMutationCommand(flags, mutate) {
     return textResponse(renderTaskMutationRow(await withTaskCommandRepository(flags, mutate)));
 }
-export function parseTaskAddInput(input) {
-    if (!input.trim())
-        throw new FlowError("EMPTY_PARAM", "task add input cannot be blank");
-    const lines = input.split(/\r?\n/);
-    const firstLine = lines[0]?.startsWith("# ") ? lines[0].slice(2) : lines[0];
-    const title = firstLine?.trim() ?? "";
-    if (!title)
-        throw new FlowError("EMPTY_PARAM", "task title cannot be blank");
-    if (lines.length > 1 && lines[1].trim() !== "") {
-        throw new FlowError("EMPTY_PARAM", "task add body must follow the title after a blank line");
-    }
-    return { title, body: lines.slice(2).join("\n") };
-}
 export function taskSelection(flags) {
     return flags.all ? "all" : flags.done ? "done" : "default";
 }

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

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task show",
     summary: "Show one task and its children tree",
-    usage: ["keiyaku task show [-C|--cwd DIR] COORDINATE [--json]"],
+    usage: ["keiyaku task show [-C|--cwd DIR] [--contract ADDR] COORDINATE [--json]"],
     stdin: { mode: "argument" },
-    flags: ["cwd", "json"],
+    flags: ["cwd", "contract", "json"],
     purpose: "Read one task and every descendant linked by parent edges.",
 };

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

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

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

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