@astrosheep/keiyaku 4.6.4 → 4.6.7

package/build/plugins/codex/skills/keiyaku-babysit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: keiyaku-babysit
+description: >-
+  Entering babysit mode: supervising parallel work across multiple Akuma and
+  Contracts as they advance, instead of doing the work yourself.
+---
+
+# Keiyaku Babysit
+
+Babysitting is a method, not a role: no new identity, permission, ledger,
+status, id, or lifecycle. It is how whoever holds work in flight schedules
+their own attention across it.
+
+## Lanes At Any Grain
+
+A lane is anything you are answerable for that moves without you: a Worker on
+an Arc, a Reviewer mid-examination, a whole Contract whose fulfillment loop you
+handed to one Aku. Handing work down narrows a lane; it never empties it — you
+did not hand off your answerability, you booked yourself for the next question,
+the next verify, the next return. When a Contract's whole loop is delegated,
+your lane is the holder itself: watch the journaled record — bind, amends,
+testimony, placement — verify at the boundaries you kept, and steer through the
+holder, never past it. One delegated loop is one lane, however much moves
+inside it.
+
+## Attention
+
+**Sweep.** Pass over every lane at natural pause points instead of dwelling on
+one; depth goes where the sweep finds movement or silence that should not be
+there.
+
+**Critical path.** The lane the most other lanes wait on gets attention first,
+regardless of which lane is loudest.
+
+**Wait graph.** Know who waits on whom before deciding where to look; a cycle
+in that graph is the emergency, everything else is schedule.
+
+**Blocked lanes.** A blocked lane outranks every healthy one — unblock before
+you optimize.
+
+**Verify returns.** A return is not done because it arrived; it is done when
+checked against what was asked. Book the verify when you delegate, not after.
+
+**Steer early.** The cheapest steer is before divergence compounds: ask the
+question at the first doubt, not at delivery.
+
+**Lightest lane.** Keep each lane as light as it can be; do not babysit what
+does not move without you.
+
+## Failure Shapes
+
+| Observed shape | First response |
+| --- | --- |
+| Silent wedge: initial answer empty and worktree clean | Inspect status and history, then send one steering `tell`. If the worker remains unresponsive, `kill` and call a new Akuma; an empty answer alone is not proof the Contract failed. |
+| Verdict record refused with `not-allowed` | Read the worker's analysis in history. Record the verdict yourself if you did not deliver the candidate, or call a new Reviewer with the grant from `keiyaku-workflow` and have it inspect current work and record a fresh verdict. The refused request wrote no Contract testimony. |
+| Review stale after changed candidate tender | Normal content-currentness result. Give the same Reviewer the changed diff and current terms with `tell`; have it re-examine and record current testimony. A target move alone does not stale review. |
+| Target moved under the appointed worktree | Have the Deliverer inspect target movement and merge the target branch (main when selected) in that worktree when required; resolve conflicts there, then audit again. Do not resolve against a stale integration preview. |
+| Typed refusal names its rule | Fix the named input or physical condition, then retry from a fresh observation. Do not repeat the same request blindly. |
+
+## What Babysitting Never Owns
+
+Commands and semantics belong to task, bind, workflow, and akuma. Acceptance
+belongs to the Contract's journal and its Reviewer's testimony. The question
+belongs to whoever commissioned it. Babysitting decides only when you look and
+what you check next.

