@abelxiaoxing/cadence 1.4.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",
@@ -51,7 +51,8 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
-    "typebox": "*"
+    "typebox": "*",
+    "@earendil-works/pi-ai": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
@@ -60,7 +61,8 @@
     "@types/node": "^22.15.3",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "@earendil-works/pi-ai": "0.84.3"
   },
   "repository": {
     "type": "git",

package/prompts/abel-design.md

@@ -29,9 +29,36 @@ Design resolves product and technical decisions, collects cited evidence, and co
 It never launches an implementation Worker, creates a product-code candidate, applies a product diff, runs Red/Green/Refactor, or mutates the main workspace.
 
 If no requirement can be identified or several changes cannot be distinguished, ask one focused question about the target.
-Otherwise investigate first: resolve discoverable unknowns from repository evidence and choose reversible defaults within existing authority; only unresolved substantive choices require a user decision.
+Otherwise make Design `start` the first control call, before repository discovery.
+It creates only private resumable identity and does not approve scope.
+Then resolve discoverable unknowns from repository evidence and choose reversible defaults within existing authority; only unresolved substantive choices require a user decision.
 An explicit `--change <name>` resumes only that existing change; never reinterpret a misspelling as a new requirement.
 
+## Durable Design identity
+
+Use the same `action: "design"` envelope from the first call through finalization.
+Call `start` once with either the complete new requirement or an explicit existing change name, then use the returned `runId` for every later Design operation.
+For a new requirement, the control plane normalizes and hashes the transient text itself; the raw requirement is not written to the durable journal.
+After Gate A fixes its name, bind that same provisional run with `bind-change` rather than starting a second run.
+Use `status` by `runId` to recover local lifecycle and Design facts without a model or endpoint request.
+A completed Design run is immutable; an explicit later `--change <change>` starts the next durable Design revision for that change while preserving prior approval facts for receipt verification.
+
+```json
+{"action":"design","request":{"operation":"start","requirement":"<complete-requirement>","operationId":"<unique-operation>"}}
+{"action":"design","request":{"operation":"start","change":"<existing-change>","operationId":"<unique-operation>"}}
+{"action":"design","request":{"operation":"status","runId":"<run-id>"}}
+{"action":"design","request":{"operation":"bind-change","runId":"<run-id>","operationId":"<unique-operation>","change":"<gate-a-approved-change>"}}
+```
+
+## Focused evidence collection
+
+For a local change with known paths, read applicable repository instructions, the package manifest, the affected implementation and existing tests in the same assistant turn when independent.
+Expand to callers, fixtures or architecture only for a concrete unresolved impact or verification question.
+Once observable behavior, authorized scope, existing-test impact and an executable verification command are established, proceed to the accepted contract and draft.
+Do not continue broad directory traversal or read Cadence implementation sources to reconstruct its protocol; use the current tool schema, its installed example paths and returned field diagnostics.
+The `start` / `status` response includes a current-step hint; it is guidance, not new approval authority.
+Evidence packets are optional: use them only for independent evidence gaps that justify another model call.
+
 ## Write boundary
 
 - During verified Design, the parent tool set is mechanically limited to the previously active `read`, `grep`, `find`, and `ls` tools plus `abel_dispatch`.
@@ -56,22 +83,6 @@ Identical replay is idempotent and conflicting reuse of an operation id fails cl
 {"action":"design","request":{"operation":"delete-artifact","runId":"<run-id>","operationId":"<unique-operation>","path":"specs/<capability>/spec.md"}}
 ```
 
-## Durable Design identity
-
-Use the same `action: "design"` envelope from the first call through finalization.
-Call `start` once with either the complete new requirement or an explicit existing change name, then use the returned `runId` for every later Design operation.
-For a new requirement, the control plane normalizes and hashes the transient text itself; the raw requirement is not written to the durable journal.
-After Gate A fixes its name, bind that same provisional run with `bind-change` rather than starting a second run.
-Use `status` by `runId` to recover local lifecycle and Design facts without a model or endpoint request.
-A completed Design run is immutable; an explicit later `--change <change>` starts the next durable Design revision for that change while preserving prior approval facts for receipt verification.
-
-```json
-{"action":"design","request":{"operation":"start","requirement":"<complete-requirement>","operationId":"<unique-operation>"}}
-{"action":"design","request":{"operation":"start","change":"<existing-change>","operationId":"<unique-operation>"}}
-{"action":"design","request":{"operation":"status","runId":"<run-id>"}}
-{"action":"design","request":{"operation":"bind-change","runId":"<run-id>","operationId":"<unique-operation>","change":"<gate-a-approved-change>"}}
-```
-
 ## Read-only evidence packets
 
 Use `abel_dispatch` with `action: "run"` only for bounded Design evidence.
@@ -133,6 +144,19 @@ Design settles the goal, main decisions, explicit constraints, and non-goals.
 Make the implementation delegation clear in the accepted proposal: the parent will choose its recommended solution for later implementation choices within those constraints, record material decisions, and continue to verified results without another selection or confirmation round.
 Do not ask the user to approve this delegation separately or attempt to enumerate every future implementation detail.
 
+## Structured authority for new work
+
+Use a structured `ChangeContract` as the Gate A `contract` for new designs: `goal`, `acceptance` (stable `id`, accepted `statement`, complete structured `verification`), `constraints` (stable `id` and `statement`), and `policy` (`writeRoots`, allowed dependency names in `dependencies`, and `verificationModes`).
+Use `behavior` by default; explicitly permit `mechanical` or `refactor` only for suitable work.
+Present the accepted goal, constraints and scope together with the recommended choices.
+Do not include secrets or raw conversation in the contract.
+
+Code normalizes and hashes the object.
+The journal retains the normalized authority and injects it into compiled plans; callers do not compute hashes.
+Keep acceptance IDs and statements stable when reshaping a plan.
+Compilation rejects missing acceptance verification, outside-policy writes/dependencies, or substituted authority.
+Historical prose approvals remain readable; their existence does not authorize new scope.
+
 Gate A approves the complete WHAT: goal, observable scenarios, failures, scope/non-goals, compatibility/migration/security policy, and success criteria.
 Before approval, present the unresolved behavior decisions together.
 After explicit approval:
@@ -143,7 +167,7 @@ After explicit approval:
 4. materialize schema-ready behavior artifacts one at a time.
 
 ```json
-{"action":"design","request":{"operation":"approve-gate","runId":"<run-id>","operationId":"<unique-operation>","gate":"gate-a","contract":"<complete-approved-what-contract>"}}
+{"action":"design","request":{"operation":"approve-gate","runId":"<run-id>","operationId":"<unique-operation>","gate":"gate-a","contract":{"goal":"<accepted goal>","acceptance":[{"id":"<acceptance-id>","statement":"<accepted behavior>","verification":{"kind":"static-check","id":"<acceptance-verifier-id>","runner":{"kind":"node","script":"<observed-test-path>"},"args":[],"classification":"expected-green"}}],"constraints":[],"policy":{"writeRoots":["<approved-source-path>","<approved-test-path>"],"dependencies":[],"verificationModes":["behavior"]}}}}
 ```
 
 The control plane generates the canonical behavior-contract hash; the returned proof contains its approval revision, contract hash, and owner-private record hash.
@@ -158,6 +182,46 @@ Compiling identical canonical bytes after unchanged decisions preserves the exis
 Derive HOW from Gate A plus repository evidence.
 Ask only unresolved substantive technical decisions, then build a complete task DAG with stable Requirement → Scenario → Verification → Task references.
 
+Start from the package's [single-task PlanDraft example](../config/plan-draft.example.json), resolved relative to this prompt's installed path.
+It describes a small Node consumer with `package.json`, `src/add.mjs` exporting `add`, and one existing `test/add.test.mjs` that uses Node assertions and currently covers `add(0, 0) === 0`.
+The Red phase preserves that assertion and adds `add(2, 3) === 5` with the failure marker `[ADD:positive-integers]`; Green repairs the function.
+The example's nested `changeContract` also shows the structured Gate A shape.
+Replace its goal, acceptance, paths, context, impact evidence, and verification commands with observed repository facts before approval; its sample evidence is not evidence about the current project.
+Use the project's actual full suite when adapting this single-test example.
+The control plane inherits the approved `changeContract`, so the draft may omit that duplicate object.
+Keep author input separate from the complete sealed execution plan; execution never reads author shorthand.
+Reuse an atomic command through `verificationDefinitions` and `{ "use": "name" }`; place `expectedFailure` on its Red use.
+Definitions contain an existing atomic verifier's command fields, without identity, classification, bindings, nested references, or arbitrary use-site overrides.
+Inline atomic contracts may also omit `id` and `classification`; the compiler derives stable purpose identities and phase classifications.
+In PlanDraft, omit a package-script `command` (including in a named definition or package-script runner) to bind the literal package.json script value before identity generation.
+An explicit `command` must be that exact manifest value, never a launcher such as `npm run test`.
+Gate A acceptance verifiers remain complete explicit contracts; use the observed literal script value there.
+Explicit task `read` supplies common reads to its phases, unioned with any phase-local `read`; writes, deletes, roots, dependencies, and output producers remain explicit.
+The compiler also supplies fixed baseline/repair boundary fields and `agents.managedOnly`; retain recovery attempt limits and observed AGENTS impact.
+It supplies an empty AGENTS checkpoint only when every explicitly declared impact is `none`.
+The [dependent-task example](../config/plan-draft.multiple-tasks.example.json) shows a Red-produced test consumed by another task's ordered verification, with an explicit dependency and producer.
+Ordered `steps` remain complete inline contracts; reuse means separate verification executions, never reuse of a prior successful report.
+Omit `tracking` to generate parent-owned `tasks.md` metadata from the task ids; an explicitly supplied block must match those ids and the fixed tracking policy.
+In the author portion of `tasks.md`, write one checkbox with each backticked task ID, its objective and its owned backticked `specs/<capability>/spec.md#Requirement title/Scenario title` references.
+Every Scenario must have exactly one reference.
+Do not copy generated phase verifier IDs into this text.
+Compilation installs their code-owned `ABEL:VERIFICATION-BINDINGS` region while preserving the author text.
+Editing tasks afterward requires recompilation before finalization.
+Omit phase `verificationInputs`: the compiler derives the exact paths from each verification contract and binds them to a unique declared output or an existing workspace file.
+Keep supporting sources and fixtures in `read`; input derivation never adds read/write paths, outputs, or dependencies.
+Omit each `relatedTests` entry's `disposition` and `regressionTaskId` to derive ownership from task writes; retain its observed `path` and `evidence`.
+An ambiguous producer or test owner requires an explicit correction; explicitly supplied fields are checked, never silently replaced.
+Scope, verification choices, recovery limits, and necessary AGENTS operations remain explicit.
+
+Mechanical tasks may write document/data/config files (`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, `.lock`).
+Refactor tasks preserve accepted verifier inputs.
+Both must declare no public behavior change and require an explicitly allowed mode in Gate A. Specify task `verificationMode` and Green (plus optional Refactor); omit Red in the draft.
+The compiler handles its internal compatibility representation.
+Runtime captures baseline and executes Green with affected, cumulative and post-apply verification, without generating a Red candidate.
+Behavior tasks continue to require Red/Green.
+
+An AGENTS checkpoint additionally requires its exact target path in `policy.writeRoots`; a broad source root does not grant AGENTS authority.
+
 Each task must seal:
 
 - stable id, objective, exact dependencies and edge reasons;
@@ -174,21 +238,25 @@ This task-wide read authority is part of the proposal, not an ad hoc escalation
 Keep tasks small enough for one complete patch using compact exact replacements, and separate independent outputs during planning.
 
 Impact closure must name affected existing tests and fixtures; a suite made only from newly added tests is insufficient.
+In `impactClosure.relatedTests`, `current-task` means this task edits that test: its path must appear in a phase's `write` set.
+Use `regression-task` with `regressionTaskId` when another planned task owns the edit; use `unaffected` with evidence when an existing test is preserved without edits, even if it remains in `affectedSuite`.
+Do not expand write sets merely to satisfy a disposition label.
 For public UI or API work, seal the relevant route authorization, page state, API response and contract, public HTML/template/theme behavior, and an approved browser E2E check when those surfaces are affected.
 
 The plan admits only shell-free `vitest`, `package-script`, `static-check`, or ordered `steps` contracts.
 `dev-browser` is required only by an approved browser E2E contract; its absence does not block unrelated tasks or stages.
-Pin local runners, package scripts, arguments, `minTests`, classifications, and `noInstall` behavior.
+Pin local runners, package scripts, arguments, `minTests`, and `noInstall` behavior; sealed classifications are derived from phase/purpose when omitted.
 Reject shell operators, implicit downloads, absolute/escaping paths, missing local capability, and unsupported verification shapes during Design readiness.
 
-After current Gate A approval, send the complete draft through `write-artifact` only to the relative path `plan-draft.json`.
+After current Gate A approval, send the author draft through `write-artifact` only to the relative path `plan-draft.json`.
 Before mutation-owning compilation, use the read-only typed preflight; it validates the same fixed draft and returns task/output counts plus hashes without installing canonical files or journaling a plan revision:
 
 ```json
 {"action":"design","request":{"operation":"validate-plan-draft","runId":"<run-id>"}}
 ```
 
-If preflight fails, use its safe structured diagnostics (`code`, and when applicable `taskId`, `phase`, `field`, `category`, `owner`, `verificationId`, or `outputId`) to repair the exact boundary.
+If preflight fails, correct the returned diagnostic batch using `field`, `path`, `expectedPaths`, `actualPaths`, and code-owned `hint` where available.
+Path lists marked `pathsTruncated` are partial; inspect only the identified boundary when more detail is needed.
 Do not bisect the draft blindly or repeat an unchanged validation/finalization request.
 After preflight succeeds, invoke code-owned compilation:
 
@@ -196,7 +264,8 @@ After preflight succeeds, invoke code-owned compilation:
 {"action":"design","request":{"operation":"compile-plan","runId":"<run-id>","operationId":"<unique-operation>"}}
 ```
 
-The compiler reads only that fixed safe path, validates capability and graph closure again, atomically installs canonical `implement-plan.json`, and returns its raw and canonical hashes.
+The compiler reads only that fixed safe path, validates capability and graph closure again, installs the generated verification bindings into the existing `tasks.md` and canonical `implement-plan.json` under the same compilation lease, and records the plan only after both writes succeed.
+It returns the plan’s raw and canonical hashes.
 Do not hand-assemble canonical plan bytes, hashes, generated task Markdown, or receipts.
 The canonical `ImplementPlan` contains:
 
@@ -257,6 +326,8 @@ Endpoint/transport failure in an evidence packet pauses that packet and retains
 Missing package scripts/runners or a non-executable verification contract must be corrected before Gate B; they must not be deferred as an Implement surprise.
 
 Report `READY_TO_IMPLEMENT` only when strict validation passes, user decisions are resolved and both private proofs are current, all artifacts/hashes/traceability resolve, and the canonical plan is executable.
+After successful code-owned finalization, return one brief readiness response with the change and delivery revision.
+Do not reread receipts, survey directories or restate the full decision history after that success; finalization has already reread and validated the delivery.
 Successful finalization deactivates private dispatch before an unrelated later request.
 Gate waits remain active for direct follow-up; if the user explicitly ends an unfinished Design interaction, send `{"action":"finish"}`.
 Otherwise report the current Design state, retained evidence, and the one unresolved decision or artifact that prevents readiness.
@@ -266,25 +337,3 @@ Never send `operation: "finish"`; exit only with `{"action":"finish"}`.
 Do not implement product code and do not archive, publish, release, stage, or commit implicitly.
 
 <!-- ABEL:END -->
-
-## Structured authority for new work
-
-Use a structured `ChangeContract` as the Gate A `contract` for new designs: `goal`, `acceptance` (stable `id`, accepted `statement`, complete structured `verification`), `constraints` (stable `id` and `statement`), and `policy` (`writeRoots`, allowed dependency names in `dependencies`, and `verificationModes`).
-Use `behavior` by default; explicitly permit `mechanical` or `refactor` only for suitable work.
-Present the accepted goal, constraints and scope together with the recommended choices.
-Do not include secrets or raw conversation in the contract.
-
-Code normalizes and hashes the object.
-The journal retains the normalized authority and injects it into compiled plans; callers do not compute hashes.
-Keep acceptance IDs and statements stable when reshaping a plan.
-Compilation rejects missing acceptance verification, outside-policy writes/dependencies, or substituted authority.
-Historical prose approvals remain readable; their existence does not authorize new scope.
-
-Mechanical tasks may write document/data/config files (`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, `.lock`).
-Refactor tasks preserve accepted verifier inputs.
-Both must declare no public behavior change and require an explicitly allowed mode in Gate A. Specify task `verificationMode` and Green (plus optional Refactor); omit Red in the draft.
-The compiler handles its internal compatibility representation.
-Runtime captures baseline and executes Green with affected, cumulative and post-apply verification, without generating a Red candidate.
-Behavior tasks continue to require Red/Green.
-
-An AGENTS checkpoint additionally requires its exact target path in `policy.writeRoots`; a broad source root does not grant AGENTS authority.

package/src/activity-contracts.ts

@@ -0,0 +1,82 @@
+export type PacketActivityState =
+  | "queued"
+  | "preparing"
+  | "connecting"
+  | "waiting-first-response"
+  | "running"
+  | "retrying"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "timed-out";
+
+export type PacketFailureReason =
+  | "subagent failed"
+  | "subagent cancelled"
+  | "phase timed out";
+
+export interface PacketActivityEvent {
+  state: PacketActivityState;
+  requestId: string;
+  role: string;
+  phase: string;
+  objective: string;
+  sequence: number;
+  attempt?: number;
+  maxAttempts?: number;
+  code?: string;
+  wait?: string;
+  failureReason?: PacketFailureReason;
+}
+
+export type PacketActivityObserver = (
+  event: PacketActivityEvent,
+) => void | Promise<void>;
+
+export const WORKFLOW_ACTIVITY_STATES = [
+  "queued",
+  "preparing",
+  "connecting",
+  "waiting-first-response",
+  "running",
+  "validating",
+  "retrying",
+  "verifying",
+  "paused",
+  "approval-needed",
+  "applying",
+  "recovering",
+  "operation-cancelled",
+  "discarded",
+  "rejected",
+  "completed",
+] as const;
+
+export type WorkflowActivityState = (typeof WORKFLOW_ACTIVITY_STATES)[number];
+export type ActivityState = PacketActivityState | WorkflowActivityState;
+export type TerminalActivityState =
+  | Exclude<
+      PacketActivityState,
+      | "queued"
+      | "preparing"
+      | "connecting"
+      | "waiting-first-response"
+      | "running"
+      | "retrying"
+    >
+  | WorkflowActivityState;
+
+export interface WorkflowActivityUpdate {
+  state: WorkflowActivityState;
+  stage?: "abel-design" | "abel-implement";
+  runId?: string;
+  change?: string;
+  taskId?: string;
+  phase?: string;
+  objective?: string;
+  code?: string;
+  attempt?: number;
+  maxAttempts?: number;
+  wait?: string;
+  legalCommands?: string[];
+}

package/src/candidate-artifact.ts

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { diffWritePaths } from "./contracts.ts";
+import {
+  type BeginCandidateInput,
+  TASK_LEDGER_LIMITS,
+  type TaskLedger,
+} from "./task-ledger.ts";
+import type { DurableCandidateProposal } from "./workflow-policy.ts";
+
+type ArtifactProposal = Extract<
+  DurableCandidateProposal,
+  { kind: "candidate" | "sealed-candidate" }
+>;
+interface CandidateArtifactInput {
+  ledger: TaskLedger;
+  identity: BeginCandidateInput;
+  proposal: ArtifactProposal;
+}
+
+const sha256 = (bytes: Uint8Array) =>
+  createHash("sha256").update(bytes).digest("hex");
+
+/** Inspect the same sealed bytes for normal phases and repairs. Callers own recovery policy. */
+export function inspectCandidateArtifact({
+  ledger,
+  identity,
+  proposal,
+  approvedPaths,
+}: CandidateArtifactInput & { approvedPaths: readonly string[] }):
+  | { ok: true; bytes: Buffer; paths: string[] }
+  | {
+      ok: false;
+      code: "candidate-diff-invalid" | "write-set-mismatch";
+      stage: string;
+    } {
+  const invalid = (stage: string) => ({
+    ok: false as const,
+    code: "candidate-diff-invalid" as const,
+    stage,
+  });
+  ledger.beginCandidate(identity);
+  let bytes: Buffer;
+  if (proposal.kind === "sealed-candidate") {
+    if (
+      proposal.candidateId !== identity.candidateId ||
+      !/^[a-f0-9]{64}$/u.test(proposal.artifactHash) ||
+      !Number.isSafeInteger(proposal.bytes) ||
+      proposal.bytes < 1 ||
+      !Array.isArray(proposal.paths)
+    )
+      return invalid("candidate-seal");
+    bytes = Buffer.from(ledger.readSealedCandidate(identity.candidateId));
+    if (
+      bytes.length !== proposal.bytes ||
+      sha256(bytes) !== proposal.artifactHash
+    ) {
+      throw new Error("candidate-seal-integrity-invalid");
+    }
+  } else {
+    if (
+      !(proposal.bytes instanceof Uint8Array) ||
+      proposal.bytes.length === 0
+    ) {
+      return invalid("candidate-submit");
+    }
+    bytes = Buffer.from(proposal.bytes);
+  }
+  let paths: string[];
+  try {
+    paths = diffWritePaths(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    ).paths;
+  } catch {
+    return invalid("candidate-diff");
+  }
+  if (paths.some((relative) => !approvedPaths.includes(relative))) {
+    return {
+      ok: false,
+      code: "write-set-mismatch",
+      stage: "candidate-boundary",
+    };
+  }
+  if (
+    proposal.kind === "sealed-candidate" &&
+    JSON.stringify([...proposal.paths].sort()) !==
+      JSON.stringify([...paths].sort())
+  ) {
+    return invalid("candidate-seal");
+  }
+  return { ok: true, bytes, paths };
+}
+
+/** Seal after isolated patch/dependency checks, before any phase verification. */
+export function sealCandidateArtifact({
+  ledger,
+  identity,
+  proposal,
+  bytes,
+}: CandidateArtifactInput & { bytes: Buffer }):
+  | { ok: true; artifactHash: string }
+  | { ok: false; kind: "paused" | "retryable"; code: string; stage: string } {
+  if (proposal.kind === "sealed-candidate")
+    return { ok: true, artifactHash: proposal.artifactHash };
+  let sequence = 0;
+  for (
+    let offset = 0;
+    offset < bytes.length;
+    offset += TASK_LEDGER_LIMITS.maxSegmentBytes
+  ) {
+    const segment = bytes.subarray(
+      offset,
+      Math.min(offset + TASK_LEDGER_LIMITS.maxSegmentBytes, bytes.length),
+    );
+    const accepted = ledger.appendCandidateSegment({
+      ...identity,
+      sequence,
+      bytes: segment,
+      segmentHash: sha256(segment),
+    });
+    if (!accepted.ok)
+      return {
+        ok: false,
+        kind: "paused",
+        code: accepted.code,
+        stage: "candidate-segment",
+      };
+    sequence++;
+  }
+  const sealed = ledger.sealCandidate({
+    ...identity,
+    segmentCount: sequence,
+    totalBytes: bytes.length,
+    candidateHash: sha256(bytes),
+  });
+  return sealed.ok
+    ? { ok: true, artifactHash: sealed.artifactHash }
+    : {
+        ok: false,
+        kind: "retryable",
+        code: sealed.code,
+        stage: "candidate-seal",
+      };
+}

package/src/candidate-patch.ts

@@ -147,7 +147,7 @@ export function compileCandidatePatch(input: {
     return state;
   };
 
-  for (const operation of input.operations) {
+  for (const [operationIndex, operation] of input.operations.entries()) {
     if (
       !operation ||
       typeof operation !== "object" ||
@@ -166,20 +166,40 @@ export function compileCandidatePatch(input: {
           throw new Error("candidate-patch-replace-invalid");
         }
         const relative = requirePath(operation.path);
+        const reject = (reason: string, hint: string): never => {
+          throw new Error(
+            JSON.stringify({
+              code: "candidate-patch-replace-invalid",
+              operationIndex,
+              ...(relative.length <= 512 && !/[\p{Cc}\p{Cf}]/u.test(relative)
+                ? { path: relative }
+                : {}),
+              reason,
+              hint,
+            }),
+          );
+        };
         if (!writePaths.has(relative)) {
-          throw new Error("candidate-patch-replace-invalid");
+          reject(
+            "path-not-authorized",
+            "Use only approved write paths; request context instead of widening authority.",
+          );
         }
         const state = load(relative);
-        if (
-          state.current === null ||
-          occurrenceCount(state.current, operation.oldText) !== 1
-        ) {
-          throw new Error("candidate-patch-replace-invalid");
+        const current =
+          state.current ??
+          reject(
+            "file-not-found",
+            "Use create for a new approved file, or correct the path.",
+          );
+        const occurrences = occurrenceCount(current, operation.oldText);
+        if (occurrences !== 1) {
+          reject(
+            occurrences === 0 ? "old-text-not-found" : "old-text-ambiguous",
+            "Read the approved file and supply exact unique oldText, including enough surrounding context. Operations are applied in order.",
+          );
         }
-        state.current = state.current.replace(
-          operation.oldText,
-          operation.newText,
-        );
+        state.current = current.replace(operation.oldText, operation.newText);
         break;
       }
       case "rewrite": {

package/src/candidate-workspace.ts

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import { lstatSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { observeSafePath } from "./safe-path.ts";
+
+export function runGitApply(
+  root: string,
+  diff: Uint8Array,
+  checkOnly: boolean,
+  signal: AbortSignal,
+): Promise<"ok" | "failed" | "cancelled"> {
+  if (signal.aborted) return Promise.resolve("cancelled");
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value: "ok" | "failed" | "cancelled") => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", abort);
+      resolve(value);
+    };
+    const child = spawn(
+      "git",
+      [
+        "apply",
+        ...(checkOnly ? ["--check"] : []),
+        "--recount",
+        "--whitespace=nowarn",
+        "-",
+      ],
+      { cwd: root, shell: false, stdio: ["pipe", "ignore", "ignore"] },
+    );
+    const abort = () => {
+      child.kill("SIGTERM");
+      settle("cancelled");
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    child.once("error", () => settle(signal.aborted ? "cancelled" : "failed"));
+    child.once("close", (code) =>
+      settle(signal.aborted ? "cancelled" : code === 0 ? "ok" : "failed"),
+    );
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(Buffer.from(diff));
+  });
+}
+export function revisionChanges(
+  root: string,
+  paths: readonly string[],
+): Record<
+  string,
+  { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
+> {
+  const changes: Record<
+    string,
+    { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
+  > = {};
+  for (const relative of [...new Set(paths)].sort()) {
+    const observation = observeSafePath(root, relative);
+    if (observation.kind === "absent") {
+      changes[relative] = { kind: "absent" };
+      continue;
+    }
+    if (observation.kind !== "file") {
+      throw new Error("workflow-candidate-path-unsafe");
+    }
+    const target = path.join(root, ...relative.split("/"));
+    const stat = lstatSync(target);
+    changes[relative] = {
+      kind: "file",
+      bytes: readFileSync(target),
+      mode: stat.mode & 0o777,
+    };
+  }
+  return changes;
+}