@astrosheep/keiyaku 4.6.6 → 4.6.8

package/skills/keiyaku-task/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: keiyaku-task
+description: >-
+  Must read when using Tasks for durable work planning, decomposition, or
+  dependencies.
+---
+
+# Keiyaku Task
+
+A Task is durable planning memory. It records work, decomposition, and
+relationships that must remain after the current conversation. Task is an
+independent product; it is not a Contract, Arc, Akuma, permission, acceptance
+boundary, or fulfillment lifecycle.
+
+## 1. When To Use A Task
+
+Use a Task when the plan or dependency must outlive the current conversation.
+Skip it when the work is small and no durable planning memory is needed.
+
+- Use a `kei` for one independently acceptable outcome.
+- Use an Arc for a chapter inside one `kei`.
+- Use a Task for decomposition or dependency memory.
+- Do not create a Task just to mirror a `kei`.
+
+A Task may exist without a Contract. Associating a Task with a `kei` does not
+transfer the Contract's holder, acceptance, or lifecycle to the Task.
+
+## 2. Relationships And Parallel Work
+
+Independent Tasks may start and progress in parallel when their dependencies
+allow it.
+
+Use the relationships for their actual meanings:
+
+- `needs` means this Task must wait for another Task to become terminal.
+- `parent` groups decomposition; it does not create a dependency.
+- `supersedes` points to work replaced by this Task.
+- `relates` records a connection without affecting readiness.
+
+Only `needs` orders work. Do not add it because Tasks touch the same Region or
+because one Task is related to another. A terminal Task releases its dependents.
+An `on_hold` Task is deliberately paused; it is neither ready nor blocked.
+
+## 3. Task Commands
+
+Create and inspect Tasks:
+
+```bash
+keiyaku task add "<title>"
+keiyaku task add "<title>" --priority 1 --needs <task-id>
+keiyaku task show <task-id>
+keiyaku task ls
+keiyaku task ready
+keiyaku task blocked
+keiyaku task tree <task-id>
+keiyaku task doctor
+```
+
+Use complete Task IDs for targeted commands. `ls`, `ready`, and `blocked` use
+the current namespace; use `--world` to inspect the complete Task world.
+
+Change lifecycle state:
+
+```bash
+keiyaku task start <task-id>...
+keiyaku task stop <task-id>
+keiyaku task hold <task-id>...
+keiyaku task resume <task-id>
+keiyaku task done <task-id>...
+keiyaku task drop <task-id>... --note "<reason>"
+```
+
+Use `done` when the Task is complete. Use `drop` when it will not be done.
+Both terminal states release dependent Tasks. Use `hold` for a deliberate pause,
+not for an unresolved dependency; unresolved `needs` appear in `blocked`.
+
+Update a Task without changing its lifecycle:
+
+```bash
+keiyaku task update <task-id> --title "<title>"
+keiyaku task update <task-id> --body "<body>"
+keiyaku task update <task-id> --needs <task-id>
+```
+
+Use `task compose -` when several Tasks and their relationships should be
+planned or admitted together. Use `--plan` to inspect the composition without
+writing it.
+
+## 4. After Creating A Task
+
+Read the returned Task identity. Then:
+
+1. Start ready work.
+2. Run independent Tasks in parallel.
+3. Add or remove relationships when the plan changes.
+4. Hold work that is deliberately paused.
+5. Mark completed work `done`, or mark abandoned work `drop` with a reason.
+6. Use `ready`, `blocked`, `tree`, or `doctor` to rebuild the current view.
+
+Task records planning memory. It does not perform the work, claim acceptance,
+assign a holder, or decide what a Contract may accept.
+
+Read `keiyaku-bind` for Contract authoring and `keiyaku-workflow` for Contract
+lifecycle.

