@astrosheep/keiyaku 4.0.5 → 4.1.0

package/build/src/cli/commands/contract.d.ts

@@ -5,8 +5,8 @@ export type ContractCommandSpec = Readonly<{
     flags: Readonly<Record<string, ContractFlagKind>>;
     usage: string;
     purpose: string;
+    help?: string;
 }>;
-export declare const AMEND_MINIMAL_STDIN_HELP: string;
 export declare const CONTRACT_COMMAND_SPECS: {
     readonly bind: {
         readonly positional: "none";
@@ -20,7 +20,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly gates: "raw-value";
             readonly json: "boolean";
         };
-        readonly usage: "bind [--task <task/...>] [--target <ref>] [--here] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] [--json] -";
+        readonly usage: "bind [--task <task/...>] [--target <ref>] [--here] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] -";
         readonly purpose: "Create one Contract from stdin Markdown.";
     };
     readonly amend: {
@@ -33,8 +33,9 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly gates: "raw-value";
             readonly json: "boolean";
         };
-        readonly usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [--json] [-]";
+        readonly usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]";
         readonly purpose: "Amend one Contract's document operations or structured terms.";
+        readonly help: string;
     };
     readonly deliver: {
         readonly positional: "optional";
@@ -43,10 +44,12 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly actor: "value";
             readonly message: "value";
             readonly "include-dirty": "boolean";
+            readonly "materialize-conflict": "boolean";
             readonly json: "boolean";
         };
-        readonly usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--actor <actor>] [--json]";
-        readonly purpose: "Deliver one Contract candidate.";
+        readonly usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--actor <actor>]";
+        readonly purpose: "Deliver one Contract candidate from the appointed worktree.";
+        readonly help: string;
     };
     readonly review: {
         readonly positional: "optional";
@@ -58,7 +61,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly summary: "value";
             readonly json: "boolean";
         };
-        readonly usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>] [--json]";
+        readonly usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]";
         readonly purpose: "Record one review verdict.";
     };
     readonly arc: {
@@ -68,7 +71,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly actor: "value";
             readonly json: "boolean";
         };
-        readonly usage: "arc [<contract>|@<contract>] [--actor <actor>] [--json] -";
+        readonly usage: "arc [<contract>|@<contract>] [--actor <actor>] -";
         readonly purpose: "Record stdin arc Markdown for one Contract.";
     };
     readonly abandon: {
@@ -79,7 +82,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly note: "value";
             readonly json: "boolean";
         };
-        readonly usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--json]";
+        readonly usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]";
         readonly purpose: "Abandon one Contract with an optional note.";
     };
     readonly status: {
@@ -88,7 +91,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "status [<contract>|@name|<aku/...>] [--json]";
+        readonly usage: "status [<contract>|@name|<aku/...>]";
         readonly purpose: "Read the world status board or one Contract projection.";
     };
     readonly show: {
@@ -97,7 +100,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "show [<contract>|@<contract>] [--json]";
+        readonly usage: "show [<contract>|@<contract>]";
         readonly purpose: "Read one Contract guidance projection.";
     };
     readonly ls: {
@@ -106,7 +109,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "ls task[/] [--json]\n       keiyaku ls kei[/] [--json]\n       keiyaku ls aku[/] [--json]\n       keiyaku ls aku/<akuma>[/] [--json]\n       keiyaku ls \"aku/*/*\" [--json]";
+        readonly usage: "ls task[/]\n       keiyaku ls kei[/]\n       keiyaku ls aku[/]\n       keiyaku ls aku/<akuma>[/]\n       keiyaku ls \"aku/*/*\"";
         readonly purpose: "List one identity directory.";
     };
     readonly audit: {
@@ -118,7 +121,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly actor: "value";
             readonly json: "boolean";
         };
-        readonly usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--actor <actor>] [--json]";
+        readonly usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--actor <actor>]";
         readonly purpose: "Ask what candidate preparation, Verification, and target placement would do.";
     };
     readonly reconcile: {
@@ -128,16 +131,26 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly "retry-hooks": "boolean";
             readonly json: "boolean";
         };
-        readonly usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--json]";
+        readonly usage: "reconcile [<contract>|@<contract>] [--retry-hooks]";
         readonly purpose: "Reconcile one Contract or the invocation world.";
     };
+    readonly nuke: {
+        readonly positional: "none";
+        readonly stdin: "none";
+        readonly flags: {
+            readonly confirm: "value";
+            readonly json: "boolean";
+        };
+        readonly usage: "nuke [--confirm <WorldRoot>] [--json]";
+        readonly purpose: "Remove Keiyaku-owned data from one confirmed World.";
+    };
     readonly settings: {
         readonly positional: "none";
         readonly stdin: "none";
         readonly flags: {
             readonly json: "boolean";
         };
-        readonly usage: "settings [--json]";
+        readonly usage: "settings";
         readonly purpose: "Read user and project Settings resources.";
     };
     readonly region: {
@@ -148,7 +161,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly path: "value";
             readonly json: "boolean";
         };
