@astrosheep/keiyaku 4.6.2 → 4.6.4

package/README.md

@@ -52,7 +52,7 @@ The CLI parses a predicate; the evaluator never sees a raw shell string.
 Query reads only Task facts. No Contract. No Akuma.
 
 ## Verification
-```bash
+```bash timeout=2m
 npm test
 ```
 ```
@@ -60,60 +60,60 @@ npm test
 ## What a deal looks like
 
 ```bash
-keiyaku bind - < keiyaku.md     # terms written; an isolated worktree appears
-keiyaku call worker -           # a worker goes in
-keiyaku deliver                 # tendered; Verification runs; gates judge
-keiyaku review --satisfied      # attested; main moves with a commit receipt
+keiyaku bind - < contract.md                        # terms written; an isolated worktree appears
+keiyaku call worker -                               # a worker goes in
+keiyaku deliver <contract>                          # delivered; Verification runs; gates judge
+keiyaku review <contract> --satisfied --summary -   # attested; main moves with a commit receipt
 ```
 
 ## What the journal records
 
-One real deal, pulled from this repo's own journal:
+One real deal, read back with `keiyaku history`:
 
 ```text
-$ keiyaku audit kei/add-acp-provider-and-grok-build-profile
-
-accepted audit kei/add-acp-provider-and-grok-build-profile head=0508f7eb9cb738bcab06060b13ff1a96d36e3754
-report {"reworks":1,"reviews":2,"timeline":[
-  {"kind":"bind","at":"2026-08-14T08:18:36.224Z"},
-  {"kind":"deliver","at":"2026-08-14T13:02:08.339Z"},
-  {"kind":"attestation","gate":"reviewed","verdict":"unsatisfied","summary":
-   "Implementation review found no blocking code issues; authenticated official
-    Grok smoke remains unavailable because this host has no grok binary."},
-  {"kind":"attestation","gate":"verified","verdict":"satisfied","summary":"[1 bash exit 0] …"}]}
+history  kei/ship-typed-task-query-b186 · accepted · 9 entries
+
+2026-10-04
+
+16:53 bound to targetless @ 3c5d8c0 · gate review
+16:53 delivered 210eeed · ✓ verification · 10 lines
+16:53 × review · 6 lines
+16:53 delivered aebef87 · ✓ verification · 10 lines
+16:53 ✓ review · 6 lines
+16:53 accepted
 ```
 
-The review said no — with a reason, in bytes, on the journal. The deal
-did not land until the gates had current evidence.
+The review said no, and the deal did not land. The verdict and its reason
+stay on the journal as bytes — `keiyaku history --json` reads them:
+
+```json
+{
+  "kind": "attestation",
+  "contract": "kei/ship-typed-task-query-b186",
+  "data": {
+    "gate": "reviewed",
+    "verdict": "unsatisfied",
+    "summary": "Query evaluator still reaches for Contract facts; reads are not Task-owned."
+  }
+}
+```
 
 ## The board
 
-`keiyaku status` is the one screen. A slice of this repository, right now:
+`keiyaku status` is the one screen. Two Contracts and two Tasks in flight:
 
 ```text
-kanshi ─ 7 keiyaku · 18 akuma · 286 task ─ /Users/astrosheep/Developer/keiyaku-v4 main 9cfdca6017633e51827b9b2eba3c76a7fe08e05f
-
-keiyaku 7
-! kei/add-acp-provider-and-grok-build-profile tendered
-  worktree · integration c5cafef6 · -> refs/heads/main
-  × reviewed
-⧗ kei/align-task-cli-truth-promises waiting
-  ! reviewed
-  held by task/align-task-cli-truth-promises-for-ready-compose
-
-akuma 18
-● aku/expert-akuma/a7aafc9e running
-  alias @process-custody-lead
-  keiyaku kei/make-process-custody-capability-honest (active)
-○ aku/design-akuma/cc53ef08 asleep
-  alias @timeline-design
-! aku/grok/95d90b7d stranded
-  alias @acp-provider-impl
-
-task 8 · 5 ready · 2 held
-● task/align-task-cli-truth-promises-for-ready-compose in_progress
-  Align Task CLI truth promises for ready compose and world absence
-  P0 · keiyaku kei/align-task-cli-truth-promises (active)
+CONTRACTS // recent
+
+⧗ kei/ship-typed-task-query-c898 · 1s · Ship typed Task query
+  [✓] delivery  [ ] review
+⧗ kei/tighten-receipt-vocabulary-4a70 · 18s · Tighten receipt vocabulary
+  [ ] delivery  [ ] review
+
+TASKS // recent
+
+○ task/regenerate-readme-from-real-010b · ready · P1 · Regenerate README from real output
+○ task/align-task-cli-truth-promises-3af5 · ready · P0 · Align Task CLI truth promises
 ```
 
 Marks accelerate scanning; the words carry the state.
