@astrosheep/keiyaku 2.9.8 → 2.9.10

package/skills/keiyaku/SKILL.md

@@ -33,7 +33,7 @@ EOF
 ```
 
 That's the whole loop. Skip the task when the work needs no planning:
-`keiyaku bind --place NAME --objective TEXT --scope GLOB --checks CHECK` (or the same as Markdown through `keiyaku bind -` — `bind --help` shows the shape).
+`keiyaku bind --title TEXT --context TEXT --objective TEXT --design TEXT --scope GLOB --criteria TEXT [--verification COMMAND]` (or the same settled document through `keiyaku bind -` — `bind --help` shows the shape).
 
 ## Getting oriented
 

package/skills/keiyaku-akuma/SKILL.md

@@ -41,10 +41,10 @@ addressable. `revive` starts a new projection and does not inherit an alias.
 
 ```bash
 keiyaku akuma ls                              # who's callable
-keiyaku akuma view NAME                       # resolved profile + live projections
+keiyaku akuma show NAME                       # resolved profile + live projections
 keiyaku call NAME "do the thing"              # run in foreground until it finishes
 keiyaku call NAME --wait 10m "do the thing"   # bounded: after 10m you get a snapshot, it keeps running
-keiyaku call NAME --detach "do the thing"     # fire and forget; note the projection id
+keiyaku call NAME -d "do the thing"           # short for --detach; note the projection id
 keiyaku call NAME - < prompt.md               # long prompt: literal `-` reads stdin
 keiyaku wait <proj-id>                        # join a running one; prints its activity
 keiyaku wait <proj-id> --timeout 5m           # peek for 5m; timeout = snapshot, not death
@@ -63,7 +63,7 @@ keiyaku status                                # forgot an id? it's on the board
 <KEIYAKU_HOME>/akuma/<name>.md           user profile (normally ~/.keiyaku)
 ```
 
-Use `keiyaku akuma view NAME` to inspect the resolved source and configuration.
+Use `keiyaku akuma show NAME` to inspect the resolved source and configuration.
 
 ## Expectations
 

package/skills/keiyaku-task/SKILL.md

@@ -52,8 +52,10 @@ keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
 Only ready tasks bind. Multi-bind only when the tasks describe one delivery
 intent, share a coherent write surface, and should settle together; otherwise
 keep separate contracts and express order with task `needs` or contract
-`--after`. The first task supplies name/objective defaults; provide a partial
-bind document for any missing `Scope` or `Checks`.
+`--after`. The first task supplies title/objective defaults; provide a partial
+bind document for every remaining resolved section. Final bind admission always
+requires Title, Context, Objective, Design, Scope, and Criteria; Verification
+is optional.
 
 ## Gotcha
 

package/skills/keiyaku-workflow/SKILL.md

@@ -1,251 +1,136 @@
 ---
 name: keiyaku-workflow
-description: Use when driving a Keiyaku contract — bind to start isolated work, arc/renew mid-flight, petition for review, claim or forfeit to finish.
+description: Use when driving a Keiyaku contract — bind isolated work, use arc/renew mid-flight, audit a candidate, petition to settle, or forfeit.
 allowed-tools: Bash(keiyaku *)
 ---
 
 # Keiyaku Workflow
 
-How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning is `keiyaku-task`.
-
-## Core ideas
-
-- A contract is one delivery intent with one ledger, branch, and linked worktree.
-- Workers edit and test; the host reviews their dirty tree and commits accepted bytes.
-- `audit` reads one pinned candidate. `petition` is the settlement action.
-- Scope is the smallest closure of files currently expected to be written. Amend
-  newly expected exact paths before delivery.
-- An arc is a named story chapter for one coherent stretch inside the contract.
-
-Lifecycle:
-
-```
-bound → active → petitioned → claimed | forfeited
+## Mindset
+
+- One contract carries one delivery intent through one ledger, branch, and
+  linked worktree.
+- Scope is the expected write set for this delivery, not code ownership or a
+  permission boundary.
+- Criteria state what must be true. Verification supplies executable evidence.
+- Implementation happens in the linked worktree. Commit accepted bytes before
+  `arc`, `renew`, or `petition`.
+- An arc is a coherent chapter of the same delivery. It keeps the contract,
+  worktree, branch, and final settlement.
+- `audit` reports evidence for one pinned candidate. `petition` asks to settle.
+
+```text
+bound -> active -> petitioned -> claimed | forfeited
 ```
 