-        readonly usage: "region [<contract>] [--overlap] [--json]\n       region --path <repo-relative-path> [--json]";
+        readonly usage: "region [<contract>] [--overlap]\n       region --path <repo-relative-path>";
         readonly purpose: "Read active declared Contract Regions.";
     };
 };

package/build/src/cli/commands/contract.js

@@ -1,20 +1,36 @@
-export const AMEND_MINIMAL_STDIN_HELP = [
-    "minimal stdin:",
-    "  ## Replace: Design",
-    "  <complete replacement>",
-].join("\n");
 export const CONTRACT_COMMAND_SPECS = {
-    bind: { positional: "none", stdin: "required", flags: { actor: "value", task: "value", target: "value", here: "boolean", after: "repeat-value", gates: "raw-value", json: "boolean" }, usage: "bind [--task <task/...>] [--target <ref>] [--here] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] [--json] -", purpose: "Create one Contract from stdin Markdown." },
-    amend: { positional: "optional", stdin: "optional", flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" }, usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [--json] [-]", purpose: "Amend one Contract's document operations or structured terms." },
-    deliver: { positional: "optional", stdin: "none", flags: { actor: "value", message: "value", "include-dirty": "boolean", json: "boolean" }, usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--actor <actor>] [--json]", purpose: "Deliver one Contract candidate." },
-    review: { positional: "optional", stdin: "optional", flags: { actor: "value", satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" }, usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>] [--json]", purpose: "Record one review verdict." },
-    arc: { positional: "optional", stdin: "required", flags: { actor: "value", json: "boolean" }, usage: "arc [<contract>|@<contract>] [--actor <actor>] [--json] -", purpose: "Record stdin arc Markdown for one Contract." },
-    abandon: { positional: "optional", stdin: "none", flags: { actor: "value", note: "value", json: "boolean" }, usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--json]", purpose: "Abandon one Contract with an optional note." },
-    status: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "status [<contract>|@name|<aku/...>] [--json]", purpose: "Read the world status board or one Contract projection." },
-    show: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "show [<contract>|@<contract>] [--json]", purpose: "Read one Contract guidance projection." },
-    ls: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "ls task[/] [--json]\n       keiyaku ls kei[/] [--json]\n       keiyaku ls aku[/] [--json]\n       keiyaku ls aku/<akuma>[/] [--json]\n       keiyaku ls \"aku/*/*\" [--json]", purpose: "List one identity directory." },
-    audit: { positional: "optional", stdin: "none", flags: { "include-dirty": "boolean", diff: "boolean", actor: "value", json: "boolean" }, usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--actor <actor>] [--json]", purpose: "Ask what candidate preparation, Verification, and target placement would do." },
-    reconcile: { positional: "optional", stdin: "none", flags: { "retry-hooks": "boolean", json: "boolean" }, usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--json]", purpose: "Reconcile one Contract or the invocation world." },
-    settings: { positional: "none", stdin: "none", flags: { json: "boolean" }, usage: "settings [--json]", purpose: "Read user and project Settings resources." },
-    region: { positional: "optional", stdin: "none", flags: { overlap: "boolean", path: "value", json: "boolean" }, usage: "region [<contract>] [--overlap] [--json]\n       region --path <repo-relative-path> [--json]", purpose: "Read active declared Contract Regions." },
+    bind: { positional: "none", stdin: "required", flags: { actor: "value", task: "value", target: "value", here: "boolean", after: "repeat-value", gates: "raw-value", json: "boolean" }, usage: "bind [--task <task/...>] [--target <ref>] [--here] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] -", purpose: "Create one Contract from stdin Markdown." },
+    amend: {
+        positional: "optional", stdin: "optional", flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" }, usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]", purpose: "Amend one Contract's document operations or structured terms.",
+        help: [
+            "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
+            "  ## Append: Context|Objective|Design|Criteria|<extension>",
+            "  ## Add: Criteria|<new-extension-title>",
+            "  ## Update: <existing-extension-title>",
+            "  ## Remove: Criterion <existing-title>",
+            "  ## Remove: <existing-extension-title>",
+        ].join("\n"),
+    },
+    deliver: {
+        positional: "optional", stdin: "none", flags: { actor: "value", message: "value", "include-dirty": "boolean", "materialize-conflict": "boolean", json: "boolean" }, usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--actor <actor>]", purpose: "Deliver one Contract candidate from the appointed worktree.",
+        help: [
+            "  --include-dirty         Capture the complete non-ignored worktree tree as the",
+            "                          candidate; stages nothing, commits nothing. Refused",
+            "                          while unmerged paths exist.",
+            "  --materialize-conflict  After a conflict result, project the judged targetHead",
+            "                          into the worktree as an uncommitted merge. Not a",
+            "                          delivery: resolve, stage, deliver again.",
+        ].join("\n"),
+    },
+    review: { positional: "optional", stdin: "optional", flags: { actor: "value", satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" }, usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]", purpose: "Record one review verdict." },
+    arc: { positional: "optional", stdin: "required", flags: { actor: "value", json: "boolean" }, usage: "arc [<contract>|@<contract>] [--actor <actor>] -", purpose: "Record stdin arc Markdown for one Contract." },
+    abandon: { positional: "optional", stdin: "none", flags: { actor: "value", note: "value", json: "boolean" }, usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]", purpose: "Abandon one Contract with an optional note." },
+    status: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "status [<contract>|@name|<aku/...>]", purpose: "Read the world status board or one Contract projection." },
+    show: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "show [<contract>|@<contract>]", purpose: "Read one Contract guidance projection." },
+    ls: { positional: "optional", stdin: "none", flags: { json: "boolean" }, usage: "ls task[/]\n       keiyaku ls kei[/]\n       keiyaku ls aku[/]\n       keiyaku ls aku/<akuma>[/]\n       keiyaku ls \"aku/*/*\"", purpose: "List one identity directory." },
+    audit: { positional: "optional", stdin: "none", flags: { "include-dirty": "boolean", diff: "boolean", actor: "value", json: "boolean" }, usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--actor <actor>]", purpose: "Ask what candidate preparation, Verification, and target placement would do." },
+    reconcile: { positional: "optional", stdin: "none", flags: { "retry-hooks": "boolean", json: "boolean" }, usage: "reconcile [<contract>|@<contract>] [--retry-hooks]", purpose: "Reconcile one Contract or the invocation world." },
+    nuke: { positional: "none", stdin: "none", flags: { confirm: "value", json: "boolean" }, usage: "nuke [--confirm <WorldRoot>] [--json]", purpose: "Remove Keiyaku-owned data from one confirmed World." },
+    settings: { positional: "none", stdin: "none", flags: { json: "boolean" }, usage: "settings", purpose: "Read user and project Settings resources." },
+    region: { positional: "optional", stdin: "none", flags: { overlap: "boolean", path: "value", json: "boolean" }, usage: "region [<contract>] [--overlap]\n       region --path <repo-relative-path>", purpose: "Read active declared Contract Regions." },
 };

