@astrosheep/keiyaku 2.9.11 → 2.9.13

package/build/git/worktree.js

@@ -1,7 +1,8 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { FlowError } from "../flow-error.js";
-import { createGit, wrapGitError } from "./core.js";
+import { runGitProcessBytes, runGitOrThrow } from "./process.js";
+import { wrapGitError } from "./core.js";
 export const DIRTY_FILE_CATEGORY = {
     modified: "modified",
     added: "added",
@@ -11,44 +12,106 @@ export const DIRTY_FILE_CATEGORY = {
     copied: "copied",
     untracked: "untracked",
 };
+export class GitPathEncodingError extends Error {
+    name = "GitPathEncodingError";
+    code = "GIT_PATH_ENCODING";
+    constructor() {
+        super("Git returned a path that is not valid UTF-8");
+    }
+}
 const DIRTY_WORKTREE_LIST_LIMIT = 10;
 const KEIYAKU_ARTIFACT_DIR_PREFIX = ".keiyaku/";
+const CONFLICT_STATUS_CODES = new Set(["DD", "AU", "UD", "UA", "DU", "AA", "UU"]);
 function normalizeGitPath(filePath) {
-    return filePath.trim().replace(/^\.\/+/, "");
-}
-function toDirtyStatusPathSets(status) {
-    const renamed = new Set(status.renamed.flatMap((entry) => [entry.from, entry.to]).filter((value) => value.length > 0));
-    return {
-        modified: new Set(status.modified),
-        added: new Set([...status.created, ...status.staged]),
-        deleted: new Set(status.deleted),
-        renamed,
-        conflicted: new Set(status.conflicted),
-        untracked: new Set(status.not_added),
-    };
-}
-function deriveDirtyFileCategory(file, statusPathSets) {
-    if (statusPathSets.untracked.has(file.path)) {
+    return filePath.replace(/^\.\/+/, "");
+}
+function dirtyCategory(index, workingDir) {
+    const code = `${index}${workingDir}`;
+    if (code === "??")
         return DIRTY_FILE_CATEGORY.untracked;
-    }
-    if (statusPathSets.conflicted.has(file.path)) {
+    if (CONFLICT_STATUS_CODES.has(code) || index === "U" || workingDir === "U")
         return DIRTY_FILE_CATEGORY.conflicted;
-    }
-    if (statusPathSets.renamed.has(file.path)) {
+    if (index === "R" || workingDir === "R")
         return DIRTY_FILE_CATEGORY.renamed;
-    }
-    if (statusPathSets.deleted.has(file.path)) {
+    if (index === "C" || workingDir === "C")
+        return DIRTY_FILE_CATEGORY.copied;
+    if (index === "D" || workingDir === "D")
         return DIRTY_FILE_CATEGORY.deleted;
-    }
-    if (statusPathSets.added.has(file.path)) {
+    if (index === "A" || workingDir === "A")
         return DIRTY_FILE_CATEGORY.added;
+    return DIRTY_FILE_CATEGORY.modified;
+}
+function splitNulFields(output) {
+    const fields = [];
+    let start = 0;
+    for (;;) {
+        const end = output.indexOf(0, start);
+        if (end < 0)
+            break;
+        fields.push(output.subarray(start, end));
+        start = end + 1;
+    }
+    if (start < output.length)
+        fields.push(output.subarray(start));
+    return fields;
+}
+function decodeGitPath(value) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(value);
+    }
+    catch {
+        throw new GitPathEncodingError();
+    }
+}
+/** Parse porcelain v1 -z bytes without quoting, trimming, or lossy decoding. */
+export function parsePorcelainStatusZ(output) {
+    const fields = splitNulFields(output);
+    const files = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const field = fields[index] ?? Buffer.alloc(0);
+        if (field.length === 0)
+            continue;
+        const indexCode = String.fromCharCode(field[0] ?? 0x20);
+        const workingDirCode = String.fromCharCode(field[1] ?? 0x20);
+        if (field[2] !== 0x20)
+            continue;
+        const filePath = decodeGitPath(field.subarray(3));
+        if (indexCode === "!" || workingDirCode === "!")
+            continue;
+        const renameOrCopy = indexCode === "R" || workingDirCode === "R" || indexCode === "C" || workingDirCode === "C";
+        if (renameOrCopy) {
+            decodeGitPath(fields[index + 1] ?? Buffer.alloc(0));
+            index += 1; // The second NUL field is the original path, not another status record.
+        }
+        files.push({
+            path: normalizeGitPath(filePath),
+            index: indexCode,
+            working_dir: workingDirCode,
+            category: dirtyCategory(indexCode, workingDirCode),
+        });
+    }
+    return files;
+}
+async function gitBytes(cwd, args, label) {
+    const result = await runGitProcessBytes(cwd, args);
+    if (result.error)
+        throw wrapGitError(label, result.error, cwd);
+    if (result.status !== 0) {
+        throw wrapGitError(label, Object.assign(new Error(`git exited with status ${result.status ?? "unknown"}`), {
+            stdout: result.stdout.toString("utf8"),
+            stderr: result.stderr.toString("utf8"),
+            status: result.status,
+        }), cwd);
+    }
+    return result.stdout;
+}
+async function gitOutput(cwd, args, label) {
+    try {
+        return (await runGitOrThrow(cwd, args)).stdout;
     }
-    if (statusPathSets.modified.has(file.path)) {
-        return DIRTY_FILE_CATEGORY.modified;
+    catch (error) {
+        throw wrapGitError(label, error, cwd);
     }
-    return file.index === "C" || file.working_dir === "C"
-        ? DIRTY_FILE_CATEGORY.copied
-        : DIRTY_FILE_CATEGORY.modified;
 }
 export function renderDirtyFileStatusLine(file) {
     const indexCode = file.index.length > 0 ? file.index : " ";
@@ -56,21 +119,7 @@ export function renderDirtyFileStatusLine(file) {
     return `${indexCode}${worktreeCode} ${file.path}`;
 }
 export async function getDirtyFiles(cwd) {
-    const git = createGit(cwd);
-    let status;
-    try {
-        status = await git.status();
-    }
-    catch (err) {
-        throw wrapGitError("status --porcelain", err, cwd);
-    }
-    const statusPathSets = toDirtyStatusPathSets(status);
-    return status.files.map((file) => ({
-        path: file.path,
-        index: file.index,
-        working_dir: file.working_dir,
-        category: deriveDirtyFileCategory(file, statusPathSets),
-    }));
+    return parsePorcelainStatusZ(await gitBytes(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], "status --porcelain"));
 }
 function normalizePathForDirtyMatch(cwd, filePath) {
     const normalizedPath = filePath.trim();
@@ -90,36 +139,16 @@ export async function assertCleanTrackedWorkingTree(cwd) {
     const overflowCount = dirtyFiles.length - shown.length;
     const overflowLine = overflowCount > 0 ? `\n  ... (+${overflowCount} more)` : "";
     const hasDirtyKeiyakuArtifacts = dirtyFiles.some((file) => normalizePathForDirtyMatch(cwd, file.path).startsWith(KEIYAKU_ARTIFACT_DIR_PREFIX));
-    throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}${overflowLine}\n\nBlocking changes must be committed or stashed before proceeding.`, hasDirtyKeiyakuArtifacts
-        ? { facts: { kind: "dirty_worktree", hasKeiyakuArtifacts: true } }
-        : undefined);
+    throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}${overflowLine}\n\nBlocking changes must be committed or stashed before proceeding.`, hasDirtyKeiyakuArtifacts ? { facts: { kind: "dirty_worktree", hasKeiyakuArtifacts: true } } : undefined);
 }
 export async function getUntrackedFiles(cwd) {
-    const git = createGit(cwd);
-    let output;
-    try {
-        output = await git.raw(["ls-files", "--others", "--exclude-standard"]);
-    }
-    catch (err) {
-        throw wrapGitError("ls-files --others --exclude-standard", err, cwd);
-    }
-    const files = output
-        .split(/\r?\n/)
-        .map((line) => normalizeGitPath(line))
-        .filter((line) => line.length > 0);
-    return Array.from(new Set(files));
+    const output = await gitBytes(cwd, ["ls-files", "--others", "--exclude-standard", "-z"], "ls-files --others --exclude-standard");
+    return Array.from(new Set(splitNulFields(output).filter((filePath) => filePath.length > 0).map(decodeGitPath).map(normalizeGitPath)));
 }
 /** Capture conflicted paths while the index still contains unmerged entries. */
 export async function getUnmergedPaths(cwd) {
-    const git = createGit(cwd);
-    let output;
-    try {
-        output = await git.raw(["diff", "--name-only", "--diff-filter=U", "-z"]);
-    }
-    catch (err) {
-        throw wrapGitError("diff --name-only --diff-filter=U", err, cwd);
-    }
-    return Array.from(new Set(output.split("\0").filter((filePath) => filePath.length > 0)));
+    const output = await gitBytes(cwd, ["diff", "--name-only", "--diff-filter=U", "-z"], "diff --name-only --diff-filter=U");
+    return Array.from(new Set(splitNulFields(output).filter((filePath) => filePath.length > 0).map(decodeGitPath)));
 }
 async function directoryExists(directory) {
     try {
@@ -133,30 +162,14 @@ async function directoryExists(directory) {
 }
 /** Git owns these paths; a lingering REBASE_HEAD alone is not active-rebase evidence. */
 export async function hasActiveRebase(cwd) {
-    const git = createGit(cwd);
-    let paths;
-    try {
-        paths = await Promise.all([
-            git.raw(["rev-parse", "--git-path", "rebase-merge"]),
-            git.raw(["rev-parse", "--git-path", "rebase-apply"]),
-        ]);
-    }
-    catch (error) {
-        throw wrapGitError("rev-parse --git-path rebase state", error, cwd);
-    }
+    const paths = await Promise.all([
+        gitOutput(cwd, ["rev-parse", "--git-path", "rebase-merge"], "rev-parse --git-path rebase state"),
+        gitOutput(cwd, ["rev-parse", "--git-path", "rebase-apply"], "rev-parse --git-path rebase state"),
+    ]);
     const directories = paths.map((candidate) => path.resolve(cwd, candidate.trim()));
     return (await Promise.all(directories.map(directoryExists))).some(Boolean);
 }
 export async function isPathTracked(cwd, filePath) {
-    const git = createGit(cwd);
-    let output;
-    try {
-        output = await git.raw(["ls-files", "--", filePath]);
-    }
-    catch (err) {
-        throw wrapGitError(`ls-files -- ${filePath}`, err, cwd);
-    }
-    return output
-        .split(/\r?\n/)
-        .some((line) => line.trim() === filePath);
+    const output = await gitOutput(cwd, ["ls-files", "-z", "--", filePath], `ls-files -- ${filePath}`);
+    return output.split("\0").some((line) => line === filePath);
 }

package/build/index.js

@@ -5,6 +5,7 @@ import { getConfig, initializeConfig } from "./config/env.js";
 import { ENV_KEYS } from "./config/env-keys.js";
 import { formatErrorWithCause } from "./telemetry/logger.js";
 import { runProjectionGenerationRuntime } from "./core/projection/index.js";
+import { runVerificationRuntime } from "./core/settlement/verification.js";
 import { renderCliHelp, runCliCommand } from "./cli/index.js";
 import { installCliOutputStreamErrorPolicy, writeCliOutput } from "./cli/output-stream-error-policy.js";
 import { assertSubagentCliCommandAllowed } from "./cli/subagent-guard.js";
@@ -37,6 +38,12 @@ async function main() {
         await runProjectionGenerationRuntime(projectionDirectory, cliArgs[2]);
         return;
     }
+    if (cliArgs[0] === "__keiyaku-verify") {
+        if (cliArgs.length !== 3 || !cliArgs[1] || !cliArgs[2])
+            throw new Error("invalid internal verification invocation");
+        await runVerificationRuntime(cliArgs[1], cliArgs[2]);
+        return;
+    }
     initializeConfig(process.env, findCliCwd(cliArgs) ?? process.cwd());
     const config = getConfig();
     assertSubagentCliCommandAllowed({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.11",
+  "version": "2.9.13",
   "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

@@ -1,6 +1,6 @@
 ---
 name: keiyaku-akuma
-description: Use whenever a request mentions an Akuma, akuma, devil, demon, or 恶魔 and the work may involve calling, watching, telling, killing, or reviving one; covers Keiyaku Akuma profiles, projections, artifacts, lifecycle control, and rejoin operations.
+description: Use whenever a request mentions an Akuma, akuma, devil, demon, or 恶魔 and the work may involve calling, waiting, telling, killing, or forking one; covers Keiyaku Akuma profiles, projections, artifacts, lifecycle control, and fork lineage.
 allowed-tools: Bash(keiyaku *)
 ---
 
@@ -13,11 +13,11 @@ Running devils. Contract lifecycle = `keiyaku-workflow` skill.
 - **profile** — callable configuration: frontmatter selects provider/model;
   Markdown body gives instructions. Project overrides user, which overrides builtin.
 - **projection** (`name/8hex`) — one live run of a devil. This is the id for `wait` / `tell` / `kill`.
-- **artifact** (`rsp_…`) — what a finished run left behind. This is the id for `revive`.
+- **artifact** (`rsp_…`) — what a retained finished run left behind. This is the id for `fork`.
 
 Rule of thumb: continue the same conversation with its projection id. Use an
-artifact id with `revive` only when deliberately starting a new projection;
-failed/dead state alone is not a reason to revive.
+artifact id with `fork` only when deliberately starting a new projection;
+failed/terminal state alone is not a reason to fork.
 
 ## Projection aliases
 
@@ -35,7 +35,7 @@ Aliases are per selected projection ledger, not projection identity. Keep the
 full `name/8hex` ID in durable records and exact recovery. Reusing an alias
 word atomically moves only that per-ledger ref to the new projection; it does
 not stop, mutate, or delete the prior projection. Its old full ID remains
-addressable. `revive` starts a new projection and does not inherit an alias.
+addressable. `fork` starts a new projection and does not inherit an alias.
 
 ## Common usage
 
@@ -43,16 +43,17 @@ addressable. `revive` starts a new projection and does not inherit an alias.
 keiyaku akuma ls                              # who's callable
 keiyaku akuma show NAME                       # resolved profile + live projections
 keiyaku call NAME "do the thing"              # run in foreground until it finishes
-keiyaku call NAME --wait 10m "do the thing"   # bounded: after 10m you get a snapshot, it keeps running
+keiyaku call NAME --wait 10m "do the thing"   # bounded deadline snapshot; it keeps running
 keiyaku call NAME -d "do the thing"           # short for --detach; note the projection id
 keiyaku call NAME - < prompt.md               # long prompt: literal `-` reads stdin
-keiyaku wait <proj-id>                        # join a running one; prints its activity
-keiyaku wait <proj-id> --timeout 5m           # peek for 5m; timeout = snapshot, not death
+keiyaku wait <proj-id>                        # observe one retained or active projection
+keiyaku wait <proj-id> --timeout 5m           # deadline snapshot; timeout does not stop it
 keiyaku wait <proj-a> <proj-b> --any          # return when the first member finishes
 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 fork rsp_XXXX "continue..."           # new run continuing from a retained record
+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
 ```
 
@@ -67,17 +68,22 @@ Use `keiyaku akuma show NAME` to inspect the resolved source and configuration.
 
 ## Expectations
 
-- Omit tell's bracketed `--wait DURATION` option for silent success: exit 0,
-  zero output. Supply it to perform the ordinary bounded join after acceptance.
-  Silence **is** the receipt — do not re-send. Effects show up in `wait`/`status`.
-- `tell --interrupt` is intentionally destructive. On an active runner, silent
-  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.
+- `tell` succeeds only after durable acceptance for the addressed projection.
+  Its receipt never claims provider consumption. `tell --wait DURATION` then
+  performs the ordinary bounded wait and returns that response and exit status.
+- `tell --interrupt` records tell acceptance and interruption intent; provider
+  stop/successor adoption remain asynchronous. An idle or terminal wake failure
+  preserves the accepted tell and reports its typed wake failure.
+- `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.
-- `wait` is repeatable: on a finished run it shows the final transcript again.
+- A `--wait`/`--timeout` expiry prints the admitted-set deadline snapshot and
+  exits 124. It changes no lifecycle state; observe again with `wait` anytime.
+- `wait` is repeatable: a terminal view re-renders durable terminal facts,
+  including the typed final answer and real artifact lineage when retained.
 - Supervise multiple projections with one plural `wait`. Choose `--any` to
   handle the first terminal member and refill its lane; choose `--all` only for
   final batch convergence. Keep foreground waits blocking; if bounded, use one
@@ -85,7 +91,7 @@ Use `keiyaku akuma show NAME` to inspect the resolved source and configuration.
 
 ## Occasional flags
 
-- `--incognito` — no artifact written, no revive possible (call)
-- `--effort LEVEL` — provider effort override; needs a model set (call, revive, tell)
+- `--incognito` — no artifact written, no fork possible (call)
+- `--effort LEVEL` — provider effort override; needs a model set (call, fork, tell)
 - `--repo DIR` — override repository inference only when the contract ledger
   lives in a different repository.

package/skills/keiyaku-task/SKILL.md

@@ -24,8 +24,16 @@ tasks; binding is what turns ready planning facts into one executable contract.
 ## Common usage
 
 ```bash
-keiyaku task add - < task.md                      # literal - reads the task body from stdin
-keiyaku task add "title" --pri 1 --needs k-aaa  # priority + dependency at birth
+keiyaku task add - <<'EOF'                       # canonical stdin task document
+---
+title: Parse task documents
+pri: 1
+needs:
+  - task-model
+---
+Keep parser and model validation together.
+EOF
+keiyaku task add "title" --pri 1 --needs k-aaa  # concise title plus creation flags
 keiyaku task ls                                 # all nonterminal tasks
 keiyaku task ls --filter state=ready --sort priority,modified
 keiyaku task show k-xxxx                        # full detail and parent-children tree
@@ -36,8 +44,31 @@ keiyaku task drop k-xxxx                        # won't do; kept in history, not
 keiyaku task update k-xxxx --pri 0              # also --title, --body TEXT|-, --needs,
                                                 #   --drop-needs — see --help
 keiyaku task doctor                             # check board integrity
+keiyaku task ls --contract hades                # inspect one commissioned workspace from the hub
+```
+
+## 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.
@@ -45,18 +76,43 @@ keiyaku task doctor                             # check board integrity
 ## Promoting to a contract
 
 ```bash
-keiyaku bind --task fix-parser
-keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
+keiyaku bind --task fix-parser - <<'EOF'
+# Fix parser
+
+## Context
+Valid input is rejected.
+
+## Objective
+Accept valid input.
+
+## Design & Approach
+Correct the parser at its existing boundary.
+
+## Scope
+~~~
+src/parser.ts
+~~~
+
+## Criteria
+- Valid input parses.
+EOF
 ```
 
+For a multi-task delivery, repeat `--task TASK_ID` on the same bind.
+
 Only ready tasks bind. Multi-bind only when the tasks describe one delivery
 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
 
 Task files are ordinary tracked files: checking out another branch shows *that branch's* board. Don't panic when states differ across branches — you're reading a different branch's truth, and the old one is still in git.
+
+When a task operation targets a commissioned workspace from the hub, use
+`--contract <place|slug|full-id>`. It resolves the ledger-owned materialized
+checkout and follows its normal task authority; do not use a physical
+`.keiyaku/wt/...` path as the commission identity.

package/skills/keiyaku-workflow/SKILL.md

@@ -15,36 +15,88 @@ allowed-tools: Bash(keiyaku *)
 - Criteria state what must be true. Verification supplies executable evidence.
 - Implementation happens in the linked worktree. Commit accepted bytes before
   `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.
+- An arc is a coherent stage of the same delivery. It keeps the contract,
+  worktree, branch, Scope, and final settlement; it is not independently
+  claimable.
+- `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.
+
+## Choose Topology
+
+Use arcs only when successive stages share one delivery, acceptance boundary,
+ownership, and final settlement. Scope overlap alone does not choose topology.
+Base drift calls for `renew`, not an arc. `arc --append-scope` adds to the
+cumulative contract Scope; it does not create arc-local Scope enforcement.
+
+Use separate tasks and contracts for independently deliverable work, distinct
+acceptance or ownership, or a slice that must wait on another contract. Record
+external ordering with task needs or `--after`; do not keep an otherwise
+claimable slice open merely to wait.
+
+One contract can migrate a storage format with an arc for the writer and a
+later arc for the reader, then settle once. A parent task for an API migration
+can instead track producer and consumer child contracts with separate owners
+and acceptance, ordered by a task need or `--after`.
+
 ## Bind
 
-Bind when one implementation journey is decided: motivating facts, owning
-modules, inputs and outputs, consequences, failure behavior, invariants,
-forbidden expansion, write set, acceptance criteria, and decisive checks.
+Bind a Keiyaku only after its motivating facts and design are clear. When they
+are not, complete the necessary investigation first; that investigation may
+itself be a prerequisite Keiyaku.
 Use a task only when planning or dependencies need a durable place.
 
-Declare the smallest useful Scope:
+```bash
+keiyaku bind - <<'EOF'
+# Fix parser
 
-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.
+## Context
+Valid input is rejected.
 
-```bash
-keiyaku bind - < contract.md
-keiyaku bind --task TASK_ID - < contract.md
+## Objective
+Accept valid input.
+
+## Design & Approach
+Correct the parser at its existing boundary.
+
+## Scope
+~~~
+src/parser.ts
+~~~
+
+## Criteria
+- Valid input parses.
+EOF
 ```
 
-The contract document carries `Title`, `Context`, `Objective`, `Design`,
-`Scope`, `Criteria`, and optional `Verification`. Add newly expected exact paths
-with `amend`; do not pre-authorize a broad tree for convenience.
+The H1 is the Title. The H2 sections are `Context`, `Objective`,
+`Design & Approach`, `Scope`, `Criteria`, and optional `Verification`. Use
+`bind --task TASK_ID -` to bind a ready task with the same document shape. Add
+newly expected exact paths with `amend`; do not pre-authorize a broad tree for
+convenience.
 
 ## Select The Contract
 
@@ -81,16 +133,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 +163,14 @@ 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, then use `renew --audit` when the delivery may be stale; it performs
+the ordinary delivery rewrite first and audits the resulting fresh candidate.
+Use `audit` directly when no renewal is needed. 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

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

@@ -1,12 +0,0 @@
-export const meta = {
-    command: "revive",
-    summary: "Revive an Akuma helper session",
-    usage: ["keiyaku revive ARTIFACT [BODY|-]"],
-    stdin: {
-        mode: "argument",
-        selector: { kind: "positional", index: 1, required: false, rejectBlank: true },
-    },
-    flags: ["cwd", "repo", "model", "effort"],
-    purpose: "Continue a persisted helper session.",
-    completionRank: 4,
-};