package/skills/keiyaku-workflow/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: keiyaku-workflow
+description: >-
+  Must read before binding a `kei` (Contract) or when acting as its holder.
+  Use when deciding when to bind a kei, how to shape and hold it, how to
+  delegate its work, and how to accept, amend, or end it.
+---
+
+# Keiyaku Workflow
+
+The holder runs one Contract's fulfillment loop from preparation to completion.
+
+## 1. Prepare Before Binding
+
+Before `bind`, settle the information that makes the `kei` truthful:
+
+- objective and intended outcome;
+- design and approach;
+- affected Region;
+- acceptance conditions;
+- verification and required evidence;
+- prerequisites;
+- holder.
+
+If the design, approach, or acceptance conditions are still open, do not bind.
+Resolve them with their owner first. Private implementation details may remain
+for the Deliverer; the public meaning and acceptance boundary may not.
+
+Bind independent `kei`s in parallel. Do not split one acceptance boundary just
+to create parallel work.
+
+## 2. Split the Work
+
+- Separate `kei`s have independently acceptable outcomes.
+- An Arc is a chapter of one `kei`; it is not separately accepted.
+- A Task stores decomposition or dependencies that outlive this conversation.
+
+Use `after` only when one `kei` requires another to be accepted first. Ordinary
+overlap is not a dependency.
+
+## 3. Roles
+
+A `kei` has three roles. They are responsibilities, not people, and one agent
+may fill more than one of them, with one exception below.
+
+- **Holder:** exactly one per `kei`. Owns the fulfillment loop and acceptance
+  until the Contract is accepted or abandoned. Handing work to others never
+  transfers this responsibility.
+- **Deliverer:** produces the candidate in the appointed worktree and tenders
+  it with `deliver`.
+- **Reviewer:** judges the complete Contract against its acceptance conditions
+  and records the verdict with `review`.
+
+Review is independent when the Reviewer did not deliver the candidate under
+review. That is the whole requirement. The holder may review its own `kei`; a
+fresh Akuma is not what makes review independent. Keiyaku does not check who
+reviews, so keeping the Reviewer apart from the Deliverer is the holder's duty.
+
+Any role may be filled directly or handed to an Akuma. Hand one over when other
+hands help the work, not to make review count.
+
+## 4. Lifecycle
+
+Each act changes a different part of the world:
+
+- **Bind:** Journal gains the Contract and its terms. Workspace appointment
+  names one managed worktree; the receipt reports its path. Appointment lag
+  leaves the bind admitted without a path and reports pending reconciliation.
+  `reconcile` retries workspace realization.
+- **Work:** Changes and commits belong in the appointed worktree. Another
+  lane's claim can move the target beneath it. Check target movement before
+  audit; when it matters, merge the target branch (main when selected) in the
+  worktree and resolve conflicts there before auditing.
+- **Audit:** Previews the candidate and target without tendering or claiming.
+  With `verified` selected, Verification runs for the captured subject and can
+  record an attestation. Without that gate, the section is inert text and no
+  verb runs Verification. A stopped run records no new verdict.
+- **Deliver:** Captures a tender and integration against the observed target;
+  journal gains a delivered candidate. Ready prerequisites and gates trigger
+  placement and claim in this invocation; otherwise the candidate waits.
+  Changed candidate content stales earlier review. Identical content retains
+  review across rebase or target movement.
+- **Review:** Records verdict evidence for the current document and worktree
+  content, even before delivery. Satisfied review requests placement: with a
+  delivered candidate, current gates, and ready prerequisites, it accepts in
+  this invocation. Unsatisfied review records testimony without placement.
+- **Abandon:** Records the alternate terminal outcome without accepting. Accepted
+  and abandoned Contracts cannot be reopened.
+
+Placement judges declared gates, not the producer's identity. Review does not
+replace Verification; audit never requests placement. Read the final receipt
+for stops and reconciliation lag after an admitted act.
+
+## 5. Handing A Role To An Akuma
+
+This is the one commissioning map. `call --help` owns the exact action
+vocabulary and default set. The flagship acting directly needs no grant.
+Birth freezes an Akuma's actions; `--contract` records association, not
+authority.
+
+| Role | Grant at birth | Return |
+| --- | --- | --- |
+| Holder | The actions the delegated loop will perform; include `contract.review` when this holder will review. Commission with the `kei`, current Arc when one exists, appointed worktree, and holder duties. | Acceptance or abandonment, with receipts. |
+| Deliverer | The ordinary baseline: every Task mutation, Contract audit and delivery, and Akuma management. `keiyaku -C <repo> call worker --alias @deliverer --contract <kei/...> --workdir <appointed-path> -` | The delivery receipt. |
+| Reviewer | `--allowed contract.review`: `keiyaku -C <repo> call review-akuma --alias @reviewer --contract <kei/...> --workdir <appointed-path> --allowed contract.review -` | The verdict receipt. Without the grant, `not-allowed` refuses and no verdict is recorded. |
+
+An Archetype's explicit allowed set replaces the ordinary baseline; check
+`status` for effective actions. `tell` and `fork` cannot add a grant to a live
+Akuma, so call a fresh one with the grant. Nested calls cannot exceed their
+direct parent's actions.
+
+Commission with a clear objective, current Arc when one exists, appointed
+worktree, and expected result. Never ask the Akuma that delivered a candidate
+to review it. Use `keiyaku-akuma` for invocation and observation, and command
+help for exact syntax.
+
+## 6. Decide What Happens Next
+
+The holder checks candidate, verification, review, prerequisites, and gates.
+
+- A ready delivered candidate claims automatically on delivery or satisfied
+  review; no separate claim command is needed.
+- Missing evidence or unfinished work calls for another commission or chapter.
+- Amend when the objective and acceptance boundary remain the same but terms
+  must change.
+- Abandon and bind a new `kei` when the objective or acceptance boundary changes.
+
+Read `keiyaku-bind` for authoring, `keiyaku-akuma` for delegation, and
+`keiyaku-babysit` for supervising multiple lanes.

