@astrosheep/keiyaku 2.9.6 → 2.9.8

package/build/core/task/task-git-store.js

@@ -105,6 +105,29 @@ export async function locateTaskBoard(cwd, runGitProbe = defaultRunGit) {
 function taskDirectory(board) {
     return path.join(board.root, ".keiyaku", "tasks");
 }
+const TASK_HISTORY_FORMAT = "%aI%x00%an%x00%s";
+function taskHistoryPath(taskId) {
+    return `.keiyaku/tasks/${taskId}.md`;
+}
+function parseTaskHistory(output) {
+    const fields = output.split("\0");
+    if (fields.at(-1) !== "") {
+        throw new FlowError("INTERNAL_STATE", "task history returned an incomplete record");
+    }
+    fields.pop();
+    if (fields.length % 3 !== 0) {
+        throw new FlowError("INTERNAL_STATE", "task history returned an incomplete record");
+    }
+    const entries = [];
+    for (let index = 0; index < fields.length; index += 3) {
+        entries.push({
+            timestamp: fields[index],
+            actor: fields[index + 1],
+            subject: fields[index + 2],
+        });
+    }
+    return entries;
+}
 function assertKeiyakuDirectory(board) {
     const keiyakuDirectory = path.join(board.root, ".keiyaku");
     const stat = lstatIfPresent(keiyakuDirectory);
@@ -201,6 +224,33 @@ export async function inspectTaskLock(cwd) {
         closeQuietly(database);
     }
 }
+/** Read the current hub branch's task-specific Git history without acquiring the task lock. */
+export async function readTaskHistory(cwd, taskId, deps = {}) {
+    if (!isTaskId(taskId)) {
+        throw new FlowError("INVALID_TARGET", `task history requires a canonical task id: ${taskId}`);
+    }
+    const board = await locateTaskBoard(cwd, deps.runGit);
+    if (board.mode !== "git") {
+        throw new FlowError("NOT_GIT_REPO", "task history is available only in a Git repository");
+    }
+    const result = await (deps.runGit ?? defaultRunGit)(board.root, [
+        "log",
+        "-z",
+        "--topo-order",
+        "--reverse",
+        `--format=${TASK_HISTORY_FORMAT}`,
+        "--",
+        taskHistoryPath(taskId),
+    ]);
+    if (result.error) {
+        throw new FlowError("INTERNAL_STATE", `cannot read task history: ${result.error.message}`, { cause: result.error });
+    }
+    if (result.status !== 0) {
+        const detail = result.stderr.trim() || `exit ${String(result.status)}`;
+        throw new FlowError("INTERNAL_STATE", `cannot read task history: ${detail}`);
+    }
+    return parseTaskHistory(result.stdout);
+}
 export function atomicReplaceTaskFile(filePath, text, _deps) {
     const directory = path.dirname(filePath);
     fs.mkdirSync(directory, { recursive: true });
@@ -345,8 +395,7 @@ function assertTaskDirectorySafety(directory) {
         throw new FlowError("INTERNAL_STATE", `task directory is not a regular directory: ${directory}`);
     }
 }
-export async function openTaskStore(cwd, deps = {}) {
-    const board = await locateTaskBoard(cwd, deps.runGit);
+export function openTaskStoreAt(board, deps = {}) {
     const directory = taskDirectory(board);
     return {
         mode: board.mode,
@@ -355,7 +404,7 @@ export async function openTaskStore(cwd, deps = {}) {
             return readTaskSources(directory);
         },
         async mutate(apply) {
-            return withLockHeldTaskBoard(cwd, async (transaction) => {
+            return withLockHeldTaskBoard(board.root, async (transaction) => {
                 const previousSources = transaction.sources;
                 const plan = await apply(transaction.sources);
                 validatePlan(plan);
@@ -387,6 +436,9 @@ export async function openTaskStore(cwd, deps = {}) {
         },
     };
 }
+export async function openTaskStore(cwd, deps = {}) {
+    return openTaskStoreAt(await locateTaskBoard(cwd, deps.runGit), deps);
+}
 export async function withLockHeldTaskBoard(cwd, apply, deps = {}, locatedBoard) {
     const board = locatedBoard ?? await locateTaskBoard(cwd, deps.runGit);
     const directory = taskDirectory(board);

package/build/core/worktree-path.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import { FlowError } from "../flow-error.js";
 import { createGit, wrapGitError } from "../git/core.js";
 import { readLedger } from "./ledger.js";
+import { readLedgerSnapshot } from "./ledger-batch.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { normalizeFilesystemCoordinate } from "../fs/path-coordinate.js";
 import { gitCommonRootPath, resolveGitCommonRoot } from "../git/path-coordinate.js";
@@ -73,7 +74,10 @@ export async function stableRepoRoot(cwd) {
     }
 }
 export async function contractWorktreePathFromBind(cwd, contractId, bind) {
-    return path.join(await stableRepoRoot(cwd), ".keiyaku", "wt", bind?.data.place ?? contractId);
+    return contractWorktreePathFromStableRoot(await stableRepoRoot(cwd), contractId, bind);
+}
+function contractWorktreePathFromStableRoot(stableRoot, contractId, bind) {
+    return path.join(stableRoot, ".keiyaku", "wt", bind?.data.place ?? contractId);
 }
 export async function contractWorktreePath(cwd, contractId) {
     const ledger = await readLedger(cwd, contractId);
@@ -110,7 +114,7 @@ export async function findRegisteredContractWorktreePath(cwd, contractId) {
         return undefined;
     let expected;
     try {
-        expected = await fs.realpath(await contractWorktreePathFromBind(stableRoot, contractId, bind));
+        expected = await fs.realpath(contractWorktreePathFromStableRoot(stableRoot, contractId, bind));
     }
     catch {
         return undefined;
@@ -139,48 +143,58 @@ export async function resolveContractDeliveryCwd(cwd, contractId) {
  * terminal state is optional so residual worktrees after cleanup still bind.
  */
 async function contractIdForEngineOwnedWorktree(cwd, options) {
-    const stableRoot = await stableRepoRoot(cwd);
+    const stableRoot = options.stableRoot ?? await stableRepoRoot(cwd);
     const canonicalCwd = await fs.realpath(cwd);
+    const candidates = [];
     for (const worktree of await listWorktrees(stableRoot)) {
         const branchPrefix = "refs/heads/keiyaku/";
         if (!worktree.branch?.startsWith(branchPrefix))
             continue;
-        const contractId = worktree.branch.slice(branchPrefix.length);
-        const ledger = await readLedger(stableRoot, contractId);
-        if (!ledger)
-            continue;
-        if (options.requireActive && isTerminalState(deriveContractState(ledger.entries)))
-            continue;
-        const bind = findBindEntry(ledger.entries);
-        if (!bind || bind.data.workspace !== "worktree")
-            continue;
         let canonicalWorktree;
-        let expectedWorktree;
         try {
             canonicalWorktree = await fs.realpath(worktree.path);
-            expectedWorktree = await fs.realpath(await contractWorktreePathFromBind(stableRoot, contractId, bind));
         }
         catch {
             continue;
         }
-        if (canonicalWorktree !== expectedWorktree)
+        if (!worktreeContainsCoordinate(canonicalWorktree, canonicalCwd))
             continue;
-        if (worktreeContainsCoordinate(canonicalWorktree, canonicalCwd))
-            return contractId;
+        candidates.push({
+            contractId: worktree.branch.slice(branchPrefix.length),
+            path: canonicalWorktree,
+        });
     }
-    return undefined;
+    const candidate = candidates.sort((left, right) => right.path.length - left.path.length)[0];
+    if (!candidate)
+        return undefined;
+    const ledger = await readLedgerSnapshot(stableRoot, candidate.contractId);
+    if (!ledger)
+        return undefined;
+    if (options.requireActive && isTerminalState(deriveContractState(ledger.entries)))
+        return undefined;
+    const bind = findBindEntry(ledger.entries);
+    if (!bind || bind.data.workspace !== "worktree")
+        return undefined;
+    let expectedWorktree;
+    try {
+        expectedWorktree = await fs.realpath(contractWorktreePathFromStableRoot(stableRoot, candidate.contractId, bind));
+    }
+    catch {
+        return undefined;
+    }
+    return candidate.path === expectedWorktree ? candidate.contractId : undefined;
 }
 /**
  * Resolve the contract bound by an engine-owned worktree containing cwd,
- * including when the ledger is already terminal. Task CLI contract context
- * uses this residual binding; call attachment never infers from cwd.
+ * including when the ledger is already terminal. Task CLI context uses this
+ * residual binding; call uses the active-only sibling below.
  */
-export async function contractBoundByEngineWorktree(cwd) {
-    return contractIdForEngineOwnedWorktree(cwd, { requireActive: false });
+export async function contractBoundByEngineWorktree(cwd, stableRoot) {
+    return contractIdForEngineOwnedWorktree(cwd, { requireActive: false, stableRoot });
 }
-/** Existing-contract verbs may infer only a verified, active engine binding. */
-export async function activeContractBoundByEngineWorktree(cwd) {
-    return contractIdForEngineOwnedWorktree(cwd, { requireActive: true });
+/** Existing-contract verbs and no-selector call attachment use only this verified active binding. */
+export async function activeContractBoundByEngineWorktree(cwd, stableRoot) {
+    return contractIdForEngineOwnedWorktree(cwd, { requireActive: true, stableRoot });
 }
 export async function cleanupContractWorkspace(cwd, contractId) {
     const stableRoot = await stableRepoRoot(cwd);

package/build/flow-error.js

@@ -20,7 +20,7 @@ export function renderTemplate(template, values) {
 }
 function formatInvalidSettingsDiseaseHints(diseases) {
     return diseases.map((disease) => {
-        const where = disease.knob ? `${disease.source}:${disease.knob}` : `${disease.source}:(root)`;
+        const where = disease.knob ? `${disease.coordinate}:${disease.knob}` : `${disease.coordinate}:(root)`;
         return `${where}: ${disease.reason}`;
     });
 }

package/build/generated/version.js

@@ -1,3 +1,3 @@
 // Generated into build output by scripts/build.mjs
-export const VERSION = "2.9.6";
-export const GIT_HASH = "cb7f9ef";
+export const VERSION = "2.9.8";
+export const GIT_HASH = "c9cfce1";

package/build/git/refs.js

@@ -1,5 +1,51 @@
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "./core.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, runGitProcess, wrapGitError, } from "./core.js";
 const ZERO_OBJECT_ID = "0000000000000000000000000000000000000000";
+/** Normalize a configured branch to the sole local-branch ref spelling. */
+export function normalizeLocalBranchRef(branch) {
+    return branch.startsWith("refs/heads/") ? branch : `refs/heads/${branch}`;
+}
+function isMissingExactRef(result) {
+    return result.status === 1 && result.stdout === "";
+}
+function parseShowRefRows(output) {
+    const lines = output.split(/\r?\n/);
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (lines.length === 0 || lines.some((line) => line.length === 0))
+        return null;
+    const rows = [];
+    for (const line of lines) {
+        const match = /^(?<objectId>[0-9a-fA-F]{40}|[0-9a-fA-F]{64}) (?<ref>refs\/\S+)$/.exec(line);
+        if (!match?.groups)
+            return null;
+        rows.push({ objectId: match.groups.objectId, ref: match.groups.ref });
+    }
+    return rows;
+}
+function throwGitProcessFailure(commandLabel, result, cwd) {
+    const failure = result.error ?? Object.assign(new Error(result.stderr || `git ${commandLabel} exited ${result.status}`), {
+        stderr: result.stderr,
+        stdout: result.stdout,
+    });
+    throw wrapGitError(commandLabel, failure, cwd);
+}
+/**
+ * Resolve only a local branch through the argv-based Git boundary. A configured
+ * short name is never allowed to fall through Git's revision search rules.
+ */
+export async function resolveLocalBranchHead(cwd, branch, run = runGitProcess) {
+    const ref = normalizeLocalBranchRef(branch);
+    const result = await run(cwd, ["show-ref", ref]);
+    if (isMissingExactRef(result))
+        return null;
+    if (result.status === 0) {
+        const exactRows = parseShowRefRows(result.stdout)?.filter((row) => row.ref === ref);
+        if (exactRows?.length === 1) {
+            return { ref, head: exactRows[0].objectId };
+        }
+    }
+    return throwGitProcessFailure(`show-ref ${ref}`, result, cwd);
+}
 async function resolveRefOrNull(cwd, ref) {
     const git = createGit(cwd);
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.6",
+  "version": "2.9.8",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",

package/skills/keiyaku-akuma/SKILL.md

@@ -19,6 +19,24 @@ Rule of thumb: continue the same conversation with its projection id. Use an
 artifact id with `revive` only when deliberately starting a new projection;
 failed/dead state alone is not a reason to revive.
 
+## Projection aliases
+
+When a lane will be supervised repeatedly, assign a short stable alias at call
+time and use it as the operator coordination handle:
+
+```bash
+keiyaku call worker-akuma --alias release-lane --detach "implement the brief"
+keiyaku wait release-lane --timeout 10m
+keiyaku tell release-lane "run the focused checks before handoff"
+keiyaku kill release-lane
+```
+
+Aliases are per selected projection ledger, not projection identity. Keep the
+full `name/8hex` ID in durable records and exact recovery. Reusing an alias
+word atomically moves only that per-ledger ref to the new projection; it does
+not stop, mutate, or delete the prior projection. Its old full ID remains
+addressable. `revive` starts a new projection and does not inherit an alias.
+
 ## Common usage
 
 ```bash
@@ -30,6 +48,8 @@ keiyaku call NAME --detach "do the thing"     # fire and forget; note the projec
 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
+keiyaku wait <proj-a> <proj-b> --any          # return when the first member finishes
+keiyaku wait <proj-a> <proj-b> --all          # return when every member finishes
 keiyaku tell <proj-id> [--wait DURATION] <BODY|-> # optionally tell, then bounded-join
 keiyaku revive rsp_XXXX "continue..."         # new run continuing from a record
 keiyaku kill <proj-id>                        # stop it; record survives, revive still works
@@ -50,10 +70,18 @@ Use `keiyaku akuma view NAME` to inspect the resolved source and configuration.
 - Omit tell's bracketed `--wait DURATION` option for silent success: exit 0,
   zero output. Supply it to perform the ordinary bounded join after acceptance.
   Silence **is** the receipt — do not re-send. Effects show up in `wait`/`status`.
+- `tell --interrupt` is intentionally destructive. On an active runner, silent
+  success means the tell and interrupt intent are durable; provider stop and
+  successor wake continue asynchronously under the same projection id. Idle or
+  terminal state uses ordinary tell plus wake and reports its typed wake error.
 - Body is required for `call`/`tell`. Literal `-` selects stdin; unselected
   piped bytes are ignored and cannot change an argv body.
 - A `--wait`/`--timeout` expiry prints a live snapshot and exits 0 — the run continues; rejoin with `wait` anytime.
 - `wait` is repeatable: on a finished run it shows the final transcript again.
+- Supervise multiple projections with one plural `wait`. Choose `--any` to
+  handle the first terminal member and refill its lane; choose `--all` only for
+  final batch convergence. Keep foreground waits blocking; if bounded, use one
+  operationally meaningful timeout instead of repeated short-timeout polling.
 
 ## Occasional flags
 

package/skills/keiyaku-workflow/SKILL.md

@@ -13,7 +13,8 @@ How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning
 - 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 an audit boundary, not a write lock. Amend changed intent before delivery.
+- 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:
@@ -22,11 +23,86 @@ 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;
+- 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.
+
+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.
+
+## Choosing 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:
+
+```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"
+```
+
+Unknown filenames within one component may use a one-component wildcard:
+
+```bash
+keiyaku bind --place repair-pump-fixtures --objective "repair the affected pump fixtures" \
+             --scope "tests/fixtures/pump/*" --checks "pump fixture tests green"
+```
+
+A recursive pattern is reserved for an actual whole-tree operation:
+
+```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"
+```
+
+If implementation evidence later identifies one more expected file, amend with
+that exact path:
+
+```bash
+keiyaku amend --append-scope "src/pump/metrics.ts" - < amendment.md
+```
+
+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.
+
 ## The default flow
 
 ```bash
 keiyaku bind --place fix-pump --objective "make the pump test pass" \
-             --scope "src/pump/**" --checks "pump tests green"
+             --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:
@@ -51,8 +127,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 +139,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 +150,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
@@ -82,32 +199,39 @@ keiyaku arc - < arc.md       # optional iteration boundary: seals the current in
 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
-# Scope terms can be appended durably during a lifecycle operation:
-keiyaku @fix-pump arc --append-scope "docs/generated/**" - < arc.md
-keiyaku @fix-pump renew --append-scope "docs/generated/**"
 keiyaku log                  # this contract's history
 ```
 
-`amend` accepts prose plus an optional ordered scope-pattern delta:
+`amend` accepts prose plus one optional ordered scope-pattern delta. Use either
+repeated flags:
+
+```sh
+keiyaku amend --append-scope "docs/api-reference.md" --append-scope "!docs/obsolete-api-reference.md" - < amendment.md
+```
+
+or a document section:
 
 ````markdown
-Clarify the owned documentation surface.
+Clarify the newly expected documentation files.
 
 ## Scope Append
-```
-docs/**
-!docs/generated/**
-```
+~~~
+docs/api-reference.md
+!docs/obsolete-api-reference.md
+~~~
 ````
 
 `Scope Append` appends ordered raw gitignore-subset lines in one column-zero
-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.
+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.
 
 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.