@@ -122,9 +122,8 @@ Marks accelerate scanning; the words carry the state.
 
 ```markdown
 ---
-provider: claude-agent-sdk
-model: claude-sonnet-4-5
-access: write
+provider: pi
+model: kimi-coding/k3-256k
 description: Repository implementation agent
 ---
 Make scoped changes and run relevant tests.
@@ -132,6 +131,55 @@ Make scoped changes and run relevant tests.
 
 One Markdown file, one worker. `keiyaku call worker` summons it.
 
+## Configuration
+
+Settings are JSON at two addresses: `~/.keiyaku/settings.json` for the user,
+`.keiyaku/settings.json` in the project. A project record
+wholly shadows the same-name user record. There is no write command; edit the
+files directly and inspect the merged, provenance-annotated view with
+`keiyaku settings`.
+
+Named gate groups provide reusable gate sets. Bind and amend select them with
+`--gates`; the `default` group applies when binding with `--gates` omitted.
+Amending without `--gates` keeps the existing gates:
+
+```json
+{
+  "gates": {
+    "default": { "kind": "bundle", "gates": ["reviewed"] },
+    "strict": { "kind": "bundle", "gates": ["reviewed", "verified"] }
+  }
+}
+```
+
+Selections accept the built-in names `reviewed` and `verified`, or configured
+group names. Unknown names are rejected with the known names listed. Custom gates
+must be declared inside a configured group; they stay unsatisfied until a producer
+attests them.
+
+Worktree hooks run commands when a Contract's managed worktree is created or
+destroyed — dependency installs are the usual suspect:
+
+```json
+{
+  "worktree": {
+    "create": [
+      { "name": "install", "argv": ["npm", "ci", "--ignore-scripts", "--prefer-offline"], "timeoutMs": 300000 }
+    ],
+    "destroy": [
+      { "name": "teardown", "argv": ["docker", "compose", "down", "-v"], "timeoutMs": 60000 }
+    ]
+  }
+}
+```
+
+Hooks run as one ordered phase inside the worktree and must be replay-safe: a
+retry reruns the phase from its beginning. Create hooks prepare the worktree;
+destroy hooks release external resources the worktree deletion alone cannot.
+A failing hook retains the worktree
+and reports lag; it never abandons the Contract. `keiyaku settings --help`
+lists every recognized namespace.
+
 ## Install
 
 ```bash

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

@@ -1,8 +1,9 @@
 ---
 name: keiyaku-akuma
 description: >-
-  Calling an Akuma: delegate work to a new or existing worker, then observe,
-  guide, and collect the result.
+  Use when the work involves Akuma or Aku, or when you want other hands on
+  it: delegating a job, or fanning out research, checks, or other parallel
+  work.
 ---
 
 # Keiyaku Akuma
@@ -22,7 +23,7 @@ waiting for the first answer. Use explicit `--wait <duration>` when this
 invocation should block while observing that initial work. `--wait` only bounds
 this command; it never stops the Akuma. Read `call --help` for flag syntax,
 defaults, and action vocabulary.
-For seat grants see `keiyaku-workflow`'s table; Reviewers need `--allowed contract.review`.
+To hand a Contract role to an Akuma, use the grant table in `keiyaku-workflow`.
 
 The selected Akuma name is a reusable worker configuration, not an individual.
 Calling it again creates an independent Akuma. Use different names for

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

@@ -46,8 +46,8 @@ skeptics to break the finalists, and generate replacements only for the
 identified weaknesses. Bound rounds and cost; "keep improving" is not a useful
 stop condition.
 
-Independent judgment needs independent contexts. Create separate Akuma for
-blind comparisons or adversarial verification. Reuse an identity for follow-up
+Blind comparisons and adversarial checks need separate contexts. Create
+separate Akuma for them. Reuse an identity for follow-up
 investigation, not as a supposedly fresh judge of its own earlier answer.
 
 ## Public Entry And A Single Structured Turn

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

@@ -52,7 +52,7 @@ does not move without you.
 | 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; call a new Reviewer with the grant from `keiyaku-workflow`, then have it inspect current work and record a fresh verdict. The refused request wrote no Contract testimony. |
