@astrosheep/keiyaku 2.9.4 → 2.9.6

package/build/git/diff/structured.js

@@ -0,0 +1,127 @@
+import { createGit, wrapGitError } from "../core.js";
+import { diffPathspecArgs } from "./pathspec.js";
+import { parseHunkRange, parseUnifiedHunks, splitDiffByFile } from "./parsers.js";
+function parseRawDiff(output) {
+    const fields = output.split("\0");
+    const files = [];
+    let index = 0;
+    while (index < fields.length) {
+        const header = fields[index++];
+        if (!header)
+            continue;
+        const statusToken = header.trim().split(/\s+/).at(-1) ?? "";
+        const status = statusToken[0];
+        if (status !== "A" && status !== "M" && status !== "D" && status !== "R" && status !== "C" && status !== "T" && status !== "U")
+            continue;
+        const firstPath = fields[index++] ?? "";
+        if (status === "R" || status === "C") {
+            const path = fields[index++] ?? "";
+            files.push({
+                oldPath: firstPath,
+                path,
+                status,
+                similarity: Number.parseInt(statusToken.slice(1), 10) || 0,
+            });
+        }
+        else {
+            files.push({ path: firstPath, status });
+        }
+    }
+    return files;
+}
+function withoutTerminalPatchDelimiter(patch) {
+    return patch.endsWith("\n") ? patch.slice(0, -1) : patch;
+}
+function parseNumstat(output) {
+    const fields = output.split("\0");
+    const stats = [];
+    let index = 0;
+    while (index < fields.length) {
+        const record = fields[index++];
+        if (!record)
+            continue;
+        const [added = "0", removed = "0", path = ""] = record.split("\t");
+        const binary = added === "-" || removed === "-";
+        if (path) {
+            stats.push({ path, insertions: binary ? 0 : Number.parseInt(added, 10) || 0, deletions: binary ? 0 : Number.parseInt(removed, 10) || 0, binary });
+            continue;
+        }
+        const oldPath = fields[index++] ?? "";
+        const newPath = fields[index++] ?? "";
+        stats.push({ path: newPath, oldPath, insertions: binary ? 0 : Number.parseInt(added, 10) || 0, deletions: binary ? 0 : Number.parseInt(removed, 10) || 0, binary });
+    }
+    return stats;
+}
+function structuredLines(raw, oldStart, newStart) {
+    let oldLine = oldStart;
+    let newLine = newStart;
+    const lines = [];
+    for (const line of raw) {
+        if (line.startsWith("\"))
+            continue;
+        if (line.startsWith("+")) {
+            lines.push({ kind: "addition", content: line.slice(1), oldLine: null, newLine: newLine++ });
+        }
+        else if (line.startsWith("-")) {
+            lines.push({ kind: "deletion", content: line.slice(1), oldLine: oldLine++, newLine: null });
+        }
+        else {
+            lines.push({ kind: "context", content: line.startsWith(" ") ? line.slice(1) : line, oldLine: oldLine++, newLine: newLine++ });
+        }
+    }
+    return lines;
+}
+function parsePatchHunks(section) {
+    return parseUnifiedHunks([...section]).hunks.flatMap((hunk, index) => {
+        const range = parseHunkRange(hunk.header);
+        if (!range)
+            return [];
+        return [{
+                index,
+                header: hunk.header,
+                oldStart: range.oldStart,
+                oldLines: range.oldLines,
+                newStart: range.newStart,
+                newLines: range.newLines,
+                lines: structuredLines(hunk.lines, range.oldStart, range.newStart),
+            }];
+    });
+}
+export async function readStructuredDiff(cwd, from, to, options = {}) {
+    const git = createGit(cwd);
+    const range = `${from}..${to}`;
+    const pathspec = diffPathspecArgs({ excludePaths: options.excludePaths });
+    try {
+        const [raw, numstat, patch] = await Promise.all([
+            git.raw(["diff", "--raw", "-z", "--find-renames", range, ...pathspec]),
+            git.raw(["diff", "--numstat", "-z", "--find-renames", range, ...pathspec]),
+            git.raw(["diff", "--no-color", "--no-ext-diff", "--unified=3", "--find-renames", range, ...pathspec]),
+        ]);
+        const rawFiles = parseRawDiff(raw);
+        const stats = parseNumstat(numstat);
+        const sections = splitDiffByFile(withoutTerminalPatchDelimiter(patch));
+        const files = rawFiles.map((file, index) => {
+            const stat = stats[index];
+            return {
+                ...file,
+                insertions: stat?.insertions ?? 0,
+                deletions: stat?.deletions ?? 0,
+                binary: stat?.binary ?? false,
+                hunks: parsePatchHunks(sections[index] ?? []),
+            };
+        });
+        return {
+            from,
+            to,
+            files,
+            stat: {
+                filesChanged: files.length,
+                insertions: files.reduce((sum, file) => sum + file.insertions, 0),
+                deletions: files.reduce((sum, file) => sum + file.deletions, 0),
+            },
+        };
+    }
+    catch (error) {
+        throw wrapGitError(`diff --find-renames ${range}`, error, cwd);
+    }
+}

package/build/index.js

@@ -3,10 +3,10 @@ import { VERSION, GIT_HASH } from "./generated/version.js";
 import * as fs from "node:fs/promises";
 import { getConfig, initializeConfig } from "./config/env.js";
 import { ENV_KEYS } from "./config/env-keys.js";
-import { logErrorWithCause } from "./telemetry/logger.js";
+import { formatErrorWithCause } from "./telemetry/logger.js";
 import { runProjectionGenerationRuntime } from "./core/projection/index.js";
 import { renderCliHelp, runCliCommand } from "./cli/index.js";
-import { installCliOutputStreamErrorPolicy } from "./cli/output-stream-error-policy.js";
+import { installCliOutputStreamErrorPolicy, writeCliOutput } from "./cli/output-stream-error-policy.js";
 import { assertSubagentCliCommandAllowed } from "./cli/subagent-guard.js";
 installCliOutputStreamErrorPolicy(process.stdout, process.stderr);
 const packageVersion = VERSION;
@@ -45,16 +45,16 @@ async function main() {
         args: cliArgs,
     });
     if (cliArgs.length === 1 && cliArgs[0] === "--version") {
-        console.log(GIT_HASH ? `${packageVersion} (${GIT_HASH})` : packageVersion);
+        await writeCliOutput(process.stdout, `${GIT_HASH ? `${packageVersion} (${GIT_HASH})` : packageVersion}\n`);
         return;
     }
     if (cliArgs.length === 0 || (cliArgs.length === 1 && (cliArgs[0] === "--help" || cliArgs[0] === "-h"))) {
-        console.log(renderCliHelp(packageVersion));
+        await writeCliOutput(process.stdout, `${renderCliHelp(packageVersion)}\n`);
         return;
     }
     process.exitCode = await runCliCommand(cliArgs);
 }