package/build/src/cli/commands/install.d.ts

@@ -1,4 +1,4 @@
-import { type ProcessInput, type ProcessOutcome } from "../../runtime/proc/run.js";
+import type { ProcessInput, ProcessOutcome } from "../../runtime/proc/run.js";
 export declare const HARNESS_NAMES: readonly ["codex", "claude", "opencode", "pi"];
 export type HarnessName = typeof HARNESS_NAMES[number];
 export type ParsedInstallCommand = Readonly<{
@@ -16,7 +16,7 @@ export type InstallInvocationResult = Readonly<{
     results: readonly HarnessInstallResult[];
 }>;
 export type InstallRunner = (input: ProcessInput) => Promise<ProcessOutcome>;
-export declare const INSTALL_USAGE = "install <codex|claude|opencode|pi> [--json]\n       install --all [--json]";
+export declare const INSTALL_USAGE = "install <codex|claude|opencode|pi>\n       install --all";
 export declare function parseInstallCommand(argv: readonly string[]): ParsedInstallCommand;
 export declare function renderInstallHelp(): string;
 export declare function installAssetsRoot(): string;

package/build/src/cli/commands/install.js

@@ -1,9 +1,8 @@
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runCrossPlatformProcess } from "../../runtime/proc/run.js";
-import { CliUsageError, usageLine, withJsonAutomationHelp } from "../usage.js";
+import { CliUsageError, usageLine } from "../usage.js";
 export const HARNESS_NAMES = ["codex", "claude", "opencode", "pi"];
-export const INSTALL_USAGE = "install <codex|claude|opencode|pi> [--json]\n       install --all [--json]";
+export const INSTALL_USAGE = "install <codex|claude|opencode|pi>\n       install --all";
 function isHarness(value) {
     return value !== undefined && HARNESS_NAMES.includes(value);
 }
@@ -43,7 +42,7 @@ export function parseInstallCommand(argv) {
     };
 }
 export function renderInstallHelp() {
-    return withJsonAutomationHelp(`Install the Keiyaku skills into one or more agent harnesses.\n\n${usageLine(INSTALL_USAGE)}`);
+    return `Install the Keiyaku skills into one or more agent harnesses.\n\n${usageLine(INSTALL_USAGE)}`;
 }
 const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
 const ASSET_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../integrations/marketplace");