package/build/plugins/codex/skills/keiyaku-bind/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: keiyaku-bind
+description: >-
+  Must read before binding a `kei` (Contract). Use when deciding what belongs
+  in one `kei`, how to divide its work, and how to write or run `bind`.
+---
+
+# Before Binding A Keiyaku
+
+Bind records a Contract whose objective, design, and acceptance boundary are
+settled. Do not use it to leave an open design for someone else to decide.
+
+## 1. What Must Be Clear Before Binding
+
+Settle these facts first:
+
+- objective and intended outcome;
+- architecture and module boundaries;
+- detailed design and implementation approach;
+- public interfaces, behavior, data, and persistence;
+- ordering, concurrency, dependencies, and failure behavior;
+- acceptance conditions;
+- verification and required evidence;
+- the affected Region;
+- the one holder responsible for the `kei`.
+
+The Design section is a detailed design document. It may contain subsections
+such as:
+
+- Architecture: components, module boundaries, ownership, and connections;
+- Interfaces And Behavior: public surfaces, inputs, outputs, success, and
+  refusal behavior;
+- Data And Persistence: data shape, identity, lifecycle facts, and persistence;
+- Approach And Flow: implementation approach, dependencies, ordering,
+  concurrency, and failure handling;
+- Pseudocode: algorithms and control flow.
+
+Record every design decision the implementation must follow. Add other Design
+subsections when needed. Do not bind while the architecture, design, approach,
+or acceptance conditions are open.
+
+### Contract Shape: Mandatory Acceptance Boundary Check
+
+Before every bind, identify the independently acceptable outcomes. For each
+proposed part, ask whether it can be reviewed and accepted while another part
+remains unfinished. If it can, you MUST bind it as a separate `kei`. Do not bind
+an aggregate Contract containing independently acceptable outcomes.
+
+A shared request, audit, theme, product name, worker, verification command, or
+overlapping Region does NOT justify combining acceptance boundaries. Worker
+assignment and Contract boundaries are separate decisions: one worker may
+serve several Contracts, and several workers may contribute to one outcome.
+A request to "open a kei" does not by itself instruct you to combine outcomes.
+
+Keep parts together only when they jointly establish one outcome that cannot
+be meaningfully accepted in parts. State that inseparability in Context and
+make Criteria judge the same outcome. Do not manufacture inseparability by
+writing one broad Objective around unrelated fixes.
+
+- Use an Arc only for a chapter inside that one acceptance boundary; an Arc is
+  not separately accepted and MUST NOT substitute for an independent `kei`.
+- Use a Task for decomposition or dependency memory that must outlive the
+  current conversation.
+
+A `kei` owns one independently acceptable outcome and its delivery lifecycle. A
+Task records decomposition or dependency memory; it may exist without a `kei`,
+and it does not create a second acceptance or lifecycle. Associate a `kei` with
+an existing Task only when that Task has real scheduling or dependency value.
+Do not create a Task just to mirror a `kei`.
+
+### Parallel Work
+
+Parallel work is the default.
+
+- Bind and advance independent `kei`s in parallel. Each has its own acceptance
+  boundary and holder.
+- Within one `kei`, run independent Tasks or Arc chapters in parallel whenever
+  their work can proceed independently. They converge on the one acceptance
+  boundary, which the holder owns.
+
+Region overlap is planning information. It does not prevent parallel work and
+is not a lock, ownership claim, exact diff, or dependency. Use `--after` only
+when one result must exist before another can proceed because of a real logical
+dependency. Do not add `--after` merely because work touches the same Region.
+
+## 2. Bind Syntax
+
+Read the command's help for the complete option grammar:
+
+```bash
+keiyaku -C <repo> bind --help
+```
+
+Inspect declared Regions when planning parallel work:
+
+```bash
+keiyaku -C <repo> region
+keiyaku -C <repo> region <kei/...>
+keiyaku -C <repo> region --path 'src/**' --path 'tests/**'
+```
+
+These list active Regions, read one Contract's Region, or show active Regions
+overlapping the supplied patterns. Overlap is coordination information only.
+
+Bind from stdin with a heredoc or a saved Markdown file:
+
+~~~~bash
+keiyaku -C <repo> bind - <<'KEIYAKU'
+# <Delivery name>
+
+## Context
+<Motivation, authority, baseline, and boundaries.>
+
+## Objective
+<One observable, independently acceptable outcome.>
+
+## Design
+### Architecture
+<Components, module boundaries, ownership, and connections.>
+
+### Interfaces And Behavior
+<Public surfaces, inputs, outputs, success, and refusal behavior.>
+
+### Data And Persistence
+<Data shape, identity, lifecycle facts, and persistence decisions.>
+
+### Approach And Flow
+<Implementation approach, dependencies, ordering, concurrency, and failure.>
+
+### Pseudocode
+<Algorithms and control flow.>
+
+## Region
+<One repository-relative write pattern per nonblank line.>
+
+## Criteria
+### <observable acceptance condition>
+<How to observe pass or refusal.>
+
+## Verification
+```bash timeout=5m
+<commands runnable exactly as written>
+```
+KEIYAKU
+~~~~
+
+Use the narrowest justified Region patterns for likely writes. A trailing `/`
+is directory shorthand for `/**`. Patterns may be fenced lines, list items, or
+bare lines; those forms are combined. Region patterns are planning evidence,
+not a prediction of the exact diff.
+
+Verification is optional. Each declaration is a closed bash, zsh, or pwsh
+fence containing commands runnable as written. Use separate fences when checks
+need different timeouts or results. Use an explicit timeout for bounded
+commands; `5m` is the normal baseline.
+
+Verification runs only when the Contract selects the `verified` gate, against
+the exact integration snapshot in a clean disposable worktree for that attempt.
+`deliver` reuses current satisfied evidence or runs the declarations; unsatisfied
+results and runtime stops prevent placement. `audit` runs declarations for a
+prospective candidate. Without `verified`, no verb runs Verification and the
+section is inert document text. `reviewed` independently requires review
+evidence. Selected gates are checked at placement.
+
+For an existing Task with real scheduling or dependency value:
+
+```bash
+keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
+```
+
+For a real logical dependency between Contracts:
+
+```bash
+keiyaku -C <repo> bind --after <kei/...> - < CONTRACT.md
+```
+
+Gate selection is part of binding:
+
+```bash
+keiyaku -C <repo> bind --gates <name,...> - < CONTRACT.md
+keiyaku -C <repo> bind --gates "" - < CONTRACT.md
+keiyaku -C <repo> bind --gates reviewed - < CONTRACT.md
+```
+
+Omitting `--gates` uses `gates.default`, or `reviewed` when no default group
+exists. `--gates ""` selects no gates. Gates are named acceptance obligations,
+not work assignments. Named gate groups and worktree hooks live in Settings;
+see the README Configuration section or `keiyaku settings --help`.
+
+## 3. After Binding
+
+Binding appoints one managed worktree for the `kei`. Read the receipt as the
+handoff. Keep the complete `kei/...` identity and note:
+
+- the holder;
+- the appointed worktree path (absent when appointment lagged);
+- the target;
+- gates and prerequisites;
+- whether the `kei` is ready or waiting.
+
+Work in the appointed worktree. When appointment lags, the receipt carries no
+path and the `kei` shows pending reconciliation instead. If the receipt is
+waiting, the stated prerequisites remain; do not bind a duplicate Contract.
+
+The holder now owns the lifecycle:
+
+1. Start the work directly or delegate Tasks, Arc chapters, Akumas, or Contract roles.
+2. Run independent work in parallel and let it converge on the one acceptance
+   boundary.
+3. Prepare and deliver the candidate.
+4. Coordinate verification, review evidence, gates, and prerequisites.
+5. Continue until the `kei` is accepted, amend terms while keeping the same
+   objective and acceptance boundary, or abandon it when either has changed.
+
+Continue with `keiyaku-workflow` for this lifecycle. For Akuma invocation,
+telling, waiting, permissions, and history, read `keiyaku-akuma`.