-## Before Bind
-
-`bind` begins implementation from a settled executable contract.
-
-Before binding, complete the fact and decision work needed to state the delivery:
-
-- reproduce or otherwise establish the motivating fact;
-- read the registered authority and locate the current owning modules;
-- settle inputs, outputs, state consequences, failure behavior, invariants, and
-  forbidden expansion;
-- identify the smallest expected write set and account for known write overlap
-  and delivery dependencies; ownership remains with the authority registry and
-  its owning chapter;
-- write checks that prove the critical success path, the highest-risk rejection,
-  and the relevant durability, concurrency, or recovery boundary.
-
-Use tasks, fact scans, and bare read-only exploration while gathering evidence
-and settling decisions. Task `ready` reports that its dependencies are
-satisfied; the coordinator promotes it after establishing semantic contract
-readiness. Bind when Objective, Scope, and Checks describe one complete
-implementation journey and contain every product or architecture decision the
-worker needs.
+## Bind
 
-After bind, the worker implements and verifies that contract. `amend` records
-new evidence or a change of intent that genuinely emerges during implementation
-or review, then implementation continues from the updated contract.
+Bind when one implementation journey is decided: motivating facts, owning
+modules, inputs and outputs, consequences, failure behavior, invariants,
+forbidden expansion, write set, acceptance criteria, and decisive checks.
+Use a task only when planning or dependencies need a durable place.
 
-## Choosing Scope
+Declare the smallest useful Scope:
 
-Scope names the files this contract is currently expected to write, not a
-territory the contract owns. Choose the narrowest form supported by the
-evidence, in this order:
-
-1. When the write set is known, list exact repository-relative paths, one per
-   line. This is the default and needs no justification.
-2. When filenames are not yet known but changes are scattered within one
-   directory, use a one-component wildcard for that component.
-3. Use the recursive wildcard only for a real whole-subtree rewrite, migration,
-   or generated-output operation. The Objective must state why the entire tree
-   is expected to change.
-
-Known files use exact paths:
+1. exact paths when known;
+2. a one-component wildcard when names inside one directory are still open;
+3. a recursive wildcard only for a real subtree rewrite, migration, or
+   generated output.
 
 ```bash
-keiyaku bind --place fix-pump --objective "make the pump test pass" \
-             --scope "src/pump.ts" --scope "tests/unit/pump.test.ts" \
-             --checks "pump tests green"
+keiyaku bind - < contract.md
+keiyaku bind --task TASK_ID - < contract.md
 ```
 
-Unknown filenames within one component may use a one-component wildcard:
+The contract document carries `Title`, `Context`, `Objective`, `Design`,
+`Scope`, `Criteria`, and optional `Verification`. Add newly expected exact paths
+with `amend`; do not pre-authorize a broad tree for convenience.
 
-```bash
-keiyaku bind --place repair-pump-fixtures --objective "repair the affected pump fixtures" \
-             --scope "tests/fixtures/pump/*" --checks "pump fixture tests green"
-```
+## Select The Contract
 
-A recursive pattern is reserved for an actual whole-tree operation:
+Use `-C DIR` to select the effective directory. A contract worktree carries its
+contract identity:
 
 ```bash
-keiyaku bind --place regenerate-api-docs \
-             --objective "regenerate API documentation because the generator changes every file under docs/generated" \
-             --scope "docs/generated/**" --checks "generated API docs are current"
+keiyaku -C .keiyaku/wt/cloud audit
+keiyaku -C .keiyaku/wt/cloud log
 ```
 
-If implementation evidence later identifies one more expected file, amend with
-that exact path:
+From a repository hub, name the contract with `--contract ADDR` or `@ADDR`:
 
 ```bash
-keiyaku amend --append-scope "src/pump/metrics.ts" - < amendment.md
+keiyaku -C /work/keiyaku --contract repair-status.01K... audit
 ```
 
-Amend is cheap. Broad Scope consumes parallel coordination and weakens audit
-signal, so moving to a broader pattern needs a reason; moving narrower does not.
+`bind -C DIR` creates a new contract in the selected repository. Full contract
+ID is durable identity; slug and place are convenience addresses.
 
