@astrosheep/keiyaku 2.9.13 → 4.0.1

package/README.md

@@ -1,136 +1,9 @@
 # Keiyaku
 
-契約 — a contract.
+Keiyaku is an agent-facing contract workflow.
 
-Keiyaku is an AI-first CLI: its user is a coding agent. Not a human writing
-specs for an agent to implement — an agent delegating to other agents,
-running the whole loop itself: writing the terms, calling the worker,
-supervising the run, settling the outcome.
+The first milestone is intentionally narrow: a Git-backed facts kernel with
+per-contract append-only journals, Git-tree evidence, atomic path-set CAS,
+and tests that prove clone and garbage-collection durability.
 
-That is why it is a contract system rather than a spec system. A spec relies
-on someone with judgment reading it charitably; here both the worker and the
-judge are models, and a model honors what you wrote, not what you meant. So
-terms are binding, the worker — an akuma (悪魔, demon) — runs on an isolated
-branch, gates and a reviewer judge the diff against the criteria alone, and
-settlement is mechanical: the change lands on main with a commit-hash
-receipt, or the branch is deleted. No human needs to be in the loop for any
-step; nothing depends on anyone eyeballing anything.
-
-```bash
-npm install -g @astrosheep/keiyaku
-```
-
-Node ≥ 22.19, inside a git repository with a clean worktree.
-
-## One deal, end to end
-
-```bash
-# Write the terms: Title, Context, Objective, Design & Approach, Scope, Criteria.
-# The criteria are read by the letter — precision goes here, not in prompts.
-keiyaku bind - < contract.md
-
-# Put an akuma on it. It works alone in the contract's own worktree.
-keiyaku call worker-akuma --detach "fulfill the contract"
-
-# It runs for as long as it needs. You are not its babysitter —
-# but you can be:
-keiyaku wait worker-akuma/3f21ab9e --timeout 10m
-keiyaku tell worker-akuma/3f21ab9e "criteria 3 also covers the CLI output"
-keiyaku kill worker-akuma/3f21ab9e        # death is not an error state
-
-# Ask for judgment: gates run, a reviewer akuma reads the diff
-# against the criteria.
-keiyaku petition
-
-# claim  → the change lands on main, with a commit-hash receipt
-# forfeit → the branch is deleted; partial fulfillment is forfeiture
-```
-
-Every step appends to the contract's ledger. `keiyaku log` replays any deal,
-finished or dead, from its receipts.
-
-## The board
-
-`keiyaku status` is the one screen of state. Real output:
-
-```text
-kanshi ─────────────────────────────────────────────────────── 現世 b4c38cc
-
-marks ● active · … starting · ⧗ waiting · ○ ready · ‖ paused · ✓ success · × stopped · ! failed/broken · ? unknown
-
-keiyaku 2
-⧗ fridge Add task arrange for atomic existing-task reorganization   waiting on task-reorganization.01J8TEST · active 27m
-● hermitcrab Let task commands select a contract workspace                                          bound 8m
-
-task 120
-● in_progress P1 centralize-repository-ledger-test-construction   last update 14h ago
-‖ on_hold P0 windows-common-commands-must-eliminate-git-proc      last update 3d ago
-+ 108 ready · 9 blocked · 1 on hold
-
-akuma 2/2
-running 1/1
-● worker-default/e03addad @fridge       out · running for 27m · last activity 2s ago
-recent terminal 1/1
-! worker-default/64b92f01               failed 5m ago · ran 12m · last activity 5m ago
-full roster: keiyaku status --akuma
-```
-
-The indicator grammar is shared across contracts, Akuma, and tasks; every row
-still names its exact state. `⧗` appears only with a typed wait reason, never
-because work is old or behind its target. Terminal failure is factual state; it
-does not by itself mean `needs attention` or an actionable obligation.
-Durations are measured, exit codes are real, and drift is reported as `behind
-<ref> by <count>`, never as a `renew` recommendation.
-
-## An akuma is one Markdown file
-
-Filename is the name, frontmatter picks the provider and model, the body is
-the standing instructions. That's all it takes to make one callable.
-
-```markdown
----
-provider: codex-sdk
-model: gpt-5.4
-description: Repository implementation agent
----
-Make scoped changes and run relevant tests.
-```
-
-Providers: `codex-sdk`, `codex-app-server`, `claude-agent-sdk`,
-`opencode-sdk`, `pi` — one contract can be worked by any of them, and a
-finished run leaves an artifact that `fork` can continue from, even across
-sessions.
-
-`.keiyaku/settings.json` assigns roles and gates:
-
-```json
-{
-  "default": "worker-akuma",
-  "reviewer": "review-akuma",
-  "gate": { "commands": [{ "label": "tests", "command": "npm", "args": ["test"] }] }
-}
-```
-
-## And the rest
-
-| | |
-| --- | --- |
-| contract | `bind` `arc` `amend` `renew` `audit` `petition` `forfeit` `log` |
-| akuma | `call` `tell` `wait` `kill` `fork` `status` `history` |
-| tasks | `task add/show/ls/log/start/stop/hold/resume/done/drop/update/doctor` |
-| system | `guide` `completion` `dump-env` |
-
-`keiyaku task` is a file-backed planning board for work that isn't worth a
-contract yet — typed dependencies, one micro-commit per change, promotion
-into a contract when it's ready.
-
-Conventions hold everywhere: a literal `-` reads stdin for long bodies,
-`--json` where structure matters, and a rejected command states the legal
-grammar instead of guessing intent. State lives in `KEIYAKU.md` (the active
-contract) and `.keiyaku/` (akuma, settings, task board, history).
-
-Full product documentation: [`docs/keiyaku-v3/`](docs/keiyaku-v3/README.md).
-
-Keiyaku is early and experimental — breaking changes are intentional.
-
-MIT.
+No v3 runtime code is wired into this repository.

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

