@astrosheep/keiyaku 4.0.1 → 4.0.3

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-workflow/SKILL.md

@@ -1,28 +1,35 @@
 ---
 name: keiyaku-workflow
-description: Use when authoring, binding, delivering, reviewing, amending, auditing, or abandoning a Keiyaku v4 Contract.
+description: Use when authoring, binding, auditing, delivering, reviewing, amending, or abandoning a Keiyaku v4 Contract.
 ---
 
 # Keiyaku Workflow
 
-A Contract turns one bounded delivery into acceptable terms: write what done
-means, bind it, work in the worktree the receipt names, and deliver. When
-every declared gate is current, the result lands on the target ref. This is
-the whole trip from current work to `claimed`.
+A Contract turns one bounded delivery into acceptable terms: bind it, work in
+the appointed worktree, audit the Contract, deliver, then review. When every
+declared gate is current, the result lands on the target ref.
 
 ## How The Delivery Moves
 
 ```text
-contract document -> bind -> work in the Contract worktree -> deliver
-                             -> review gates -> placement -> claimed
-                                                      \-> abandoned
+contract document -> bind -> work -> audit -> deliver -> review gates
+                                                    -> placement -> claimed
+                                                                \-> abandoned
 ```
 
 The lifecycle is `waiting -> bound -> pending-delivery -> claimed | abandoned`;
-the last two are terminal. `--after` prerequisites hold a Contract at
-`waiting`; it becomes `bound` automatically once they are satisfied. You never
-push it through states by hand: `deliver` and satisfied reviews request
-placement, and placement claims when the gates allow it.
+the last two are terminal. Reserve `--after` for true logical ordering: one
+Contract's result must ultimately build on another's settled outcome, or their
+intended work has a large or irreconcilable interaction that should be
+sequenced. Ordinary Region overlap is not enough. Small overlaps may proceed
+under Git's optimistic write model and be resolved manually or by a delegated
+worker. At runtime prerequisites are placement obligations, not a delivery
+admission gate: a Contract may record `bound` and deliver before they claim,
+while placement waits for the current prerequisites and declared gates. Active
+terms may amend `--after` after `bound` or `deliver`; terminal Contracts remain
+immutable. You never push it through states by hand: `deliver` and satisfied
+reviews request placement, and placement claims when every prerequisite and
+gate allows it.
 
 ## Bind
 
@@ -34,15 +41,31 @@ bind inputs, and read the receipt. Continue here from that receipt.
 Change and test code in the worktree the bind receipt names. `deliver` accepts
 a clean worktree by default. You may commit first, or explicitly include all
 non-ignored staged, unstaged, and untracked final bytes with
-`deliver --include-dirty`. Check where you are at any point:
+`deliver --include-dirty`.
+
+## Regain The Picture
+
+Rebuild state from reads, not memory — after a compact, a handoff, or any
+surprising receipt, read before acting:
 
 ```bash
-keiyaku status [<contract>|@<contract>]
+keiyaku status                    # the whole board
+keiyaku status <contract>         # lifecycle, candidate, one mark per gate
+keiyaku show <contract>           # the exact current Contract terms
+keiyaku region                    # every active Contract's declared surfaces
+keiyaku region <contract>         # one Contract's declared intent
+keiyaku region --overlap          # which declared intents intersect
+keiyaku region --path <path>      # which active Contracts declare this path
 ```
 
-`status` shows the lifecycle state, the candidate, and one mark per gate: `✓`
-current satisfied, `!` current unsatisfied, `?` stale because the patch or
-document changed after the evidence, and `○` missing.
+`status` marks each gate: `✓` current satisfied, `!` current unsatisfied, `?`
+stale because the patch or document changed after the evidence, `○` missing.
+A Region is a Contract's declared write intent — not ownership, not a gate,
+and not a Git conflict. Read the world before decomposing or commissioning
+into an occupied repository; read `--overlap` before choosing a landing order
+or an `--after` edge; read `--path` before touching a file that may belong to
+another lane. Regions are declarations only, a coarse planning signal: actual
+touched paths and conflicts remain Git's.
 
 ## Commission A Contract
 
@@ -71,25 +94,54 @@ frontmatter names `Contract`, then reads the listed owner documents and source
 files before acting. Do not substitute a generic repository tour for the files
 that actually govern the assignment.
 