-## The default flow
+## Drive The Work
 
 ```bash
-keiyaku bind --place fix-pump --objective "make the pump test pass" \
-             --scope "src/pump.ts" --scope "tests/unit/pump.test.ts" \
-             --checks "pump tests green"
-# or the same four fields as Markdown: keiyaku bind - < contract.md
-#   (# <name> / ## Objective / ## Scope / ## Checks)
-# or promote one or more ready tasks:
-keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
-
-cd .keiyaku/wt/fix-pump          # worker edits/tests here and leaves a dirty tree
+keiyaku arc - < arc.md
+keiyaku renew
+keiyaku amend - < amendment.md
+keiyaku log
+keiyaku status
+```
 
-# Back on the host after reviewing the worker's diff and test report:
-git -C .keiyaku/wt/fix-pump add -- <accepted-paths>
-git -C .keiyaku/wt/fix-pump commit -m "fix pump"
+- `arc` seals one coherent chapter and opens the next. It is not a child
+  contract or a parallel worktree.
+- `renew` rebases onto an advanced target. Re-run verification after it.
+- `amend` records a changed intent, invariant, Scope, Criteria, or Verification
+  before implementation relies on that change.
 
-# Rehearse the exact pinned delivery before settlement:
-keiyaku @fix-pump audit
+Scope changes are ordered terms. Use flags for simple additions or one
+`Scope Append` block for an ordered delta:
 