package/build/integrations/marketplace/.claude-plugin/marketplace.json

@@ -1,5 +0,0 @@
-{
-  "name": "keiyaku",
-  "owner": { "name": "Keiyaku" },
-  "plugins": [{ "name": "keiyaku", "source": "./plugins/keiyaku" }]
-}

package/build/integrations/marketplace/plugins/keiyaku/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "keiyaku-harness",
-  "version": "4.5.28",
-  "type": "module",
-  "main": "./opencode.js",
-  "keywords": [
-    "pi-package"
-  ],
-  "pi": {
-    "extensions": [
-      "../../../pi/keiyaku.ts"
-    ],
-    "skills": [
-      "./skills"
-    ]
-  }
-}

package/build/src/cli/commands/amend.d.ts

@@ -1,12 +0,0 @@
-import { type ActorId, type Keiyaku, type Repo } from "../../index.js";
-import type { ParsedAmend } from "./contract-grammar.js";
-type AmendCommandInput = Readonly<{
-    command: ParsedAmend;
-    repo: Repo;
-    contract: Keiyaku;
-    markdown?: string;
-    gates?: readonly string[];
-    actor?: ActorId;
-}>;
-export declare function amendFromCommand({ command, repo, contract, markdown, gates, actor, }: AmendCommandInput): ReturnType<Keiyaku["amend"]>;
-export {};

package/build/src/cli/commands/amend.js

@@ -1,10 +0,0 @@
-import { contractFromInput } from "../selectors.js";
-export function amendFromCommand({ command, repo, contract, markdown, gates, actor, }) {
-    const after = command.clearAfter === true ? [] : command.after?.map((id) => contractFromInput(repo, id).id);
-    return contract.amend({
-        ...(markdown === undefined ? {} : { markdown }),
-        ...(actor === undefined ? {} : { actor }),
-        ...(after === undefined ? {} : { after }),
-        ...(gates === undefined ? {} : { gates }),
-    });
-}

package/build/src/cli/commands/bind.d.ts

@@ -1,11 +0,0 @@
-import { type ActorId, type BindResult, type KeiyakuLibrary, type Repo } from "../../index.js";
-import type { ParsedBind } from "./contract-grammar.js";
-type BindCommandInput = Readonly<{
-    command: ParsedBind;
-    repo: Repo;
-    library: KeiyakuLibrary;
-    markdown?: string;
-    actor?: ActorId;
-}>;
-export declare function bindFromCommand({ command, repo, library, markdown, actor, }: BindCommandInput): Promise<BindResult>;
-export {};

package/build/src/cli/commands/bind.js

@@ -1,23 +0,0 @@
-import { contractFromInput } from "../selectors.js";
-export async function bindFromCommand({ command, repo, library, markdown, actor, }) {
-    if (command.forkOf !== undefined) {
-        return library.bind({
-            repo,
-            forkOf: contractFromInput(repo, command.forkOf).id,
-            ...(command.target === undefined ? {} : { target: command.target }),
-            ...(actor === undefined ? {} : { actor }),
-        });
-    }
-    const after = command.after?.map((id) => contractFromInput(repo, id).id);
-    if (markdown === undefined)
-        throw new Error("Markdown bind command is missing stdin terms");
-    return library.bind({
-        repo,
-        markdown,
-        ...(command.task === undefined ? {} : { task: command.task }),
-        ...(command.target === undefined ? {} : { target: command.target }),
-        ...(actor === undefined ? {} : { actor }),
-        ...(after === undefined ? {} : { after }),
-        ...(command.gates === undefined ? {} : { gates: command.gates }),
-    });
-}

package/build/src/dispatch/association.d.ts

@@ -1 +0,0 @@
-export { dispatchAssociationSchema, NO_DISPATCH_ASSOCIATION, parseDispatchAssociation, type DispatchAssociation, } from "../akuma/dispatch-association.js";

package/build/src/dispatch/association.js

@@ -1 +0,0 @@
-export { dispatchAssociationSchema, NO_DISPATCH_ASSOCIATION, parseDispatchAssociation, } from "../akuma/dispatch-association.js";