@astrosheep/keiyaku 2.9.7 → 2.9.8

package/build/core/worktree-path.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import { FlowError } from "../flow-error.js";
 import { createGit, wrapGitError } from "../git/core.js";
 import { readLedger } from "./ledger.js";
+import { readLedgerSnapshot } from "./ledger-batch.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { normalizeFilesystemCoordinate } from "../fs/path-coordinate.js";
 import { gitCommonRootPath, resolveGitCommonRoot } from "../git/path-coordinate.js";
@@ -73,7 +74,10 @@ export async function stableRepoRoot(cwd) {
     }
 }
 export async function contractWorktreePathFromBind(cwd, contractId, bind) {
-    return path.join(await stableRepoRoot(cwd), ".keiyaku", "wt", bind?.data.place ?? contractId);
+    return contractWorktreePathFromStableRoot(await stableRepoRoot(cwd), contractId, bind);
+}
+function contractWorktreePathFromStableRoot(stableRoot, contractId, bind) {
+    return path.join(stableRoot, ".keiyaku", "wt", bind?.data.place ?? contractId);
 }
 export async function contractWorktreePath(cwd, contractId) {
     const ledger = await readLedger(cwd, contractId);
@@ -110,7 +114,7 @@ export async function findRegisteredContractWorktreePath(cwd, contractId) {
         return undefined;
     let expected;
     try {
-        expected = await fs.realpath(await contractWorktreePathFromBind(stableRoot, contractId, bind));
+        expected = await fs.realpath(contractWorktreePathFromStableRoot(stableRoot, contractId, bind));
     }
     catch {
         return undefined;
@@ -139,48 +143,58 @@ export async function resolveContractDeliveryCwd(cwd, contractId) {
  * terminal state is optional so residual worktrees after cleanup still bind.
  */
 async function contractIdForEngineOwnedWorktree(cwd, options) {
-    const stableRoot = await stableRepoRoot(cwd);
+    const stableRoot = options.stableRoot ?? await stableRepoRoot(cwd);
     const canonicalCwd = await fs.realpath(cwd);
+    const candidates = [];
     for (const worktree of await listWorktrees(stableRoot)) {
         const branchPrefix = "refs/heads/keiyaku/";
         if (!worktree.branch?.startsWith(branchPrefix))
             continue;
-        const contractId = worktree.branch.slice(branchPrefix.length);
-        const ledger = await readLedger(stableRoot, contractId);
-        if (!ledger)
-            continue;
-        if (options.requireActive && isTerminalState(deriveContractState(ledger.entries)))
-            continue;
-        const bind = findBindEntry(ledger.entries);
-        if (!bind || bind.data.workspace !== "worktree")
-            continue;
         let canonicalWorktree;
-        let expectedWorktree;
         try {
             canonicalWorktree = await fs.realpath(worktree.path);
-            expectedWorktree = await fs.realpath(await contractWorktreePathFromBind(stableRoot, contractId, bind));
         }
         catch {
             continue;
         }
-        if (canonicalWorktree !== expectedWorktree)
+        if (!worktreeContainsCoordinate(canonicalWorktree, canonicalCwd))
             continue;
-        if (worktreeContainsCoordinate(canonicalWorktree, canonicalCwd))
-            return contractId;
+        candidates.push({
+            contractId: worktree.branch.slice(branchPrefix.length),
+            path: canonicalWorktree,
+        });
     }
-    return undefined;
+    const candidate = candidates.sort((left, right) => right.path.length - left.path.length)[0];
+    if (!candidate)
+        return undefined;
+    const ledger = await readLedgerSnapshot(stableRoot, candidate.contractId);
+    if (!ledger)
+        return undefined;
+    if (options.requireActive && isTerminalState(deriveContractState(ledger.entries)))
+        return undefined;
+    const bind = findBindEntry(ledger.entries);
+    if (!bind || bind.data.workspace !== "worktree")
+        return undefined;
+    let expectedWorktree;
+    try {
+        expectedWorktree = await fs.realpath(contractWorktreePathFromStableRoot(stableRoot, candidate.contractId, bind));
+    }
+    catch {
+        return undefined;
+    }
+    return candidate.path === expectedWorktree ? candidate.contractId : undefined;
 }
 /**
  * Resolve the contract bound by an engine-owned worktree containing cwd,
- * including when the ledger is already terminal. Task CLI contract context
- * uses this residual binding; call attachment never infers from cwd.
+ * including when the ledger is already terminal. Task CLI context uses this
+ * residual binding; call uses the active-only sibling below.
  */
-export async function contractBoundByEngineWorktree(cwd) {
-    return contractIdForEngineOwnedWorktree(cwd, { requireActive: false });
+export async function contractBoundByEngineWorktree(cwd, stableRoot) {
+    return contractIdForEngineOwnedWorktree(cwd, { requireActive: false, stableRoot });
 }
-/** Existing-contract verbs may infer only a verified, active engine binding. */
-export async function activeContractBoundByEngineWorktree(cwd) {
-    return contractIdForEngineOwnedWorktree(cwd, { requireActive: true });
+/** Existing-contract verbs and no-selector call attachment use only this verified active binding. */
+export async function activeContractBoundByEngineWorktree(cwd, stableRoot) {
+    return contractIdForEngineOwnedWorktree(cwd, { requireActive: true, stableRoot });
 }
 export async function cleanupContractWorkspace(cwd, contractId) {
     const stableRoot = await stableRepoRoot(cwd);

package/build/flow-error.js

@@ -20,7 +20,7 @@ export function renderTemplate(template, values) {
 }
 function formatInvalidSettingsDiseaseHints(diseases) {
     return diseases.map((disease) => {
-        const where = disease.knob ? `${disease.source}:${disease.knob}` : `${disease.source}:(root)`;
+        const where = disease.knob ? `${disease.coordinate}:${disease.knob}` : `${disease.coordinate}:(root)`;
         return `${where}: ${disease.reason}`;
     });
 }

package/build/generated/version.js

@@ -1,3 +1,3 @@
 // Generated into build output by scripts/build.mjs
-export const VERSION = "2.9.7";
-export const GIT_HASH = "e0169c3";
+export const VERSION = "2.9.8";
+export const GIT_HASH = "c9cfce1";

package/build/git/refs.js

@@ -1,5 +1,51 @@
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "./core.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, runGitProcess, wrapGitError, } from "./core.js";
 const ZERO_OBJECT_ID = "0000000000000000000000000000000000000000";
+/** Normalize a configured branch to the sole local-branch ref spelling. */
+export function normalizeLocalBranchRef(branch) {
+    return branch.startsWith("refs/heads/") ? branch : `refs/heads/${branch}`;
+}
+function isMissingExactRef(result) {
+    return result.status === 1 && result.stdout === "";
+}
+function parseShowRefRows(output) {
+    const lines = output.split(/\r?\n/);
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (lines.length === 0 || lines.some((line) => line.length === 0))
+        return null;
+    const rows = [];
+    for (const line of lines) {
+        const match = /^(?<objectId>[0-9a-fA-F]{40}|[0-9a-fA-F]{64}) (?<ref>refs\/\S+)$/.exec(line);
+        if (!match?.groups)
+            return null;
+        rows.push({ objectId: match.groups.objectId, ref: match.groups.ref });
+    }
+    return rows;
+}
+function throwGitProcessFailure(commandLabel, result, cwd) {
+    const failure = result.error ?? Object.assign(new Error(result.stderr || `git ${commandLabel} exited ${result.status}`), {
+        stderr: result.stderr,
+        stdout: result.stdout,
+    });
+    throw wrapGitError(commandLabel, failure, cwd);
+}
+/**
+ * Resolve only a local branch through the argv-based Git boundary. A configured
+ * short name is never allowed to fall through Git's revision search rules.
+ */
+export async function resolveLocalBranchHead(cwd, branch, run = runGitProcess) {
+    const ref = normalizeLocalBranchRef(branch);
+    const result = await run(cwd, ["show-ref", ref]);
+    if (isMissingExactRef(result))
+        return null;
+    if (result.status === 0) {
+        const exactRows = parseShowRefRows(result.stdout)?.filter((row) => row.ref === ref);
+        if (exactRows?.length === 1) {
+            return { ref, head: exactRows[0].objectId };
+        }
+    }
+    return throwGitProcessFailure(`show-ref ${ref}`, result, cwd);
+}
 async function resolveRefOrNull(cwd, ref) {
     const git = createGit(cwd);
     try {

package/package.json

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

package/skills/keiyaku-akuma/SKILL.md

@@ -19,6 +19,24 @@ 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.
 
+## Projection aliases
+
+When a lane will be supervised repeatedly, assign a short stable alias at call
+time and use it as the operator coordination handle:
+
+```bash
+keiyaku call worker-akuma --alias release-lane --detach "implement the brief"
+keiyaku wait release-lane --timeout 10m
+keiyaku tell release-lane "run the focused checks before handoff"
+keiyaku kill release-lane
+```
+
+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.
+
 ## Common usage
 
 ```bash

package/skills/keiyaku-workflow/SKILL.md

@@ -13,7 +13,8 @@ How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning
 - 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.
+- Scope is the smallest closure of files currently expected to be written. Amend
+  newly expected exact paths before delivery.
 - An arc is a named story chapter for one coherent stretch inside the contract.
 
 Lifecycle:
@@ -32,8 +33,9 @@ Before binding, complete the fact and decision work needed to state the delivery
 - read the registered authority and locate the current owning modules;
 - settle inputs, outputs, state consequences, failure behavior, invariants, and
   forbidden expansion;
-- declare one coherent ownership region and account for known write overlap and
-  delivery dependencies;
+- identify the smallest expected write set and account for known write overlap
+  and delivery dependencies; ownership remains with the authority registry and
+  its owning chapter;
 - write checks that prove the critical success path, the highest-risk rejection,
   and the relevant durability, concurrency, or recovery boundary.
 
@@ -48,11 +50,59 @@ After bind, the worker implements and verifies that contract. `amend` records
 new evidence or a change of intent that genuinely emerges during implementation
 or review, then implementation continues from the updated contract.
 
+## Choosing Scope
+
+Scope names the files this contract is currently expected to write, not a
+territory the contract owns. Choose the narrowest form supported by the
+evidence, in this order:
+
+1. When the write set is known, list exact repository-relative paths, one per
+   line. This is the default and needs no justification.
+2. When filenames are not yet known but changes are scattered within one
+   directory, use a one-component wildcard for that component.
+3. Use the recursive wildcard only for a real whole-subtree rewrite, migration,
+   or generated-output operation. The Objective must state why the entire tree
+   is expected to change.
+
+Known files use exact paths:
+
+```bash
+keiyaku bind --place fix-pump --objective "make the pump test pass" \
+             --scope "src/pump.ts" --scope "tests/unit/pump.test.ts" \
+             --checks "pump tests green"
+```
+
+Unknown filenames within one component may use a one-component wildcard:
+
+```bash
+keiyaku bind --place repair-pump-fixtures --objective "repair the affected pump fixtures" \
+             --scope "tests/fixtures/pump/*" --checks "pump fixture tests green"
+```
+
+A recursive pattern is reserved for an actual whole-tree operation:
+
+```bash
+keiyaku bind --place regenerate-api-docs \
+             --objective "regenerate API documentation because the generator changes every file under docs/generated" \
+             --scope "docs/generated/**" --checks "generated API docs are current"
+```
+
+If implementation evidence later identifies one more expected file, amend with
+that exact path:
+
+```bash
+keiyaku amend --append-scope "src/pump/metrics.ts" - < amendment.md
+```
+
+Amend is cheap. Broad Scope consumes parallel coordination and weakens audit
+signal, so moving to a broader pattern needs a reason; moving narrower does not.
+
 ## The default flow
 
 ```bash
 keiyaku bind --place fix-pump --objective "make the pump test pass" \
-             --scope "src/pump/**" --checks "pump tests green"
+             --scope "src/pump.ts" --scope "tests/unit/pump.test.ts" \
+             --checks "pump tests green"
 # or the same four fields as Markdown: keiyaku bind - < contract.md
 #   (# <name> / ## Objective / ## Scope / ## Checks)
 # or promote one or more ready tasks:
@@ -149,29 +199,34 @@ keiyaku arc - < arc.md       # optional iteration boundary: seals the current in
 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
-# 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:
+`amend` accepts prose plus one optional ordered scope-pattern delta. Use either
+repeated flags:
+
+```sh
+keiyaku amend --append-scope "docs/api-reference.md" --append-scope "!docs/obsolete-api-reference.md" - < amendment.md
+```
+
+or a document section:
 
 ````markdown
-Clarify the owned documentation surface.
+Clarify the newly expected documentation files.
 
 ## Scope Append
 ~~~
-docs/**
-!docs/generated/**
+docs/api-reference.md
+!docs/obsolete-api-reference.md
 ~~~
 ````
 
 `Scope Append` appends ordered raw gitignore-subset lines in one column-zero
 tilde fence; direct input also accepts a matching 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.
+`!pattern` can narrow earlier scope. Flags and a document Scope Append block
+are mutually exclusive; plain amendment prose plus flags is valid. Use
+`--append-scope PATTERN` when a lifecycle operation discovers one durable term.
 
 Gotchas:
 - `-C DIR` selects the effective working directory; repository discovery starts there.