-keiyaku petition - <<'EOF'
-## Oath
-I made the pump test pass; ran the suite, all green.
-EOF
-# petition seals your work (a seal = your commits + intent frozen into one
-#   reviewable unit; arc and renew also seal) and runs the settlement pipeline —
-# passes → claimed (merged to main); a gate fails → fix, petition again.
-# The oath is required (OATH_MISSING otherwise) and checked for presence, not content.
+````markdown
+## Scope Append
 ```
-
-A task is optional planning, not a prerequisite. Bind settled new work directly;
-use `--task` when promoting existing tracked planning after the same readiness
-judgment.
-
-That's the whole small case: bind → worker dirty-tree handoff → host review/commit → petition.
-
-Multi-bind tasks only when they are evidence for the same delivery intent, share
-one coherent write surface, and should settle together. This reduces competing
-contracts/worktrees; it does not replace `needs` or contract `--after` ordering.
-
-`audit` is read-only and never invokes an Akuma or settles the contract. Exit 0
-means it constructed the report, not that the candidate is acceptable. Use
-`--diff-budget BYTES` when bounded diff evidence is useful.
-
-Commissioned workers never write Git metadata. The host alone reviews and
-commits accepted bytes before `arc`, `renew`, or `petition`.
-
-Dispatch rule: every time a dispatcher sends a worker, whether through
-`keiyaku call` or any other agent tool, the prompt must explicitly tell that
-worker to read the worktree-root `.keiyaku/KEIYAKU.md` first and follow its
-objective, scope, and checks. The file is the contract-body carrier; do not
-copy its rendered body into a dispatch prompt.
-
-## Review findings
-
-Review findings are evidence for diagnosis, not a queue of local patches. Before
-changing code, classify each finding as a contract hole, missing invariant or
-owner, execution slip, test gap, or provider/capability failure. A second
-finding in the same transition, a race that crosses module owners, or a finding
-that contradicts the contract is a root-cause signal: stop symptom patching,
-record the governing invariant and ownership correction with `amend`, and
-refactor the boundary before sending another tell or accepting another diff.
-
-A default review dispatch is:
-
-> First read the worktree-root `.keiyaku/KEIYAKU.md`. Review the candidate end
-> to end against the contract and repository law. On every review round, treat
-> the current candidate as a new complete implementation: reassess its overall
-> coherence and regression risks rather than checking only whether prior
-> findings were patched. Report material findings first. For each problem,
-> explain the underlying cause and recommend a root-cause correction direction,
-> not a patch-sized edit. If the evidence is insufficient, state what remains
-> unknown. Do not modify files or Git metadata.
-
-Add candidate-specific evidence only when it helps the reviewer judge coverage;
-do not copy the contract body or seed an expected defect. Reviewer suggestions
-inform the coordinator's judgment but do not amend the contract. The
-coordinator owns the final diagnosis; a worker may implement a settled
-correction but may not invent a new state machine or compatibility rule.
-
-Do not claim a contract while related findings remain unresolved merely because
-each individual test or patch passes. Re-run the focused interleaving or
-boundary evidence and an independent review against the corrected ownership
-model. Repeated tells that only add guards to the same disputed path are not
-progress; if the contract cannot express the required invariant, amend or
-forfeit and bind a coherent replacement.
-
-After a worker fixes review findings, prefer telling the same review projection
-to re-check those findings and the corrected candidate. Start a fresh reviewer
-only when the earlier projection is unavailable or incompatible, its context is
-no longer trustworthy, or a genuinely fresh independent perspective is useful.
-This is an efficiency preference, not an acceptance gate.
-
-## Mid-flight commands (use when needed, skip otherwise)
-
-```bash
-keiyaku arc - < arc.md       # optional iteration boundary: seals the current intent, opens
-                             #   the next. Markdown: # <title> / ## Objective / ## Brief.
-                             #   Only needed when one contract has multiple distinct pushes.
-keiyaku renew                # main moved under you → rebase onto it. Refuses on conflict
-                             #   instead of guessing; resolve, then renew again.
-keiyaku amend - < amendment.md # scope/checks changed → update the paper before the code
-keiyaku log                  # this contract's history
+src/new-owner.ts
+!src/retired/**
 ```
+````
 
-`amend` accepts prose plus one optional ordered scope-pattern delta. Use either
-repeated flags:
+Later `!pattern` terms narrow earlier matches. Do not mix the block with
+`--append-scope` flags.
 
-```sh
-keiyaku amend --append-scope "docs/api-reference.md" --append-scope "!docs/obsolete-api-reference.md" - < amendment.md
-```
+After an explicit arc seal, commit any new work and open the next arc before
+`renew` or `petition`.
 
-or a document section:
+## Review
 
-````markdown
-Clarify the newly expected documentation files.
+Review the complete candidate against the contract and repository law on every
+round. Findings identify a contract hole, missing owner or invariant, execution
+slip, test gap, or provider failure. Correct the governing model when the owner,
+flow, commit point, failure outcomes, obsolete paths, or proof matrix is wrong;
+use `amend` when the contract must change.
 
-## Scope Append
-~~~
-docs/api-reference.md
-!docs/obsolete-api-reference.md
-~~~
-````
+Ask reviewers for material findings with file references and root-cause
+direction. Reviewers do not modify files or amend the contract. Keep related
+findings open until the corrected candidate and focused boundary evidence have
+been reviewed again.
 
-`Scope Append` appends ordered raw gitignore-subset lines in one column-zero
-tilde fence; direct input also accepts a matching backtick fence. `Scope Add`
-and Markdown bullets are rejected. A later
-`!pattern` can narrow earlier scope. Flags and a document Scope Append block
-are mutually exclusive; plain amendment prose plus flags is valid. Use
-`--append-scope PATTERN` when a lifecycle operation discovers one durable term.
+## Settle
 
-Gotchas:
-- `-C DIR` selects the effective working directory; repository discovery starts there.
-- Base drift blocks ordinary petition. `petition --renew` runs the same renew
-  first and settles only after that renew succeeds; it never auto-opens an arc.
-- After an explicit `arc` seals, new loose commits need another `arc` before `renew`/`petition` accept them.
-- Not in the worktree? Address a contract with `--contract ADDR` (place, slug, or full id) or the `keiyaku @addr <verb>` prefix.
-
-## Ending it
+Before settlement, renew if the target moved, then rerun the declared evidence.
+`audit` is read-only; exit 0 means it produced a report, not that the candidate
+passed. Petition requires an oath and runs the settlement gates:
 
 ```bash
-keiyaku forfeit --reason "superseded by fix-pump-v2"
-# abandon: worktree destroyed, history kept. Manual only — nothing auto-forfeits.
+keiyaku audit
+keiyaku petition - <<'EOF'
+## Oath
+I completed the contract and verified the submitted candidate.
+EOF
 ```
 
-There is no `claim` command: claiming is the tail of a passing petition.
-
-## Reading status
+A passing petition claims into the target. A failed gate leaves the contract
+available for correction. End a superseded delivery explicitly:
 
 ```bash
-keiyaku status               # every contract row: state, place, what to do next
+keiyaku forfeit --reason "superseded by CONTRACT"
 ```
+
+Forfeit preserves history and removes the contract worktree. There is no
+separate `claim` command.