Resume held workflows after recording a design decision

examples/adversarial-implementation/README.md

@@ -535,6 +535,85 @@ custom/workflow provider storage contract or migration of old inline records.
 External reviewer models and publication use their existing workflows. The
 phase entry retains the implementation workflow's role and model policy.
 
+### Resolve a decision hold
+
+A Planner or Architect that returns `needs_decision`, and an Implementor that
+returns `needs_discovery` naming the Architect, hold the ticket for an accepted
+decision. When the hold is at the clean launch revision before implementation
+feedback, its envelope names the supported operation:
+
+```json
+{"entry": "resolve-decision.md", "gate": "planning", "action": "resolve_decision",
+ "result": "/absolute/path/to/work/attempts/0000/result.json", "input": "ticket-decision.v1"}
+```
+
+Save the decision and its provenance as text files, then save one request that
+binds them to this exact hold. Every field is required and no other field is
+accepted:
+
+```json
+{
+  "schema": "ticket-decision.v1",
+  "work": "selected-task",
+  "continuation": {"path": "/absolute/path/to/work/continuations/HASH.json", "utf8Bytes": 13240, "sha256": "HASH"},
+  "heldResult": {"path": "/absolute/path/to/work/attempts/0000/result.json", "utf8Bytes": 2210, "sha256": "RESULT_HASH"},
+  "disposition": "accept",
+  "decision": {"path": "/absolute/path/to/decision.md", "utf8Bytes": 412, "sha256": "DECISION_HASH"},
+  "provenance": {"path": "/absolute/path/to/provenance.md", "utf8Bytes": 96, "sha256": "PROVENANCE_HASH"},
+  "acceptedInputs": []
+}
+```
+
+`continuation` copies the held envelope's descriptor and `heldResult` the
+retained descriptor of its final call's result. Each artifact descriptor names an
+absolute path and its exact UTF-8 byte length and SHA-256. The decision and
+provenance are always selected for the routed owner, followed by
+`acceptedInputs` in order. A recorded reference keeps its first text; give changed
+text a fresh path. Provenance states the actual authority, such as standing
+coordinator authority. It is evidence for the routed owner; it neither overrides
+a permission nor records a new human answer.
+
+```bash
+deno task xmd run --allow-absolute examples/adversarial-implementation/resolve-decision.md \
+  --props-record /absolute/path/to/held-record.json \
+  --props-decision /absolute/path/to/decision.json \
+  --include examples/adversarial-implementation/components --raw
+```
+
+Resolution calls no role. It validates the held result, records the decision under
+the hold's continuation digest, prepares the original owner and publishes the
+successor. Continue the returned envelope with `continue.md --props-steps 1`; that
+ordinary step dispatches the owner through the existing source, identity, input
+and publication checks:
+
+| Held result | Disposition | Next owner | Then |
+| --- | --- | --- | --- |
+| discovery Planner `needs_decision` | `accept` | original Planner | original Implementor |
+| discovery Planner `needs_decision` | `amend` | original Architect | retained Planner, then original Implementor |
+| discovery Architect `needs_decision` | `accept` | same Architect | retained Planner, then original Implementor |
+| implementation Implementor `needs_discovery` naming the Architect | either | original Architect | retained Planner, then original Implementor |
+
+The original task, sessions, calls, results, delivered inputs, source anchor and
+correction count are unchanged; resolution grants no further corrections. Every
+other hold refuses, including an Architect amendment, an API conflict routed to
+the Planner, execution failure, uncertain native work, changed input, source
+mismatch, an exhausted correction bound and publication failure. A held result
+whose phase execution failed after the result was saved also refuses; resolution
+requires the call's execution record to show completion. A dirty or moved
+checkout, prior implementation feedback, a stale or foreign binding and a changed
+input also refuse. A refusal returns a held envelope carrying the failure and
+leaves the managed ticket unchanged; keep the original envelope.
+
+Repeating the same request against the same hold returns its recorded successor
+without publishing again. The repeat checks the evidence the successor retained,
+under current File permission and protection; it does not reread the decision's
+original files, so they may later change or disappear. A different decision for a resolved hold refuses. If
+reservation, publication or the receipt is interrupted, the hold stays held and
+its reservation directory preserves the first failure for operator disposition. A
+matching successor file alone does not confirm the interrupted write. Repeated
+continuation of an older envelope reuses the existing call reservation and resends
+no role effect.
+
 ## Supervise a live REPL phase
 
 Keep the original ACP call pending, or reconnect passively with the existing

examples/adversarial-implementation/components/Entry/ResolveDecision.md

@@ -0,0 +1,19 @@
+---
+props:
+  type: object
+  properties:
+    record: {type: string}
+    decision: {type: string}
+  required: [record, decision]
+  additionalProperties: false
+returns: {type: object}
+---
+<Ticket.Read path={props.record} limit={65536} as="text" />
+<Parse schema={{type:"object"}} as="envelope">{text}</Parse>
+<Ticket.Envelope value={envelope} as="envelope" />
+<Ticket.Capture as="resolved"><Ticket.ResolveDecision record={envelope} decision={props.decision} as="work" /><Json value={work} /></Ticket.Capture>
+<If condition={resolved.status === "completed"}>
+<Parse schema={{type:"object"}} as="work">{resolved.output}</Parse>
+<Ticket.Outward value={work} as="bounded" /><Return value={bounded} />
+<Else><Ticket.Outward value={{schema:"ticket-return.v1",work:envelope.work,source:envelope.source,status:"hold",revision:envelope.revision,publication:"held",continuation:envelope.continuation,pending:null,hold:"Decision resolution was refused without changing the managed ticket. Keep the original envelope; correct the decision input or follow the hold's existing recovery.",failure:{name:"DecisionRefused",message:resolved.failure.split("\n").filter(line => !/^\s+at /.test(line)).join("\n").slice(0,1024),data:null}}} as="bounded" /><Return value={bounded} /></Else>
+</If>

examples/adversarial-implementation/components/Ticket/Advance.md

@@ -14,6 +14,8 @@ returns: {type: object}
 ---
 
 A decision or contract conflict holds the ticket for its existing approval gate.
+An implementation discovery hold keeps its validated next owner as a routing fact;
+a hold whose phase execution failed after saving its result records that failure.
 A correction clears prior verdicts. Readiness requires every selected reviewer to
 PASS the same signed implementation SHA; it does not authorize delivery or merge.
 Selected feedback documents remain available across reviews and corrections.
@@ -32,7 +34,7 @@ Selected feedback documents remain available across reviews and corrections.
 <Let as="continuation" value={gate === "planning" ? {phase:"implementation",role:"implementor"} : gate === "architect-discovery" ? {phase:"discovery",role:"planner"} : call.assignment.continuation} />
 <Let as="assignment" value={{...prepared.assignment,continuation}} />
 </If>
-<Return value={{...state,gate,assignment,status:held ? "hold" : "running",dispatchable:!held && props.pending.execution.status !== "failed",hold:held ? {kind:result.outcome,reason:result.handoff} : null,discovery:[...(state.discovery ?? []),{role:call.role,revision:result.revision,result:props.pending.resultPath,requests:result.discoveryRequests ?? [],gaps:result.discoveryGaps ?? []}]}} />
+<Return value={{...state,gate,assignment,status:held ? "hold" : "running",dispatchable:!held && props.pending.execution.status !== "failed",hold:held ? {kind:result.outcome,reason:result.handoff,...(props.pending.execution.status === "failed" ? {execution:"failed"} : {})} : null,discovery:[...(state.discovery ?? []),{role:call.role,revision:result.revision,result:props.pending.resultPath,requests:result.discoveryRequests ?? [],gaps:result.discoveryGaps ?? []}]}} />
 </If>
 <If condition={call.assignment.phase !== "discovery"}>
 <Let as="correction" value={result.outcome === "changes_required" || result.outcome === "missing_evidence"} />
