@astrosheep/keiyaku 4.0.0 → 4.0.2

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

@@ -1,72 +1,288 @@
 ---
 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 is one delivery authority. Its document is ordinary input until
-`bind` admits it; the bound Contract owns its coordinates, terms, prerequisite
-snapshot, candidate, reviews, gates, and terminal decision. Task planning and
-Akuma execution remain separate products.
+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.
 
-## Lifecycle
+## How The Delivery Moves
 
 ```text
-bind -> waiting | bound -> pending delivery -> claimed
-                                      \-> abandoned
+contract document -> bind -> work -> audit -> deliver -> review gates
+                                                    -> placement -> claimed
+                                                                \-> abandoned
 ```
 
-`claimed` and `abandoned` are terminal. A prerequisite `after` list is ordered
-and immutable after `bound`; `amend` can replace terms and change prerequisites
-only before they are consumed. `deliver` tenders current worktree bytes.
-`review --satisfied` records testimony and requests placement; placement claims
-only when every declared gate is current. `review --unsatisfied` records
-judgment without claiming. `audit` observes and never places.
+The lifecycle is `waiting -> bound -> pending-delivery -> claimed | abandoned`;
+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
 
-Write one canonical Contract document to stdin and bind it:
+Use `keiyaku-bind` to decide readiness, author one bounded Contract, choose
+bind inputs, and read the receipt. Continue here from that receipt.
+
+## Work In The Contract Worktree
+
+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`.
+
+## Regain The Picture
+
+Rebuild state from reads, not memory — after a compact, a handoff, or any
+surprising receipt, read before acting:
+
+```bash
+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` 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
+
+When another agent will fulfill or review the Contract, the commissioning
+harness must pass one explicit seat and one exact worktree. `--contract` or an
+equivalent association identifies the Contract; it does not appoint a seat.
+Never ask the worker to infer either value.
+
+Use this minimum handoff in the dispatch body, regardless of harness:
+
+```text
+Contract: kei/...
+Seat: Deliverer | Reviewer
+Worktree: /absolute/path/from-the-bind-receipt
+Read first:
+- .keiyaku/KEIYAKU.md
+- <owner documents governing this delivery>
+- <source files named or selected from the Contract Region for this work>
+Objective:
+<bounded assignment>
+```
+
+Every `Read first` path is relative to `Worktree` unless it is absolute. The
+worker starts by reading `.keiyaku/KEIYAKU.md` in that worktree, confirms its
+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 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 bind -
-keiyaku bind --target <ref> -
-keiyaku bind --here -
-keiyaku bind --after <kei/...> --gates <name> -
+keiyaku wait kei/<contract> --all --timeout 5m
+keiyaku wait kei/<first> kei/<second> --any --timeout 5m
 ```
 
-The document owns the delivery objective, design, scope, criteria, and optional
-verification declaration. Use the exact `bind --help` grammar; do not invent
-identity or timestamps. A successful receipt is the source of the complete
-Contract coordinate and any managed worktree facts.
+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
+
+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.
 
-## Work And Acceptance
+When a complex Keiyaku cannot be split without breaking one acceptance
+boundary, organize its fulfillment into arcs. Do not hand the whole
+undifferentiated Contract to one Deliverer and trust one pass to finish it.
+Record and work one current chapter at a time.
+
+An arc is a chapter as in a work of literature: one named part of the
+delivery's story, not a task list, progress slice, or claim that the work is
+mechanically sequential. Its title names the chapter, Objective states that
+chapter's aim, and Brief commissions work for that 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 status [<contract>|@<contract>]
-keiyaku amend [<contract>|@<contract>] -
-keiyaku arc [<contract>|@<contract>] -
-keiyaku deliver [<contract>|@<contract>]
-keiyaku review [<contract>|@<contract>] --satisfied
-keiyaku review [<contract>|@<contract>] --unsatisfied
-keiyaku audit [<contract>|@<contract>] [--show-diff-body]
-keiyaku reconcile [<contract>|@<contract>]
+keiyaku arc <contract> - <<'KEIYAKU'
+# <chapter title>
+
+## Objective
+<nonblank objective>
+
+## Brief
+<nonblank dispatch brief>
+KEIYAKU
 ```
 
-Use complete `kei/...` IDs or `@...` managed-worktree references. Omitted
-selectors are contextual only when the CLI reports exactly one active
-worktree contract. `amend` reads amendment operations, `arc` reads arc
-Markdown, and both require their final `-`; `deliver`, `review`, `audit`, and
-`reconcile` do not read an unselected stdin body. `review --summary <text>` is
-opaque testimony and is mutually exclusive with review stdin.
+All chapters live inside that Contract's single delivery and acceptance
+boundary. The document grammar authority is `docs/document.md`.
+
+## Amend Or Start Over
+
+Use `amend` when a discovery during the same delivery changes terms but the
+original Objective, Design, and acceptance boundary still truthfully describe
+the result:
+
+```bash
+keiyaku amend <contract> -
+```
+
+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` 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
+included. Read the receipt:
+
+- When every gate is current, the receipt shows placement and `claimed`; the
+  delivery is done.
+- 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.
+- 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
+
+A `reviewed` gate wants a recorded judgment of the current patch:
+
+```bash
+keiyaku review <contract> --satisfied --summary "<conclusion>"
+keiyaku review <contract> --unsatisfied --summary "<finding>"
+```
+
+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
+
+Placement follows the Git mental model you already have:
+
+- Delivering from a managed worktree to a checked-out target behaves like a
+  merge. Non-overlapping staged, unstaged, and untracked files in that checkout
+  are preserved. A staged path refuses only when Git cannot carry it through
+  the predecessor-to-candidate merge; overlapping worktree changes and
+  colliding untracked files also refuse. The receipt lists the exact paths.
+  The deliver or review you just ran still counts: the recorded candidate and
+  any `✓ reviewed` verdict are kept, but nothing claims and nothing moves.
+  The target ref, its checkout, and your bytes stay exactly where they were,
+  and the Contract stays `pending-delivery`.
+- A `--here` Contract behaves like a commit with gates: it lands on the current
+  branch and cannot deliver to a foreign checked-out target.
+
+After a refusal, handle the listed paths, then `deliver` again or record a
+satisfied review; either command requests placement again.
+
+## Recover Or End
+
+```bash
+keiyaku reconcile <contract>                  # finish accepted lagging effects
+keiyaku abandon <contract> --note "<why>"     # terminal; target untouched
+```
 
