@astrosheep/keiyaku 2.9.11 → 2.9.12

package/build/core/task/settlement-git.js

@@ -5,6 +5,12 @@ import { runGitProcess } from "../../git/core.js";
 import { openGitStreamingBatch } from "../../git/streaming-batch.js";
 import { parseTaskDocument } from "./task.js";
 import { parseTaskCoordinate } from "./coordinate.js";
+function observePublicationEffect(observer, effect) {
+    try {
+        observer?.(effect);
+    }
+    catch { /* observation cannot participate in the Git transaction */ }
+}
 async function gitResult(cwd, args, input, env, signal) {
     return await runGitProcess(cwd, args, { input, env, signal });
 }
@@ -78,9 +84,11 @@ export async function createTaskMutationCommit(input) {
             ], undefined, env, input.signal);
         }
         const tree = (await git(input.cwd, ["write-tree"], undefined, env, input.signal)).trim();
-        const parentTree = (await git(input.cwd, ["show", "-s", "--format=%T", input.parent], undefined, undefined, input.signal)).trim();
-        if (tree === parentTree)
-            return input.parent;
+        if (!input.requireCommit) {
+            const parentTree = (await git(input.cwd, ["show", "-s", "--format=%T", input.parent], undefined, undefined, input.signal)).trim();
+            if (tree === parentTree)
+                return input.parent;
+        }
         return (await git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject], undefined, undefined, input.signal)).trim();
     }
     finally {
@@ -88,15 +96,37 @@ export async function createTaskMutationCommit(input) {
     }
 }
 /** Stage only the mutated task paths into the real index; leave unrelated entries alone. */
