@astrosheep/keiyaku 2.9.6 → 2.9.7

package/skills/keiyaku-workflow/SKILL.md

@@ -22,6 +22,32 @@ Lifecycle:
 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;
+- declare one coherent ownership region and account for known write overlap and
+  delivery dependencies;
+- 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.
+
+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.
+
 ## The default flow
 
 ```bash
@@ -51,8 +77,9 @@ EOF
 # The oath is required (OATH_MISSING otherwise) and checked for presence, not content.
 ```
 
-A task is optional planning, not a prerequisite. Bind directly for new work;
-use `--task` only when promoting existing tracked planning into this contract.
+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.
 
@@ -62,7 +89,7 @@ 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` for bounded output and `--json` for complete typed facts.
+`--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`.
@@ -73,6 +100,46 @@ 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
@@ -94,20 +161,22 @@ keiyaku log                  # this contract's history
 Clarify the owned documentation surface.
 
 ## Scope Append
-```
+~~~
 docs/**
 !docs/generated/**
-```
+~~~
 ````
 
 `Scope Append` appends ordered raw gitignore-subset lines in one column-zero
-backtick fence; `Scope Add` and Markdown bullets are rejected. A later
+tilde fence; direct input also accepts a matching backtick fence. `Scope Add`
+and Markdown bullets are rejected. A later
 `!pattern` can narrow earlier scope. Use `--append-scope PATTERN` when a
 lifecycle operation discovers one durable term.
 
 Gotchas:
 - `-C DIR` selects the effective working directory; repository discovery starts there.
-- Base drift blocks petition — if main moved, `renew` first; petition tells you.
+- 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.