-A `Deliverer` implements and verifies the terms, keeps all work in `Worktree`,
-and reports the candidate, checks run, and unmet terms. A `Reviewer` reads the
-same worktree and Contract, judges the current candidate with direct evidence,
-and does not modify it. If `Seat`, `Worktree`, or the required reading list is
-missing or contradictory, the worker stops and asks the caller instead of
-guessing.
+A `Deliverer` implements and verifies the terms in `Worktree`. Commission a
+`Reviewer` after delivery. The reviewer inspects the complete current Contract
+worktree snapshot, not a worker report or named candidate commit, and does not
+modify it. Missing or contradictory seat, worktree, or reading list means stop
+and ask.
+
+Observe commissioned workers through their Contract association instead of
+collecting Aku ids by hand:
+
+```bash
+keiyaku wait kei/<contract> --all --timeout 5m
+keiyaku wait kei/<first> kei/<second> --any --timeout 5m
+```
+
+A Contract selector snapshots its dispatched workers when the command starts.
+Use `--all` to wait for every selected worker or `--any` to return when one
+finishes; an expanded set with more than one worker requires an explicit mode.
+
+## Decompose Complex Work
 
-## Arcs For Large Deliveries
+Complex Keiyaku should be divided along independently acceptable delivery
+boundaries. Use judgment to find those boundaries from the work's objectives,
+dependencies, Regions, and acceptance criteria; raw size or file count is not
+the test. Give each resulting Contract coherent terms. Connect them with
+`--after` only when one must proceed from another's settled result or their
+intended work is unsafe to run concurrently.
 
-When one Contract carries several coherent chunks, record each chunk as an arc
-before moving to the next:
+When one acceptance boundary still spans several coherent chapters,
+organize them as arcs. An arc is a chapter of the delivery's
+story, not a task list: its title names the chapter, Objective is the
+chapter's aim, Brief opens the next chapter. When an Arc is active, stay
+within that current chapter. `.keiyaku/KEIYAKU.md` renders the current Arc.
+Record the next chapter before entering it:
 
 ```bash
-keiyaku arc <contract> -
+keiyaku arc <contract> - <<'KEIYAKU'
+# <chapter title>
+
+## Objective
+<nonblank objective>
+
+## Brief
+<nonblank dispatch brief>
+KEIYAKU
 ```
 
-The stdin body is the arc's Markdown; see `arc --help` for its shape. Arcs
-narrate one delivery; they do not split acceptance. Work that needs its own
-independent acceptance is a new Contract, not an arc.
+All chapters live inside that Contract's single delivery and acceptance
+boundary. The document grammar authority is `docs/document.md`.
 
 ## Amend Or Start Over
 
@@ -105,14 +157,35 @@ See `amend --help` for the operation grammar. If the objective or boundary
 itself changed, `abandon` with a note and bind a new Contract; do not steer an
 old Contract onto a different delivery.
 
+## Audit Before Delivery
+
+Audit is how you see a delivery before it exists:
+
+```bash
+keiyaku audit <contract> --diff
+```
+
+Audit answers three already-adjudicated questions: candidate, Verification,
+and target. It uses the same candidate preparation as deliver, shows the
+prospective identity and optional requested diff, and runs declared
+Verification against that candidate. A terminal run records ordinary
+subject-bound `verified` testimony; it does not record a delivery or request
+placement. Read those three answers instead of trusting a worker's completion
+report.
+
 ## Deliver
 
+Deliver when the worktree content is the candidate you intend to land:
+
 ```bash
 keiyaku deliver <contract>
 ```
 
-`deliver` tenders the clean `HEAD`, runs the declared `Verification`, records
-the candidate, and requests placement. If the workspace is dirty, the refusal
+`deliver` freshly tenders the clean `HEAD`, records the candidate, and requests
+placement. When a current audit attestation names the identical integration
+snapshot and Verification segment, deliver reuses it; otherwise it runs the
+declarations. Worktree, target, policy, document, Verification, or
+snapshot-producing option changes prevent reuse. If the workspace is dirty, the refusal
 lists staged, unstaged, and untracked paths, a short statistic, and the
 `--include-dirty` option. Use that option only when the complete current
 workspace is the intended delivery; dirty submodule internals cannot be
@@ -123,10 +196,9 @@ included. Read the receipt:
 - When a gate is not current, the receipt shows the recorded candidate and the
   placement stop. This is not a failed delivery. The Contract stays
   `pending-delivery` while you complete the gates.
-
-Verification declarations may set an individual timeout in the fence info
-string, using an explicit duration unit such as `bash timeout=5m`. Omit the
-attribute for an unbounded declaration; there is no Verification-wide timeout.
+- A lag row reports an accepted physical effect that has not finished. The
+  delivery stands; `reconcile` completes the effect later. It never changes
+  the verdict.
 
 ## Review Gates
 