-export async function reconcileTaskMutationIndex(cwd, writes, signal) {
+async function reconcileTaskMutationIndexPath(cwd, write, signal) {
+    const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text, undefined, signal)).trim();
+    await git(cwd, [
+        "update-index",
+        "--add",
+        "--cacheinfo",
+        `100644,${oid},${taskMutationPath(write)}`,
+    ], undefined, undefined, signal);
+}
+export async function reconcileTaskMutationIndex(cwd, writes, signal, reconcilePath = async (input) => {
+    await reconcileTaskMutationIndexPath(input.cwd, input.write, input.signal);
+}) {
     for (const write of writes) {
-        const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text, undefined, signal)).trim();
-        await git(cwd, [
-            "update-index",
-            "--add",
-            "--cacheinfo",
-            `100644,${oid},${taskMutationPath(write)}`,
-        ], undefined, undefined, signal);
+        await reconcilePath({ cwd, write, signal });
+    }
+}
+async function snapshotTaskMutationIndex(cwd, writes, signal) {
+    const snapshot = [];
+    for (const write of writes) {
+        const taskPath = taskMutationPath(write);
+        const output = await git(cwd, ["ls-files", "--stage", "-z", "--", taskPath], undefined, undefined, signal);
+        snapshot.push({ path: taskPath, entries: output.split("\0").filter(Boolean) });
+    }
+    return snapshot;
+}
+async function restoreTaskMutationIndex(cwd, snapshot, signal) {
+    for (const item of snapshot) {
+        await git(cwd, ["update-index", "--force-remove", "--", item.path], undefined, undefined, signal);
+        if (item.entries.length > 0) {
+            await git(cwd, ["update-index", "-z", "--index-info"], `${item.entries.join("\0")}\0`, undefined, signal);
+        }
     }
 }
 /**
@@ -114,20 +144,33 @@ export async function publishTaskMutationCommit(input, deps = {}) {
             parent: branch.head,
             writes: input.writes,
             subject: input.subject,
+            requireCommit: input.requireCommit,
             signal: input.signal,
         });
         if (commit === branch.head) {
-            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit, detail: "current" });
+            const indexBefore = await snapshotTaskMutationIndex(input.cwd, input.writes, input.signal);
             try {
-                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal);
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit });
+                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal, deps.reconcileIndexPath);
+                observePublicationEffect(input.observeEffect, { effect: "task-reconciliation", status: "succeeded", commit, detail: "current" });
+                observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "succeeded", commit });
+                return commit;
             }
             catch (error) {
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "failed", commit, error });
+                try {
+                    await restoreTaskMutationIndex(input.cwd, indexBefore, input.signal);
+                }
+                catch (restoreError) {
+                    observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error: restoreError });
+                    throw new FlowError("INTERNAL_STATE", "cannot restore task index after reconciliation failure", { cause: restoreError });
+                }
+                observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error });
+                throw error;
             }
-            return commit;
         }
+        const indexBefore = await snapshotTaskMutationIndex(input.cwd, input.writes, input.signal);
         try {
+            await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal, deps.reconcileIndexPath);
+            observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "succeeded", commit });
             await updateBranch({
                 cwd: input.cwd,
                 ref: branch.ref,
@@ -135,22 +178,22 @@ export async function publishTaskMutationCommit(input, deps = {}) {
                 expected: branch.head,
                 signal: input.signal,
             }, deps);
-            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit, detail: "published" });
-            try {
-                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal);
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit });
-            }
-            catch (error) {
-                // Branch fact remains authoritative; index may be repaired by a later mutation.
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "failed", commit, error });
-            }
+            observePublicationEffect(input.observeEffect, { effect: "task-reconciliation", status: "succeeded", commit, detail: "published" });
             return commit;
         }
         catch (error) {
             lastError = error;
+            try {
+                await restoreTaskMutationIndex(input.cwd, indexBefore, input.signal);
+            }
+            catch (restoreError) {
+                observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error: restoreError });
+                throw new FlowError("INTERNAL_STATE", "cannot restore task index after publication failure", { cause: restoreError });
+            }
+            observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error });
         }
     }
-    input.observeEffect?.({ effect: "task-reconciliation", status: "failed", error: lastError });
+    observePublicationEffect(input.observeEffect, { effect: "task-reconciliation", status: "failed", error: lastError });
     throw lastError;
 }
 async function taskTreeEntries(cwd, commit) {

package/build/core/task/task-git-store.js

@@ -337,6 +337,7 @@ export function openTaskStoreAt(board, deps = {}) {
                             gitDir: transaction.location.gitDir,
                             writes: plan.writes,
                             subject: subject,
+                            requireCommit: plan.requireCommit,
                             signal: deps.signal,
                         });
                     }

package/build/core/task/task-store-repository.js

@@ -75,6 +75,7 @@ function mutationPlan(sources, mutation) {
         writes: prepared.writes,
         value: mutation.select(prepared.board),
         ...(mutation.subject === undefined ? {} : { subject: mutation.subject }),
+        requireCommit: mutation.requireCommit ?? true,
     };
 }
 export function taskRepositoryFromStore(store) {

package/build/flow-error.js

@@ -68,6 +68,11 @@ export function resolveFlowErrorHints(code, context, facts) {
             return ["Pass one complete task coordinate from the listed candidates."];
         case "UNKNOWN_COMMAND":
             return ["Run `keiyaku --help` to inspect available commands."];
+        case "UNKNOWN_OPTION":
+        case "UNKNOWN_ADDRESS":
+        case "INVALID_USAGE":
+        case "STDIN_EMPTY":
+            return [];
         case "EMPTY_PARAM":
             return ["One or more required parameters are empty."];
         case "DIRTY_WORKTREE":
@@ -95,7 +100,7 @@ export function resolveFlowErrorHints(code, context, facts) {
         case "FROM_DRAFT_NOT_FOUND":
             return ["The path in `from_draft` does not exist. `from_draft` must reference an existing file path (absolute or relative to `cwd`)."];
         case "INVALID_KEIYAKU_DRAFT":
-            return ["Invalid draft/input. Use a `# <title>` heading with non-empty `## Context`, `## Objective`, `## Design`, `## Scope`, `## Criteria`, and `## Verification` sections (or the equivalent shape in `from_draft`)."];
+            return ["Invalid draft/input. Use a `# <title>` heading with non-empty `## Context`, `## Objective`, `## Design & Approach`, `## Scope`, `## Criteria`, and `## Verification` sections (or the equivalent shape in `from_draft`)."];
         case "BIND_TASK_INCOMPLETE":
             return ["Task supplies title/objective defaults; pipe only the missing sections as partial contract Markdown on stdin."];
         case "KEIYAKU_FILE_EXISTS":

package/build/generated/version.js

@@ -1,3 +1,3 @@
 // Generated into build output by scripts/build.mjs
-export const VERSION = "2.9.11";
-export const GIT_HASH = "4384d75";
+export const VERSION = "2.9.12";
+export const GIT_HASH = "25d9570";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.11",
+  "version": "2.9.12",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "start": "node build/index.js",
     "test:unit": "node scripts/run-unit-tests.mjs",
     "test:boundaries": "node scripts/check-import-boundaries.mjs",
-    "test:integration": "node --import ./tests/support/real-provider-path-sentinel.mjs --import tsx --test tests/integration/integration.test.ts",
+    "test:integration": "node --import ./tests/support/real-provider-path-sentinel.mjs --import tsx --test --test-concurrency=4 tests/integration/*.test.ts",
     "pretest:cli-expect": "npm run build",
     "test:cli-expect": "node --import ./tests/support/real-provider-path-sentinel.mjs --test --test-concurrency=8 tests/cli-expect/suite/*.test.mjs",
     "test:real-providers": "KEIYAKU_REAL_PROVIDERS=1 node --import tsx --test --test-concurrency=1 tests/real-provider/matrix.test.ts",

package/skills/keiyaku-akuma/SKILL.md

@@ -52,7 +52,8 @@ keiyaku wait <proj-a> <proj-b> --any          # return when the first member fin
 keiyaku wait <proj-a> <proj-b> --all          # return when every member finishes
 keiyaku tell <proj-id> [--wait DURATION] <BODY|-> # optionally tell, then bounded-join
 keiyaku revive rsp_XXXX "continue..."         # new run continuing from a record
-keiyaku kill <proj-id>                        # stop it; record survives, revive still works
+keiyaku kill <proj-id>                        # request a stop; returns an acceptance receipt
+keiyaku kill <proj-id> --wait 5m               # request a stop, then observe the result for 5m
 keiyaku status                                # forgot an id? it's on the board
 ```
 
@@ -74,6 +75,10 @@ Use `keiyaku akuma show NAME` to inspect the resolved source and configuration.
   success means the tell and interrupt intent are durable; provider stop and
   successor wake continue asynchronously under the same projection id. Idle or
   terminal state uses ordinary tell plus wake and reports its typed wake error.
+- `kill` returns an acceptance receipt; it does not include the final result.
+  Use `kill --wait DURATION` when you need to observe the ordinary final result.
+  `DURATION` is required. A timeout ends observation only and does not undo the
+  stop request.
 - Body is required for `call`/`tell`. Literal `-` selects stdin; unselected
   piped bytes are ignored and cannot change an argv body.
 - A `--wait`/`--timeout` expiry prints a live snapshot and exits 0 — the run continues; rejoin with `wait` anytime.

package/skills/keiyaku-task/SKILL.md

@@ -38,6 +38,28 @@ keiyaku task update k-xxxx --pri 0              # also --title, --body TEXT|-, -
 keiyaku task doctor                             # check board integrity
 ```
 
+## Atomic reorganization
+
+Use `task compose` when the final tree and its complete outgoing relation sets
+need review as one operation. Pass the compact sketch through stdin and check
+it before applying it:
+
+```bash
+keiyaku task compose --check - <<'EOF'
++ Project grouping
+  @parser needs=@types
+  @renderer relates=
+@release parent=
+EOF
+keiyaku task compose - < composition.md
+```
+
+An indented line assigns its parent. A top-level `@reference` keeps its parent;
+`parent=` explicitly clears it. `needs=`, `supersedes=`, and `relates=` replace
+only their named complete relation sets, and an explicit empty assignment clears
+that set. Omit a relation to preserve it. Use the command help for the current
+sketch grammar and receipt fields; this skill does not redefine task policy.
+
 ## Dependencies
 
 `--needs` stores the forward edge; `blocks` on the other task is derived automatically. Cycles are rejected at write time. Use needs to express "don't start B before A lands" — nothing more.
@@ -54,7 +76,7 @@ intent, share a coherent write surface, and should settle together; otherwise
 keep separate contracts and express order with task `needs` or contract
 `--after`. The first task supplies title/objective defaults; provide a partial
 bind document for every remaining resolved section. Final bind admission always
-requires Title, Context, Objective, Design, Scope, and Criteria; Verification
+requires Title, Context, Objective, Design & Approach, Scope, and Criteria; Verification
 is optional.
 
 ## Gotcha

package/skills/keiyaku-workflow/SKILL.md

@@ -17,12 +17,33 @@ allowed-tools: Bash(keiyaku *)
   `arc`, `renew`, or `petition`.
 - An arc is a coherent chapter of the same delivery. It keeps the contract,
   worktree, branch, and final settlement.
-- `audit` reports evidence for one pinned candidate. `petition` asks to settle.
+- `audit` is the primary integrated review of one pinned candidate; `petition`
+  asks to settle that candidate.
 
 ```text
 bound -> active -> petitioned -> claimed | forfeited
 ```
 
+## Choosing Scope
+
+Scope names the files this contract is currently expected to write. Use exact
+repository-relative paths when known, a one-component wildcard for unknown
+files in one directory, and a recursive wildcard only when the Objective calls
+for changing the whole subtree.
+
+## Scope
+~~~
+src/pump.ts
+~~~
+
+Scope overlap means contracts may write the same paths; it does not prove their
+changes conflict or forbid parallel work. If intents are independent, proceed
+in parallel and use `--after` to order settlement; use `--exclusive` only when
+concurrent work is unsafe.
+
+Amend is cheap. Broad Scope consumes parallel coordination and weakens audit
+signal, so broader patterns need a reason while narrower terms do not.
+
 ## Bind
 
 Bind when one implementation journey is decided: motivating facts, owning
@@ -30,19 +51,12 @@ modules, inputs and outputs, consequences, failure behavior, invariants,
 forbidden expansion, write set, acceptance criteria, and decisive checks.
 Use a task only when planning or dependencies need a durable place.
 
-Declare the smallest useful Scope:
-
-1. exact paths when known;
-2. a one-component wildcard when names inside one directory are still open;
-3. a recursive wildcard only for a real subtree rewrite, migration, or
-   generated output.
-
 ```bash
 keiyaku bind - < contract.md
 keiyaku bind --task TASK_ID - < contract.md
 ```
 
-The contract document carries `Title`, `Context`, `Objective`, `Design`,
+The contract document carries `Title`, `Context`, `Objective`, `Design & Approach`,
 `Scope`, `Criteria`, and optional `Verification`. Add newly expected exact paths
 with `amend`; do not pre-authorize a broad tree for convenience.
 
@@ -81,16 +95,14 @@ keiyaku status
 - `amend` records a changed intent, invariant, Scope, Criteria, or Verification
   before implementation relies on that change.
 
-Scope changes are ordered terms. Use flags for simple additions or one
-`Scope Append` block for an ordered delta:
+Scope changes are ordered terms. Use `--append-scope` for a simple addition or
+one `Scope Append` block for an ordered delta:
 
-````markdown
 ## Scope Append
-```
+~~~
 src/new-owner.ts
 !src/retired/**
-```
-````
+~~~
 
 Later `!pattern` terms narrow earlier matches. Do not mix the block with
 `--append-scope` flags.
@@ -113,9 +125,12 @@ been reviewed again.
 
 ## Settle
 
-Before settlement, renew if the target moved, then rerun the declared evidence.
-`audit` is read-only; exit 0 means it produced a report, not that the candidate
-passed. Petition requires an oath and runs the settlement gates:
+Commit, renew if stale, then run `audit` first. Audit already combines the
+candidate diff, Scope, Criteria, Verification, and delivery context.
+
+If the evidence is sufficient, petition. Otherwise, run only the check needed
+for a specific gap. `not configured` is not itself a failure. Audit exit 0 means
+a report was produced, not that the candidate passed.
 
 ```bash
 keiyaku audit