Repository navigation
Description
Slice 1 of the build order in docs/architecture/software-factory-design.md, §9.1. One event: a Release on next has reviewed a pull request to this repo, the machine user's approval of it stands, the pull request has merged through the queue, and its status block said why at each step.
Opened 2026-10-19 by the plan review, on the Maintainer's word. The review found that §9.1's eleven-step critical path had stories for none of its steps; this epic gives it one each. It opens while slice 0 finishes (its exit is seven pull requests: #161, #26, #19, #28, #14 with #27, #13 with #25, #8). Stories here that need no slice-0 result start as slots free.
First: what only the Maintainer can do
| Thing | Exactly what | Blocks |
|---|---|---|
| A read token for the private held-out home | For the eval job only, stored as an environment secret restricted to main (design §4.9, credentials table) |
The eval-set story, #8 |
| A second canary token window | The machine user's token again, for batch 2a (P-2, P-5, P-25) after #27 has revoked the first | Batch 2a |
| The release identity's key, once P-30 names it | Stored as the others were | The Release story |
| The decision on #89 | The machine user's least role and the paths it owns | The ruleset switch, and so the first approval |
Done when
From §9.1 "Slice 1 is done when", and its critical path items 1 to 11. Each names the story that proves it. Split on 2026-10-22, from the plan reviews of that day: §9.1's done-when is the event alone, so the checks that follow it no longer read as gating it. The slice still closes on every box below.
The event: what §9.1's done-when needs
A Release on next has reviewed a pull request to this repo, the machine user's approval of it stands, the pull request has merged through the queue, and its status block said why at each step.
- Every batch-2 trial has a fixture, or the mechanism it would have replaced is replaced (§6.1). Trials P-2, P-5, P-23 and P-25: an App in the merge queue, and threads resolved by another App #185, Trials P-35, P-36, P-37 and P-38: what a Lens's check is read from, the queue's base, and the approved commit #186, Trial P-30: one identity cuts a Release and moves a channel tag under the tag ruleset #189 (P-30), on Canary set-up: the ruleset, code owners and identities the trials need #24's canary; Trial P-26: the model CLI's sandbox hides the parent's environment and limits connections #188 (P-26, closed: its fixture records the failure Design: the CLI's sandbox limits connections but passes the parent's environment through (P-26 failed); the run job relies on the scrub and --tools "" #287 answers). P-40 last: Trial P-40: after a base move a conflicting pull request reads false by the next read, and a clean one keeps its old merge commit (#809) #815, Trial P-40's second run: in the second after a base move a pull request that now conflicts still reads as merging (#809) #818, Trial P-40: the first run's reads by GraphQL, unknown at the first read after the base moved and worked out by the next (#809) #829, record 0214 in A read in the second after a base move may give the merge state of before it, and the snapshot's last read holds it (#809, record 0214) #820.
- The facts and records ports exist. Each grounded rule is read from its fixture, or named with why not. A rule named for its shape alone is owed a re-recording in the port's own query, under a follow-up issue. Every refusal a trial recorded is read as no answer (FR-56). The two port stories (done), and Port: the paths a pull request changes, with both names of a rename #138; the re-recording is Trials: each grounded rule the ports read in another shape than was recorded is recorded again in the port's own query, the checks port's status rollup first #807. Reworded on 2026-11-13; the old text and the ruling are in the audit's second comment below.
- The poller runs one pass, records it, and raises the reconciliation alert (I-33). Controller: one pass reads, decides, records, dispatches, writes the view and raises the reconciliation alert #193, Controller: reconciliation, every write by a Factory identity matched to a recorded Effect (I-33) #306.
-
runandapplyserve the review Intent; the model holds no credential that can write (FR-10). Harness: run and apply for the review Intent, and the model holds no credential that can write #194. - The review is given the whole diff, or the pull request is held: no approval stands on content no review read. Kernel: a pull request whose diff the Task cannot carry whole is held, never reviewed in part #327.
- The review Intent has a held-out eval set, and may not serve without one (FR-55). The review Intent's held-out eval set, from the proof of concept's merged-then-reverted pull requests #183, Workflows: eval.yml runs the review Intent's held-out cases and writes eval-report/1 #309.
- The approval is an act of a Run with no Engine, by the machine user, bound to the admitted commit. The approving act: the machine user approves from a Run with no Engine, bound to the admitted commit #195.
- The entry shim is frozen and the workflows hold their shape under
tools/check_workflows.py. Workflows: the frozen entry shim, the poller, the Run's three jobs and the nudge, each held to its shape #196. - A Release is cut and
nextmoved. Release: cut an immutable tag, move next, and roll back in one action #197, its cut and move. -
mainrequires the machine user's approval of the latest push, and the Maintainer's own approval plus the hermetic check still merge a fix when the Release is broken. Redesign the machine user's permissions: approve everywhere, own no rules #89, then The ruleset switch: main requires the machine user's approval of the most recent commit, and slice 1's event is recorded #198's ruleset switch. This comes before the event: an approval means nothing until the ruleset requires it (The ruleset switch: main requires the machine user's approval of the most recent commit, and slice 1's event is recorded #198's ruling 6; the orchestrator's ruling of 2026-10-31). - The event is recorded, with the §9.2 count of the Maintainer's approvals before it and the continue-or-stop call. The ruleset switch: main requires the machine user's approval of the most recent commit, and slice 1's event is recorded #198, its record.
Then, to close the slice
- The Release is rolled back once (§10.3 exit criterion 3 needs one; §9.1's event does not). Release: cut an immutable tag, move next, and roll back in one action #197, its rollback.
- A pull request the Factory opens is bound to its issue by its Run or branch: built and tested, with the writer landing with the push Effect (Acceptance: a pull request the Factory opens is bound to its issue by the Run that opened it #342, slice 2). An outsider's closing edit makes no issue done: its close reads as declined (0132), an edit after the approval holds the item (0140), and the window after the last pass is named (§4.9, Gaps record 0140 names: edits around the approval and the queue's merge, issues linked by hand #550). Acceptance: a pull request is bound to the issue it serves by its Run or branch, not by its author's closing link #295's limit, restated: before any Role is named to open pull requests, or any contract is in force (A check refuses naming a Role to open pull requests while open_pull_request has no writer (#295's limit, restated) #808 holds it). Acceptance: a pull request is bound to the issue it serves by its Run or branch, not by its author's closing link #295, An approved outsider's description edit before the queue merges adds closing keywords, and GitHub closes those issues with the pull request as the closer #280. Reworded on 2026-11-13; the old text and the ruling are in the audit's second comment below.
Follow-ups: under this epic until slice 2's opens, gating nothing here
| Issue | Gates instead |
|---|---|
#282, what resolvedBy says when an App resolves a thread |
Any Role given resolve_thread. With resolvedBy null the Kernel reads the thread thread_unreadable and defers the item with needs_you (kernel/derive.py, unreadable_thread) until a person re-resolves it |
| #287, the CLI's sandbox passes the parent's environment (P-26, P-50, P-51 failed) | Any Intent run with a tool: --tools "" stays until a trial of the outer sandbox passes |
#139, apply refuses a Role's push to a protected path |
The first Role that pushes (slice 2, its ruling on #139) |
| #254, P-31, the relay's webhook | The relay, slice 3 |
| #265, grounding of four simulator rules | Nothing; the simulator's honesty |
| #299, every actor's write access in the issue world | Nothing; the simulator's honesty |
| #807, each grounded rule the ports read in another shape than was recorded is recorded again, the checks port's status rollup first | Nothing here; FR-56's cover of the ports' own reads. A read-only trial sitting |
| #342, the Run that opens a pull request binds it to its issue | Moved to slice 2 with the push Effect (ruling of 2026-11-13). The first Role named to open pull requests, and any contract in force |
#808, a check refuses naming an opening Role while open_pull_request has no writer |
The same: it holds #295's limit as restated |
| #550 (closed), the window after the last pass and before the queue's merge, in which an edit is never read (decision 0140; §4.9 accepts it for slice 1) | Carried to slice 2 by number, so that "accepted for slice 1" does not become permanent |
Order
| Group | Stories | Waits on |
|---|---|---|
| Now, beside slice 0 | The eval set. Trials batch 2c (no machine-user token). P-33 and P-34. The grounding triage | Nothing; #27's revocation for the trials |
| After slice 0's exit | The facts port, then the records port (lane a). Batch 2a and P-30 in the second token window; batch 2b; P-26 | The ports: the exit. The trials: the Maintainer's token |
| Then | The Controller (lane b). run and apply (lane s). The workflows |
The ports; the eval set |
| Last | The Release. #89, then the ruleset switch, then the event | P-30; the Harness |
Moved here from the slice-0 epic: #138 "Port: the paths a pull request changes, with both names of a rename" (into the facts port) and #139 "Harness: apply refuses a Role's push to a protected path or a Lens's input that no model Lens has reviewed" (into the Harness story). #140 and #141 wait for slice 2.
Rules for every story
As the slice-0 epic's, with two more:
- The first story to create one of the reserved directories (
adapters/,controller/,harness/,roles/,release/,evals/) re-points every Boundary row and lesson waiting on it, to a named test or to a narrower wait, in the same PR.tools/check_context.pyfails until it does. - A decision record takes its number when its PR is enqueued, as the next free number (the Maintainer, 2026-10-19).
Not in slice 1
The fix and implement Intents, acceptance contracts, the opening Run, the relay, the dashboard page, domain Roles, any App beyond the three, any Consumer repo, FR-12's injection suite (slice 2, before the first stable).
Activity
37 remaining items
don-petry commentedon Oct 31, 2026
Ticked by the audit of epic #182, each read against
mainat 39a4837:kernel/derive.pyholdstoo_largeatlimits.max_diff_characters, andtests.test_decide.Contentpasses at 39a4837.The other boxes are left open: the audit could not show them holding on
main.🤖 Audit of epic #182 by Claude Code
don-petry commentedon Oct 31, 2026
Corrected on the orchestrator's ruling of 2026-10-31, from the audit of this epic.
The audit ticked one box here: the whole diff, or held. The rest stay open; what each lacks is in the audit's table.
🤖 Audit of this epic by Claude Code
P-31's placement gets a short record, 0106, and every batch of sectio…
Section 6.1: P-31 is the relay's trial, not the first approval's (com…
Controller: a pass gathers what reconciliation reads and carries what…
don-petry commentedon Nov 13, 2026
Slice 1's event, the recovery shown once, and continue or stop
The event
"Rulesets: main counts the machine user's approval, as the switch of 2026-11-11 left it (#198, record 0191)" (#730), on 2026-11-11. The fixture is
release/fixtures/event.slice-1.json, held whole bytests/test_release.py::test_the_slice_1_event_is_whole.mainlast changed: it counts one approvalp_KQ88EB3ZFFWPE132C4EKawaiting_checksp_NANTVRFXGVRZ0YMK958Xadmits the review Runawaiting_reviewp_3RBP88Z3BEKDSTMRXSDXactsissue_approvalapproval_duep_11GYAWVG130RGYV4Y1X1in_merge_queueTwo things the event does not show. The Factory's queue step has not enqueued a pull request: the Maintainer's login enqueued this one. And two pull requests merged on the machine user's approval before it, #726 and #729; #730 is taken as the event because it is the switch's own record.
The recovery, shown with the Factory paused
"A path only a person decides is listed apart from a Lens's inputs, and a change to it needs a person's approval (record 0200)" (#779) merged on 2026-11-12 on the Maintainer's approval by hand as the machine user, with the Factory paused from before the approval until after the merge. It changes a model Lens's inputs, so the Factory may not approve it (0052); the Pause was set to show the story's third box.
FACTORY_PAUSEDtotrueon the repop_K630MVRBSVW07507562Z, factory/v0.1.10paused: true, alertpaused; #779verifying,model_lens_input_needs_person, no Run and no actp_JTGWHDP93NXGJ6491724paused: true; #779verifying,paused, deferred: the item itself recording the Pause, where unpaused the Kernel's Decision is to take it out of the queue; alertwrite_unmatchedfor the hand approval, as record 0198 saysverifypassed on the merge group, and it mergedp_2TB94E7ERTXT8JXEXT4Xreads itmerged, stillpaused: trueFACTORY_PAUSEDbackp_KKMVV2Q1VSRQY190Z5HTat 23:12:33Z, readspaused: falseand raises no alertBetween steps 2 and 3, under the same Pause,
nextwas rolled back and moved forward again (below).One alert not expected: the pass of step 5 also raised
reconciliation_unreadable. The next pass, seven minutes later and still paused, did not, and nor did any after it.write_unmatchedwas raised by each pass from step 5 until the one after the merge (p_MYG4BA801TNYRE46E4H9, 23:08:27Z), and by none from 23:12:33Z on; "Factory alerts" (#786) closed itself at 23:15:27Z. Open question: the alarm cleared when the pull request it names merged, with nobody having matched the write, "write_unmatched clears once the pull request it names leaves the open set, so a machine-user write nobody matched closes its own alarm" (#787).What the earlier hand merge showed. "When the Factory cannot or may not approve, the Maintainer approves by hand as the machine user (#198's ruling 5, record 0198)" (#761) merged earlier that day on the same hand approval (review 5874680260 at 12:46:11Z, merged as e0ac3ff at 13:01:18Z) with no Pause set: the item was held
hands_off, and the pass after it,p_37HR7EM2QA7T7R81NJGY, raisedwrite_unmatchedon "Factory alerts" (#778). It showed the hand approval and its alarm; #779 showed them with the Factory paused.The first rollback, under the same Pause
rollback:nextfrom factory/v0.1.10 (e719181) to factory/v0.1.9 (b61f0ec)moveto factory/v0.1.10:nextback to e719181, through the eval gate, on eval run 43267765670Fixtures, all merged:
release/fixtures/rollback.v0-1-10.json(#785, a184082);release/fixtures/cut.v0-1-10.json, the cut read after the rollback (#788, bb3ca9e); and the test that holds the rollback whole,tests/test_release.py::test_the_first_rollback_moved_next_back_within_its_time_and_a_move_brought_it_forward_again, with 24 mutants (#790, 251c7ba).With them the fixture box of "Release: cut an immutable tag, move next, and roll back in one action" (#197) is ticked. Its second sentence asks that every row and lesson waiting on
release/be re-pointed. Two still wait, onrelease/promote.py(docs/lessons.md, the gate that reads a promotion with no runs) and onrelease/cutover.py(evals/AGENTS.md, the cutover's own gate). Both belong to slice 3's promotion and cut-over, which #197 does not build, so they do not block the tick (the Factory Builder's ruling, 2026-11-13).The count, shown before the decision
Read on 2026-11-11, of pull requests merged into
mainbefore the event merged at 03:57:41Z (release/decision-points.json):mainbefore the eventconfig/hooks.jsonGitHub's search gives 387 merged before that time, all authored by don-petry; the repo's history gives the same 387 squash commits, of which 165 change a path the protected list names as it stood at 687db79. Passing 40 stops nothing: it is the signal to shrink the slice or to fall back on the proof of concept's reviewer.
Continue or stop
Continue. The Maintainer decided on 2026-11-13, after reading the count above.
The decision is recorded in
release/decision-points.jsonby a pull request that follows this comment. It merges on his own approval, by hand, which is the act that shows a person decided (records 0198 and 0200).🤖 Generated with Claude Code
don-petry commentedon Nov 13, 2026
Slice-1 exit audit, 2026-11-13
Each box read against
mainat 132676a, on the Factory Builder's word. A box is ticked where every story it names is closed and what it says is shown onmain. Nine of thirteen are ticked; four are not, and say why.Ticked
maincontroller/pass_.py,controller/reconcile.py;tests/test_controller.py::test_the_pass_record_holds_what_the_kernel_was_given_and_replays_it,::test_a_write_no_effect_recorded_raises_one_alert_and_is_named_in_the_view;tests/test_reconcile.py::test_each_write_is_matched_to_the_effect_that_recorded_it. Live: each pass on factory/v0.1.11 is recorded, andwrite_unmatchedwas raised for each hand approval of 2026-11-12 and 2026-11-13runandapplyserve the review Intent; the model holds no credential that can writetests/test_tools.py::test_the_runs_jobs_keep_each_key_apart_and_always_leave_the_outcome,tests/test_apply.py::test_nothing_is_minted_for_a_refused_result_and_the_token_is_revoked_whatever_happens,tests/test_harness.py::test_the_cli_is_given_no_tool. A review now has the read tools alone (decision 0138)tests/test_approve.py::test_the_act_approves_the_commit_it_read_and_claims_only_what_it_reads_back,tests/test_tools.py::test_the_approving_act_holds_the_approvers_token_alone;trials/P-7.json, passtests/test_tools.py::test_a_shim_is_held_word_for_word,::test_the_pollers_shim_stands_as_its_template_and_its_hash; the nudge is the poller'sworkflow_run(decision 0115)nextmovedrelease/fixtures/cut.v0-1-0.jsontocut.v0-1-10.json; the comment on #197mainrequires the machine user's approval of the latest push, and the Maintainer's own approval plus the hermetic check still merge a fixconfig/rulesets.json; the recovery shown on #779 under a Pause; the comment on #198release/fixtures/event.slice-1.json;release/decision-points.json, continue, 2026-11-13 (#795); the comment aboverelease/fixtures/rollback.v0-1-10.jsonand its test (#785, #790): 16 seconds, against FR-49's 15 minutesThree things the ticked boxes do not say, found on the way:
controller/brakes.py, not built. The box does not ask for it.tools/machine_user_drift.sh, run by hand.Not ticked, and what remains
mergeable; the simulator models no move of the base;trials/P-29.base.jsonrecorded the clean case alone. No issue is open to run it. Every other batch-2 trial is settled, each failed fixture answered by a later pass or a recorded change. "Trials P-41, P-42 and P-43: reviews, labels and check runs on a pull request, and the lists read short" (#250) is also still open, on rules that wait on slice 2trials/fixture replays through themtests/test_adapters.py::test_the_port_reads_each_grounded_rule_as_the_fake_assumes_itreads each grounded rule from its fixture, names 26 rules as not read, and never runs the fake. That narrower form is what closed #283 (by #311). The box's words or the test must changemain(trials/P-63.json), and a closed gate refuses every cut and move. Butconfig/harness.jsonnames no gate set, and decision 0169 says none exists yet: the gate readsevals/pr-review, a development set, until the held-out one comes. Nothing refuses a Run at run time; the cutover's gate waits onrelease/cutover.pyconfig/defaults.jsonnames no opening Role, and "Acceptance: a pull request the Factory opens is bound to its issue by the Run that opened it" (#342) is open, waiting onharness/push.py. And GitHub still closes the issue on an outsider's edit (trials/P-48.json, fail); the Kernel reads it declined, never done (decision 0132), and decision 0140 names an edit after the last pass as never read🤖 Generated with Claude Code
don-petry commentedon Nov 13, 2026
Two boxes reworded, and what closes the eval set's box
Rulings of 2026-11-13 on the four boxes the audit above left open (Solution Architect, delegated, with the Factory Builder, on the Maintainer's away approval). Neither rewording touches §9.1's done-when, the event, which has happened; both change words the plan review set. The old text and the new, so that what moved can be seen:
The ports' box
Old. "The facts and records ports exist, and every
trials/fixture replays through them (FR-56, L-51). The two port stories (done), and #138."New. "The facts and records ports exist. Each grounded rule is read from its fixture, or named with why not. A rule named for its shape alone is owed a re-recording in the port's own query, under a follow-up issue. Every refusal a trial recorded is read as no answer (FR-56)."
Why. The fake answers no request: it is a set of rules, so "replay every fixture through it" names nothing that can be run, and #283 was closed in this narrower form by #311. L-51's rule, that every rule of the fake cites a recorded answer, holds. But 15 of the 26 rules the contract test names as not read are there for their shape alone: the port's own query was never recorded. That is a gap in what the tests cover, not in safety, since the ports refuse what they cannot read, and the new words do not approve it: "Trials: each grounded rule the ports read in another shape than was recorded is recorded again in the port's own query, the checks port's status rollup first" (#807) owes the re-recording, and is in the follow-ups table. §9.1 asks only for the two ports.
The binding's box
Old. "A pull request is bound to the issue it serves by its Run or branch, and an outsider's closing edit closes nothing (#295 "must not outlive slice 1"). #295, #280."
New. "A pull request the Factory opens is bound to its issue by its Run or branch: built and tested, with the writer landing with the push Effect (#342, slice 2). An outsider's closing edit makes no issue done: its close reads as declined (0132), an edit after the approval holds the item (0140), and the window after the last pass is named (§4.9, #550)."
Why. The binding by the Run's record and the branch is built and tested; only its writer is missing, and it waits on the push Effect, which §9.1 puts in slice 2 (record 0188). "Closes nothing" the Factory cannot deliver: P-48 failed, and GitHub closes the issue. What the design rules is what the new words say. Two things go with it:
config/defaults.jsonnames none. "A check refuses naming a Role to open pull requests while open_pull_request has no writer (Acceptance: a pull request is bound to the issue it serves by its Run or branch, not by its author's closing link #295's limit, restated)" (A check refuses naming a Role to open pull requests while open_pull_request has no writer (#295's limit, restated) #808) holds the limit by a check. This moves Acceptance: a pull request the Factory opens is bound to its issue by the Run that opened it #342 from slice 1 to slice 2.Both boxes are ticked now that #807 and #808 exist.
The eval set's box stays open
"The review Intent has a held-out eval set, and may not serve without one (FR-55)" closes only when
nextcarries a Release cut through the named gate set's pooled gate: at least three dispatches, held to the set's own bars (decision 0169). Supplying and naming the set is not enough, because the Release serving now was cut onevals/pr-review. Today the Factory serves on a development set, as an interim (0169): its gate readsevals/pr-reviewuntil the held-out set is seated, which is the Maintainer's to supply. No run-time refusal is added in slice 1: for this repo, "may not serve without one" is held at the cut and the move, which a closed gate refuses.The trials' box
Lane d runs P-40. The box stays open until its fixture is in, or what a failure replaces is recorded.
🤖 Generated with Claude Code