Skip to content

Epic: slice 1, first approval. A Release on next reviews a pull request to this repo, and the machine user's approval stands #182

Open
53 of 57 issues completed

Description

@don-petry

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.

Then, to close the slice

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.py fails 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

  1. added sub-issues on Oct 19, 2026
  2. 37 remaining items

  3. don-petry commented on Oct 31, 2026

    @don-petry
    ContributorAuthor

    Ticked by the audit of epic #182, each read against main at 39a4837:

    The other boxes are left open: the audit could not show them holding on main.

    🤖 Audit of epic #182 by Claude Code

  4. don-petry commented on Oct 31, 2026

    @don-petry
    ContributorAuthor

    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

  5. don-petry commented on Nov 13, 2026

    @don-petry
    ContributorAuthor

    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 by tests/test_release.py::test_the_slice_1_event_is_whole.

    When What By Status on the item
    02:18:03Z main last changed: it counts one approval The switch
    03:13:04Z The pull request opened don-petry
    03:26:49Z Pass p_KQ88EB3ZFFWPE132C4EK factory/v0.1.6 verifying: awaiting_checks
    03:38:29Z Pass p_NANTVRFXGVRZ0YMK958X admits the review Run factory/v0.1.6 verifying: awaiting_review
    03:38:33Z to 03:40:46Z Review Run 42954100593, success; the Role's review of the head at 03:40:33Z combsmith-sf-pr-review
    03:42:19Z Pass p_3RBP88Z3BEKDSTMRXSDX acts issue_approval factory/v0.1.6 converged: approval_due
    03:42:56Z Review 5853546913: APPROVED at 8fc5492 donpetry-bot
    03:43:04Z Added to the merge queue don-petry
    03:45:08Z Pass p_11GYAWVG130RGYV4Y1X1 factory/v0.1.6 queued: in_merge_queue
    03:57:41Z Merged as d9eeb54 The queue

    Two 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.

    Step When What was read
    0. The merge queue, before the Pause 17:39:54Z Empty
    1. The Maintainer set FACTORY_PAUSED to true on the repo 18:37:43Z The variable, read back
    2. The first pass created after it recorded the Pause 18:43:41Z, pass p_K630MVRBSVW07507562Z, factory/v0.1.10 paused: true, alert paused; #779 verifying, model_lens_input_needs_person, no Run and no act
    3. He approved the head by hand, as the machine user 22:53:27Z Review 5883244267, APPROVED, by donpetry-bot, of 39d28ff; no Run of the Factory made it
    4. His login enqueued it 22:53:47Z Added to the merge queue by don-petry
    5. The pass after it 22:54:29Z, pass p_JTGWHDP93NXGJ6491724 paused: true; #779 verifying, paused, deferred: the item itself recording the Pause, where unpaused the Kernel's Decision is to take it out of the queue; alert write_unmatched for the hand approval, as record 0198 says
    6. verify passed on the merge group, and it merged 23:07:57Z Merged as 973e63d; pass p_2TB94E7ERTXT8JXEXT4X reads it merged, still paused: true
    7. He set FACTORY_PAUSED back 23:09:31Z The variable, read back; the first pass created after it, p_KKMVV2Q1VSRQY190Z5HT at 23:12:33Z, reads paused: false and raises no alert

    Between steps 2 and 3, under the same Pause, next was 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_unmatched was 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, raised write_unmatched on "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

    When What Read
    22:12:32Z to 22:12:48Z Release run 43317751252, rollback: next from factory/v0.1.10 (e719181) to factory/v0.1.9 (b61f0ec) Deployment 7751076685 of b61f0ec, success at 22:12:44Z; 16 seconds from the dispatch to the end of the run, against FR-49's 15 minutes
    22:13:11Z to 22:13:34Z Release run 43317854989, move to factory/v0.1.10: next back to e719181, through the eval gate, on eval run 43267765670 Deployment 7751092797 of e719181, success at 22:13:30Z

    Fixtures, 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, on release/promote.py (docs/lessons.md, the gate that reads a promotion with no runs) and on release/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 main before the event merged at 03:57:41Z (release/decision-points.json):

    Counted Figure
    Merged into main before the event 387
    Of them, the Maintainer's own 387
    Of them, changed a protected path of config/hooks.json 165
    The design's starting figure 40

    GitHub'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.json by 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

  6. don-petry commented on Nov 13, 2026

    @don-petry
    ContributorAuthor

    Slice-1 exit audit, 2026-11-13

    Each box read against main at 132676a, on the Factory Builder's word. A box is ticked where every story it names is closed and what it says is shown on main. Nine of thirteen are ticked; four are not, and say why.

    Ticked

    Box Stories Evidence on main
    The poller runs one pass, records it, and raises the reconciliation alert #193, #306, closed controller/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, and write_unmatched was raised for each hand approval of 2026-11-12 and 2026-11-13
    run and apply serve the review Intent; the model holds no credential that can write #194, closed tests/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)
    The review is given the whole diff, or the pull request is held #327, closed Ticked before this audit
    The approval is an act of a Run with no Engine, by the machine user, bound to the admitted commit #195, closed 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, pass
    The entry shim is frozen and the workflows hold their shape #196, closed tests/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's workflow_run (decision 0115)
    A Release is cut and next moved #197, closed Twelve cuts, factory/v0.1.0 to factory/v0.1.11; release/fixtures/cut.v0-1-0.json to cut.v0-1-10.json; the comment on #197
    main requires the machine user's approval of the latest push, and the Maintainer's own approval plus the hermetic check still merge a fix #89, #198, closed Ruleset 24886320, read live, and config/rulesets.json; the recovery shown on #779 under a Pause; the comment on #198
    The event is recorded, with the count and the continue-or-stop call #198, closed release/fixtures/event.slice-1.json; release/decision-points.json, continue, 2026-11-13 (#795); the comment above
    The Release is rolled back once #197, closed release/fixtures/rollback.v0-1-10.json and its test (#785, #790): 16 seconds, against FR-49's 15 minutes

    Three things the ticked boxes do not say, found on the way:

    Not ticked, and what remains

    Box Every named story closed? What is not shown
    Every batch-2 trial has a fixture, or the mechanism it would have replaced is replaced Yes P-40 is in §6.1's batch 2 and has no fixture, and nothing was replaced for it. The Kernel defers on an unknown mergeable; the simulator models no move of the base; trials/P-29.base.json recorded 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 2
    The facts and records ports exist, and every trials/ fixture replays through them Yes The ports exist and are tested. No test replays every fixture: tests/test_adapters.py::test_the_port_reads_each_grounded_rule_as_the_fake_assumes_it reads 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 change
    The review Intent has a held-out eval set, and may not serve without one Yes The eval job runs and passed on main (trials/P-63.json), and a closed gate refuses every cut and move. But config/harness.json names no gate set, and decision 0169 says none exists yet: the gate reads evals/pr-review, a development set, until the held-out one comes. Nothing refuses a Run at run time; the cutover's gate waits on release/cutover.py
    A pull request is bound to the issue it serves by its Run or branch, and an outsider's closing edit closes nothing Yes The binding is built and tested but dormant: config/defaults.json names 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 on harness/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

  7. don-petry commented on Nov 13, 2026

    @don-petry
    ContributorAuthor

    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:

    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 next carries 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 on evals/pr-review. Today the Factory serves on a development set, as an interim (0169): its gate reads evals/pr-review until 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions