hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/deliver/deliver.bluebook

@@ -0,0 +1,945 @@
+Hecks.bluebook "Hecks" do
+  domain_module "Deliver" do
+    vision "Take finished work into the shared line."
+
+    # A checkout's state, read and never written: nothing needs a raw `git status`, `git diff` or
+    # `git log`. The `Reading` port's adapter answers each query; the aggregate keeps no record.
+    aggregate "Workspace" do
+      description "A look at a checkout: its branch, what it changed and what it committed."
+      acknowledges :no_command_surface, "a look at a checkout: it answers the state of a checkout and changes nothing"
+
+      attribute :checkout, Place
+      identified_by :checkout
+
+      # A directory inside the repository; the current directory when a query names none.
+      value_object "Place" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Document" do
+        attribute :text, String
+      end
+
+      query "Status" do
+        description "The checkout's branch, whether it is a linked worktree, where it stands against main and origin/main, and what is changed or untracked."
+        attribute :checkout, Place, optional: true
+        returns Document
+      end
+
+      query "Changes" do
+        description "What the checkout changed since a ref (main by default): the diffstat, or the paths alone."
+        attribute :checkout,   Place,   optional: true
+        attribute :since,      Word,    optional: true
+        attribute :names_only, Boolean, optional: true
+        returns Document
+      end
+
+      query "History" do
+        description "The commits in a range, newest first (the last 20 when none is named)."
+        attribute :checkout, Place, optional: true
+        attribute :range,    Word,  optional: true
+        returns Document
+      end
+
+      query "Settings" do
+        description "What this copy resolves for each setting that can come from a variable, its own world or a default, and which one supplied it."
+        attribute :domain, Place, optional: true
+        returns Document
+      end
+
+      query "Doctor" do
+        description "Whether this checkout can run Hecks here: overlay files parse, the stores answer, the toolchain pin matches, and what this worktree cannot see."
+        attribute :domain, Place, optional: true
+        returns Document
+      end
+
+      query "Where" do
+        description "Where this checkout's domain resolves: the store each bluebook uses and why, the audience and environment with their reasons, and any overlay file this worktree lacks."
+        attribute :domain, Place, optional: true
+        returns Document
+      end
+    end
+
+    # A commit made in a checkout under a message: asked of the git port, then recorded or declined. It commits
+    # what is staged, or the named paths, and never pushes, amends, forces, or commits onto main. Those go
+    # through `Landing` and `SendTrain`.
+    aggregate "Revision" do
+      description "One commit made in a checkout, or declined with the reason: what it says and what it is on."
+
+      attribute :run,      RunKey
+      attribute :checkout, Word,   optional: true
+      attribute :message,  Text,   optional: true
+      attribute :paths,    Text,   optional: true
+      attribute :sha,      Word,   optional: true
+      attribute :report,   Report, optional: true
+      attribute :refusal,  Report, optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A directory or a commit.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      # What a commit says, and which paths it stages first, separated by spaces.
+      value_object "Text" do
+        attribute :value, String
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "declined"
+        transition "Record"  => "committed", from: "requested"
+        transition "Decline" => "declined",  from: "requested"
+        mark :terminal, "committed", "declined"
+      end
+
+      command "Make" do
+        role "Operator"
+        goal "Commit what is staged in a checkout under a message: never pushed, never amended, never onto main"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :message,  Text, sets: true
+        attribute :paths,    Text, optional: true, sets: true
+
+        given("a commit says what it commits") do
+          message.value.to_s.strip != ""
+        end
+
+        emits CommitRequested
+      end
+
+      command "Record" do
+        role "System"
+        goal "Record the commit a checkout made, by the sha it has"
+
+        reference_to Revision
+        attribute :sha,    Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits CommitRecorded
+      end
+
+      command "Decline" do
+        role "System"
+        goal "Record why a commit could not be made"
+
+        reference_to Revision
+        attribute :refusal, Report, sets: true
+
+        emits CommitDeclined
+      end
+    end
+
+    # A linked worktree opened on a new branch from main: asked of the git port, then recorded or declined. The
+    # path is the one the caller names, or a directory under the checkout's `.claude/worktrees`. `Landing` and
+    # `Landing.retire!` take it from there, so a session that cannot run `git worktree add` itself can still open one.
+    aggregate "LinkedTree" do
+      description "A linked worktree opened on a new branch from main, or declined with the reason."
+
+      attribute :run,      RunKey
+      attribute :checkout, Word,   optional: true
+      attribute :branch,   Word,   optional: true
+      attribute :path,     Word,   optional: true
+      attribute :sha,      Word,   optional: true
+      attribute :report,   Report, optional: true
+      attribute :refusal,  Report, optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A directory or a branch name.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "declined"
+        transition "Record"  => "opened",   from: "requested"
+        transition "Decline" => "declined", from: "requested"
+        transition "Pulled"  => "pulled",   from: "requested"
+        transition "PullDeclined" => "declined", from: "requested"
+        mark :terminal, "opened", "declined", "pulled"
+      end
+
+      command "Add" do
+        role "Operator"
+        goal "Open a linked worktree on a new branch from main, never on main itself"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :branch,   Word, sets: true
+        attribute :path,     Word, optional: true, sets: true
+
+        given("a worktree is opened on a branch other than main") do
+          branch.value.to_s.strip != "" && branch.value.to_s.strip != "main"
+        end
+
+        emits AddRequested
+      end
+
+      command "PullMain" do
+        role "Operator"
+        goal "Bring local main up to date with origin/main: fetch, fast-forward when behind, rebase its unpushed commits when diverged, refusing a dirty or mid-rebase checkout"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+
+        emits PullRequested
+      end
+
+      command "Pulled" do
+        role "System"
+        goal "Record where main stands once it is up to date with origin/main"
+
+        reference_to LinkedTree
+        attribute :sha,    Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits MainPulled
+      end
+
+      command "PullDeclined" do
+        role "System"
+        goal "Record why main could not be pulled"
+
+        reference_to LinkedTree
+        attribute :refusal, Report, sets: true
+
+        emits PullDeclinedRecorded
+      end
+
+      command "Record" do
+        role "System"
+        goal "Record the worktree a checkout opened, by the sha it stands on"
+
+        reference_to LinkedTree
+        attribute :path,   Word,   optional: true, sets: true
+        attribute :sha,    Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits AddRecorded
+      end
+
+      command "Decline" do
+        role "System"
+        goal "Record why a worktree could not be opened"
+
+        reference_to LinkedTree
+        attribute :refusal, Report, sets: true
+
+        emits AddDeclined
+      end
+    end
+
+    policy "AddWorktreeWhenRequested" do
+      on      "LinkedTree.AddRequested"
+      ask     :create, with: { run: :run }
+    end
+
+    policy "PullMainWhenRequested" do
+      on      "LinkedTree.PullRequested"
+      ask     :pull, with: { run: :run }
+    end
+
+    policy "RecordThePull" do
+      on      "LinkedTree.PullAnswered"
+      trigger LinkedTree::Pulled, with: { sha: :sha, report: :report }
+    end
+
+    policy "DeclineThePull" do
+      on      "LinkedTree.PullRefused"
+      trigger LinkedTree::PullDeclined, with: { refusal: :refusal }
+    end
+
+    policy "RecordTheWorktree" do
+      on      "LinkedTree.CreateAnswered"
+      trigger LinkedTree::Record, with: { path: :path, sha: :sha, report: :report }
+    end
+
+    policy "DeclineTheWorktree" do
+      on      "LinkedTree.CreateRefused"
+      trigger LinkedTree::Decline, with: { refusal: :refusal }
+    end
+
+    # Lands a branch on main after its mechanical gate work: comment style is fixed, the shape
+    # ledger is checked, the quick gate runs, then the branch lands and boards the push train. Rubocop
+    # autocorrect is not a step yet (no command), so offenses it would fix still stop the gate. A
+    # refusal parks the instance in needs_human; a person confirms the ledger and starts it again.
+    # A saga cannot dispatch when it starts, so a policy starts the fix. It hears ShipStarted, emitted
+    # after ShipRequested is handled, because policies run before sagas for one event: on ShipRequested
+    # the fix would finish before the saga exists to hear it.
+    policy "StartTheCommentFix" do
+      on      "Shipment.ShipStarted"
+      trigger StyleRun::FixComments, with: { run: :run, paths: :paths, confirm: :confirm }
+    end
+
+    process_manager "GateAndBoard" do
+      correlates_by :"run.value"
+      starts_on Shipment::ShipRequested
+
+      # The command a caller dispatches to resume each stage of a faulted run (`hecks resume`).
+      resumes "gated=GateRun.Gate"
+      resumes "checking=ConformanceRun.CheckShapeLedger"
+      resumes "landing=Landing.Land"
+      resumes "boarding=SendTrain.Board"
+
+      # Each step records itself and waits. The caller dispatches the next command at top level:
+      # ConformanceRun.CheckShapeLedger, then GateRun.Gate, then Landing.Land, then SendTrain.Board.
+      # A dispatch made from inside this saga would run past the reaction depth bound.
+      transition StyleRun::StyleCompleted => "checking", from: "fixing"
+      transition ConformanceRun::ConformanceAccepted => "gated", from: %w[checking needs_human]
+      transition GateRun::GateCompleted => "landing", from: "gated"
+      transition Landing::BranchLanded => "boarding", from: "landing"
+
+      transition SendTrain::BranchPushed => "boarded", from: "boarding"
+      transition SendTrain::CarriedByEarlierPush => "boarded", from: "boarding"
+
+      transition StyleRun::StyleFaulted => "needs_human", from: "fixing"
+      transition ConformanceRun::ConformanceFaulted => "needs_human", from: "checking"
+      transition GateRun::GateFaulted => "needs_human", from: "gated"
+      transition Landing::LandingRefused => "needs_human", from: "landing"
+      transition SendTrain::PushFaulted => "needs_human", from: "boarding"
+    end
+
+    # Agents merge straight to local main and clean up what they merged. A landing merges a worktree's
+    # branch onto main, fast-forward first and as a merge commit when main moved; a conflict is
+    # reported and never settled, and nothing is forced or pushed. A retirement removes the worktree
+    # and its branch once the branch is on main, and refuses while it holds uncommitted work or
+    # commits main lacks, so no unpushed work is deleted. Landings queue: each takes a ticket in a line kept in
+    # the main checkout's git directory and waits its turn, first come first served, for up to the world's
+    # `landing` wait window, saying its place and the holder. The holder beats a heartbeat while it works; a
+    # ticket silent for the stale window is abandoned and removed, which the next landing's report says. A
+    # train holds the front place and lands every ready branch behind it in order, skipping one that
+    # conflicts, fails the quick gate or overlaps a started row, and telling its waiting landing why.
+    aggregate "Landing" do
+      description "One branch landed on local main, or one worktree retired: done, or refused with the reason."
+      acknowledges :key_by_value, "the run id of the LinkedTree this landing takes its checkout and branch from, and a landing whose id names no recorded tree falls back to the explicit checkout and branch, so a reference that refused an unknown tree would break the fallback",
+                   of: :from
+      created_by "Landing.land!"
+
+      attribute :run,      RunKey
+      attribute :confirm, Switch, optional: true
+      attribute :checkout, Word,   optional: true
+      attribute :branch,   Word,   optional: true
+      attribute :onto,     Word,   optional: true
+      attribute :from,     RunKey, optional: true
+      attribute :landed,   Word,   optional: true
+      attribute :report,   Report, optional: true
+      attribute :refusal,  Report, optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A branch, a directory or a commit.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      value_object "Document" do
+        attribute :text, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "refused"
+        transition "Record"  => "landed",  from: "requested"
+        transition "Clear"   => "retired", from: "requested"
+        transition "Refuse"  => "refused", from: "requested"
+        transition "Decline" => "refused", from: "requested"
+        transition "Convoy"  => "convoyed", from: "requested"
+        mark :terminal, "landed", "refused", "retired", "convoyed"
+      end
+
+      command "Land" do
+        role "Operator"
+        goal "Merge a worktree's branch onto local main: fast-forward when it can be, a merge commit when main moved, never forced, never pushed"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :branch,   Word, optional: true, sets: true
+        attribute :from,     RunKey, optional: true, sets: true
+        attribute :onto,     Word, default: "main", sets: true
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("merges the branch onto local main needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits LandingRequested
+      end
+
+      command "Finish" do
+        role "Operator"
+        goal "Rebase a worktree's branch onto local main, run the quick gate, land it through the queue and tidy, refusing by name at the first failure"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :branch,   Word, optional: true, sets: true
+        attribute :onto,     Word, default: "main", sets: true
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("rebases, lands and tidies needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits FinishRequested
+      end
+
+      command "Train" do
+        role "Operator"
+        goal "Hold the front place in the landing line and land every ready branch behind it, in ticket order"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :onto,     Word, default: "main", sets: true
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("lands every ready branch onto local main needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits TrainRequested
+      end
+
+      command "Convoy" do
+        role "System"
+        goal "Record which branches the train landed and which it skipped, with the reasons"
+
+        reference_to Landing
+        attribute :report, Report, sets: true
+
+        emits TrainRan
+      end
+
+      command "Record" do
+        role "System"
+        goal "Record the commit main names once the branch is on it"
+
+        reference_to Landing
+        attribute :branch, Word, sets: true
+        attribute :landed, Word, sets: true
+        attribute :report, Report, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+
+        emits BranchLanded
+      end
+
+      command "Refuse" do
+        role "System"
+        goal "Record why a branch could not be landed"
+
+        reference_to Landing
+        attribute :refusal, Report, sets: true
+
+
+        emits LandingRefused
+      end
+
+      command "Retire" do
+        role "Operator"
+        goal "Remove a merged worktree and delete its branch, unless it holds uncommitted work or commits main lacks"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :branch,   Word, optional: true, sets: true
+        attribute :onto,     Word, default: "main", sets: true
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("removes the worktree and deletes its branch needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits RetirementRequested
+      end
+
+      command "Clear" do
+        role "System"
+        goal "Record that the worktree and its branch are gone"
+
+        reference_to Landing
+        attribute :branch, Word, sets: true
+        attribute :report, Report, sets: true
+
+
+        emits WorktreeRetired
+      end
+
+      command "Decline" do
+        role "System"
+        goal "Record why a worktree was kept"
+
+        reference_to Landing
+        attribute :refusal, Report, sets: true
+
+
+        emits RetirementDeclined
+      end
+
+      query "Outcome" do
+        description "How one landing or retirement ended: the commit main names, or why it was refused."
+        attribute :run, RunKey
+        where(run: :run)
+        order_by :run
+      end
+
+      query "Unlanded" do
+        description "Every branch with commits that are not on main, or with uncommitted work, and where its worktree is."
+        attribute :checkout, Word, optional: true
+        attribute :onto,     Word, optional: true
+        returns Document
+      end
+    end
+
+    policy "MergeWhenLanding" do
+      on      "Landing.LandingRequested"
+      ask     :merge, with: { run: :run }
+    end
+
+    policy "FinishWhenFinishing" do
+      on      "Landing.FinishRequested"
+      ask     :finish_branch, with: { run: :run }
+    end
+
+    policy "RecordTheLanding" do
+      on      "Landing.MergeAnswered"
+      trigger Landing::Record, with: { branch: :branch, landed: :landed, report: :report, checkout: :checkout }
+    end
+
+    policy "RunTheTrain" do
+      on      "Landing.TrainRequested"
+      ask     :convene, with: { run: :run }
+    end
+
+    policy "RecordTheTrain" do
+      on      "Landing.ConveneAnswered"
+      trigger Landing::Convoy, with: { report: :report }
+    end
+
+    policy "RecordTheRefusedTrain" do
+      on      "Landing.ConveneRefused"
+      trigger Landing::Refuse, with: { refusal: :refusal }
+    end
+
+    policy "RecordTheRefusedLanding" do
+      on      "Landing.MergeRefused"
+      trigger Landing::Refuse, with: { refusal: :refusal }
+    end
+
+    # A landed branch finishes the Work row it was cut for. The LandedWork port finds the open row the
+    # branch names (the whole branch name, else the name without a leading `qa/`) and answers its key;
+    # a branch with no open row is refused by the port and nothing follows. The Tickets bluebook finishes
+    # the row that was found (FinishWorkWhenBranchLanded).
+    policy "FindWorkWhenBranchLanded" do
+      on      "Landing.BranchLanded"
+      ask     :find_landed_work, with: { branch: :branch }
+    end
+
+    policy "RemoveWhenRetiring" do
+      on      "Landing.RetirementRequested"
+      ask     :remove, with: { run: :run }
+    end
+
+    policy "RecordTheRetirement" do
+      on      "Landing.RemovalAnswered"
+      trigger Landing::Clear, with: { branch: :branch, report: :report }
+    end
+
+    policy "RecordTheKeptWorktree" do
+      on      "Landing.RemovalRefused"
+      trigger Landing::Decline, with: { refusal: :refusal }
+    end
+
+    # A commit that was asked for is made by the git port, which answers with its sha or refuses with why.
+    policy "CommitWhenMade" do
+      on      "Revision.CommitRequested"
+      ask     :commit, with: { run: :run }
+    end
+
+    policy "RecordTheCommit" do
+      on      "Revision.CommitAnswered"
+      trigger Revision::Record, with: { sha: :sha, report: :report }
+    end
+
+    policy "DeclineTheCommit" do
+      on      "Revision.CommitRefused"
+      trigger Revision::Decline, with: { refusal: :refusal }
+    end
+
+    # The copy of Hecks that runs the train follows what it pushed, so the next boarding and the
+    # records it keeps run the code that landed, not the code that was there when it was set up.
+    # It reacts to the recorded push and takes the pushed commit from it.
+    policy "KeepTheLauncherCurrent" do
+      on      "SendTrain.BranchPushed"
+      ask     :refresh, with: { run: :run, pushed: :pushed }
+    end
+
+    # Many agents finish together and each would push, running every pre-push check at once. A
+    # boarding waits its turn behind the push in flight from the same repository, then pushes the
+    # local branch with whatever else has landed on it, or finds an earlier push already carried it.
+    aggregate "SendTrain" do
+      description "One push of a checkout's branch, taken in turn: carried by an earlier push, pushed, or refused."
+
+      attribute :run,      RunKey
+      attribute :confirm, Switch, optional: true
+      attribute :branch,   Word,   optional: true
+      attribute :remote,   Word,   optional: true
+      attribute :checkout, Word,   optional: true
+      attribute :full_gate, Switch, optional: true
+      attribute :boarded,  Word,   optional: true
+      attribute :pushed,   Word,   optional: true
+      attribute :report,   Report, optional: true
+      attribute :refusal,  Report, optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A branch, a remote, a directory or a commit.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      value_object "Switch" do
+        attribute :value, Boolean
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "faulted"
+        transition "Send"  => "pushed",  from: "requested"
+        transition "Ride"  => "carried", from: "requested"
+        transition "Fault" => "faulted", from: "requested"
+        transition "Summarize" => "surveyed", from: "requested"
+        mark :terminal, "carried", "faulted", "pushed", "surveyed"
+      end
+
+      command "Board" do
+        role "Operator"
+        goal "Push this checkout's branch once the push ahead of it lands, unless that push already carried it"
+
+        attribute :run,       RunKey, sets: true
+        attribute :branch,    Word, default: "main", sets: true
+        attribute :remote,    Word, default: "origin", sets: true
+        attribute :checkout,  Word, optional: true, sets: true
+        # Run the whole `pre_push` stage, the suite included, which also writes the CI attestation
+        # note; without it the push runs only the `quick` stage.
+        attribute :full_gate, Switch, optional: true, sets: true
+        attribute :confirm,   Switch, optional: true, sets: true
+
+        given("pushes the branch to the remote needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits BoardingRequested
+      end
+
+      # A survey pushes nothing: it lists every checkout under a directory (`checkout`) whose branch
+      # has commits its remote does not, so what waits to board is known before anything boards.
+      command "Survey" do
+        role "Operator"
+        goal "List every checkout under a directory whose branch has commits its remote does not"
+
+        attribute :run,      RunKey, sets: true
+        attribute :remote,   Word, default: "origin", sets: true
+        attribute :checkout, Word, optional: true, sets: true
+
+
+        emits SurveyRequested
+      end
+
+      command "Summarize" do
+        role "System"
+        goal "Record what a survey found waiting to push"
+
+        reference_to SendTrain
+        attribute :report, Report, sets: true
+
+
+        emits CheckoutsSurveyed
+      end
+
+      # The branch was pushed: every commit on it reached the remote, what this boarding carried and
+      # whatever landed on it while it waited.
+      command "Send" do
+        role "System"
+        goal "Record the commit a boarding pushed"
+
+        reference_to SendTrain
+        attribute :checkout, Word, sets: true
+        attribute :boarded,  Word, sets: true
+        attribute :pushed,   Word, sets: true
+        attribute :report,   Report, sets: true
+
+
+        emits BranchPushed
+      end
+
+      # An earlier push already took the boarded commit to the remote, so this one pushed nothing.
+      command "Ride" do
+        role "System"
+        goal "Record that an earlier push already carried the boarded commit"
+
+        reference_to SendTrain
+        attribute :checkout, Word, sets: true
+        attribute :boarded,  Word, sets: true
+        attribute :report,   Report, sets: true
+
+
+        emits CarriedByEarlierPush
+      end
+
+      command "Fault" do
+        role "System"
+        goal "Record why a boarding could not push"
+
+        reference_to SendTrain
+        attribute :refusal, Report, sets: true
+
+
+        emits PushFaulted
+      end
+
+      query "Outcome" do
+        description "How one boarding ended: pushed, carried by an earlier push, or why it failed."
+        attribute :run, RunKey
+        where(run: :run)
+        order_by :run
+      end
+    end
+
+    # A boarding is carried by the train, which runs its steps in order while it holds the line: the
+    # Hecks domain's mint, then the settlement and the push. A shape that did not move passes straight
+    # through; a refused mint is the train's refusal, named, and nothing is pushed.
+    policy "CarryWhenBoarded" do
+      on      "SendTrain.BoardingRequested"
+      ask     :carry, with: { run: :run }
+    end
+
+    policy "RecordThePush" do
+      on      "SendTrain.TrainAnswered"
+      where   { outcome.value == "pushed" }
+      trigger SendTrain::Send, with: { checkout: :checkout, boarded: :boarded, pushed: :pushed, report: :report }
+    end
+
+    policy "RecordTheRide" do
+      on      "SendTrain.TrainAnswered"
+      where   { outcome.value == "carried" }
+      trigger SendTrain::Ride, with: { checkout: :checkout, boarded: :boarded, report: :report }
+    end
+
+    policy "RecordTheRefusedPush" do
+      on      "SendTrain.TrainRefused"
+      trigger SendTrain::Fault, with: { refusal: :refusal }
+    end
+
+    policy "SurveyWhenAsked" do
+      on      "SendTrain.SurveyRequested"
+      ask     :tally, with: { run: :run }
+    end
+
+    policy "RecordTheSurvey" do
+      on      "SendTrain.SurveyAnswered"
+      trigger SendTrain::Summarize, with: { report: :report }
+    end
+
+    policy "RecordTheRefusedSurvey" do
+      on      "SendTrain.SurveyRefused"
+      trigger SendTrain::Fault, with: { refusal: :refusal }
+    end
+
+    # Deploys stay by hand: a push that reached the remote says a deploy is ready, and nothing more.
+    # Like KeepTheLauncherCurrent, it reacts to the recorded push and takes the pushed commit from it.
+    policy "AnnounceWhenPushed" do
+      on      "SendTrain.BranchPushed"
+      ask     :announce, with: { run: :run, pushed: :pushed }
+    end
+
+    # The request that starts GateAndBoard, under its own identity so the Landing record it leads to
+    # is a separate one: Land creates a Landing under the same run key, and that would collide.
+    aggregate "Shipment" do
+      description "One request to fix, gate, land and board a branch: the gate-and-board saga starts on it."
+
+      attribute :run,    RunKey
+      attribute :confirm, Switch, optional: true
+      attribute :branch, Word
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A branch, a directory or a commit.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      command "Ship" do
+        role "Operator"
+        goal "Start the gate-and-board saga for a branch: fix comment style, check the ledger, gate, land on main, board the push train"
+
+        attribute :run,      RunKey, sets: true
+        attribute :branch,   Word, sets: true
+        attribute :checkout, Word
+        attribute :paths,    Word, default: "lib/hecks,spec"
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("lands the branch and pushes it to the remote needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits ShipRequested
+        emits ShipStarted
+      end
+    end
+
+    aggregate "ReviewRequest" do
+      description "One pull request opened or squash-merged on GitHub, and what GitHub answered."
+
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+      attribute :branch,  Word,   optional: true
+      attribute :base,    Word,   optional: true
+      attribute :number,  Word,   optional: true
+      attribute :url,     Word,   optional: true
+      attribute :report,  Report, optional: true
+      attribute :refusal, Report, optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A branch, a number or a URL.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      value_object "Document" do
+        attribute :text, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "refused"
+        transition "Record"  => "opened", from: "requested"
+        transition "Confirm" => "merged", from: "requested"
+        transition "Refuse"  => "refused", from: "requested"
+        mark :terminal, "opened", "merged", "refused"
+      end
+
+      command "Open" do
+        role "Operator"
+        goal "Open a pull request from a branch onto a base, and keep the number and URL GitHub gives it"
+
+        attribute :run,    RunKey, sets: true
+        attribute :branch, Word, sets: true
+        attribute :base,   Word, default: "main", sets: true
+        attribute :confirm, Switch, optional: true, sets: true
+
+        given("opens a pull request on GitHub needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits "PullRequestRequested"
+      end
+
+      command "Take" do
+        role "Operator"
+        goal "Squash-merge an open pull request by its number; never with an admin override"
+
+        attribute :run,    RunKey, sets: true
+        attribute :number, Word, sets: true
+        attribute :confirm, Switch, optional: true, sets: true
+
+        given("squash-merges the pull request on GitHub needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits "PullRequestMergeRequested"
+      end
+
+      command "Record" do
+        role "System"
+        goal "Record the number and URL GitHub gave an opened pull request"
+
+        reference_to ReviewRequest
+        attribute :number, Word, sets: true
+        attribute :url,    Word, sets: true
+        attribute :report, Report, sets: true
+
+        emits "PullRequestOpened"
+      end
+
+      command "Confirm" do
+        role "System"
+        goal "Record that GitHub squash-merged a pull request"
+
+        reference_to ReviewRequest
+        attribute :number, Word, sets: true
+        attribute :report, Report, sets: true
+
+        emits "PullRequestMerged"
+      end
+
+      command "Refuse" do
+        role "System"
+        goal "Record why GitHub refused a pull request"
+
+        reference_to ReviewRequest
+        attribute :refusal, Report, sets: true
+
+        emits "PullRequestRefused"
+      end
+
+      query "Status" do
+        description "The state of one pull request on GitHub: its number, state, URL and checks, as text."
+        attribute :number, Word
+        returns Document
+      end
+    end
+
+    policy "CreatePullRequestWhenRequested" do
+      on      "ReviewRequest.PullRequestRequested"
+      ask     :create, with: { run: :run }
+    end
+
+    policy "RecordTheOpenedPullRequest" do
+      on      "ReviewRequest.OpenAnswered"
+      trigger ReviewRequest::Record, with: { number: :number, url: :url, report: :report }
+    end
+
+    policy "RecordTheRefusedOpen" do
+      on      "ReviewRequest.OpenRefused"
+      trigger ReviewRequest::Refuse, with: { refusal: :refusal }
+    end
+
+    policy "SquashWhenMergeRequested" do
+      on      "ReviewRequest.PullRequestMergeRequested"
+      ask     :squash, with: { run: :run }
+    end
+
+    policy "RecordTheMergedPullRequest" do
+      on      "ReviewRequest.SquashAnswered"
+      trigger ReviewRequest::Confirm, with: { number: :number, report: :report }
+    end
+
+    policy "RecordTheRefusedMerge" do
+      on      "ReviewRequest.SquashRefused"
+      trigger ReviewRequest::Refuse, with: { refusal: :refusal }
+    end
+  end
+end