@@ -0,0 +1,12 @@
+{
+  "name": "keiyaku",
+  "interface": { "displayName": "Keiyaku" },
+  "plugins": [
+    {
+      "name": "keiyaku",
+      "source": { "source": "local", "path": "./plugins/keiyaku" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Productivity"
+    }
+  ]
+}

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

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

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

@@ -0,0 +1,7 @@
+{
+  "name": "keiyaku",
+  "version": "0.1.0+codex.20260813114301",
+  "description": "Use the Keiyaku contract, task, and Akuma CLI.",
+  "author": { "name": "Keiyaku" },
+  "skills": "./skills/"
+}

package/build/integrations/marketplace/plugins/keiyaku/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "keiyaku",
+  "version": "0.1.0+codex.20260813114301",
+  "description": "Use the Keiyaku contract, task, and Akuma CLI.",
+  "author": {
+    "name": "Keiyaku"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Keiyaku",
+    "shortDescription": "Use Keiyaku in Codex.",
+    "longDescription": "Keiyaku adds the agent-facing workflow CLI.",
+    "developerName": "Keiyaku",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": "Use Keiyaku to coordinate this work."
+  }
+}

package/build/integrations/marketplace/plugins/keiyaku/opencode.js

@@ -0,0 +1,16 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const skills = ["keiyaku", "keiyaku-task", "keiyaku-bind", "keiyaku-workflow", "keiyaku-akuma"]
+  .map((name) => fileURLToPath(new URL(`./skills/${name}/SKILL.md`, import.meta.url)));
+
+export default {
+  id: "keiyaku",
+  server: async () => ({
+    config: async (config) => {
+      const instructions = config.instructions ?? (config.instructions = []);
+      await Promise.all(skills.map((skill) => readFile(skill, "utf8")));
+      for (const skill of skills) if (!instructions.includes(skill)) instructions.push(skill);
+    },
+  }),
+};

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

@@ -0,0 +1,8 @@
+{
+  "name": "keiyaku-harness",
+  "version": "0.1.0+codex.20260813114301",
+  "type": "module",
+  "main": "./opencode.js",
+  "keywords": ["pi-package"],
+  "pi": { "skills": ["./skills"] }
+}

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