+| 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. |

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

@@ -183,9 +183,10 @@ 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 bundle
+Omitting `--gates` uses `gates.default`, or `reviewed` when no default group
 exists. `--gates ""` selects no gates. Gates are named acceptance obligations,
-not work assignments.
+not work assignments. Named gate groups and worktree hooks live in Settings;
+see the README Configuration section or `keiyaku settings --help`.
 
 ## 3. After Binding
 
@@ -204,7 +205,7 @@ 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 seats.
+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.

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

@@ -38,13 +38,26 @@ to create parallel work.
 Use `after` only when one `kei` requires another to be accepted first. Ordinary
 overlap is not a dependency.
 
-## 3. Hold the `kei`
+## 3. Roles
 
-Every `kei` has exactly one holder. The holder coordinates the work and owns
-acceptance until the Contract is accepted or abandoned. Delegation does not
-transfer that responsibility. An Akuma holding the whole loop needs the `kei`, current Arc
-when one exists, appointed worktree, holder duties, and actions its commission
-will perform. Birth freezes permissions; Contract association grants none.
+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
 
@@ -78,31 +91,30 @@ 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. Seats And Capabilities
+## 5. Handing A Role To An Akuma
 
 This is the one commissioning map. `call --help` owns the exact action
-vocabulary and default set. `--contract` records association, not authority.
+vocabulary and default set. The flagship acting directly needs no grant.
+Birth freezes an Akuma's actions; `--contract` records association, not
+authority.
 
-| Seat | Grant and commission | Return |
+| Role | Grant at birth | Return |
 | --- | --- | --- |
-| Holder | Direct flagship commands need no Akuma grant. A delegated holder gets only its birth-time actions; include review when the delegated loop records review. | Own the acceptance loop and inspect receipts. |
-| Deliverer | The ordinary baseline includes every Task mutation, Contract audit and delivery, and Akuma management. `keiyaku -C <repo> call worker --alias @deliverer --contract <kei/...> --workdir <appointed-path> -` | Produce and tender the candidate; return the receipt. |
-| Reviewer | Add `--allowed contract.review` at birth: `keiyaku -C <repo> call review-akuma --alias @reviewer --contract <kei/...> --workdir <appointed-path> --allowed contract.review -` | Record a verdict and return its receipt. Without the grant, `not-allowed` refuses the mutation; no Contract verdict is recorded. |
+| 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
+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; call a fresh one with the grant. Nested calls cannot exceed their direct
-parent's actions.
-
-## 6. Delegate the Work
+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. A Deliverer produces the candidate. A Reviewer
-checks the complete Contract against its acceptance conditions and returns
-verdict evidence. Use `keiyaku-akuma` for invocation and observation, and
-command help for exact syntax.
+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.
 
-## 7. Decide What Happens Next
+## 6. Decide What Happens Next
 
 The holder checks candidate, verification, review, prerequisites, and gates.
 

package/build/src/akuma/providers/pi/events.js

@@ -164,10 +164,11 @@ function translateMessage(event, state) {
         state.assistantSeen = true;
         state.answer = text;
     }
-    // Gemini emits an empty text block alongside every tool-use message. It is
+    // Some providers emit a blank text block alongside every tool-use message:
+    // empty from Gemini, whitespace from openai-responses-style proxies. It is
     // transport scaffolding, not narration; an ordinary terminal empty answer
     // remains public evidence.
