From a69096a6aba1c34006f5bb717bb65a8aefce563c Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 14:14:27 -0700 Subject: [PATCH 1/9] docs(atelier): add accountable dogfood runbook Document the separate planner, worker, recovery, audit, and operator roles for one real Atelier changeset. Define the durable evidence needed at promotion, delegation, recovery, delivery, audit, and explicit acceptance while preserving the v0 boundaries around merge, deployment, and native-ticket mutation. --- skills/atelier/SKILL.md | 7 ++ skills/atelier/references/dogfood.md | 128 +++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 skills/atelier/references/dogfood.md diff --git a/skills/atelier/SKILL.md b/skills/atelier/SKILL.md index 09db7700..eb141448 100644 --- a/skills/atelier/SKILL.md +++ b/skills/atelier/SKILL.md @@ -75,6 +75,13 @@ be supplied to `scripts/audit.py accept` for the one acceptance commit. Reusing report evidence is rejected. Acceptance never implies merge, deployment, native-ticket mutation, or issue closure. +## Dogfood one accountable changeset + +Use `references/dogfood.md` to run the first end-to-end Atelier exercise. It +keeps the planner, worker, fresh recovery task, audit task, and operator as +separate actors; records their durable handoffs; and does not treat a ready pull +request as acceptance, merge, deployment, or ticket completion. + ## Mailbox boundary The strict v1 mailbox schema and fresh-clone reconstruction helper are diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md new file mode 100644 index 00000000..659c7a06 --- /dev/null +++ b/skills/atelier/references/dogfood.md @@ -0,0 +1,128 @@ +# Dogfood one accountable changeset + +Use this runbook to exercise one small Atelier change from a human-approved +assignment through a ready pull request, live audit, and an explicit operator +decision. It is a procedure for collecting evidence, not evidence that any +particular dogfood run succeeded. + +The disposable composition experiment is not a substitute for this run. This +run uses one real GitHub-backed Atelier assignment and the production planning, +claiming, delegation, audit, and acceptance boundaries. + +## Choose the change and roles + +Select one open native GitHub ticket that is independently reviewable, has no +unresolved native blocker, and can finish at one ordinary ready pull request. +Do not use this runbook to add another provider, a stack, merge, deployment, +ticket mutation, or a later evaluation. + +Keep these roles in separate tasks: + +- The planner discusses and promotes the assignment. +- The worker claims it and delegates its implementation to Agent Scripts. +- A fresh recovery task reconstructs state after a deliberate interruption. +- The auditor reads the delivered state and presents predicate verdicts. +- The operator alone accepts or rejects the audited delivery. + +Each task may read native GitHub state and reconstruct the canonical Git +mailbox. No task may rely on another task's transcript, an uncommitted local +file, or a host-local projection as shared state. + +## Plan and promote in a planner task + +1. Complete the host preflight in `host-boundary.md` and capture a complete + GitHub observation at a new read boundary. +2. Read `planning.md`. Create or revise one complete draft with + `scripts/planning.py`; give it a single ticket, bounded scope, non-goals, + constraints, done definition, verification expectations, and review shape. +3. Preview the exact draft revision against a fresh observation and the current + project policy. Show the operator the rendered assignment, policy commit, + authority ceiling, required evidence, and preview digest. +4. Wait for the operator to approve that exact preview. Capture a newer + observation after that confirmation, then promote the same revision with + `scripts/planning.py approve`. + +The promotion is the durable implementation boundary. Drafting, previewing, or +asking to continue does not grant worker authority. + +## Claim and delegate in a separate worker task + +1. Start without the planner transcript. Complete a fresh host preflight, read + the canonical mailbox with `mailbox-validation.md`, and capture a complete + current GitHub observation. +2. Read `claiming.md`. Claim only the approved, eligible assignment with + `scripts/claiming.py claim`; retain the returned claim ID, worker run ID, + continuation token, and approved mailbox commit. +3. Read `delegation.md`. Use `scripts/delegation.py` with `operation: prepare` + to seal one immutable Agent Scripts v2 invocation and its host-owned fresh + observation command into the claim. +4. Give that unchanged invocation to one fresh + `agent-scripts:implement-ticket` worker. The implementation worker follows + Agent Scripts' own workflow, uses every checkpoint before an allowed + external mutation, and sends `candidate_published` immediately after every + remote candidate advancement. +5. Finalize only the returned terminal result with a fresh GitHub observation. + A `ready_pr` receipt must name one open, non-draft, mergeable ordinary pull + request and its exact remote ref and head. A blocked result must preserve its + exact acknowledged candidate, if one exists, and its remaining obligation. + +Atelier validates the invocation, checkpoint fence, candidate acknowledgement, +and terminal result. It does not implement the ticket workflow, merge the pull +request, or close the issue. + +## Exercise interruption and fresh-task recovery + +Deliberately stop the original worker only at a durable boundary: after its +claim, a checkpoint response, candidate acknowledgement, block, release, or +delivery receipt. Do not interrupt an in-flight mailbox write and then invent a +replacement result. + +Start a new task with no earlier task transcript. It must: + +1. repeat the host preflight and reread the native ticket, current policy, and + canonical mailbox; +2. reconstruct the active work, claim fence, checkpoint ledger, receipts, and + any exact remote candidate using `mailbox-validation.md`; +3. verify a declared candidate against its full remote ref and head before + treating it as transferable; and +4. use the explicit `block`, `release`, or `takeover` transition in + `claiming.md` when its preconditions pass. + +The recovery task must retain the prior fence and token as historical evidence. +It must never mint a token, guess a candidate SHA, reuse a stale observation, +or continue an invocation whose material ticket observation has changed. + +## Audit, then obtain an operator decision + +After a delivered `ready_pr` receipt, start a separate audit task. Read +`audit.md`, complete the host preflight, reconstruct the mailbox from its +canonical branch, and capture one complete current GitHub observation. Normalize +the exact aggregate `review-code-change` result and every live review/comment +disposition, then run `scripts/audit.py audit`. + +Present the complete report and its acceptance fence to the operator. Every +predicate must remain visibly `satisfied`, `violated`, `unknown`, or `stale`; +do not summarize a missing predicate as clean. + +Only an explicit confirmation of that exact fence may begin acceptance. Capture +a strictly newer complete observation, then run `scripts/audit.py accept` with +the same evidence and the confirmed fence. Acceptance records the operator's +decision in the mailbox. It does not merge, deploy, mutate or close the native +ticket, delete a branch, or accept the parent initiative. + +## Preserve the evidence packet + +Keep the following identifiers and artifacts available through native GitHub +state or the canonical mailbox: + +| Transition | Required durable evidence | +| --- | --- | +| Approval | Work ID and revision, rendered preview digest, approver/timestamp, policy commit, authority ceiling, and required evidence. | +| Claim and delegation | Claim ID, worker run ID, full checkpoint ledger, immutable invocation digest, and exact Agent Scripts capability identity. | +| Candidate and delivery | Remote URL, full ref, head SHA, candidate acknowledgement, required validation results, independent review identity/verdict, and pull-request topology. | +| Recovery | Previous fence, checkpoint tail, block/release/takeover receipt, rationale, and verified transferable candidate or explicit absence. | +| Audit and acceptance | Complete provider observations, normalized review and feedback dispositions, audit report/fence, explicit operator decision, and acceptance commit when accepted. | + +If any item cannot be reread, is stale, or conflicts with current native or +mailbox state, report that condition. Do not replace it with a narrative claim +that the dogfood run passed. From 2cad5e683171a74889bf220a060b16bdd6f8393e Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 14:28:29 -0700 Subject: [PATCH 2/9] docs(atelier): state the v0 declined-fence boundary Clarify that a declined audit fence must not create an invented rejection record. The work remains delivered until an explicitly authorized product boundary adds a durable rejection transition. --- skills/atelier/references/dogfood.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index 659c7a06..b4bb7e12 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -22,7 +22,7 @@ Keep these roles in separate tasks: - The worker claims it and delegates its implementation to Agent Scripts. - A fresh recovery task reconstructs state after a deliberate interruption. - The auditor reads the delivered state and presents predicate verdicts. -- The operator alone accepts or rejects the audited delivery. +- The operator alone may accept the audited delivery. Each task may read native GitHub state and reconstruct the canonical Git mailbox. No task may rely on another task's transcript, an uncommitted local @@ -110,6 +110,12 @@ the same evidence and the confirmed fence. Acceptance records the operator's decision in the mailbox. It does not merge, deploy, mutate or close the native ticket, delete a branch, or accept the parent initiative. +If the operator declines the fence, do not run `accept` and do not invent a +rejection record. The current v0 production boundary has no durable rejection +transition: the work remains delivered, and a separate authorized product +change is required before this runbook can claim to preserve a rejected +decision. + ## Preserve the evidence packet Keep the following identifiers and artifacts available through native GitHub @@ -121,7 +127,7 @@ state or the canonical mailbox: | Claim and delegation | Claim ID, worker run ID, full checkpoint ledger, immutable invocation digest, and exact Agent Scripts capability identity. | | Candidate and delivery | Remote URL, full ref, head SHA, candidate acknowledgement, required validation results, independent review identity/verdict, and pull-request topology. | | Recovery | Previous fence, checkpoint tail, block/release/takeover receipt, rationale, and verified transferable candidate or explicit absence. | -| Audit and acceptance | Complete provider observations, normalized review and feedback dispositions, audit report/fence, explicit operator decision, and acceptance commit when accepted. | +| Audit and acceptance | Complete provider observations, normalized review and feedback dispositions, audit report/fence, and the acceptance commit when explicitly accepted. A declined fence remains delivered; v0 records no rejection transition. | If any item cannot be reread, is stale, or conflicts with current native or mailbox state, report that condition. Do not replace it with a narrative claim From 71d25fb3f924189631c42be82f8cb305ff74e29a Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 14:43:19 -0700 Subject: [PATCH 3/9] docs(atelier): route epic terminal results to planning Document that a delegated requires-epic result is recorded as a blocked planner handoff, retains any transferable candidate, and never invokes epic execution from the dogfood runbook. --- skills/atelier/references/dogfood.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index b4bb7e12..db9da4ec 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -65,6 +65,9 @@ asking to continue does not grant worker authority. A `ready_pr` receipt must name one open, non-draft, mergeable ordinary pull request and its exact remote ref and head. A blocked result must preserve its exact acknowledged candidate, if one exists, and its remaining obligation. + Finalize `requires_epic` as the production blocked, planner-action receipt; + preserve any transferable candidate and return the assignment to planning. + Do not invoke `implement-epic` from this runbook. Atelier validates the invocation, checkpoint fence, candidate acknowledgement, and terminal result. It does not implement the ticket workflow, merge the pull From c81ba44a7c536884c31e40315b272158aec1fc8e Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 22:37:21 -0700 Subject: [PATCH 4/9] docs(atelier): make recovery lifecycle explicit Branch fresh-task recovery by reconstructed work state so released candidates are reclaimed with a fresh claim and delivered work remains available for audit unless separately authorized rework requires takeover. --- skills/atelier/references/dogfood.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index db9da4ec..1e539549 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -84,12 +84,20 @@ Start a new task with no earlier task transcript. It must: 1. repeat the host preflight and reread the native ticket, current policy, and canonical mailbox; -2. reconstruct the active work, claim fence, checkpoint ledger, receipts, and +2. reconstruct the work lifecycle, claim fence, checkpoint ledger, receipts, and any exact remote candidate using `mailbox-validation.md`; 3. verify a declared candidate against its full remote ref and head before treating it as transferable; and -4. use the explicit `block`, `release`, or `takeover` transition in - `claiming.md` when its preconditions pass. +4. choose the production transition from the reconstructed lifecycle: + - for active work whose worker is being replaced, use `takeover` with the exact + replaced fence; + - for blocked work whose worker is being replaced, use `takeover` and preserve + the unresolved blocker and blocked state; + - for released, approved work, use a fresh `claim`; verify and inherit any exact + transferable candidate, and do not combine release with reacquisition; or + - for delivered work, leave the delivery intact for the separate audit task. + Use delivered `takeover` only after an independently authorized rework decision + because it returns the transferred candidate to active work. The recovery task must retain the prior fence and token as historical evidence. It must never mint a token, guess a candidate SHA, reuse a stale observation, From e6394efd9e6af0f554d4e4090ce968f759816eb4 Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 22:52:06 -0700 Subject: [PATCH 5/9] docs(atelier): redelegate recovered claims Require recovered active claims to seal a new delegated invocation, launch a fresh Agent Scripts worker, service checkpoints, and finalize with current evidence while preserving blocked recovery truth. --- skills/atelier/references/dogfood.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index 1e539549..4758e23e 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -99,6 +99,16 @@ Start a new task with no earlier task transcript. It must: Use delivered `takeover` only after an independently authorized rework decision because it returns the transferred candidate to active work. +When `takeover` or a fresh `claim` produces a new active claim, repeat the +preconditions in `delegation.md` against that new fence: capture a fresh complete +GitHub observation, use `scripts/delegation.py` `prepare` to seal a new immutable +invocation into the claim, pass it unchanged to one fresh +`agent-scripts:implement-ticket` worker, service every checkpoint, and finalize the +terminal result with another fresh observation. Never reuse the prior claim's +invocation after takeover or a fresh claim, even when the native ticket is unchanged. +A recovery that remains blocked is truthful blocked evidence, not a delivered or +completed end-to-end dogfood run. + The recovery task must retain the prior fence and token as historical evidence. It must never mint a token, guess a candidate SHA, reuse a stale observation, or continue an invocation whose material ticket observation has changed. From c143f3338df8bb8449e46302198efb99d0db1952 Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 23:10:17 -0700 Subject: [PATCH 6/9] docs(atelier): distinguish durable dogfood evidence Document which lifecycle evidence survives through GitHub and the canonical mailbox. Treat previews, provider observations, and audit outputs as live-boundary artifacts and fail closed when their raw retention is required. --- skills/atelier/references/dogfood.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index 4758e23e..4dd5a8fc 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -139,17 +139,26 @@ decision. ## Preserve the evidence packet -Keep the following identifiers and artifacts available through native GitHub -state or the canonical mailbox: +Use only native GitHub state and canonical-mailbox records for cross-task +reconstruction: -| Transition | Required durable evidence | +| Transition | Durable production record | | --- | --- | -| Approval | Work ID and revision, rendered preview digest, approver/timestamp, policy commit, authority ceiling, and required evidence. | +| Approval | Work ID and approved revision, approver/timestamp, policy commit, authority ceiling, and required evidence. | | Claim and delegation | Claim ID, worker run ID, full checkpoint ledger, immutable invocation digest, and exact Agent Scripts capability identity. | | Candidate and delivery | Remote URL, full ref, head SHA, candidate acknowledgement, required validation results, independent review identity/verdict, and pull-request topology. | | Recovery | Previous fence, checkpoint tail, block/release/takeover receipt, rationale, and verified transferable candidate or explicit absence. | -| Audit and acceptance | Complete provider observations, normalized review and feedback dispositions, audit report/fence, and the acceptance commit when explicitly accepted. A declined fence remains delivered; v0 records no rejection transition. | - -If any item cannot be reread, is stale, or conflicts with current native or -mailbox state, report that condition. Do not replace it with a narrative claim -that the dogfood run passed. +| Audit and acceptance | Persisted predicate verdicts, normalized review and feedback evidence, and the acceptance commit when explicitly accepted. A declined fence remains delivered; v0 records no rejection transition. | + +The rendered preview and digest, complete provider-observation files, and audit +report and fence are temporary operator or host outputs. Use them only at their +live decision boundaries; production v0 does not persist them as shared Atelier +state. A fresh task captures a new provider observation and reconstructs the +durable records above instead of expecting those files to survive. + +If a dogfood acceptance criterion requires retaining one of those raw temporary +artifacts, report the run blocked: v0 has no authorized durable production path +for it. Do not invent another mailbox document, commit host-local output, or +replace the missing artifact with a narrative claim that the run passed. Also +report any durable item that cannot be reread, is stale, or conflicts with +current native or mailbox state. From d78c76b3713a9d91906255125ece4f864f636fa7 Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Wed, 29 Jul 2026 23:31:39 -0700 Subject: [PATCH 7/9] docs(atelier): correct dogfood claim handoff Require the approval commit before claiming, retain the actual claim transition fence, and distinguish the host-local delegated invocation from its durable mailbox digest. --- skills/atelier/references/dogfood.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index 4dd5a8fc..61c0b23d 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -50,12 +50,16 @@ asking to continue does not grant worker authority. 1. Start without the planner transcript. Complete a fresh host preflight, read the canonical mailbox with `mailbox-validation.md`, and capture a complete current GitHub observation. -2. Read `claiming.md`. Claim only the approved, eligible assignment with - `scripts/claiming.py claim`; retain the returned claim ID, worker run ID, - continuation token, and approved mailbox commit. +2. Read `claiming.md`. From canonical mailbox Git history, identify the exact + commit that promoted the current work revision to `approved`; supply it as + `approved_commit` when claiming the eligible assignment with + `scripts/claiming.py claim`. Retain the returned claim ID, worker run ID, + continuation token, canonical claim-transition `commit`, and `base_revision`. 3. Read `delegation.md`. Use `scripts/delegation.py` with `operation: prepare` - to seal one immutable Agent Scripts v2 invocation and its host-owned fresh - observation command into the claim. + to write one immutable Agent Scripts v2 invocation to the current task's + host-local path. Preparation seals only the invocation digest into the claim; + the invocation and its host-owned fresh observation command are not shared + mailbox state and are not reusable by a recovery task. 4. Give that unchanged invocation to one fresh `agent-scripts:implement-ticket` worker. The implementation worker follows Agent Scripts' own workflow, uses every checkpoint before an allowed From 480830c9812e06b8a0d60206791d7d5c0ea70d87 Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Thu, 30 Jul 2026 00:15:48 -0700 Subject: [PATCH 8/9] docs(atelier): make audit review self-contained Require the fresh audit task to rerun review-code-change against the receipt-bound candidate and treat normalized audit evidence as temporary host state. --- skills/atelier/references/dogfood.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index 61c0b23d..8ba53ea0 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -121,9 +121,13 @@ or continue an invocation whose material ticket observation has changed. After a delivered `ready_pr` receipt, start a separate audit task. Read `audit.md`, complete the host preflight, reconstruct the mailbox from its -canonical branch, and capture one complete current GitHub observation. Normalize -the exact aggregate `review-code-change` result and every live review/comment -disposition, then run `scripts/audit.py audit`. +canonical branch, and capture one complete current GitHub observation. Run a +fresh `review-code-change` in that audit task against the receipt-bound delivered +head and comparison base, using raw current evidence rather than a worker-local +artifact. Normalize that exact aggregate result and every live review/comment +disposition, then run `scripts/audit.py audit`. The delivery receipt contributes +only the review identity and verdict; the normalized audit-evidence file remains +a temporary host output unless explicit acceptance persists it. Present the complete report and its acceptance fence to the operator. Every predicate must remain visibly `satisfied`, `violated`, `unknown`, or `stale`; From 0e677e46fb0cb9e80ca2bcc6f943ce8eb756fd45 Mon Sep 17 00:00:00 2001 From: Atelier Protocol Experiment Date: Thu, 30 Jul 2026 05:23:41 -0700 Subject: [PATCH 9/9] docs(atelier): complete blocked recovery handoff Explain that blocked takeover preserves the unresolved decision, then requires explicit resolution, release of the exact blocked fence, and a separate fresh claim before preparing another invocation. --- skills/atelier/references/dogfood.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/skills/atelier/references/dogfood.md b/skills/atelier/references/dogfood.md index 8ba53ea0..344abdba 100644 --- a/skills/atelier/references/dogfood.md +++ b/skills/atelier/references/dogfood.md @@ -96,14 +96,20 @@ Start a new task with no earlier task transcript. It must: - for active work whose worker is being replaced, use `takeover` with the exact replaced fence; - for blocked work whose worker is being replaced, use `takeover` and preserve - the unresolved blocker and blocked state; + the unresolved blocker and blocked state. Takeover does not resolve the + decision or make the replacement claim active. Present the blocker for an + explicit planner or operator decision; when that decision authorizes another + attempt, use `release` with the replacement claim's exact blocked fence to + return the work to approved while preserving its receipt and transferable + candidate. Start a separate fresh `claim` with new claim, run, and token + identities before preparing another invocation; - for released, approved work, use a fresh `claim`; verify and inherit any exact transferable candidate, and do not combine release with reacquisition; or - for delivered work, leave the delivery intact for the separate audit task. Use delivered `takeover` only after an independently authorized rework decision because it returns the transferred candidate to active work. -When `takeover` or a fresh `claim` produces a new active claim, repeat the +When an active `takeover` or a fresh `claim` produces a new active claim, repeat the preconditions in `delegation.md` against that new fence: capture a fresh complete GitHub observation, use `scripts/delegation.py` `prepare` to seal a new immutable invocation into the claim, pass it unchanged to one fresh