-main().catch((err) => {
-    logErrorWithCause("Fatal error:", err, { mirrorToDebugLog: false });
-    process.exit(1);
+await main().catch(async (err) => {
+    await writeCliOutput(process.stderr, `${formatErrorWithCause("Fatal error:", err)}\n`);
+    process.exitCode = 1;
 });

package/build/telemetry/logger.js

@@ -31,6 +31,9 @@ function stringifyUnknown(error) {
         return String(error);
     }
 }
+export function formatErrorWithCause(message, error) {
+    return `${message} ${stringifyUnknown(error)}`;
+}
 export function logInfo(message, options = {}) {
     log("info", message, options);
 }
@@ -41,6 +44,5 @@ export function logError(message, options = {}) {
     log("error", message, options);
 }
 export function logErrorWithCause(message, error, options = {}) {
-    const details = stringifyUnknown(error);
-    logError(`${message} ${details}`, options);
+    logError(formatErrorWithCause(message, error), options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.4",
+  "version": "2.9.6",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",

package/skills/keiyaku/SKILL.md

@@ -25,7 +25,7 @@ cd .keiyaku/wt/<place>                       # work here yourself, or call an Ak
 keiyaku call <akuma> "fix it"                # worker leaves reviewed source as a dirty tree
 # host coordinator reviews, then git -C <worktree> add/commit accepted paths
 keiyaku status                               # is anything stuck? what's next?
-keiyaku petition <<'EOF'                     # done: seal + settle; the oath is required
+keiyaku petition - <<'EOF'                   # done: seal + settle; the oath is required
 ## Oath
 I fixed the flaky test; suite is green.
 EOF
@@ -33,7 +33,7 @@ EOF
 ```
 
 That's the whole loop. Skip the task when the work needs no planning:
-`keiyaku bind --place NAME --objective TEXT --scope GLOB --checks CHECK` (or the same as Markdown on stdin — `bind --help` shows the shape).
+`keiyaku bind --place NAME --objective TEXT --scope GLOB --checks CHECK` (or the same as Markdown through `keiyaku bind -` — `bind --help` shows the shape).
 
 ## Getting oriented
 

package/skills/keiyaku-akuma/SKILL.md

@@ -8,9 +8,10 @@ allowed-tools: Bash(keiyaku *)
 
 Running devils. Contract lifecycle = `keiyaku-workflow` skill.
 
-## Mind model
+## Core ideas
 
-- **profile** — a devil you can call (`keiyaku akuma ls`). Markdown file: frontmatter = provider/model config, body = its instructions. Project `.keiyaku/akuma/` > user `~/.keiyaku/akuma/` > builtin.
+- **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`.
 
@@ -22,6 +23,7 @@ failed/dead state alone is not a reason to revive.
 
 ```bash
 keiyaku akuma ls                              # who's callable
+keiyaku akuma view 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 --detach "do the thing"     # fire and forget; note the projection id
@@ -34,19 +36,28 @@ keiyaku kill <proj-id>                        # stop it; record survives, revive
 keiyaku status                                # forgot an id? it's on the board
 ```
 
+## Configuration
+
+```text
+<repo>/.keiyaku/akuma/<name>.md          project profile
+<KEIYAKU_HOME>/akuma/<name>.md           user profile (normally ~/.keiyaku)
+```
+
+Use `keiyaku akuma view 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`.
-- Body is required for `call`/`tell`. Piping stdin without a literal `-` does nothing.
+- 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.
-- Only `--contract ADDR` attaches a new call to a contract (by place, slug, or full id). Without it, call is standalone; `--bare` remains an explicit synonym. `call` only — `revive` takes neither and follows artifact provenance.
 
 ## Occasional flags
 
 - `--incognito` — no artifact written, no revive possible (call)
 - `--effort LEVEL` — provider effort override; needs a model set (call, revive, tell)
-- `-C DIR` — run relative to another directory (all akuma commands)
-- `--repo DIR` — you almost never need this: the repo is inferred from where you stand (`-C` included). Only for the rare case where the contract ledger lives in a *different* repo. Never pass it the same value as `-C`.
+- `--repo DIR` — override repository inference only when the contract ledger
+  lives in a different repository.

package/skills/keiyaku-task/SKILL.md

@@ -8,22 +8,26 @@ allowed-tools: Bash(keiyaku *)
 
 Planning notes that live in the repo. Executing them is `keiyaku-workflow` (`bind --task`).
 
-## Mind model
+## Core ideas
 
-A task is a Markdown file in `.keiyaku/tasks/` — id `k-<12hex>`, priority 0–3 (0 highest, default 2), optional body. It has no branch and runs nothing; it's the queue you pull from. States:
+A task is a tracked planning fact, not a worker or execution. Its immutable ID
+is a normalized title slug with a numeric collision suffix when needed. It has
+priority 0–3 (0 highest), optional body, and no branch of its own.
 
 ```
 open ⇄ in_progress → done | drop
 ```
 
-**Ready** = open + every `needs` dependency done. Ready is computed for you — `status` and `task ls` surface it.
+**Ready** = open + every `needs` dependency satisfied. `needs` only orders
+tasks; binding is what turns ready planning facts into one executable contract.
 
 ## Common usage
 
 ```bash
-keiyaku task add "fix the flaky pump test"      # body: pipe stdin for details
+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 ls                                 # all open, priority order
+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
 keiyaku task start k-xxxx                       # mark in_progress (start ≠ execute)
 keiyaku task stop k-xxxx                        # back to open
@@ -41,10 +45,15 @@ keiyaku task doctor                             # check board integrity
 ## Promoting to a contract
 
 ```bash
-keiyaku bind --task k-xxxx
+keiyaku bind --task fix-parser
+keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
 ```
 
-Only a **ready** task binds. in_progress → `task stop` first; blocked → finish its needs first. Binding links the task to the contract; the contract's intent you still write yourself — the title doesn't auto-expand into a spec.
+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 name/objective defaults; provide a partial
+bind document for any missing `Scope` or `Checks`.
 
 ## Gotcha
 

package/skills/keiyaku-workflow/SKILL.md

@@ -8,9 +8,15 @@ allowed-tools: Bash(keiyaku *)
 
 How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning is `keiyaku-task`.
 
-## Mind model
+## Core ideas
 
-A contract = one branch + one linked worktree + a ledger (its record file in the repo). A sandbox worker edits and tests inside that worktree, then hands the host coordinator an uncommitted dirty tree plus its changed-file and check report. The host reviews and commits accepted bytes before running workflow verbs that seal or rewrite delivery. States:
+- A contract is one delivery intent with one ledger, branch, and linked worktree.
+- Workers edit and test; the host reviews their dirty tree and commits accepted bytes.
+- `audit` reads one pinned candidate. `petition` is the settlement action.
+- Scope is an audit boundary, not a write lock. Amend changed intent before delivery.
+- An arc is a named story chapter for one coherent stretch inside the contract.
+
+Lifecycle:
 
 ```
 bound → active → petitioned → claimed | forfeited
@@ -21,9 +27,10 @@ bound → active → petitioned → claimed | forfeited
 ```bash
 keiyaku bind --place fix-pump --objective "make the pump test pass" \
              --scope "src/pump/**" --checks "pump tests green"
-# or the same four fields as Markdown: keiyaku bind < contract.md
+# or the same four fields as Markdown: keiyaku bind - < contract.md
 #   (# <name> / ## Objective / ## Scope / ## Checks)
-# or promote a ready task:            keiyaku bind --task k-xxxx
+# or promote one or more ready tasks:
+keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
 
 cd .keiyaku/wt/fix-pump          # worker edits/tests here and leaves a dirty tree
 
@@ -31,7 +38,10 @@ cd .keiyaku/wt/fix-pump          # worker edits/tests here and leaves a dirty tr
 git -C .keiyaku/wt/fix-pump add -- <accepted-paths>
 git -C .keiyaku/wt/fix-pump commit -m "fix pump"
 
-keiyaku petition <<'EOF'
+# Rehearse the exact pinned delivery before settlement:
+keiyaku @fix-pump audit
+
+keiyaku petition - <<'EOF'
 ## Oath
 I made the pump test pass; ran the suite, all green.
 EOF
@@ -41,37 +51,62 @@ EOF
 # The oath is required (OATH_MISSING otherwise) and checked for presence, not content.
 ```
 
+A task is optional planning, not a prerequisite. Bind directly for new work;
+use `--task` only when promoting existing tracked planning into this contract.
+
 That's the whole small case: bind → worker dirty-tree handoff → host review/commit → petition.
 
-Commissioned workers never run `git add`, `git commit`, or another command that writes Git metadata. Codex workspace-write deliberately keeps `.git` and a linked worktree's resolved gitdir read-only; adding either location to writable roots is not an authorization mechanism. A worker-side Git metadata refusal is therefore not failed delivery. The host coordinator alone commits accepted bytes with native Git, then continues `arc`, `renew`, or `petition`.
+Multi-bind tasks only when they are evidence for the same delivery intent, share
+one coherent write surface, and should settle together. This reduces competing
+contracts/worktrees; it does not replace `needs` or contract `--after` ordering.
+
+`audit` is read-only and never invokes an Akuma or settles the contract. Exit 0
+means it constructed the report, not that the candidate is acceptable. Use
+`--diff-budget BYTES` for bounded output and `--json` for complete typed facts.
+
+Commissioned workers never write Git metadata. The host alone reviews and
+commits accepted bytes before `arc`, `renew`, or `petition`.
+
+Dispatch rule: every time a dispatcher sends a worker, whether through
+`keiyaku call` or any other agent tool, the prompt must explicitly tell that
+worker to read the worktree-root `.keiyaku/KEIYAKU.md` first and follow its
+objective, scope, and checks. The file is the contract-body carrier; do not
+copy its rendered body into a dispatch prompt.
 
 ## Mid-flight commands (use when needed, skip otherwise)
 
 ```bash
-keiyaku arc < arc.md         # optional iteration boundary: seals the current intent, opens
+keiyaku arc - < arc.md       # optional iteration boundary: seals the current intent, opens
                              #   the next. Markdown: # <title> / ## Objective / ## Brief.
                              #   Only needed when one contract has multiple distinct pushes.
 keiyaku renew                # main moved under you → rebase onto it. Refuses on conflict
                              #   instead of guessing; resolve, then renew again.
-keiyaku amend < amendment.md # scope/checks changed → update the paper before the code
+keiyaku amend - < amendment.md # scope/checks changed → update the paper before the code
+# Scope terms can be appended durably during a lifecycle operation:
+keiyaku @fix-pump arc --append-scope "docs/generated/**" - < arc.md
+keiyaku @fix-pump renew --append-scope "docs/generated/**"
 keiyaku log                  # this contract's history
 ```
 
 `amend` accepts prose plus an optional ordered scope-pattern delta:
 
-```markdown
+````markdown
 Clarify the owned documentation surface.
 
-## Scope Add
+## Scope Append
+```
 docs/**
 !docs/generated/**
 ```
+````
 
-`Scope Add` appends patterns to the contract; it is not set-union semantics.
-Patterns retain ordered Git-ignore behavior, so a later `!pattern` excludes a
-previous match and can narrow the effective scope.
+`Scope Append` appends ordered raw gitignore-subset lines in one column-zero
+backtick fence; `Scope Add` and Markdown bullets are rejected. A later
+`!pattern` can narrow earlier scope. Use `--append-scope PATTERN` when a
+lifecycle operation discovers one durable term.
 
 Gotchas:
+- `-C DIR` selects the effective working directory; repository discovery starts there.
 - Base drift blocks petition — if main moved, `renew` first; petition tells you.
 - After an explicit `arc` seals, new loose commits need another `arc` before `renew`/`petition` accept them.
 - Not in the worktree? Address a contract with `--contract ADDR` (place, slug, or full id) or the `keiyaku @addr <verb>` prefix.