@astrosheep/keiyaku 4.6.7 → 4.6.9

package/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 Debt for confirmed unresolved work and dependencies that must outlive
+  the current conversation.
+
+A `kei` owns one independently acceptable outcome and its delivery lifecycle. A
+Debt records confirmed unresolved work; it may exist without a `kei`,
+and it does not create a second acceptance or lifecycle. Associate a `kei` with
+an existing Debt only when the delivery actually settles that unresolved work.
+Do not create a Debt 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 Debts 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 Debt that this delivery settles:
+
+```bash
+keiyaku -C <repo> bind --debt <debt/...> - < 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 Debts, 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/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/skills/keiyaku-debt/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: keiyaku-debt
+description: >-
+  Must read when recording confirmed unresolved work or dependencies in Debts.
+---
+
+# Keiyaku Debt
+
+A Debt records confirmed unresolved work and its relationships. Debt is an
+independent product; it is not a Contract, Arc, Akuma, permission, acceptance
+boundary, or fulfillment lifecycle.
+
+## 1. When To Use A Debt
+
+Use a Debt when confirmed unresolved work or a dependency must outlive the
+current conversation. Keep plans and execution progress in reasoning or session
+notes instead.
+
+- Use a `kei` for one independently acceptable outcome.
+- Use an Arc for a chapter inside one `kei`.
+- Use a Debt for confirmed unresolved work and its prerequisites.
+- Do not create a Debt just to mirror a `kei`.
+
+A Debt may exist without a Contract. Associating a Debt with a `kei` does not
+transfer the Contract's holder, acceptance, or lifecycle to the Debt.
+
+## 2. Relationships And Parallel Work
+
+Independent work may proceed in parallel when its dependencies allow it.
+Debt records no execution-progress state.
+
+Use the relationships for their actual meanings:
+
+- `needs` means this Debt must wait for another Debt to become terminal.
+- `parent` groups decomposition; it does not create a dependency.
+- `supersedes` points to work replaced by this Debt.
+- `relates` records a connection without affecting readiness.
+
+Only `needs` orders work. Do not add it because Debts touch the same Region or
+because one Debt is related to another. A terminal Debt releases its dependents.
+
+## 3. Debt Commands
+
+Create and inspect Debts:
+
+```bash
+keiyaku debt add "<title>"
+keiyaku debt add "<title>" --priority 1 --needs <debt-id>
+keiyaku debt show <debt-id>
+keiyaku debt ls
+keiyaku debt ready
+keiyaku debt blocked
+keiyaku debt tree <debt-id>
+keiyaku debt doctor
+```
+
+Use complete Debt IDs for targeted commands. `ls`, `ready`, and `blocked` use
+the current namespace; use `--world` to inspect the complete Debt world.
+
+Close work:
+
+```bash
+keiyaku debt done <debt-id>...
+keiyaku debt drop <debt-id>... --note "<reason>"
+```
+
+Use `done` when the Debt is complete. Use `drop` when it is no longer owed.
+Both terminal states release dependent Debts. Unresolved `needs` appear in
+`blocked`; open work with all prerequisites terminal appears in `ready`.
+
+Update a Debt without changing its lifecycle:
+
+```bash
+keiyaku debt update <debt-id> --title "<title>"
+keiyaku debt update <debt-id> --body "<body>"
+keiyaku debt update <debt-id> --needs <debt-id>
+```
+
+## 4. After Creating A Debt
+
+Read the returned Debt identity. Then:
+
+1. Add or remove relationships when the confirmed prerequisites change.
+2. Mark completed work `done`, or work no longer owed `drop` with a reason.
+3. Use `ready`, `blocked`, `tree`, or `doctor` to inspect the current ledger.
+
+Debt records unresolved work. 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 Debt records confirmed unresolved work and its dependencies.
+
+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 Debt 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/claude/skills/keiyaku-task/SKILL.md

@@ -1,104 +0,0 @@
----
-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-task/SKILL.md

@@ -1,104 +0,0 @@
----
-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.