@@ -137,17 +209,40 @@ keiyaku review <contract> --satisfied --summary "<conclusion>"
 keiyaku review <contract> --unsatisfied --summary "<finding>"
 ```
 
-Have an independent reviewer read the exact Contract worktree first; the
-`review` command records the gate-visible verdict. `--satisfied` requests
-placement. If the same patch is already delivered and the other gates are
-current, the receipt shows `claimed`. Review works before or after deliver.
-When the reviewed projection includes ordinary dirty workspace bytes, the
-review receipt discloses those paths and stats; delivery still needs
-`deliver --include-dirty` before those bytes become the candidate.
-
-Fixing findings changes the patch, which turns earlier evidence stale (`?` in
-`status`): review the current patch again. Record `--unsatisfied` only when the
-negative judgment should remain in Contract history.
+Have an independent reviewer inspect the delivered Contract worktree snapshot.
+The `review` command records the verdict. `--satisfied` requests placement; if
+the other gates are current, the receipt shows `claimed`.
+
+Fixing findings changes the patch and makes earlier evidence stale (`?` in
+`status`). Audit the rework, deliver it, then review again. Record
+`--unsatisfied` only when the negative judgment should remain in Contract
+history.
+
+## When Multiple Contracts Overlap On One Target
+
+When active Contracts write a shared surface, landing order is a coordinator
+judgment, not Contract state. Keep the decision in the workflow skill; do not
+persist a train or add a second placement authority.
+
+- `audit` and a reviewer's report are preliminary. `review --satisfied` is
+  authoritative gate testimony: it requests placement and claims when
+  delivery, prerequisites, and all gates are current. Record it only when the
+  reviewed bytes are intended to land now.
+- Before recording a satisfied review, or delivering a Contract with no
+  declared gates, ask whether the exact patch will survive until placement. A
+  pure rebase whose `ChangeId` is unchanged keeps the existing review current;
+  do not re-review content addressing kept alive. Conflict resolution that
+  changes the `ChangeId` makes earlier testimony stale and requires a fresh
+  review against the resolved candidate.
+- For Contracts known to overlap, resolve the current-target integration before
+  the authoritative review. Preliminary feedback may happen earlier, but it
+  is not a satisfied gate until its reviewed patch is the candidate intended
+  for placement. Land overlapping Contracts one at a time; let independent,
+  non-overlapping Contracts proceed without ceremony. Treat overlap as a
+  planning signal, not a correctness verdict.
+- After target movement, a changed candidate, or a placement refusal, read the
+  current Contract facts again. Recompute the next landing judgment from those
+  facts; do not rely on a remembered queue or promise exactly one rebase.
 
 ## Target Placement
 
@@ -168,18 +263,16 @@ Placement follows the Git mental model you already have:
 After a refusal, handle the listed paths, then `deliver` again or record a
 satisfied review; either command requests placement again.
 
-## Observe, Recover, Or End
+## Recover Or End
 
 ```bash