@@ -49,6 +51,6 @@ Selected feedback documents remain available across reviews and corrections.
 <Let as="gate" value={held || result.outcome === "escalate" ? state.gate : correction ? "implementation" : ready ? "feedback-ready" : remaining[0] + "-review"} />
 <Let as="status" value={held ? "hold" : ready ? "feedback_ready" : props.pending.execution.status === "failed" ? "paused" : "running"} />
 <Let as="assignment" value={{...props.pending.manifest.assignment,phase:gate === "implementation" ? "implementation" : "review",assessment:reviewPolicy.assessment,reviewKind:reviewPolicy.kind,revision,priorRevision:props.pending.manifest.assignment.revision,request:result.handoff,handoffInputs:result.handoffInputs ?? [],changedPaths:props.observation.changedPaths,artifacts:[...result.artifacts,props.observation.path],evidence:result.evidence,findings:result.findings,contract:result.contract ?? state.assignment.contract ?? null}} />
-<Return value={{...state,status,dispatchable:!held && !ready && props.pending.execution.status !== "failed",round,gate,revision,reviews,reviewPolicy,exactApproval,exactReview,assignment,feedbackInputs:result.outcome === "complete" && call.role === "implementor" ? [...new Set([...(state.feedbackInputs ?? []),...(state.assignment.handoffInputs ?? []),...(result.handoffInputs ?? [])])] : state.feedbackInputs ?? [],discovery:[...(state.discovery ?? []),...((result.discoveryRequests?.length ?? 0) + (result.discoveryGaps?.length ?? 0) > 0 ? [{role:call.role,revision:result.revision,result:props.pending.resultPath,requests:result.discoveryRequests ?? [],gaps:result.discoveryGaps ?? []}] : [])],feedback:result.outcome === "complete" && call.role === "implementor" ? [props.pending.resultPath,props.observation.path] : state.feedback,hold:held ? {kind:correction ? "correction_bound" : result.outcome,reason:result.handoff} : null}} />
+<Return value={{...state,status,dispatchable:!held && !ready && props.pending.execution.status !== "failed",round,gate,revision,reviews,reviewPolicy,exactApproval,exactReview,assignment,feedbackInputs:result.outcome === "complete" && call.role === "implementor" ? [...new Set([...(state.feedbackInputs ?? []),...(state.assignment.handoffInputs ?? []),...(result.handoffInputs ?? [])])] : state.feedbackInputs ?? [],discovery:[...(state.discovery ?? []),...((result.discoveryRequests?.length ?? 0) + (result.discoveryGaps?.length ?? 0) > 0 ? [{role:call.role,revision:result.revision,result:props.pending.resultPath,requests:result.discoveryRequests ?? [],gaps:result.discoveryGaps ?? []}] : [])],feedback:result.outcome === "complete" && call.role === "implementor" ? [props.pending.resultPath,props.observation.path] : state.feedback,hold:held ? {kind:correction ? "correction_bound" : result.outcome,reason:result.handoff,...(result.outcome === "needs_discovery" ? {next:result.next} : {}),...(props.pending.execution.status === "failed" ? {execution:"failed"} : {})} : null}} />
 
 </If>

examples/adversarial-implementation/components/Ticket/Decision.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { envelope, state } from "./control.ts";
+import { describe, descriptor, readBounded, same, stateLimit, textLimit } from "./text-storage.ts";
+
+export const props = {
+  type: "object",
+  properties: {
+    path: { type: "string", pattern: "^/" },
+    record: { type: "object" },
+    saved: { type: "object" },
+  },
+  required: ["path", "record", "saved"],
+  additionalProperties: false,
+};
+const reference = descriptor.extend({ path: z.string().startsWith("/") }).strict();
+const text = reference.extend({ utf8Bytes: z.number().int().min(1).max(textLimit) }).strict();
+const request = z
+  .object({
+    schema: z.literal("ticket-decision.v1"),
+    work: z.string().min(1),
+    continuation: reference,
+    heldResult: reference,
+    disposition: z.enum(["accept", "amend"]),
+    decision: text,
+    provenance: text,
+    acceptedInputs: z.array(reference),
+  })
+  .strict();
+type Reference = z.infer<typeof reference>;
+
+export default function* Decision(value: unknown) {
+  const input = z
+    .object({ path: z.string().startsWith("/"), record: envelope, saved: state })
+    .strict()
+    .parse(value);
+  const source = yield* readBounded(input.path, stateLimit);
+  const selected = request.parse(JSON.parse(source));
+  const { saved } = input;
+  if (selected.work !== saved.manifest.work) {
+    throw new Error("The decision names another work item; no resolution was recorded.");
+  }
+  if (
+    input.record.continuation === null ||
+    !same(selected.continuation, input.record.continuation)
+  ) {
+    throw new Error(
+      "The decision is bound to another or stale continuation; bind it to this exact confirmed hold.",
+    );
+  }
+  const call = saved.calls.at(-1);
+  const result = typeof call?.result === "string" ? saved.documents[call.result] : undefined;
+  if (result === undefined || !same(selected.heldResult, result)) {
+    throw new Error(
+      "The decision names another held result; bind it to the retained result of the final call.",
+    );
+  }
+  const references = new Map<string, Reference>();
+  for (const entry of [selected.decision, selected.provenance, ...selected.acceptedInputs]) {
+    const prior = references.get(entry.path);
+    if (prior !== undefined && !same(prior, entry)) {
+      throw new Error("One decision reference names different contents: " + entry.path);
+    }
+    references.set(entry.path, entry);
+  }
+  return {
+    request: selected,
+    file: describe(input.path, source),
+    references: [...references.keys()],
+    descriptors: Object.fromEntries(references),
+  };
+}