-    if (hasTextContent(message.content) && !(message.stopReason === "toolUse" && text.length === 0)) {
+    if (hasTextContent(message.content) && !(message.stopReason === "toolUse" && text.trim().length === 0)) {
         translated.push({ type: "assistant", text });
     }
     return translated;

package/build/src/body/render.d.ts

@@ -1,4 +1,12 @@
 import type { ArcData } from "../core/facts/types.js";
-import type { ContractBody } from "./types.js";
+import type { ContractBody, DecodedContractDocument } from "./types.js";
 export declare function renderContractBody(body: ContractBody, currentArc?: ArcData): string;
+/**
+ * Binding persists the canonical rendering of decoded terms, never the caller's
+ * literal byte stream: layout-only authorship is normalized at admission so it
+ * never reappears as phantom changes in later amendment diffs.
+ */
+export declare function decodeCanonicalContractDocument(source: string, options?: Readonly<{
+    requireTimeout?: boolean;
+}>): DecodedContractDocument;
 export declare function renderAmendedContractBody(currentSource: string, body: ContractBody, changedSections: ReadonlySet<string>): string;

package/build/src/body/render.js

@@ -1,4 +1,5 @@
 import { formatDuration } from "../duration.js";
+import { decodeContractDocument } from "./decode.js";
 import { parseToAST } from "../markdown/parse.js";
 import { indexDocument, indexedHeadings, normalizeTitle, rawSlice } from "../markdown/query.js";
 import { CONTRACT_SECTIONS } from "./shape.js";
@@ -54,6 +55,16 @@ export function renderContractBody(body, currentArc) {
         .join("\n\n")
         .concat("\n");
 }
+/**
+ * Binding persists the canonical rendering of decoded terms, never the caller's
+ * literal byte stream: layout-only authorship is normalized at admission so it
+ * never reappears as phantom changes in later amendment diffs.
+ */
+export function decodeCanonicalContractDocument(source, options = {}) {
+    const decoded = decodeContractDocument(source, options);
+    const rendered = renderContractBody(decoded);
+    return rendered === decoded.document.bytes ? decoded : decodeContractDocument(rendered, options);
+}
 function sections(document) {
     return indexedHeadings(indexDocument(document), { level: 2 }).filter((node) => node.type === "section");
 }

package/build/src/cli/commands/akuma-grammar.js

@@ -304,8 +304,10 @@ function parseAddressed(action, rawSelectors, flags, output, fail) {
     return { command: action, akuma, at, output };
 }
 function parsePrompted(action, positionals, stdin, fail) {
-    if (positionals.length < 1 || positionals.length > 2)
-        fail(`${action} has invalid positional arguments`);
+    if (positionals.length === 0)
+        fail(action === "call" ? "call requires an Akuma name" : `${action} requires an Akuma selector`);
+    if (positionals.length > 2)
+        fail(`${action} accepts at most ${action === "call" ? "a name" : "a selector"} and one prompt`);
     const argument = positionals[1];
     if (stdin && argument !== undefined)
         fail(`${action} accepts either a prompt argument or stdin, not both`);
@@ -406,7 +408,14 @@ export function parseAkumaCommand(argv) {
                 : parseAsk(flags, parsed.subject, parsed.prompt, output, fail);
     }
     if (spec.arity === "one-or-more" ? positionals.length === 0 : positionals.length !== spec.arity) {
-        fail(`${action} has invalid positional arguments`);
+        if (positionals.length === 0)
+            fail(spec.arity === "one-or-more"
+                ? `${action} requires at least one Akuma selector`
+                : `${action} requires an Akuma selector`);
+        else
+            fail(spec.arity === 1
+                ? `${action} accepts one Akuma selector`
+                : `${action} accepts exactly ${spec.arity} Akuma selectors`);
     }
     if (stdin)
         fail(`${action} reads no stdin`);

package/build/src/cli/commands/akuma.js

@@ -9,6 +9,7 @@ import { executionChannel } from "../../akuma/requests.js";
 import { settings } from "../../settings.js";
 import { AkumaWorldScopeError } from "../../index.js";
 import { akumasWithExecution } from "../../library/akumas.js";
+import { World } from "../../world.js";
 import { contractFromInput } from "../selectors.js";
 import { ActivityDriver } from "../activity.js";
 import { displayContext, resultContext, writeJson, writeStderr, writeStdout } from "../streams.js";
@@ -67,6 +68,11 @@ async function inputInitiator(input) {
     catch { }
     if (initiator === undefined)
         return {};
+    // Plugins coordinate within an established World; a `call` may run where the
+    // marker does not exist yet, and activating there would only fail noisily.
+    // The initiator still travels with the request either way.
+    if (!(await World.established(input.path)))
+        return { initiator };
     try {
         await emitInitiatingPluginSignal({
             world: input.path,

package/build/src/cli/commands/contract-grammar.js

@@ -22,6 +22,9 @@ function optionalFlag(flags, name) {
 function refuse(command, message) {
     throw new CliUsageError(message, commandGuide(command, CONTRACT_COMMAND_SPECS[command].usage));
 }
+// The CLI restates the literal gate-word grammar its help prints; the corpus
+// pin in cli-parse.test.ts keeps this shape honest against the owner's gateWord.
+const GATE_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/u;
 function parseGateNames(parts, command) {
     const value = optionalFlag(parts.flags, "gates");
     if (value === undefined)
@@ -32,6 +35,10 @@ function parseGateNames(parts, command) {
     if (names.some((name) => name.length === 0)) {
         refuse(command, '--gates requires comma-separated names or "" to clear gates');
     }
+    const invalid = names.find((name) => !GATE_NAME_PATTERN.test(name));
+    if (invalid !== undefined) {
+        refuse(command, `--gates name must match ^[a-z][a-z0-9-]{0,63}$: ${invalid}`);
+    }
     return names;
 }
 function parseBind(parts) {

package/build/src/cli/commands/contract-help.d.ts

@@ -106,7 +106,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly json: "boolean";
         };
         readonly usage: "ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls \"aku/<name>/*\" [--limit <count>]\nls \"aku/*/*\" [--limit <count>]";
-        readonly purpose: "List Tasks, Contracts, or Akumas.";
+        readonly purpose: "List tasks (ls task), contracts (ls kei), or akumas (ls aku).";
         readonly details: string;
     };
     readonly audit: {

package/build/src/cli/commands/contract-help.js

@@ -15,11 +15,15 @@ export const CONTRACT_COMMAND_SPECS = {
         usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]",
         purpose: "Create a Contract from stdin Markdown or copy an existing Contract as a starting point.",
         details: [
-            "--gates <name,...> accepts gate words and configured bundle names together.",
-            "A matching bundle expands; otherwise the name is a literal gate. Duplicates",
-            "are removed in first-seen order. Gate words match ^[a-z][a-z0-9-]{0,63}$.",
+            "Gates are acceptance obligations checked at placement: reviewed awaits a",
+            "satisfied review, verified awaits a passing Verification run.",
+            "",
+            "--gates <name,...> selects reviewed, verified, or named gate groups from Settings",
+            "(keiyaku settings). A group expands into its gates; unknown names are rejected",
+            "with the known names listed. Custom gates must be declared in a configured group.",
+            "Duplicates are removed in first-seen order. Names match ^[a-z][a-z0-9-]{0,63}$.",
             "Omitting --gates selects gates.default, or reviewed when no default exists.",
-            '--gates "" explicitly binds without gates; --gates reviewed needs no bundle.',
+            '--gates "" explicitly binds without gates; --gates reviewed needs no configuration.',
             "",
             "Binding appoints one managed worktree for the Contract and the receipt",
             "reports its path; the holder and delegates work there. When appointment",
@@ -55,9 +59,14 @@ export const CONTRACT_COMMAND_SPECS = {
         usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
         purpose: "Change a Contract's document, prerequisites, or acceptance gates.",
         details: [
-            "--gates <name,...> replaces gates using gate words and configured bundle names.",
-            "A matching bundle expands; otherwise the name is a literal gate. Duplicates",
-            "are removed in first-seen order. Gate words match ^[a-z][a-z0-9-]{0,63}$.",
+            "Gates are acceptance obligations checked at placement: reviewed awaits a",
+            "satisfied review, verified awaits a passing Verification run.",
+            "",
+            "--gates <name,...> replaces gates using reviewed, verified, or named gate groups",
+            "from Settings (keiyaku settings). A group expands into its gates; unknown names",
+            "are rejected with the known names listed. Custom gates must be declared in a",
+            "configured group. Duplicates are removed in first-seen order.",
+            "Names match ^[a-z][a-z0-9-]{0,63}$.",
             'Omitting --gates leaves gates unchanged; --gates "" clears them.',
             "",
             "  ## Context|Objective|Design|Region|Criteria|Verification|<extension>  (replace, or add new extension)",
@@ -88,6 +97,7 @@ export const CONTRACT_COMMAND_SPECS = {
             "Delivery requests integration. If prerequisites and gates pass, it integrates now and accepts the Contract; otherwise the candidate remains waiting.",
             "Only changed candidate work invalidates earlier review. If Verification did not finish, repeating delivery resumes that candidate; --overwrite replaces it.",
             "Delivery never counts as an independent review verdict.",
+            "Content identity names the change's content hash, never a commit; it survives rebase and Git cannot look it up.",
             "",
             "  --materialize-conflict  Write the observed integration conflict into the worktree as an uncommitted merge.",
             "                          With --include-dirty, current non-ignored changes are preserved first.",
@@ -147,8 +157,9 @@ export const CONTRACT_COMMAND_SPECS = {
         stdin: "none",
         flags: { limit: "value", json: "boolean" },
         usage: 'ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]',
-        purpose: "List Tasks, Contracts, or Akumas.",
+        purpose: "List tasks (ls task), contracts (ls kei), or akumas (ls aku).",
         details: [
+            "ls kei lists active Contracts; accepted and abandoned ones leave the list, and their record stays in history and Git.",
             "ls aku/ lists the callable Akuma-name catalog; ls aku/<name> lists the living Akumas under one name.",
             'ls "aku/<name>/*" is the same living set in glob form; ls "aku/*/*" lists every living Akuma.',
         ].join("\n"),
@@ -162,6 +173,7 @@ export const CONTRACT_COMMAND_SPECS = {
         details: [
             "--include-dirty checks all non-ignored worktree changes, staged or not.",
             "--show-diff includes the proposed candidate diff when one can be prepared.",
+            "Content identity names the change's content hash, never a commit; it survives rebase and Git cannot look it up.",
             "Progress appears on stderr; stdout contains one final result.",
         ].join("\n"),
     },
@@ -210,7 +222,7 @@ export function renderContractHelp(command) {
             "command; edit the files directly.",
             "",
             "Recognized settings:",
-            "  gates                            gate bundles selected by bind and amend",
+            "  gates                            named gate groups selected by bind and amend",
             "  worktree                         commands run when worktrees are created or destroyed",
             "  git.requireBranchesToBeUpToDate  whether deliver and audit require up-to-date target branches",
             "  providers                        the available Akuma and how each is run",

package/build/src/cli/commands/contract.js

@@ -148,7 +148,9 @@ async function contractLibrary(command, execution, configuration, runtime) {
     return composeContractLibrary(execution, createKeiyakuHandle, {
         ...(configuration === undefined ? {} : { settings: configuration }),
         ...(actor === undefined ? {} : { actor }),
-    });
+    }, 
+    // The CLI owns this default: an omitted Markdown --target names the invocation branch.
+    { kind: "current-branch" });
 }
 async function runBind(command, input, library) {
     const { coordinates, runtime } = input;

package/build/src/cli/commands/task-grammar.js

@@ -204,14 +204,12 @@ export function renderTaskHelp(action) {
         const spec = TASK_COMMAND_SPECS[action];
         return `${spec.purpose}\n\n${renderTaskUsage(action)}${spec.details === undefined ? "" : `\n\n${spec.details}`}`;
     }
+    const nameWidth = Math.max(...Object.keys(TASK_COMMAND_SPECS).map((name) => name.length));
     return [
         "usage  keiyaku task <command> ...",
+        "      keiyaku task <command> --help   shows that command's complete usage",
         "",
-        "commands:",
-        ...Object.values(TASK_COMMAND_SPECS).flatMap((spec) => spec.usage
-            .split("\n")
-            .map((line) => `  ${line}`)
-            .concat(`    ${spec.purpose}`)),
+        ...Object.entries(TASK_COMMAND_SPECS).map(([name, spec]) => `  ${name.padEnd(nameWidth)}  ${spec.purpose}`),
     ].join("\n");
 }
 function renderTaskUsage(action) {
@@ -387,8 +385,12 @@ function validateListSelector(selector, fail) {
 }
 function validateTaskScan(action, scanned, fail) {
     const spec = TASK_COMMAND_SPECS[action], { positionals, flags, stdin } = scanned;
-    if (positionals.length < spec.arity[0] || positionals.length > spec.arity[1])
-        fail(`task ${action} has invalid positional arguments`);
+    if (positionals.length < spec.arity[0])
+        fail(spec.arity[1] === 1 ? `task ${action} requires a TaskId` : `task ${action} requires at least one TaskId`);
+    if (positionals.length > spec.arity[1])
+        fail(spec.arity[1] === 0
+            ? `task ${action} accepts no positional arguments`
+            : `task ${action} accepts at most ${spec.arity[1]} positional argument${spec.arity[1] === 1 ? "" : "s"}`);
     if (action === "add" && (stdin === "document") === (positionals.length === 1))
         fail("task add requires either TITLE or '-' input");
     if (action === "add" &&

package/build/src/cli/parse.js

@@ -294,6 +294,11 @@ export function parseArgv(argv) {
     const help = helpCoordinate(invocation.commandArgv);
     if (help !== null)
         return { help };
+    // A bare invocation asks for orientation: the root help index, not a refusal.
+    if (invocation.commandArgv.length === 0)
+        return { help: { kind: "root" } };
+    if (invocation.commandArgv.length === 1 && invocation.commandArgv[0] === "task")
+        return { help: { kind: "task" } };
     if (invocation.commandArgv.length === 1 && invocation.commandArgv[0] === "--version")
         return { version: true };
     const task = invocation.commandArgv[0] === "task" ? parseTaskCommand(invocation.commandArgv.slice(1)) : undefined;