Skip to content
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,10 @@ Feedback:
paths are affected, including checking existing APIs before accepting a new
one. The workflow or coordinator owns mechanical validation and review
bookkeeping.
- Start Fable reviews without waiting for CI on `main` or the reviewed branch.
Main health and required checks remain merge gates; a review pass waives
neither.
- Start internal feedback reviews without waiting for CI. Start final Fable
delivery review only after the operator submits the exact draft with internal
feedback complete and required PR CI green. Main health and required checks
remain merge gates.
- When a required Fable review is unavailable (including exhausted quota), use
Codex Astra (`gpt-6-astra`) with the same independence from the Implementor,
scope, reasoning-effort policy and correction limits. Reconcile any in-flight
Expand Down
73 changes: 58 additions & 15 deletions examples/adversarial-implementation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,11 +248,12 @@ xmd run --allow-absolute /absolute/path/to/workflow/examples/adversarial-impleme
--include /absolute/path/to/workflow/examples/adversarial-implementation/components --raw
```

`status` starts no model. It reads the saved joined review, the current PR and
GitHub's CI workflow runs. Its `nextAction` is computed from the same facts as
its `status` and `remaining` fields. When it requests `review`, select
`--props-action review` on that command to perform the independent review with
the provider, model, effort and session recorded at launch. The review uses
Read `status` to see the current heads, submitted revision, required gates,
and next action. After exact-SHA internal feedback and green required CI,
run the same command with `--props-action submit --props-revision <full SHA>`.
Submission pins the clean checkout's commit on the matching open draft PR
against main. Interim pushes, feedback, CI retries and status reads leave the
draft waiting for submission. The review uses
normal coding-agent permissions in a provider scope of its own. It receives the
original captured acceptance text and may inspect source and run focused checks;
it receives no implementation, delegation, posting or merge task.
Expand Down Expand Up @@ -291,14 +292,15 @@ again. `status`, `closeout` and `reconcile` ask nothing and start no reviewer.

```text
feedback pending -> continue original feedback
feedback ready -> independent review pending -> joined exact-commit verdict
| Fable unavailable/refused -> one Astra review (review)
feedback + green required CI -> explicit submit -> joined exact-commit verdict
| Fable unavailable/refused -> one Astra review (submit)
| no reviewer completed -> review_held: answer via review
| incomplete/uncertain -> reconcile original call
| blocking finding -> request approved repair
| pass + required CI + main -> finish PR metadata
| all passed + PR ready -> await authorized merge
| confirmed merge -> delivered
| comment pending -> publish-review
| published changes required -> request approved repair
| published pass + checks -> ready
| all passed + PR ready -> await authorized merge
| confirmed merge -> delivered
```

Independent review summaries allow 1500 characters; detailed observations belong
Expand Down Expand Up @@ -340,6 +342,28 @@ and saves a raw reply the execution joined but never wrote. It never shortens te
a model call or overwrites a contradictory receipt. Missing or uncertain execution
continues to hold. Status uses this same validation boundary to read receipts.

`submit` and `reconcile` publish each validated verdict as a comment on the
current pull request, including findings that require repair. The comment
names the exact reviewed commit and the reviewer who supplied the result.
Delivery uses `<PullRequest.Comments>` to reconcile and verify the comment. With
the native GitHub provider, include the repository URL in the host's
`XMD_WORKFLOW_GITHUB_PULL_REQUESTS` allowlist. For a host that reads one repository:

```sh
export XMD_WORKFLOW_GITHUB_PULL_REQUESTS='{"allowed":["https://github.com/owner/repository"]}'
```

Once GitHub returns the matching comment, the workflow saves its URL with the
reviewed SHA. A new head has its own comment.

If `nextAction` is `publish_review`, use `--props-action publish-review` with
the same record and PR number. It checks for the matching comment before any
write and adopts it if GitHub already accepted it. Concurrent calls with the
same delivery record share one write reservation per PR and reviewed SHA.
If a write could have reached GitHub and no matching comment is visible, the
reservation stays in place for reconciliation. `status` and `closeout` only
read GitHub. A pending comment holds readiness and the repair handoff.

Reconciliation is limited to independent review from a work item launched under
the same response contract. Its assignment retains the exact response schema; a
missing or different schema refuses rather than reinterpreting an old reply. It validates only corrections recorded under the original review assignment.
Expand Down Expand Up @@ -377,8 +401,27 @@ Main health reuses the repository's authoritative selection
rule for a push to main's exact current head. Pending, cancelled, skipped and
failed runs cannot pass. The maintainer-applied `ci-main-red-fix` exception keeps
the repository's CI contract: it substitutes composability for the main lookup
inside CI. A draft PR remains `publication_pending`; only a confirmed merge with
a merge commit reports `delivered`. Refresh status before acting on readiness.
inside CI. Run `--props-action ready` when status reports `ready_pending`.
It verifies the existing PASS comment, then refreshes the source and checks.
The result gives the maintainer the exact reviewed SHA to compare with the
current GitHub head before marking the draft ready. Repeating the command
returns the same comment on the same revision. The GitHub readiness mutation
accepts the PR identity and has no expected-head field. Status observes the
maintainer's transition and reports `ready_for_merge` while the exact gates
still pass. Merge requires separate authorization. A confirmed merge with a
merge commit reports `delivered`.

If the local or remote head moves, status retains the submitted SHA and
original attempt and reports both observed heads. New review attempts record
the local HEAD reflog before and after the reviewer runs. A change in its
history holds the joined reply for reconciliation, even if the checkout has
returned to the submitted SHA. A disrupted primary attempt also holds before
it can select a replacement reviewer. Restore the submitted
revision for publication or readiness, or use `reconcile` to recover the
original attempt. Supply `--props-revision <full SHA>` when selecting among
older attempts. A joined changes-required verdict with a verified comment
allows an approved repair to be submitted after fresh exact feedback and
green required CI. Submit the repair explicitly with its own SHA.

The saved `status.json` is the last observation, not a second execution state.
Use the command for a current answer. Local records are trusted workflow
Expand Down Expand Up @@ -782,8 +825,8 @@ including whether existing APIs suffice. Mechanical validation and review
bookkeeping stay with their existing workflow or coordinator owners. This guide
adds no workflow phase or review stage.

Start required Fable reviews when the exact feedback commit and focused evidence
are ready, without waiting for CI on `main` or the reviewed branch. When Fable
Start final Fable review when the operator submits the exact draft with
completed internal feedback and green required PR CI. When Fable
is unavailable, including exhausted Claude quota, use an independent Codex Astra
(`gpt-6-astra`) reviewer under the same scope, effort policy and correction
limits. Reconcile any in-flight call and preserve its findings before fallback.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,12 @@ Status: {status.status}

Revision: {reportRevision}

<If condition={status.local != null}>
Local head: {status.local.head}

Pull request head: {status.remote.observedRevision ?? status.remote.revision}
</If>

Next action: {status.nextAction}

<Each in={status.required} let="gate">
Expand All @@ -30,6 +36,10 @@ Next action: {status.nextAction}
<If condition={status.review != null}>
Independent review: {status.review.result.verdict}

<If condition={status.reviewPublication?.state === "verified"}>
Published review comment {status.reviewPublication.url}
</If>

{status.review.result.summary}

<Each in={status.review.result.findings} let="finding">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ props:
selection: {type: object}
position: {type: integer, minimum: 0, maximum: 1}
attempt: {type: string, pattern: '^/'}
branch: {type: string, minLength: 1}
required: [delivery, selection, position, attempt]
additionalProperties: false
---
Expand All @@ -15,12 +16,24 @@ props:
A release that fails ends the run and leaves the attempt reserved, so it holds
for reconciliation and can never select a replacement.

<Delivery.Source repository={props.delivery.repository} trackHead={true} as="before" />
<Dir path={props.attempt}><File path="source-before.json"><Json value={before} /></File></Dir>
<If condition={!before.clean || before.head !== props.selection.revision || props.branch !== undefined && before.branch !== props.branch}><Fail message="Source changed before dispatch. Preserve the reserved attempt for reconciliation." /></If>
<If condition={before.headHistory === null}><Fail message="Review requires a readable HEAD reflog before dispatch. Preserve the reserved attempt for reconciliation." /></If>
<Let as="entry" value={props.selection.reviewers[props.position]} />
<Dir path={props.attempt}><File path="assignment.json"><Json value={{work:props.selection.work,revision:props.selection.revision,reviewer:entry.reviewer,acceptance:props.selection.policy.acceptance,responseSchema:props.selection.responseSchema,...(props.selection.maxResponseCorrections === undefined ? {} : {maxResponseCorrections:props.selection.maxResponseCorrections})}} /></File></Dir>
<Try>
<Delivery.Role delivery={props.delivery} revision={props.selection.revision} reviewer={entry.reviewer} choices={entry.choices} position={props.position} attempt={props.attempt} />
<Dir path={props.attempt}><File path="execution.json"><Json value={{status:"completed",failure:null}} /></File></Dir>
<Delivery.Source repository={props.delivery.repository} trackHead={true} as="after" />
<Dir path={props.attempt}>
<File path="source-after.json"><Json value={after} /></File>
<File path="execution.json"><Json value={{status:"completed",failure:null}} /></File>
</Dir>
<Catch as="error">
<Dir path={props.attempt}><File path="execution.json"><Json value={{status:"failed",failure:error.name + ": " + error.message}} /></File></Dir>
<Delivery.Source repository={props.delivery.repository} trackHead={true} as="after" />
<Dir path={props.attempt}>
<File path="source-after.json"><Json value={after} /></File>
<File path="execution.json"><Json value={{status:"failed",failure:error.name + ": " + error.message}} /></File>
</Dir>
</Catch>
</Try>
26 changes: 26 additions & 0 deletions examples/adversarial-implementation/components/Delivery/Gates.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
description: 'Read exact feedback, checkout and GitHub gates for delivery. Use <Delivery.Gates delivery={delivery} number={123} as="gates" />.'
props:
type: object
properties:
delivery: {type: object}
number: {type: integer, minimum: 1}
required: [delivery, number]
additionalProperties: false
returns: {type: object}
---

<Delivery.Schema as="schemas" />
<Parse schema={schemas.policy} as="policy"><Json value={props.delivery.policy} /></Parse>
<Let as="feedback" value={null} />
<Dir path={props.delivery.directory}><Glob include={["feedback.json"]} as="files" /></Dir>
<If condition={files.length !== 0}>
<Ticket.Text path={props.delivery.directory + "/feedback.json"} as="text" />
<Parse schema={{type:"object",properties:{status:{const:"feedback_ready"},revision:{type:"string",pattern:"^[0-9a-f]{40}$"}},required:["status","revision"],additionalProperties:false}} as="feedback">{text}</Parse>
</If>
<Delivery.Remote repository={policy.repository} number={props.number} as="remote" />
<Delivery.Source repository={props.delivery.repository} as="source" />
<Let as="ciPassed" value={remote.ciGreen === true && remote.ci?.status === "completed" && remote.ci?.conclusion === "success"} />
<Let as="mainPassed" value={remote.mainRepair || remote.main.run?.status === "completed" && remote.main.run?.conclusion === "success"} />
<Let as="sourceMatches" value={source.clean && remote.stable && remote.revision === source.head && remote.branch === source.branch && remote.base === "main"} />
<Return value={{feedback,remote,source,ciPassed,mainPassed,sourceMatches,eligible:sourceMatches && feedback?.revision === source.head && remote.state === "open" && remote.draft && ciPassed}} />
18 changes: 18 additions & 0 deletions examples/adversarial-implementation/components/Delivery/Legacy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
description: 'Find original attempts available for recovery. Use <Delivery.Legacy delivery={delivery} as="revisions" />.'
props:
type: object
properties:
delivery: {type: object}
required: [delivery]
additionalProperties: false
returns: {type: array}
---

<Dir path={props.delivery.directory}>
```bash exec as="listing"
printf '%s\n' review-*
```
</Dir>
<If condition={listing.exitCode !== 0}><Fail message="Could not list retained review attempts." /></If>
<Return value={listing.stdout.trim().split("\n").filter(path => /^review-[0-9a-f]{40}$/.test(path)).map(path => path.slice(7))} />
45 changes: 45 additions & 0 deletions examples/adversarial-implementation/components/Delivery/Pin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
description: 'Read the admitted candidate and its successor slot. Use <Delivery.Pin delivery={delivery} number={123} as="admission" />.'
props:
type: object
properties:
delivery: {type: object}
number: {type: integer, minimum: 1}
required: [delivery, number]
additionalProperties: false
returns: {type: object}
---

<Let as="prefix" value={"candidate-" + props.number + "-"} />
<Dir path={props.delivery.directory}><Glob include={[prefix + "*/admission.json"]} as="records" /></Dir>
<Let as="pin" value={null} />
<Let as="seen" value={[]} />
<Let as="index" value={1} />
<Let as="schema" value={{type:"object",properties:{schema:{const:"delivery-candidate.v1"},work:{const:props.delivery.work},repository:{const:props.delivery.policy.repository},checkout:{const:props.delivery.repository},number:{const:props.number},revision:{type:"string",pattern:"^[0-9a-f]{40}$"},branch:{type:"string",minLength:1},previous:{type:["string","null"]},feedback:{type:"object"},ci:{type:"object"},repair:{type:["object","null"]}},required:["schema","work","repository","checkout","number","revision","branch","previous","feedback","ci","repair"],additionalProperties:false}} />
<Let as="invalid" value={false} />
<If condition={records.length !== 0}>
<Loop max={records.length}>
<Let as="expected" value={prefix + index + "/admission.json"} />
<If condition={!invalid && records.includes(expected)}>
<Ticket.Text path={props.delivery.directory + "/" + expected} as="text" />
<SafeParse schema={schema} as="read">{text}</SafeParse>
<If condition={read.ok && read.value.previous === (pin?.revision ?? null) && !seen.includes(read.value.revision)}>
<Let as="pin" value={read.value} />
<Let as="seen" value={[...seen,pin.revision]} />
<Let as="index" value={index + 1} />
<Else>
<Let as="invalid" value={true} />
</Else>
</If>
<Else>
<Let as="invalid" value={true} />
</Else>
</If>
</Loop>
</If>
<Let as="slot" value={props.delivery.directory + "/" + prefix + index} />
<Let as="quoted" value={"'" + slot.replaceAll("'","'\"'\"'") + "'"} />
```bash exec as="occupied"
test -e {quoted} -o -L {quoted}
```
<Return value={{pin,slot,incomplete:invalid || occupied.exitCode === 0,seen}} />
15 changes: 15 additions & 0 deletions examples/adversarial-implementation/components/Delivery/Ready.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
description: 'Verify the exact reviewed draft for maintainer readiness. Use <Delivery.Ready delivery={delivery} number={123} as="status" />.'
props:
type: object
properties:
delivery: {type: object}
number: {type: integer, minimum: 1}
required: [delivery, number]
additionalProperties: false
returns: {type: object}
---

<Delivery.Status delivery={props.delivery} number={props.number} as="status" />
<If condition={status.pin === null || !["ready_pending","ready_for_merge"].includes(status.status) || status.reviewPublication?.state !== "verified"}><Fail message={"Readiness requires the submitted PASS and verified comment. Next action is " + status.nextAction + "."} /></If>
<Return value={status} />
Loading
Loading