examples/adversarial-implementation/components/Ticket/DecisionInputs.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { describe, descriptor, readBounded, same, snapshot, textLimit } from "./text-storage.ts";
+
+export const props = {
+  type: "object",
+  properties: { descriptors: { type: "object" }, documents: { type: "object" } },
+  required: ["descriptors", "documents"],
+  additionalProperties: false,
+};
+
+// A first resolution observes each decision input once: a recorded reference keeps
+// its retained text, and a new reference must match its origin's current bytes.
+export default function* DecisionInputs(value: unknown) {
+  const { descriptors, documents } = z
+    .object({
+      descriptors: z.record(z.string(), descriptor),
+      documents: z.record(z.string(), snapshot),
+    })
+    .strict()
+    .parse(value);
+  for (const entry of Object.values(descriptors)) {
+    const retained = documents[entry.path];
+    const current = retained ?? describe(entry.path, yield* readBounded(entry.path, textLimit));
+    if (!same(entry, current)) {
+      throw new Error(
+        (retained === undefined
+          ? "Decision input differs from its descriptor: "
+          : "A recorded reference keeps its first text; give changed text a fresh reference: ") +
+          entry.path,
+      );
+    }
+  }
+  return Object.keys(descriptors);
+}

examples/adversarial-implementation/components/Ticket/Publish.ts

@@ -86,14 +86,41 @@ export default function* Publish(value: unknown) {
           remainingRequiredDeliveryWork: ["independent-review", "required-ci", "main-health"],
         }
       : {};
+  const last = record.calls.at(-1);
+  const hold = record.checkpoint.hold;
+  const decision =
+    !record.checkpoint.dispatchable &&
+    record.checkpoint.status === "hold" &&
+    record.checkpoint.revision === record.manifest.assignment.revision &&
+    record.checkpoint.feedback.length === 0 &&
+    hold?.execution === undefined &&
+    last?.status === "accepted" &&
+    typeof last.result === "string" &&
+    ((hold?.kind === "needs_decision" &&
+      last.assignment.phase === "discovery" &&
+      last.role !== "implementor") ||
+      (hold?.kind === "needs_discovery" &&
+        last.role === "implementor" &&
+        hold.next?.phase === "discovery" &&
+        hold.next.role === "architect"))
+      ? last.result
+      : null;
   const nextAction =
     record.checkpoint.status === "feedback_ready" && typeof deliveryDirectory === "string"
       ? { entry: "delivery.md", record: deliveryDirectory + "/requirements.json", action: "review" }
-      : {
-          entry: "continue.md",
-          gate: record.checkpoint.gate,
-          action: record.checkpoint.dispatchable ? "continue_feedback" : "resolve_feedback_hold",
-        };
+      : decision !== null
+        ? {
+            entry: "resolve-decision.md",
+            gate: record.checkpoint.gate,
+            action: "resolve_decision",
+            result: decision,
+            input: "ticket-decision.v1",
+          }
+        : {
+            entry: "continue.md",
+            gate: record.checkpoint.gate,
+            action: record.checkpoint.dispatchable ? "continue_feedback" : "resolve_feedback_hold",
+          };
   return {
     ...presentation,
     nextAction,