@@ -0,0 +1,42 @@
+---
+name: keiyaku
+description: Use the Keiyaku v4 CLI for contract delivery, task coordination, and Akuma work.
+---
+
+# Keiyaku
+
+Use `keiyaku` as an agent-facing ledger. Keep decisions with the flagship;
+read `<command> --help` before using flags.
+
+## Model
+
+- `task` is planning; see `keiyaku-task`.
+- A Contract is delivery authority; see `keiyaku-bind` to author and bind one,
+  then `keiyaku-workflow` for the remaining lifecycle.
+- An Akuma is a callable worker; see `keiyaku-akuma`.
+
+Settings owns named gate sets. Omitting `--gates` selects `gates.default`, or
+freezes an empty gate list when that entry is absent. `--gates <name>` selects
+one configured set; it does not add a literal gate word.
+
+## 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
+```
+
+```bash
+keiyaku -C <cwd> call <akuma> [--contract <kei/...>] [--alias @name] [--wait [--timeout <duration>] | -d | --detach] [--json] -
+keiyaku -C <repo> wait <aku/...>
+keiyaku -C <repo> tell <aku/...> -
+```
+
+`-C` is the invocation and Akuma execution cwd. Add `--repo <path>` only when
+a Contract or Dispatch reader must use a different Git repository.
+
+Use text by default; add `--json` when a script needs structured output.

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

@@ -0,0 +1,53 @@
+---
+name: keiyaku-akuma
+description: Use when delegating work to, supervising, steering, inspecting, forking, or stopping a Keiyaku v4 Akuma.
+---
+
+# Keiyaku Akuma
+
+An Akuma is a durable callable worker projection. Its complete id is
+`aku/<archetype>/<hex8>`; keep that id for recovery.
+
+## Choose A Verb
+
+```bash
+keiyaku -C <cwd> call <akuma> [--contract <kei/...>] [--alias @name] [--wait [--timeout <duration>] | -d | --detach] [--json] -
+keiyaku -C <repo> wait <aku/...> [--timeout <duration>]
+keiyaku -C <repo> tell <aku/...> -
+keiyaku -C <repo> tell <aku/...> --interrupt -
+keiyaku -C <repo> history <aku/...>
+keiyaku -C <repo> fork <aku/...> --at <historyId>
+keiyaku -C <repo> kill <aku/...>
+```
+
+`call` starts from an Archetype, requires a final stdin body, and waits up to
+five minutes by default. Its execution cwd is exactly `-C` (or the process cwd
+when omitted). Use `--repo <path>` only with a Contract or Dispatch reader that
+must use a different Git repository. Use `-d` or `--detach` to return after birth. `tell` continues
+the same projection, including after it has answered. `fork` starts a child
+from one exact retained answered-turn coordinate and leaves the source alone.
+`tell --interrupt` puts down the current Body synchronously, then records the
+Tell for its successor. `kill` stops the current Body while preserving the
+Akuma's Heart, session, history, pending Tells, and Body Requests; a later Tell
+wakes the same Akuma.
+
+## Observe
+
+```bash
+keiyaku -C <repo> status
+keiyaku -C <repo> status <aku/...>
+keiyaku -C <repo> wait <aku/...> --timeout 5m
+keiyaku -C <repo> history <aku/...> --before <index>
+keiyaku -C <repo> history <aku/...> --since <index>
+keiyaku -C <repo> history <aku/...> --last
+```
+
+Bare `status` shows the compact fleet. Exact `status <aku/...>` and `wait`
+share the public status carrier; a wait timeout returns the current snapshot,
+not a fabricated timeout state. History cursors are persistent activity
+sequences and `--before`/`--since` are exclusive. `--last` writes only the
+complete answer bytes. Use `--json` when a script needs the typed values.
+
+Read the exact command help for duration syntax and provider-specific Archetype
+configuration. Do not use old `follow`, plural wait, `--after`, or `--at`
+index forms; they are not root commands.

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

@@ -0,0 +1,94 @@
+---
+name: keiyaku-bind
+description: Author and bind one Keiyaku delivery Contract. Use when deciding whether a bounded delivery is ready for Contract terms, writing those terms for an implementer, binding an existing Task with `bind --task`, choosing bind inputs, or interpreting the bind receipt and worktree handoff.
+---
+
+# Keiyaku Bind
+
+Use bind when the work is a delivery decision rather than an investigation.
+The objective and delivery boundary should be clear, the expected write surface
+should be truthful, and every criterion should be decidable without inventing
+taste at review time. Investigate first when a plausible unresolved fact could
+change the objective, governing design, criteria, or delivery boundary.
+
+## Author The Terms
+
+Write for the implementer and reviewer. Include facts they cannot safely
+recover locally: the owner, boundary, data-flow direction, commit point, single
+authority, and forbidden parallel shapes. Leave ordinary helper names and
+equivalent local control flow to the implementation.
+
+A design statement earns its place when a test-green candidate could violate
+it. A criterion names one observable condition that can accept or reject the
+candidate. Keep the Region truthful and no broader than the intended write
+surface.
+
+Start from this complete shape:
+
+~~~markdown
+# <delivery name>
+
+## Context
+<established facts that frame the decision>
+
+## Objective
+<one observable delivery outcome>
+
+## Design
+<ownership, boundaries, and constraints a test-green candidate could violate>
+
+## Region
+```
+<expected write surface>
+```
+
+## Criteria
+### <criterion title>
+<one decidable acceptance condition>
+
+## Verification
+```bash
+<optional executable check>
+```
+~~~
+
+Use an H1 title and the H2 sections shown above. `Verification` is optional.
+When a declaration needs a limit, put an explicit duration such as
+`bash timeout=5m` in its fence info string; omit it for an unbounded declaration.
+Keep extra rationale and investigation logs out of the Contract.
+
+## Bind
+
+Inspect the actual command surface before choosing inputs:
+
+```bash
+keiyaku -C <repo> bind --help
+```
+
+Bind the complete document through stdin. A Task is optional: a Contract is
+complete delivery authority on its own, and ordinary bounded delivery does not
+require creating planning state first. Use `--task` only when an existing Task
+already carries real scheduling, dependency, or coordination value and this
+Contract is specifically its delivery:
+
+```bash
+keiyaku -C <repo> bind - < CONTRACT.md
+keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
+```
+
+Do not create a Task merely to make `bind --task` available or to mirror the
+Contract objective. That adds a second lifecycle with no planning reader.
+
+Use `bind --help` as the installed command authority for optional target,
+workspace, prerequisite, gate-set, actor, and JSON inputs. Do not guess flags
+from an older installation or repository checkout.
+
+## Read The Receipt
+
+Treat the receipt as the handoff. Keep the complete `kei/...` identity, work in
+the reported managed worktree when one was created, and retain the target and
+gate facts it reports. A waiting receipt means prerequisites remain; it is not
+a second authoring workflow. A post-admission lag does not erase the admitted
+Contract; read the typed facts, effects, and lag before acting.
+
+Continue the delivery with `keiyaku-workflow`.

package/build/integrations/marketplace/plugins/keiyaku/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/integrations/marketplace/plugins/keiyaku/skills/keiyaku-task/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: keiyaku-task
+description: "Use when planning work in a Keiyaku v4 repo: add tasks, wire dependencies, inspect readiness, and track lifecycle."
+---
+
+# Keiyaku Task
+
+Task is a directory-context planning product. It is separate from Contract
+delivery and Akuma execution. A task records intent; `start` does not execute
+it and no task command binds a Contract. Task use is optional: create one only
+when planning needs a durable reader such as priority, dependencies, readiness,
+or coordination across deliveries. Do not create one as boilerplate before
+binding a Contract. Contract `bind --task <task/...>` optionally associates an
+existing Task through Settlement-owned TaskHolder: claim settles the current
+held Task to `done`, and abandon releases it. Task Markdown carries no Contract
+field.
+
+## Lifecycle
+
+```text
+open -> in_progress -> done | drop
+  |          |
+  +-> on_hold <-+
+```
+
+Use `ready` for open tasks whose `needs` are terminal. `blocked` reports open
+or in-progress tasks with unresolved needs. `on_hold` appears in neither view.
+Both `done` and `drop` release dependents. `doctor` diagnoses the complete
+world and never repairs it.
+
+## Common Commands
+
+```bash
+keiyaku task add "title"
+keiyaku task add "title" --priority 1 --needs <task-id>
+keiyaku task add --namespace <ns> -
+keiyaku task show <task-id>
+keiyaku task ls
+keiyaku task ls --closed
+keiyaku task ls --all --world
+keiyaku task ready
+keiyaku task blocked
+keiyaku task tree <task-id> [--full]
+keiyaku task doctor
+```
+
+`ls`, `ready`, and `blocked` use the current namespace; add `--world` to
+observe the complete Task world. `show`, `tree`, `update`, and lifecycle
+commands require a complete TaskId and never infer namespace.
+
+## Mutations
+
+```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 <text>]
+keiyaku task update <task-id> --title <text>
+keiyaku task namespace [<namespace>]
+```
+
+Use `--json` on any command when a script must inspect the typed result.
+Relations are explicit facts: `needs` orders work, `parent` groups it,
+`supersedes` navigates replacement, and `relates` does not affect readiness.
+
+## Batch Create Or Modify
+
+Use `task compose -` to create and modify multiple Tasks in one planning
+document:
+
+```bash
+keiyaku task compose - <<'EOF'
+ns=feature
++ Parent pri=0
+Parent body.
+  + Child needs=@task/existing
+@task/existing pri=1 relates+=@task/other
+Replacement body.
+EOF
+```
+
+- Optional first line `ns=<segment/...>` selects the allocation namespace;
+  `ns=` selects root.
+- `+ <title>` creates a Task. `@task/<id>` modifies an existing Task.
+- Two spaces of indentation assign the preceding shallower Task as `parent`.
+- Inline assignments are `pri=`, `parent=`, `needs=`, `supersedes=`, and
+  `relates=`. Relation values are comma-separated `@task/...` references.
+- `=` replaces or clears a field. `+=` appends only to `needs`, `supersedes`,
+  or `relates`.
+- Prose after a node replaces its body; bare `body=` clears it. Prefix body
+  lines beginning with `+ `, `@task/`, or `\` with one `\`.
+
+Compose does not change Task lifecycle state. Each changed Task is admitted
+independently; an incomplete result returns a canonical draft for the remaining
+batch.