@astrosheep/keiyaku 2.8.4 → 2.9.0

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

@@ -0,0 +1,11 @@
+import { TASK_SUBCOMMANDS } from "../../../types.js";
+export const meta = {
+    command: "task",
+    summary: "Manage lightweight repository tasks",
+    usage: ["keiyaku task <subcommand>"],
+    stdin: "none",
+    flags: [],
+    purpose: "Manage the file-backed task board.",
+    subcommands: TASK_SUBCOMMANDS,
+    completionRank: 15,
+};

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

@@ -0,0 +1,18 @@
+import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
+import { updateTask } from "../../../../core/task.js";
+import { renderTaskMutationRow } from "../../../render/task.js";
+import { textResponse } from "../../../render/shared.js";
+import { effectiveDirectory } from "../../shared.js";
+export const handler = async (stdin, flags, _signal, positional) => {
+    const body = flags.taskBody === "-" ? stdin : flags.taskBody;
+    const task = await updateTask(await openTaskCommandRepository(effectiveDirectory(flags)), positional[0], {
+        ...(flags.taskTitle === undefined ? {} : { title: flags.taskTitle }),
+        ...(body === undefined ? {} : { body }),
+        ...(flags.taskPri === undefined ? {} : { pri: flags.taskPri }),
+        ...(flags.taskNeeds === undefined ? {} : { addNeeds: flags.taskNeeds }),
+        ...(flags.taskDropNeeds === undefined ? {} : { dropNeeds: flags.taskDropNeeds }),
+        ...(flags.taskParent !== undefined ? { parent: flags.taskParent } : flags.taskNoParent ? { parent: null } : {}),
+        ...(flags.taskFrom === undefined ? {} : { from: flags.taskFrom }),
+    });
+    return textResponse(renderTaskMutationRow(task));
+};

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

@@ -0,0 +1,8 @@
+export const meta = {
+    command: "task update",
+    summary: "Update task facts",
+    usage: ["keiyaku task update [-C|--cwd DIR] ID [--title TEXT] [--body TEXT|-] [--pri 0-3] [--needs ID] [--drop-needs ID] [--parent ID|--no-parent] [--from ID]"],
+    stdin: "none",
+    flags: ["cwd", "title", "body", "pri", "needs", "drop-needs", "parent", "no-parent", "from"],
+    purpose: "Change mutable task facts.",
+};

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

@@ -0,0 +1,14 @@
+import { FlowError } from "../../../../flow-error.js";
+import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
+import { readTaskBoard, resolveTaskReadId } from "../../../../core/task.js";
+import { renderTaskShow, renderTaskShowJson } from "../../../render/task.js";
+import { textResponse } from "../../../render/shared.js";
+import { effectiveDirectory } from "../../shared.js";
+import { taskJsonText } from "../shared.js";
+export const handler = async (_stdin, flags, _signal, positional) => {
+    const board = await readTaskBoard(await openTaskCommandRepository(effectiveDirectory(flags)));
+    const task = board.byId.get(resolveTaskReadId(board, positional[0]));
+    if (!task)
+        throw new FlowError("INTERNAL_STATE", "resolved task disappeared from the board");
+    return textResponse(flags.json ? taskJsonText(renderTaskShowJson(task)) : renderTaskShow(task));
+};

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

@@ -0,0 +1,8 @@
+export const meta = {
+    command: "task view",
+    summary: "View one task",
+    usage: ["keiyaku task view [-C|--cwd DIR] ID [--json]"],
+    stdin: "none",
+    flags: ["cwd", "json"],
+    purpose: "Read one task from the working-tree board.",
+};

package/build/cli/completion.js

@@ -1,24 +1,23 @@
-import { assertSettingsKnobUsable, loadKeiyakuSettings } from "../config/settings.js";
-import { loadAkumaCatalogV2 } from "../config/akuma-loader_v2.js";
+import { assertSettingsKnobUsable } from "../config/settings/disease.js";
+import { loadKeiyakuSettings } from "../config/settings/loader.js";
+import { loadAkumaCatalog } from "../config/akuma-loader.js";
 import { listContractIds } from "../core/ledger.js";