-keiyaku audit <contract> [--show-diff-body]   # report only; never places
 keiyaku reconcile <contract>                  # finish accepted lagging effects
 keiyaku abandon <contract> --note "<why>"     # terminal; target untouched
 ```
 
-`audit` is one aggregate read of the document, candidate diff, Verification,
-gates, and target status. `reconcile` completes physical effects of already
-accepted placements; it does not retry an ordinary placement refusal.
-`abandon` ends the Contract and never touches the target.
+`reconcile` completes physical effects of already accepted placements; it does
+not retry an ordinary placement refusal. `abandon` ends the Contract and never
+touches the target.
 
 ## Routine Output
 

package/build/src/akuma/abort.d.ts

@@ -0,0 +1,2 @@
+export declare function abortable<T>(operation: Promise<T>, signal: AbortSignal, disposeLate?: (value: T) => Promise<void> | void): Promise<T>;
+export declare function abortableDelay(milliseconds: number, signal?: AbortSignal): Promise<void>;

package/build/src/akuma/abort.js

@@ -0,0 +1,50 @@
+export function abortable(operation, signal, disposeLate) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        let aborted = false;
+        const abort = () => {
+            aborted = true;
+            if (disposeLate === undefined)
+                reject(signal.reason);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+        void operation.then(async (value) => {
+            signal.removeEventListener("abort", abort);
+            if (!aborted) {
+                resolve(value);
+                return;
+            }
+            try {
+                await disposeLate?.(value);
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            reject(signal.reason);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(aborted ? signal.reason : error);
+        });
+    });
+}
+export function abortableDelay(milliseconds, signal) {
+    if (signal === undefined)
+        return new Promise((resolve) => setTimeout(resolve, milliseconds));
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, milliseconds);
+        const abort = () => {
+            clearTimeout(timeout);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}

package/build/src/akuma/akuma.d.ts

@@ -1,4 +1,4 @@
-import { type AkumaLife, type CollarProbe, type KillEvidence, type ResumeCoordinate, type Soul } from "./heart/index.js";
+import { type AkumaLife, type KillEvidence, type ResumeCoordinate, type Soul } from "./heart/index.js";
 import { type AkuId } from "./identity.js";
 import { type ActivityHistory, type ActivitySnapshot } from "./projection.js";
 import { type Settings } from "../settings.js";
@@ -8,18 +8,19 @@ export type AkumaListRow = Readonly<{
     archetype: string;
     description?: string;
     life: AkumaLife;
-    collar: CollarProbe;
+    lifeAt: string | null;
     confinement: Soul["confinement"];
     pending: readonly string[];
 }>;
 export type AkumaStatus = Readonly<{
     id: AkuId;
     life: AkumaLife;
-    collar: CollarProbe;
+    readonly?: Soul["readonly"];
     timeline: ActivitySnapshot;
     strandedReason?: "resume-unsupported";
 }>;
-export type { ActivityHistory, ActivityRow, ActivitySnapshot, ActivitySnapshotEntry } from "./projection.js";
+export type { ReadonlyRestraint } from "./provider-recipe.js";
+export type * from "./projection.js";
 export type UnbornAkumaListRow = Readonly<{
     id: AkuId;
     life: "unborn" | "stillborn";
@@ -46,11 +47,11 @@ export type TellResult = Readonly<{
     }>;
 }>;
 export type InterruptReceipt = Readonly<{
-    kind: "unstoppable";
-    evidence: "no-collar" | "collar-unverifiable" | "unavailable" | "alive-after-sigkill" | "leash-held-after-put-down";
+    kind: "unavailable";
+    evidence: "hung" | "untidy" | "unavailable";
 }> | Readonly<{
     kind: "interrupted";
-    putDown: "was-idle" | "self-aborted" | "collar";
+    putDown: "was-idle" | "self-aborted";
     tell: TellResult;
 }>;
 export type ForkReceipt = Readonly<{
@@ -75,19 +76,27 @@ export declare class AkumaNotBornError extends Error {
     readonly kind = "akuma-not-born";
     constructor(id: AkuId);
 }
-/** Package-internal compact observation for action feedback. */
-export declare function readActionFeedbackStatus(worldPath: WorldRoot, id: AkuId): AkumaStatus;
+/** Package-internal action observation; it uses the same snapshot selector as status. */
+export declare function readActionFeedbackStatus(worldPath: WorldRoot, id: AkuId): Promise<AkumaStatus>;
+export type BudgetedStatusObservation = Readonly<{
+    status: AkumaStatus;
+    ordinarySelected: number;
+}>;
+/** Package-internal budgeted observation; Fleet allocates, Akuma still selects. */
+export declare function readBudgetedStatus(worldPath: WorldRoot, id: AkuId, input: Readonly<{
+    ordinaryBudget: number;
+}>): Promise<BudgetedStatusObservation>;
 export declare class AkumaHandle {
     readonly id: AkuId;
     private readonly worldPath;
     constructor(id: AkuId, worldPath: WorldRoot);
     private get paths();
-    status(): AkumaStatus;
+    status(): Promise<AkumaStatus>;
     history(input?: Readonly<{
         before?: number;
         since?: number;
         limit?: number;
-    }>): ActivityHistory;
+    }>): Promise<ActivityHistory>;
     wait(predicate?: (status: AkumaStatus) => boolean, options?: Readonly<{
         timeoutMs?: number;
     }>): Promise<AkumaStatus>;
@@ -97,7 +106,7 @@ export declare class AkumaHandle {
         at: string;
     }>): Promise<ForkReceipt>;
     kill(): Promise<KillEvidence>;
-    lastAnswer(): LastAnswer;
+    lastAnswer(): Promise<LastAnswer>;
 }
 export type LastAnswer = Readonly<{
     kind: "answer";
@@ -114,11 +123,11 @@ export declare class Akuma {
     of(input: Readonly<{
         id: string;
     }>): AkumaHandle;
-    listArchetypes(): readonly string[];
+    listArchetypes(): Promise<readonly string[]>;
     call(input: Readonly<{
         archetype: string;
         body: string;
         cwd?: string;
     }>): Promise<AkumaHandle>;
-    list(input?: AkumaListInput): AkumaList;
+    list(input?: AkumaListInput): Promise<AkumaList>;
 }