@@ -80,12 +79,13 @@ function diagnostic(argv, outcome) {
 export function installAssetsRoot() {
     return ASSET_ROOT;
 }
-export async function installHarnesses(harnesses, environment, runner = runCrossPlatformProcess) {
+export async function installHarnesses(harnesses, environment, runner) {
+    const run = runner ?? (await import("../../runtime/proc/run.js")).runCrossPlatformProcess;
     const results = [];
     for (const harness of harnesses) {
         let failure;
         for (const argv of recipes(harness)) {
-            const detail = diagnostic(argv, await runner({ argv, env: environment, timeoutMs: INSTALL_TIMEOUT_MS }));
+            const detail = diagnostic(argv, await run({ argv, env: environment, timeoutMs: INSTALL_TIMEOUT_MS }));
             if (detail.length > 0) {
                 failure = detail;
                 break;

package/build/src/cli/commands/nuke.d.ts

@@ -0,0 +1,10 @@
+import { type NukeResult } from "../../index.js";
+import type { WorldRoot } from "../../world.js";
+import { type ParsedCommand } from "../parse.js";
+import type { InvocationResult } from "../result.js";
+export declare function invokeNuke(command: Extract<ParsedCommand, {
+    command: "nuke";
+}>, world: WorldRoot | null): Promise<Readonly<{
+    kind: "nuke";
+    result: NukeResult;
+}> | InvocationResult>;

package/build/src/cli/commands/nuke.js

@@ -0,0 +1,20 @@
+import { Keiyaku, KeiyakuRefused } from "../../index.js";
+import { CliUsageError } from "../parse.js";
+export async function invokeNuke(command, world) {
+    if (world === null)
+        throw new CliUsageError("no Keiyaku world contains the invocation cwd");
+    try {
+        return {
+            kind: "nuke",
+            result: await Keiyaku.nuke({
+                world,
+                ...(command.confirm === undefined ? {} : { confirm: command.confirm }),
+            }),
+        };
+    }
+    catch (error) {
+        if (error instanceof KeiyakuRefused)
+            return { kind: "refused", verb: "nuke", refusal: error.refusal };
+        throw error;
+    }
+}

package/build/src/cli/commands/task-invoke.d.ts

@@ -1,7 +1,10 @@
 import { type BlockedTaskList, type TaskBatchResult, type TaskCompositionResult, type TaskDecompositionTree, type TaskDetail, type TaskDoctorReport, type TaskList, type TaskMutationResult, type TaskNamespaceResult, type TaskQueryResult, type TaskUpdateResult } from "../../task/index.js";
 import type { ParsedTaskCommand } from "./task.js";
 import type { WorldRoot } from "../../world.js";
-export type TaskInvocationResult = TaskMutationResult | TaskUpdateResult | TaskBatchResult | TaskCompositionResult | TaskDetail | TaskList | BlockedTaskList | TaskQueryResult | TaskDecompositionTree | TaskDoctorReport | TaskNamespaceResult | TaskWorldObservation;
+export type TaskShowResult = TaskDetail | readonly TaskDetail[] | Extract<TaskMutationResult, {
+    kind: "refused";
+}>;
+export type TaskInvocationResult = TaskMutationResult | TaskUpdateResult | TaskBatchResult | TaskCompositionResult | TaskShowResult | TaskList | BlockedTaskList | TaskQueryResult | TaskDecompositionTree | TaskDoctorReport | TaskNamespaceResult | TaskWorldObservation;
 type TaskWorldRead = TaskList | BlockedTaskList | TaskQueryResult | TaskDoctorReport;
 export type TaskWorldObservation = Readonly<{
     kind: "present";
@@ -16,9 +19,24 @@ export type TaskWorldObservation = Readonly<{
 }>;
 type TaskInput = Readonly<{
     world: WorldRoot | null;
+    context: Readonly<{
+        directory: string;
+        boundary: string;
+    }>;
     establish(): Promise<WorldRoot>;
     readStdin(): Promise<string>;
     actor?: string;
 }>;
+export declare function invokeTaskFromEdge(input: Readonly<{
+    parsed: ParsedTaskCommand;
+    world: WorldRoot | null;
+    context: Readonly<{
+        directory: string;
+        boundary: string;
+    }>;
+    establish: () => Promise<WorldRoot>;
+    readStdin: () => Promise<string>;
+    actor: string | undefined;
+}>): Promise<TaskInvocationResult>;
 export declare function invokeTask(command: ParsedTaskCommand, input: TaskInput): Promise<TaskInvocationResult>;
 export {};

package/build/src/cli/commands/task-invoke.js

@@ -1,6 +1,24 @@
-import { Tasks, } from "../../task/index.js";
+import { Tasks, observeTaskDetails, } from "../../task/index.js";
 import { injectedBodyRequests, requestBodyTask } from "../../akuma/requests.js";
 import { decodeTaskMutationRequest } from "../../task/mutation.js";
+import { resolveTaskNamespaceContext, writeTaskNamespaceContext } from "../../task/context.js";
+import { CliUsageError } from "../usage.js";
+export async function invokeTaskFromEdge(input) {
+    try {
+        return await invokeTask(input.parsed, {
+            world: input.world,
+            context: input.context,
+            establish: input.establish,
+            readStdin: input.readStdin,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+        });
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            throw new CliUsageError(error.message);
+        throw error;
+    }
+}
 function value(command, name) {
     const item = command.flags[name];
     return typeof item === "string" ? item : undefined;
@@ -19,8 +37,8 @@ function priority(raw) {
 function state(raw) { return raw; }
 function ids(items) { return items; }
 function limit(command) { const raw = value(command, "limit"); return raw === undefined ? undefined : Number(raw); }
-async function invokeAdd(tasks, command, input) {
-    const selectedNamespace = namespace(value(command, "namespace"));
+async function invokeAdd(tasks, command, input, current) {
+    const selectedNamespace = namespace(value(command, "namespace")) ?? current;
     const actor = input.actor;
     if (command.stdin === "document") {
         return tasks.addDocument({
@@ -56,19 +74,19 @@ async function invokeUpdate(tasks, command, readStdin) {
         ...(addRelates === undefined ? {} : { addRelates }), ...(dropRelates === undefined ? {} : { dropRelates }),
     });
 }
-async function addMutationRequest(command, input) {
-    const selectedNamespace = namespace(value(command, "namespace"));
+async function addMutationRequest(command, input, current) {
+    const selectedNamespace = namespace(value(command, "namespace")) ?? current;
     if (command.stdin === "document")
         return { action: "task.addDocument", input: {
                 markdown: await input.readStdin(),
-                ...(selectedNamespace === undefined ? {} : { namespace: selectedNamespace }),
+                namespace: selectedNamespace,
             } };
     const body = value(command, "body"), note = value(command, "note");
     const initialState = state(value(command, "state")), selectedPriority = priority(value(command, "priority"));
     const needs = ids(values(command, "needs")), parent = value(command, "parent");
     const supersedes = ids(values(command, "supersedes")), relates = ids(values(command, "relates"));
     return { action: "task.add", input: {
-            title: command.positionals[0], ...(selectedNamespace === undefined ? {} : { namespace: selectedNamespace }),
+            title: command.positionals[0], namespace: selectedNamespace,
             ...(body === undefined ? {} : { body }), ...(note === undefined ? {} : { note }),
             ...(initialState === undefined ? {} : { state: initialState }),
             ...(selectedPriority === undefined ? {} : { priority: selectedPriority }),
@@ -109,11 +127,11 @@ function lifecycleMutationRequest(command) {
         default: throw new Error(`task action cannot forward: ${command.action}`);
     }
 }
-async function mutationRequest(command, input) {
+async function mutationRequest(command, input, current) {
     if (command.action === "add")
-        return await addMutationRequest(command, input);
+        return await addMutationRequest(command, input, current);
     if (command.action === "compose")
-        return { action: "task.compose", markdown: await input.readStdin() };
+        return { action: "task.compose", markdown: await input.readStdin(), namespace: current };
     if (command.action === "update")
         return await updateMutationRequest(command, input);
     return lifecycleMutationRequest(command);
@@ -122,7 +140,7 @@ function validatedMutationRequest(request) {
     switch (request.action) {
         case "task.add":
         case "task.addDocument": return decodeTaskMutationRequest(request.action, { input: request.input });
-        case "task.compose": return decodeTaskMutationRequest(request.action, { markdown: request.markdown });
+        case "task.compose": return decodeTaskMutationRequest(request.action, { markdown: request.markdown, namespace: request.namespace });
         case "task.update": return decodeTaskMutationRequest(request.action, { id: request.id, input: request.input });
         case "task.start":
         case "task.stop":
@@ -132,17 +150,23 @@ function validatedMutationRequest(request) {
         case "task.drop": return decodeTaskMutationRequest(request.action, { ids: request.ids, ...(request.note === undefined ? {} : { note: request.note }) });
     }
 }
-async function invokeRead(tasks, command) {
+function readScope(command, current) {
+    return command.flags.world === true ? { scope: "world" } : { namespace: current ?? [] };
+}
+async function invokeRead(tasks, command, current) {
     const id = command.positionals[0];
     switch (command.action) {
         case "show": {
-            const detail = await tasks.task({ id }).read();
-            return detail ?? { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
+            const ids = command.positionals.map((taskId) => tasks.task({ id: taskId }).id);
+            const observed = await observeTaskDetails(tasks.root, ids);
+            if (observed.kind !== "accepted")
+                return observed;
+            return command.output === "json" || observed.value.length > 1 ? observed.value : observed.value[0];
         }
-        case "ls": return tasks.list({ selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active", ...(command.flags.world === true ? { scope: "world" } : {}), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
-        case "ready": return tasks.ready({ ...(command.flags.world === true ? { scope: "world" } : {}), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
-        case "blocked": return tasks.blocked({ ...(command.flags.world === true ? { scope: "world" } : {}), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
-        case "query": return tasks.query({ ...(command.where === undefined ? {} : { where: command.where }), ...(command.flags.world === true ? { scope: "world" } : {}), ...(value(command, "sort") === undefined ? {} : { sort: value(command, "sort") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "ls": return tasks.list({ selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active", ...readScope(command, current), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "ready": return tasks.ready({ ...readScope(command, current), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "blocked": return tasks.blocked({ ...readScope(command, current), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "query": return tasks.query({ ...(command.where === undefined ? {} : { where: command.where }), ...readScope(command, current), ...(value(command, "sort") === undefined ? {} : { sort: value(command, "sort") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
         case "tree": return tasks.task({ id }).tree();
         case "doctor": return tasks.doctor();
         default: throw new Error(`task action is not a read: ${command.action}`);
@@ -153,9 +177,9 @@ function isWorldObservation(command) {
         || command.action === "query" || command.action === "doctor";
 }
 function diagnostic(error) { return error instanceof Error ? error.message : String(error); }
-async function observeWorldRead(tasks, command) {
+async function observeWorldRead(tasks, command, current) {
     try {
-        return { kind: "present", value: await invokeRead(tasks, command) };
+        return { kind: "present", value: await invokeRead(tasks, command, current) };
     }
     catch (error) {
         return { kind: "failed", failure: { message: diagnostic(error) } };
@@ -175,13 +199,13 @@ function missingWorld(command) {
     }
     return missing(command.positionals[0]);
 }
-async function invokeLocalMutation(tasks, command, input) {
+async function invokeLocalMutation(tasks, command, input, current) {
     if (isWorldObservation(command))
-        return observeWorldRead(tasks, command);
+        return observeWorldRead(tasks, command, current);
     if (command.action === "show" || command.action === "tree")
-        return invokeRead(tasks, command);
+        return invokeRead(tasks, command, current);
     if (command.action === "add")
-        return await invokeAdd(tasks, command, input);
+        return await invokeAdd(tasks, command, input, current ?? []);
     if (command.action === "update")
         return await invokeUpdate(tasks, command, input.readStdin);
     const id = command.positionals[0];
@@ -201,10 +225,10 @@ async function invokeLocalMutation(tasks, command, input) {
         case "namespace": {
             const selected = namespace(command.positionals[0]);
             if (selected !== undefined)
-                await tasks.setNamespace({ namespace: selected });
-            return tasks.namespace();
+                await writeTaskNamespaceContext(input.context.directory, selected);
+            return { kind: "accepted", value: selected ?? current ?? [] };
         }
-        case "compose": return tasks.compose({ markdown: await input.readStdin(), ...(input.actor === undefined ? {} : { actor: input.actor }) });
+        case "compose": return tasks.compose({ markdown: await input.readStdin(), namespace: current ?? [], ...(input.actor === undefined ? {} : { actor: input.actor }) });
         default: throw new Error(`task action has no invocation: ${command.action}`);
     }
 }
@@ -220,10 +244,20 @@ export async function invokeTask(command, input) {
     const world = input.world ?? (establishesWorld(command) ? await input.establish() : null);
     if (world === null)
         return missingWorld(command);
+    const tasks = Tasks.of(world);
+    const contextSensitive = command.action === "namespace" || command.action === "add" || command.action === "compose"
+        || ((command.action === "ls" || command.action === "ready" || command.action === "blocked" || command.action === "query") && command.flags.world !== true);
+    let current;
+    if (contextSensitive) {
+        const resolved = await resolveTaskNamespaceContext(input.context);
+        if (typeof resolved === "object" && "kind" in resolved)
+            return { kind: "refused", refusal: resolved };
+        current = resolved;
+    }
     const requests = injectedBodyRequests();
     if (requests !== null && forwardsMutation(command)) {
-        const request = validatedMutationRequest(await mutationRequest(command, input));
+        const request = validatedMutationRequest(await mutationRequest(command, input, current ?? []));
         return await requestBodyTask({ directory: requests, world, request });
     }
-    return await invokeLocalMutation(Tasks.of(world), command, input);
+    return await invokeLocalMutation(tasks, command, input, current);
 }

package/build/src/cli/commands/task-query.d.ts

@@ -1,5 +1,5 @@
-import { type TaskQueryExpression } from "../../task/index.js";
-export type { TaskQueryExpression } from "../../task/index.js";
+import { type TaskQueryExpression } from "../../task/query.js";
+export type { TaskQueryExpression } from "../../task/query.js";
 export declare function parseTaskQueryExpression(source: string): TaskQueryExpression;
 export declare function validateTaskLimit(source: string): void;
 export declare function validateTaskParent(source: string): void;

package/build/src/cli/commands/task-query.js

@@ -1,5 +1,4 @@
-import { TASK_RELATION_PREDICATE_FIELDS, } from "../../task/index.js";
-import { MAX_TASK_LIMIT, normalizeTaskQuery } from "../../task/query.js";
+import { MAX_TASK_LIMIT, TASK_RELATION_PREDICATE_FIELDS, normalizeTaskQuery, } from "../../task/query.js";
 function syntax(message, offset) { throw new Error(`${message} at column ${offset + 1}`); }
 function scanString(source, offset) {
     let index = offset + 1;

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

@@ -1,4 +1,4 @@
-import { CliUsageError, isBlankInput, usageLine, withJsonAutomationHelp } from "../usage.js";
+import { CliUsageError, isBlankInput, usageLine } from "../usage.js";
 import { parseTaskQueryExpression, validateTaskLimit, validateTaskParent, } from "./task-query.js";
 const COMMON = { json: "boolean" };
 const TASK_COMMAND_SPECS = {
@@ -9,18 +9,18 @@ const TASK_COMMAND_SPECS = {
   [--note <text>] [--actor <actor>]
   [--needs <TaskId>]... [--parent <TaskId>]
   [--supersedes <TaskId>]... [--relates <TaskId>]...
-  [--body <text>] [--json]
-task add [--namespace <ns>] [--actor <actor>] [--json] -`,
+  [--body <text>]
+task add [--namespace <ns>] [--actor <actor>] -`,
         purpose: "Create one Task from flags or a canonical stdin document.",
     },
-    show: { arity: [1, 1], flags: COMMON, usage: "task show <TaskId> [--json]", purpose: "Read one Task and its relationships." },
-    ls: { arity: [0, 0], flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean", limit: "value" }, usage: "task ls [--closed | --all] [--world] [--limit <n>] [--json]", purpose: "List Tasks in the selected scope." },
-    ready: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task ready [--world] [--parent <TaskId>] [--limit <n>] [--json]", purpose: "List open Tasks whose every need is terminal." },
-    blocked: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task blocked [--world] [--parent <TaskId>] [--limit <n>] [--json]", purpose: "List Tasks blocked by dependencies." },
+    show: { arity: [1, Number.POSITIVE_INFINITY], flags: COMMON, usage: "task show <TaskId>...", purpose: "Read one or more Tasks and their relationships." },
+    ls: { arity: [0, 0], flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean", limit: "value" }, usage: "task ls [--closed | --all] [--world] [--limit <n>]", purpose: "List Tasks in the selected scope." },
+    ready: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task ready [--world] [--parent <TaskId>] [--limit <n>]", purpose: "List open Tasks whose every need is terminal." },
+    blocked: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task blocked [--world] [--parent <TaskId>] [--limit <n>]", purpose: "List Tasks blocked by dependencies." },
     query: { arity: [0, 0], flags: { ...COMMON, where: "value", world: "boolean", sort: "value", limit: "value" }, usage: `task query [--where <expression>] [--world]
-  [--sort priority|created|updated|id] [--limit <n>] [--json]`, purpose: "Query Task facts with a typed boolean expression." },
-    tree: { arity: [1, 1], flags: COMMON, usage: "task tree <TaskId> [--json]", purpose: "Read one Task parent decomposition tree." },
-    doctor: { arity: [0, 0], flags: COMMON, usage: "task doctor [--json]", purpose: "Inspect Task authority without repairing it." },
+  [--sort priority|created|updated|id] [--limit <n>]`, purpose: "Query Task facts with a typed boolean expression." },
+    tree: { arity: [1, 1], flags: COMMON, usage: "task tree <TaskId>", purpose: "Read one Task parent decomposition tree." },
+    doctor: { arity: [0, 0], flags: COMMON, usage: "task doctor", purpose: "Inspect Task authority without repairing it." },
     update: {
         arity: [1, 1], flags: { ...COMMON, title: "value", body: "value", append: "value", note: "value", priority: "value", needs: "repeat", "drop-needs": "repeat", parent: "value", "no-parent": "boolean", supersedes: "repeat", "drop-supersedes": "repeat", relates: "repeat", "drop-relates": "repeat" },
         usage: `task update <TaskId> [--title <text>] [--body <text>|- | --append <text>|-]
@@ -28,17 +28,17 @@ task add [--namespace <ns>] [--actor <actor>] [--json] -`,
   [--priority 0..3] [--needs <TaskId>]... [--drop-needs <TaskId>]...
   [--parent <TaskId> | --no-parent]
   [--supersedes <TaskId>]... [--drop-supersedes <TaskId>]...
-  [--relates <TaskId>]... [--drop-relates <TaskId>]... [--json]`,
+  [--relates <TaskId>]... [--drop-relates <TaskId>]...`,
         purpose: "Apply one or more patches to a Task.",
     },
-    start: { arity: [1, 1], flags: COMMON, usage: "task start <TaskId> [--json]", purpose: "Move one open Task into progress." },
-    stop: { arity: [1, 1], flags: COMMON, usage: "task stop <TaskId> [--json]", purpose: "Return one in-progress Task to open." },
-    hold: { arity: [1, Number.POSITIVE_INFINITY], flags: COMMON, usage: "task hold <TaskId>... [--json]", purpose: "Put one or more Tasks on hold." },
-    resume: { arity: [1, 1], flags: COMMON, usage: "task resume <TaskId> [--json]", purpose: "Return one held Task to open." },
-    done: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task done <TaskId>... [--note <text>] [--json]", purpose: "Mark one or more Tasks done." },
-    drop: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task drop <TaskId>... [--note <text>] [--json]", purpose: "Drop one or more Tasks." },
-    namespace: { arity: [0, 1], flags: COMMON, usage: "task namespace [<namespace>] [--json]", purpose: "Read or replace the current Task namespace." },
-    compose: { arity: [0, 0], stdin: "compose", flags: { ...COMMON, actor: "value" }, usage: "task compose [--actor <actor>] [--json] -", purpose: "Admit Task documents independently; partial admission has no cross-file atomicity or rollback." },
+    start: { arity: [1, 1], flags: COMMON, usage: "task start <TaskId>", purpose: "Move one open Task into progress." },
+    stop: { arity: [1, 1], flags: COMMON, usage: "task stop <TaskId>", purpose: "Return one in-progress Task to open." },
+    hold: { arity: [1, Number.POSITIVE_INFINITY], flags: COMMON, usage: "task hold <TaskId>...", purpose: "Put one or more Tasks on hold." },
+    resume: { arity: [1, 1], flags: COMMON, usage: "task resume <TaskId>", purpose: "Return one held Task to open." },
+    done: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task done <TaskId>... [--note <text>]", purpose: "Mark one or more Tasks done." },
+    drop: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task drop <TaskId>... [--note <text>]", purpose: "Drop one or more Tasks." },
+    namespace: { arity: [0, 1], flags: COMMON, usage: "task namespace [<namespace>]", purpose: "Read or replace the current Task namespace." },
+    compose: { arity: [0, 0], stdin: "compose", flags: { ...COMMON, actor: "value" }, usage: "task compose [--actor <actor>] -", purpose: "Admit Task documents independently; partial admission has no cross-file atomicity or rollback." },
 };
 export function isTaskAction(value) {
     return value !== undefined && Object.hasOwn(TASK_COMMAND_SPECS, value);
@@ -46,14 +46,22 @@ export function isTaskAction(value) {
 export function renderTaskHelp(action) {
     if (action !== undefined) {
         const spec = TASK_COMMAND_SPECS[action];
-        return withJsonAutomationHelp(`${spec.purpose}\n\n${usageLine(spec.usage)}`);
+        const queryGuide = action === "query" ? [
+            "",
+            "fields: state priority title id parent under needs blocks ready blocked created updated",
+            "operators: = != < > <= >= ~ and or not ( )",
+            "examples:",
+            "  keiyaku task query --where 'priority <= 1 and ready' --world",
+            "  keiyaku task query --where 'updated < 2026-08-06T00:00:00.000Z' --world",
+        ].join("\n") : "";
+        return `${spec.purpose}\n\n${usageLine(spec.usage)}${queryGuide}`;
     }
-    return withJsonAutomationHelp([
+    return [
         "usage: keiyaku task <command> ...",
         "",
         "commands:",
         ...Object.values(TASK_COMMAND_SPECS).flatMap((spec) => spec.usage.split("\n").map((line) => `  ${line}`).concat(`    ${spec.purpose}`)),
-    ].join("\n"));
+    ].join("\n");
 }
 export function renderTaskUsage(action) {
     return usageLine(TASK_COMMAND_SPECS[action].usage);