-const TOP_LEVEL_COMMANDS = [
-    "bind",
-    "arc",
-    "call",
-    "tell",
-    "revive",
-    "log",
-    "akuma",
-    "skills",
-    "amend",
-    "renew",
-    "petition",
-    "forfeit",
-    "guide",
-    "completion",
-    "status",
-    "dump-env",
-];
+import { allCommandMetadata, getCommandMetadata } from "./commands/registry.js";
+function topLevelCommands() {
+    return allCommandMetadata()
+        .filter((meta) => meta.completionRank !== undefined)
+        .slice()
+        .sort((a, b) => {
+        const rankDelta = (a.completionRank ?? 0) - (b.completionRank ?? 0);
+        if (rankDelta !== 0)
+            return rankDelta;
+        return a.command < b.command ? -1 : a.command > b.command ? 1 : 0;
+    })
+        .map((meta) => meta.command);
+}
+function subcommandsFor(parent) {
+    return [...(getCommandMetadata(parent).subcommands ?? [])];
+}
 function filterPrefix(items, word) {
     return items.filter((item) => item.startsWith(word));
 }
@@ -28,7 +27,7 @@ async function contractAddressCandidates(cwd, word) {
 async function akumaCandidates(cwd, word) {
     const loaded = await loadKeiyakuSettings(cwd);
     assertSettingsKnobUsable(loaded, "agents");
-    return filterPrefix(Object.keys((await loadAkumaCatalogV2(cwd)).selected), word);
+    return filterPrefix(Object.keys((await loadAkumaCatalog(cwd)).selected), word);
 }
 export async function renderCompletionCandidates(input) {
     const word = input.word ?? "";
@@ -38,16 +37,16 @@ export async function renderCompletionCandidates(input) {
     if (input.previous === "call") {
         return filterPrefix([...(await akumaCandidates(input.cwd, word)), "--alias"], word).join("\n");
     }
-    if (input.previous === "show") {
-        return (await akumaCandidates(input.cwd, word)).join("\n");
-    }
     if (input.previous === "akuma") {
-        return filterPrefix(["list", "ls", "show"], word).join("\n");
+        return filterPrefix(subcommandsFor("akuma"), word).join("\n");
     }
     if (input.previous === "skills") {
-        return filterPrefix(["install"], word).join("\n");
+        return filterPrefix(subcommandsFor("skills"), word).join("\n");
+    }
+    if (input.previous === "task") {
+        return filterPrefix(subcommandsFor("task"), word).join("\n");
     }
-    return filterPrefix(TOP_LEVEL_COMMANDS, word).join("\n");
+    return filterPrefix(topLevelCommands(), word).join("\n");
 }
 export function renderCompletionScript(shell = "bash") {
     if (shell === "zsh") {

package/build/cli/flags.js

@@ -46,6 +46,11 @@ export const FLAG_SPECS = {
         placeholder: "DURATION",
         description: "Wait at most a positive duration such as 45s, 5m, or 2h (maximum 24h).",
     },
+    wait: {
+        kind: "value",
+        placeholder: "DURATION",
+        description: "After acceptance, wait at most a positive duration for the projection (maximum 24h).",
+    },
     incognito: {
         kind: "boolean",
         description: "Do not persist response history and do not allow revive.",
@@ -66,6 +71,31 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Reject bind if any active contract already exists.",
     },
+    place: {
+        kind: "value",
+        placeholder: "NAME",
+        description: "Set the H1 contract name for flag-generated bind Markdown.",
+    },
+    objective: {
+        kind: "value",
+        placeholder: "TEXT",
+        description: "Set the objective for flag-generated bind Markdown.",
+    },
+    scope: {
+        kind: "value",
+        placeholder: "GLOB",
+        description: "Set the single scope pattern for flag-generated bind Markdown.",
+    },
+    checks: {
+        kind: "value",
+        placeholder: "CHECK",
+        description: "Set the single acceptance check for flag-generated bind Markdown.",
+    },
+    task: {
+        kind: "value",
+        placeholder: "ID",
+        description: "Promote one ready task into the contract being bound.",
+    },
     after: {
         kind: "value",
         placeholder: "ID",
@@ -82,7 +112,7 @@ export const FLAG_SPECS = {
     },
     "dry-run": {
         kind: "boolean",
-        description: "Preview claim effects without changing refs, ledgers, queue, registry, or worktrees.",
+        description: "Preview bind input or petition preflight without mutation.",
     },
     waive: {
         kind: "value",
@@ -115,7 +145,54 @@ export const FLAG_SPECS = {
     },
     all: {
         kind: "boolean",
-        description: "Show all retained Akuma projections while preserving status priority order.",
+        description: "Show all retained items instead of the default filtered view.",
+    },
+    json: {
+        kind: "boolean",
+        description: "Render task data as JSON.",
+    },
+    done: {
+        kind: "boolean",
+        description: "Show terminal tasks.",
+    },
+    pri: {
+        kind: "value",
+        placeholder: "0-3",
+        description: "Set task priority from 0 through 3.",
+    },
+    needs: {
+        kind: "value",
+        placeholder: "ID",
+        description: "Add a task dependency. May be repeated.",
+    },
+    "drop-needs": {
+        kind: "value",
+        placeholder: "ID",
+        description: "Remove a task dependency. May be repeated.",
+    },
+    parent: {
+        kind: "value",
+        placeholder: "ID",
+        description: "Set the parent task.",
+    },
+    "no-parent": {
+        kind: "boolean",
+        description: "Clear the parent task.",
+    },
+    from: {
+        kind: "value",
+        placeholder: "ID",
+        description: "Add a discovery-lineage task. May be repeated.",
+    },
+    title: {
+        kind: "value",
+        placeholder: "TEXT",
+        description: "Replace the task title.",
+    },
+    body: {
+        kind: "value",
+        placeholder: "TEXT|-",
+        description: "Replace the task body; literal - reads stdin.",
     },
 };
 export const CONTROL_FLAGS = new Set(Object.keys(FLAG_SPECS));

package/build/cli/help.js

@@ -1,40 +1,11 @@
 import { FlowError } from "../flow-error.js";
-function command(name, summary, usage, stdin, flags, purpose, extra = {}) {
-    return { command: name, summary, usage, stdin, flags, purpose, ...extra };
+import { allCommandMetadata, getCommandMetadata } from "./commands/registry.js";
+export function formatSubcommandList(subcommands) {
+    return subcommands.length < 2 ? (subcommands[0] ?? "") : `${subcommands.slice(0, -1).join(", ")} or ${subcommands.at(-1)}`;
+}
+export function missingSubcommandError(name, subcommands) {
+    return new FlowError("EMPTY_PARAM", `${name} requires subcommand: ${formatSubcommandList(subcommands)}`);
 }
-export const CLI_COMMAND_METADATA = {
-    bind: command("bind", "Create a contract ledger and workspace files", ["keiyaku bind [-C|--cwd DIR] [--repo DIR] < keiyaku.md"], "required", ["cwd", "repo", "after", "exclusive", "draft-only"], "Bind a Keiyaku from a contract draft.", {
-        notes: ["bind creates a commission and does not accept @addr or --contract."],
-    }),
-    arc: command("arc", "Open the next arc and seal the current arc", ["keiyaku arc [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH] < arc.md", "keiyaku @addr arc [-C|--cwd DIR] [--repo DIR] [--waive PATH] < arc.md"], "required", ["cwd", "repo", "contract", "waive"], "Record the next title, objective, and brief. An open arc is sealed first.", {
-        input: ["# <arc title>", "", "## Objective", "<what this arc should accomplish>", "", "## Brief", "<scope, constraints, relevant files, instructions>"],
-        notes: ["An empty seal is valid.", "The command does not create delivery commits."],
-    }),
-    call: command("call", "Start an Akuma helper session", ["keiyaku call NAME [--alias WORD] [prompt|-]", "keiyaku call NAME --detach [prompt|-]", "keiyaku @addr call NAME [prompt|-]", "keiyaku call NAME --contract ADDR [prompt|-]"], "none", ["cwd", "repo", "contract", "akuma", "model", "effort", "incognito", "bare", "detach", "alias"], "Run a scoped helper task."),
-    revive: command("revive", "Revive an Akuma helper session", ["keiyaku revive ARTIFACT_ID"], "none", ["cwd", "repo", "model", "effort"], "Continue a persisted helper session."),
-    wait: command("wait", "Wait for an akuma projection", ["keiyaku wait <projection-address> [--timeout DURATION]", "keiyaku @addr wait <projection-address> [--timeout DURATION]"], "none", ["cwd", "repo", "contract", "timeout"], "Read an akuma projection until its outcome is available, or show a timeout snapshot."),
-    tell: command("tell", "Send intent to a projection mailbox", ["keiyaku tell [--effort LEVEL] PROJECTION MESSAGE", "keiyaku @addr tell [--effort LEVEL] PROJECTION MESSAGE"], "none", ["cwd", "repo", "contract", "effort"], "Write intent to the mailbox and wake only when eligible."),
-    kill: command("kill", "Stop the current projection generation", ["keiyaku kill <projection-address>", "keiyaku @addr kill <projection-address>"], "none", ["cwd", "repo", "contract"], "Terminate the current generation while keeping the projection identity and tell ledger."),
-    log: command("log", "Render a contract ledger", ["keiyaku log [-C|--cwd DIR] [--repo DIR] [--contract ADDR]", "keiyaku @addr log [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo", "contract"], "Read a contract ledger."),
-    akuma: command("akuma", "Inspect Akuma profiles", ["keiyaku akuma list|show"], "none", [], "Inspect configured helper profiles.", {
-        subcommands: ["list", "ls", "show"],
-        notes: ["Define user profiles in <KEIYAKU_HOME>/akuma/<name>.md.", "Define project profiles in .keiyaku/akuma/<name>.md.", "See README Configuration for the Markdown frontmatter format."],
-        examples: ["keiyaku akuma list", "keiyaku akuma show akuma-codex"],
-    }),
-    "akuma ls": command("akuma ls", "List Akuma profiles", ["keiyaku akuma ls [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo"], "List configured helper profiles.", { notes: ["Project profiles override user profiles, which override builtins."] }),
-    "akuma list": command("akuma list", "List Akuma profiles", ["keiyaku akuma list [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo"], "List configured helper profiles.", { notes: ["Project profiles override user profiles, which override builtins."] }),
-    "akuma show": command("akuma show", "Show an Akuma profile", ["keiyaku akuma show NAME [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo"], "Show one configured helper profile.", { notes: ["The output identifies the winning source and normalized provider configuration."] }),
-    skills: command("skills", "Install official skills", ["keiyaku skills install"], "none", [], "Install bundled official Keiyaku skills into supported agent skill directories.", { subcommands: ["install"] }),
-    "skills install": command("skills install", "Install the official Keiyaku skills", ["keiyaku skills install [-f|--force]"], "none", ["force"], "Install the bundled official Keiyaku skills into supported agent skill directories.", { notes: ["Force permits replacement of foreign collisions."] }),
-    amend: command("amend", "Record an amendment", ["keiyaku amend [-C|--cwd DIR] [--repo DIR] [--contract ADDR] < amendment.md", "keiyaku @addr amend [-C|--cwd DIR] [--repo DIR] < amendment.md"], "required", ["cwd", "repo", "contract"], "Append a prose amendment and optional structured scope delta."),
-    renew: command("renew", "Rewrite delivery onto the current base", ["keiyaku renew [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH]", "keiyaku @<id> renew [-C|--cwd DIR] [--repo DIR] [--waive PATH]"], "none", ["cwd", "repo", "contract", "waive"], "Capture receipts, rewrite delivery onto the default branch, then seal and record the renewal.", { notes: ["Refuses loose commits without an open arc.", "Refuses while an Akuma is in flight.", "Conflicts restore the worktree without ledger writes."] }),
-    petition: command("petition", "Run the gated settlement pipeline", ["keiyaku petition [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH]", "keiyaku @<id> petition [-C|--cwd DIR] [--repo DIR] [--waive PATH]"], "none", ["cwd", "repo", "contract", "waive"], "Seal an open arc, queue the contract, and run verdict and claim processing.", { notes: ["Base drift requires explicit `keiyaku renew` before petition."] }),
-    forfeit: command("forfeit", "Forfeit an addressed contract", ["keiyaku forfeit [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--reason TEXT]", "keiyaku @addr forfeit [-C|--cwd DIR] [--repo DIR] [--reason TEXT]"], "none", ["cwd", "repo", "contract", "reason"], "Record an abandoned contract without sealing it."),
-    guide: command("guide", "Print the Keiyaku guide", ["keiyaku guide"], "none", [], "Print workflow guidance."),
-    completion: command("completion", "Print shell completion", ["keiyaku completion [--shell bash|zsh]"], "none", ["cwd", "repo", "shell", "word", "previous", "complete"], "Print command and address candidates."),
-    status: command("status", "Show the Kanshi board", ["keiyaku status [-C|--cwd DIR] [--repo DIR] [--target REF] [--all]"], "none", ["cwd", "repo", "target", "all"], "Read contract, queue, and projection facts without mutation."),
-    "dump-env": command("dump-env", "Print the environment template", ["keiyaku dump-env"], "none", [], "Print supported environment keys.", { notes: ["Keiyaku loads <KEIYAKU_HOME>/.env, then .keiyaku/.env; process environment values win."] }),
-};
 function indent(lines) {
     return lines.map((line) => line ? `  ${line}` : "");
 }
@@ -50,16 +21,13 @@ function flagUsage(name, specs) {
     }
     return spec?.kind === "value" ? `--${name} ${spec.placeholder ?? "VALUE"}` : `--${name}`;
 }
-export function formatSubcommandList(subcommands) {
-    return subcommands.length < 2 ? (subcommands[0] ?? "") : `${subcommands.slice(0, -1).join(", ")} or ${subcommands.at(-1)}`;
-}
-export function missingSubcommandError(name, subcommands) {
-    return new FlowError("EMPTY_PARAM", `${name} requires subcommand: ${formatSubcommandList(subcommands)}`);
-}
+/** Metadata keyed by command; key order matches the historical CLI_COMMAND_METADATA object. */
+export const CLI_COMMAND_METADATA = Object.fromEntries(allCommandMetadata().map((meta) => [meta.command, meta]));
 export function renderCliCommandHelp(_command, spec, flagSpecs) {
     const lines = ["Keiyaku command help", "", `${spec.command} - ${spec.summary}`, ""];
     section(lines, "Usage:", spec.usage);
     section(lines, "Purpose:", [spec.purpose]);
+    section(lines, "Subcommands:", spec.subcommands);
     section(lines, "Input:", spec.input);
     section(lines, "Options:", spec.flags.map((name) => `${flagUsage(name, flagSpecs)}  ${flagSpecs[name]?.description ?? ""}`));
     section(lines, "Notes:", spec.notes);
@@ -75,11 +43,12 @@ export function renderCliHelp(version) {
         "  keiyaku @<commission> <command> [flags]",
         "",
         "Flow:",
-        "  bind -> arc -> delivery work -> arc | renew | petition",
+        "  bind -> delivery work -> petition",
+        "  optional: arc -> delivery work -> arc; renew on base drift",
         "",
         "Commands:",
         "  bind       Create a contract ledger and workspace files.",
-        "  arc        Open the next arc; seals an open arc first.",
+        "  arc        Optional iteration; seals current intent first.",
         "  renew      Rewrite delivery onto the current base and seal it.",
         "  call       Start an Akuma helper session.",
         "  wait       Wait for an akuma projection.",
@@ -95,16 +64,19 @@ export function renderCliHelp(version) {
         "  guide      Print workflow guidance.",
         "  completion Print shell completion.",
         "  status     Render the Kanshi board.",
+        "  task       Manage lightweight repository tasks.",
         "  dump-env   Print the environment template.",
         "",
         "Input:",
+        "  <> means required; [] means optional.",
         "  bind, arc, and amend read Markdown from stdin.",
-        "  call and revive read a prompt argument or stdin.",
+        "  call and tell require literal BODY or `-`; only literal `-` opens stdin.",
+        "  revive accepts an artifact plus optional BODY or `-`; only literal `-` opens stdin.",
         "",
         "Configuration:",
         "  Akuma profiles  <KEIYAKU_HOME>/akuma/*.md or .keiyaku/akuma/*.md",
         "  Settings        <KEIYAKU_HOME>/settings.json or .keiyaku/settings.json",
-        "  Inspect         keiyaku akuma list | keiyaku akuma show NAME",
+        "  Inspect         keiyaku akuma ls | keiyaku akuma view NAME",
         "  Environment     keiyaku dump-env",
         "  Full format     README Configuration",
     ].join("\n");
@@ -114,13 +86,19 @@ export function buildKeiyakuGuide(version) {
         `# Keiyaku Guide (v${version})`,
         "",
         "## Workflow",
-        "`bind -> arc -> delivery work -> arc | renew | petition`",
+        "`bind -> delivery work -> petition`",
+        "optional: `arc -> delivery work -> arc`; renew on base drift",
         "",
-        "- `arc` records intent and seals the prior open arc automatically.",
-        "- `renew` captures old receipts before rewriting delivery onto the default branch.",
-        "- `petition` seals an open arc, requires a fresh base, and starts settlement.",
+        "- `bind` supplies derived default intent a0.",
+        "- `arc` is an optional iteration boundary, not admission; the first explicit arc seals a0, and later arcs seal the previous open explicit arc.",
+        "- `renew` seals the current a0 or open explicit arc after a successful refresh onto the default branch.",
+        "- `petition` seals the current a0 or open explicit arc and starts settlement.",
+        "- After an explicit arc closes, loose commits require another arc before renew or petition.",
         "- `call` and `revive` provide helper execution without changing the ledger lifecycle.",
         "- `skills install` installs the bundled official Keiyaku skills into supported agent skill directories; force permits replacement of foreign collisions.",
         "- `status` is read-only and reports next actions, drift, queue state, and projections.",
     ].join("\n");
 }
+export function commandMetadata(command) {
+    return getCommandMetadata(command);
+}