-## Terminal Choice
+`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.
 
-`abandon [<contract>|@<contract>] [--note <text>]` writes the terminal
-abandoned fact and does not touch a target ref. There is no `petition`, `claim`,
-`forfeit`, `renew`, or `bind --task` command in v4. A successful placement
-produces the claimed terminal state; inspect the typed result and decide what
-to do next.
+## Routine Output
 
-Use default text output for routine observation. Add `--json` when a script
-needs the public result without renderer-specific text.
+Use default text output for normal operation and `--json` only when a script
+needs the public result. Use the complete `kei/...` ID, or `@...` inside a
+managed worktree. When a flag or stdin form is unclear, read that command's
+`--help` instead of guessing.

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,24 +1,26 @@
-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 "./activity.js";
+import { type ActivityHistory, type ActivitySnapshot } from "./projection.js";
 import { type Settings } from "../settings.js";
+import type { WorldRoot } from "../world.js";
 export type AkumaListRow = Readonly<{
     id: AkuId;
     archetype: string;
     description?: string;
     life: AkumaLife;
-    collar: CollarProbe;
+    lifeAt: string | null;
     confinement: Soul["confinement"];
     pending: readonly string[];
 }>;
-export type AkumaStatus = AkumaListRow & Readonly<{
-    answer?: string;
-    answerHistoryId?: string;
-    failure?: string;
-    outcomeAt?: string;
-    activity: ActivitySnapshot;
+export type AkumaStatus = Readonly<{
+    id: AkuId;
+    life: AkumaLife;
+    readonly?: Soul["readonly"];
+    timeline: ActivitySnapshot;
+    strandedReason?: "resume-unsupported";
 }>;
-export type { ActivityHistory, ActivityRow, ActivitySnapshot } from "./activity.js";
+export type { ReadonlyRestraint } from "./provider-recipe.js";
+export type * from "./projection.js";
 export type UnbornAkumaListRow = Readonly<{
     id: AkuId;
     life: "unborn" | "stillborn";
@@ -31,25 +33,26 @@ export type AkumaList = Readonly<{
     rows: readonly (AkumaListRow | UnbornAkumaListRow)[];
     searched: readonly string[];
 }>;
-export type TellReceipt = Readonly<{
-    id: string;
-    state: "recorded";
+export type AkumaListInput = Readonly<{
+    archetype?: string;
+}>;
+export type TellResult = Readonly<{
+    admission: Readonly<{
+        tellId: string;
+        fact: "recorded";
+    }>;
     wake: "spawned" | Readonly<{
         kind: "failed";
         diagnostic: string;
     }>;
 }>;
 export type InterruptReceipt = Readonly<{
-    kind: "dead";
-}> | 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";
-    tell: TellReceipt | Readonly<{
-        kind: "refused-dead";
-    }>;
+    putDown: "was-idle" | "self-aborted";
+    tell: TellResult;
 }>;
 export type ForkReceipt = Readonly<{
     kind: "forked";
@@ -73,44 +76,58 @@ export declare class AkumaNotBornError extends Error {
     readonly kind = "akuma-not-born";
     constructor(id: AkuId);
 }
+/** 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: string);
+    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>;
-    tell(body: string): Promise<TellReceipt>;
+    tell(body: string): Promise<TellResult>;
     interrupt(body: string): Promise<InterruptReceipt>;
     fork(input: Readonly<{
         at: string;
     }>): Promise<ForkReceipt>;
     kill(): Promise<KillEvidence>;
-    lastAnswer(): string;
+    lastAnswer(): Promise<LastAnswer>;
 }
+export type LastAnswer = Readonly<{
+    kind: "answer";
+    answer: string;
+}> | Readonly<{
+    kind: "no-answer";
+}>;
 export declare class Akuma {
     private readonly path;
-    private readonly settings;
+    private readonly configuredSettings?;
     private constructor();
-    static at(input: Readonly<{
-        path: string;
-        settings?: Settings;
-    }>): Akuma;
+    static of(root: WorldRoot, settings?: Settings): Akuma;
+    private settings;
     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(): AkumaList;
+    list(input?: AkumaListInput): Promise<AkumaList>;
 }