package/build/plugins/codex/skills/keiyaku-bind/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Keiyaku Bind"
+  short_description: "Author and bind a delivery Contract."
+  default_prompt: "Use $keiyaku-bind to author and bind this delivery."

package/build/plugins/codex/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/build/plugins/codex/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/plugins/opencode/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "keiyaku-harness",
+  "version": "4.6.7",
+  "type": "module",
+  "main": "./index.js"
+}

package/build/plugins/opencode/skills/keiyaku/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: keiyaku
+description: >-
+  Keiyaku is a CLI that records plans, writes handoff terms for deliveries,
+  and calls delegates. Use this skill when you need to figure out which
+  Keiyaku skill or command to reach for.
+---
+
+# Keiyaku
+
+## Model
+
+Keiyaku is three independent pillars, not a bundle: **Task** remembers plans
+and dependencies, **Contract** makes acceptance standing and auditable,
+**Akuma** invokes capability. Use any one alone; combine them only when the
+work calls for it. Behind every Contract in flight there is one holder of its
+fulfillment loop — whoever turns intent into commissions and returns into
+decisions. The flagship holds it by default, and may hand a whole Contract's
+loop to one Aku in a single commission; the harness serves both styles
+equally. See `keiyaku-workflow` for the loop, `keiyaku-bind` for authoring,
+`keiyaku-akuma` for invocation.
+
+## Quick Start
+
+```bash
+keiyaku -C <repo> task add "title"
+keiyaku -C <repo> task start <task-id>
+keiyaku -C <repo> bind [--task <task-id>] -
+keiyaku -C <repo> status
+keiyaku -C <repo> deliver [<contract>|@<contract>]
+keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
+```
+
+`-C` selects the invocation cwd and therefore the World. `--repo <path>` only
+selects the Contract repository; it never retargets that World. `call
+--workdir <path>` selects execution cwd (relative to the effective invocation
+cwd). Without it, the call uses the invocation cwd; `--contract` associates a
+Contract without selecting an execution directory.
+
+`deliver`, `review`, and `audit` may take time after their leading admission.
+Their witnessed progress is ephemeral stderr output; stdout remains one final
+text or JSON result. Ctrl-C asks the owned operation to stop and waits for its
+truthful final receipt, so it is not evidence that an already admitted action
+was rolled back.