hecks 5.0.0 → 6.0.0

data/lib/hecks/quality_control/quality_control.bluebook

@@ -2,7 +2,7 @@
 # A bug is logged with the failing test that proves it, or it is not logged.
 
 # Tunable dials for the QA loop: values in qa/settings.yml, what each is in the `QaDial` rows of the
-# Vocabulary chapter.
+# Vocabulary bluebook.
 # `require`, not `require_relative`: isolated fuzz boots load a copy of this file from a tmpdir.
 require "hecks/fuzzing/qa_settings"
 
@@ -13,7 +13,7 @@ unless defined?(QualityControlDials)
     settings = Hecks::Fuzzing::QaSettings.load(ENV.fetch("HECKS_QA_SETTINGS_PATH", Hecks::Fuzzing::QaSettings::DEFAULT_PATH))
 
     # Each dial of qa/settings.yml as a constant named for it: `PR_CAP_PER_DAY` is `pr_cap_per_day`.
-    # What each is and takes is declared once, as its `QaDial` row in the Vocabulary chapter.
+    # What each is and takes is declared once, as its `QaDial` row in the Vocabulary bluebook.
     Hecks::Vocabulary.rows("QaDial").each do |dial|
       const_set(dial.fetch("name").upcase, settings.public_send(dial.fetch("name")))
     end
@@ -29,10 +29,10 @@ Hecks.bluebook "QualityControl" do
 
   core
 
-  # The rotation and its lock: `Claim` is a lifecycle edge, so when two agents race for a chapter
+  # The rotation and its lock: `Claim` is a lifecycle edge, so when two agents race for a bluebook
   # one transition wins and the other is refused.
   aggregate "Target" do
-    description "A chapter that can be pressure-tested, and whose turn it is — the rotation, and the claim that stops two agents doing the same work twice."
+    description "A bluebook that can be pressure-tested, and whose turn it is — the rotation, and the claim that stops two agents doing the same work twice."
 
     identified_by :reference
 
@@ -43,7 +43,7 @@ Hecks.bluebook "QualityControl" do
     attribute :claimed_at, Instant
     attribute :window,     StaleAfter
     attribute :last_swept, SweptIn
-    # Recency-decayed count of how often this chapter was worth sweeping; see `YieldScore`.
+    # Recency-decayed count of how often this bluebook was worth sweeping; see `YieldScore`.
     attribute :yield_score, YieldScore
     # Consecutive `Release`s that came back clean; `hecks quality_control query sweep.run` reads it to choose sweep depth.
     # Zero means no streak yet, shared on purpose by a never-swept target and a just-surprised one.
@@ -111,7 +111,7 @@ Hecks.bluebook "QualityControl" do
     end
 
     # `suspended` is "surprised, waiting for a person": stale-claim arithmetic never reaches it, so
-    # a chapter with an unresolved surprise is not re-fuzzed until a `Release` puts it back.
+    # a bluebook with an unresolved surprise is not re-fuzzed until a `Release` puts it back.
     lifecycle :status, default: "waiting" do
       transition "Claim"   => "held",      from: ["waiting", "held"]
       transition "Release" => "waiting",   from: ["held", "suspended"]
@@ -122,7 +122,7 @@ Hecks.bluebook "QualityControl" do
 
     command "Identify" do
       role "QA engineer"
-      goal "Write down that a chapter exists which nobody has swept"
+      goal "Write down that a bluebook exists which nobody has swept"
 
       attribute :reference, TargetReference
       attribute :path,      TargetPath
@@ -136,12 +136,12 @@ Hecks.bluebook "QualityControl" do
     # read the time.
     command "Claim" do
       role "QA engineer"
-      goal "Take the next chapter in the rotation, or one whose holder has gone quiet"
+      goal "Take the next bluebook in the rotation, or one whose holder has gone quiet"
 
       # The window lives on the record, not in an argument: a caller-supplied window would let any
       # agent take a live claim by asking with a window of one second.
       reference_to Target
-      attribute :held_by,    Engineer
+      attribute :held_by,    Engineer, sets: true
       attribute :now,        Instant
       needs :now
 
@@ -149,7 +149,6 @@ Hecks.bluebook "QualityControl" do
         status != "held" || claimed_at.value + window.value <= now.value
       end
 
-      sets :held_by
       sets :claimed_at, to: :now
 
       emits "TargetClaimed"
@@ -162,7 +161,7 @@ Hecks.bluebook "QualityControl" do
 
     command "Release" do
       role "QA engineer"
-      goal "Hand a chapter back to the rotation, stamped with when, what this pass was worth, and how the clean streak moves"
+      goal "Hand a bluebook back to the rotation, stamped with when, what this pass was worth, and how the clean streak moves"
 
       # `now` is the argument and `last_swept` the field, so the entry point can fill the clock.
       #
@@ -193,24 +192,22 @@ Hecks.bluebook "QualityControl" do
     # Dispatched by `SuspendOnSurprise` as `System`; `reason` is the literal that policy supplies.
     command "Suspend" do
       role "System"
-      goal "Take a chapter out of the rotation because a check surprised, until a person releases it"
+      goal "Take a bluebook out of the rotation because a check surprised, until a person releases it"
 
       reference_to Target
-      attribute :reason, TargetReason
+      attribute :reason, TargetReason, sets: true
 
-      sets :reason
 
       emits "TargetSuspended"
     end
 
     command "Shelve" do
       role "QA engineer"
-      goal "Decide a chapter is not worth the practice's time, and say why"
+      goal "Decide a bluebook is not worth the practice's time, and say why"
 
       reference_to Target
-      attribute :reason, TargetReason
+      attribute :reason, TargetReason, sets: true
 
-      sets :reason
 
       emits "TargetShelved"
     end
@@ -218,28 +215,26 @@ Hecks.bluebook "QualityControl" do
     # `reason` is required so the record's `reason` reads as the last decision in either direction.
     command "Restore" do
       role "QA engineer"
-      goal "Put a shelved chapter back in the rotation, and say what changed"
+      goal "Put a shelved bluebook back in the rotation, and say what changed"
 
       reference_to Target
-      attribute :reason, TargetReason
+      attribute :reason, TargetReason, sets: true
 
-      sets :reason
 
       emits "TargetRestored"
     end
 
-    # Not a lifecycle move, and reachable whatever the chapter's status: a recorded path can go
+    # Not a lifecycle move, and reachable whatever the bluebook's status: a recorded path can go
     # stale (a worktree removed, a project relocated) at any point in the rotation, and fixing it
     # should not have to wait on whatever status a stale claim or a pending sweep happens to leave
-    # the chapter in.
+    # the bluebook in.
     command "Relocate" do
       role "QA engineer"
-      goal "Correct where a chapter's own domain actually lives, once its recorded path stops resolving"
+      goal "Correct where a bluebook's own domain actually lives, once its recorded path stops resolving"
 
       reference_to Target
-      attribute :path, TargetPath
+      attribute :path, TargetPath, sets: true
 
-      sets :path
 
       emits "TargetRelocated"
     end
@@ -247,13 +242,13 @@ Hecks.bluebook "QualityControl" do
     # Ordered by `last_swept` alone: `order_by` sorts one stored field, and the yield-weighted
     # blend needs `now`. `RotationPriority.pick` weights these rows in Ruby.
     query "Rotation" do
-      description "Whose turn it is — waiting chapters, least recently swept first. The one reason this aggregate exists. Raw ordering only — see Hecks::Fuzzing::RotationPriority for the yield-weighted pick built on top of these same rows."
+      description "Whose turn it is — waiting bluebooks, least recently swept first. The one reason this aggregate exists. Raw ordering only — see Hecks::Fuzzing::RotationPriority for the yield-weighted pick built on top of these same rows."
       where(status: "waiting")
       order_by :last_swept
     end
 
     query "Untouched" do
-      description "Never swept at all — zero is the epoch and means nobody has looked. The gap no count of checks can show you, because an unswept chapter leaves no rows anywhere."
+      description "Never swept at all — zero is the epoch and means nobody has looked. The gap no count of checks can show you, because an unswept bluebook leaves no rows anywhere."
       where(status: "waiting")
       where(:"last_swept.value" => 0)
       order_by :reference
@@ -272,14 +267,14 @@ Hecks.bluebook "QualityControl" do
     end
 
     query "Suspended" do
-      description "Chapters a check surprised, waiting for a person — each with the reason the policy wrote. Nothing automatic touches these; hecks quality_control query sweep.run <target> --release --notes is how one comes back."
+      description "Bluebooks a check surprised, waiting for a person — each with the reason the policy wrote. Nothing automatic touches these; hecks quality_control query sweep.run <target> --release --notes is how one comes back."
       where(status: "suspended")
       order_by :reference
     end
 
-    # Answers from the ledger which waiting chapters a mode could run against.
+    # Answers from the ledger which waiting bluebooks a mode could run against.
     query "EligibleFor" do
-      description "Waiting chapters whose recorded capabilities include one mode — e.g. mode=postgres_era for the persistence-parity axis. The ledger's own answer to which chapters a mode can reach; inference at sweep time is still what decides."
+      description "Waiting bluebooks whose recorded capabilities include one mode — e.g. mode=postgres_era for the persistence-parity axis. The ledger's own answer to which bluebooks a mode can reach; inference at sweep time is still what decides."
       attribute :mode, Capability
       where(:"capabilities.value" => { contains: :mode })
       where(status: "waiting")
@@ -287,16 +282,16 @@ Hecks.bluebook "QualityControl" do
     end
 
     query "All" do
-      description "Every chapter ever written down — the inventory a runner walking the repository checks its findings against."
+      description "Every bluebook ever written down — the inventory a runner walking the repository checks its findings against."
       order_by :reference
     end
 
-    # The commands that enrol, generate and judge chapters. TargetTools answers each by running the
+    # The commands that enrol, generate and judge bluebooks. TargetTools answers each by running the
     # script's own command as a child process (lib/hecks/quality_control/adapters/target_tools.rb) and
     # handing back what it printed; none reads or writes this aggregate's records, so each is a query.
     # `arguments` is the command's own flags as one string, such as `--domains 3 --rust`.
     value_object "Words" do
-      attribute :value, String, pattern: '[^\n\r]'
+      attribute :value, String, matches: :single_line
     end
 
     value_object "DomainPath" do
@@ -327,6 +322,12 @@ Hecks.bluebook "QualityControl" do
       returns Document
     end
 
+    query "Mutate" do
+      description "Mutation-test the Rust kernel: change one operator or return value at a time and run its tests; a mutant no test catches is a finding."
+      attribute :arguments, Words, optional: true
+      returns Document
+    end
+
     query "JudgeNovelty" do
       description "Whether a new stress domain puts two forms together on one aggregate that no existing target does: the gate before it becomes a target."
       attribute :domain,    DomainPath
@@ -342,7 +343,7 @@ Hecks.bluebook "QualityControl" do
   end
 
   aggregate "Sweep" do
-    description "One agent's pass over one chapter — every check it made, what each expected, and what actually came back."
+    description "One agent's pass over one bluebook — every check it made, what each expected, and what actually came back."
 
     reference_to Target
 
@@ -446,7 +447,7 @@ Hecks.bluebook "QualityControl" do
       attribute :observation, Observation, optional: true
       # Sticky: `outcome` is the current verdict and `Remake` resets it, but `Release`'s
       # `next_streak` needs "did anything ever surprise this sweep", which a remake must not erase.
-      # `one_of` rather than a Boolean, which this chapter has no precedent for.
+      # `one_of` rather than a Boolean, which this bluebook has no precedent for.
       attribute :ever_surprised, one_of("no", "yes"), default: { value: "no" }
 
       # `surprising` is not `failed`: it covers the crash and the quiet divergence without
@@ -460,12 +461,11 @@ Hecks.bluebook "QualityControl" do
 
       command "Held" do
         role "QA engineer"
-        goal "Record that the system did what the chapter promised"
+        goal "Record that the system did what the bluebook promised"
 
         attribute :sequence,    CheckSequence
-        attribute :observation, Observation
+        attribute :observation, Observation, sets: true
 
-        sets :observation
 
         emits "CheckHeld"
       end
@@ -475,13 +475,12 @@ Hecks.bluebook "QualityControl" do
         goal "Record that the system did something other than what was written down"
 
         attribute :sequence,    CheckSequence
-        attribute :observation, Observation
+        attribute :observation, Observation, sets: true
         # Restated so `CheckSurprised` carries a `Target` id for `SuspendOnSurprise`; see
         # `TargetRef`. Required: a caller that omits it is refused (`AbsentArgument`) rather than
         # suspending nothing.
         attribute :target,      TargetRef
 
-        sets :observation
         # A literal, set here and nowhere else; see `ever_surprised`.
         sets :ever_surprised, to: "yes"
 
@@ -493,9 +492,8 @@ Hecks.bluebook "QualityControl" do
         goal "Record a check that ran and settled nothing"
 
         attribute :sequence,    CheckSequence
-        attribute :observation, Observation
+        attribute :observation, Observation, sets: true
 
-        sets :observation
 
         emits "CheckUnsettled"
       end
@@ -535,11 +533,12 @@ Hecks.bluebook "QualityControl" do
       transition "Waive"    => "sweeping",  from: "sweeping"
       transition "Conclude" => "concluded", from: "sweeping"
       transition "Abandon"  => "abandoned", from: "sweeping"
+      mark :terminal, "abandoned", "concluded"
     end
 
     command "Open" do
       role "QA engineer"
-      goal "Begin a pass over one chapter"
+      goal "Begin a pass over one bluebook"
 
       reference_to Target
       attribute :reference, SweepReference
@@ -591,13 +590,12 @@ Hecks.bluebook "QualityControl" do
       goal "End a pass and say what it taught"
 
       reference_to Sweep
-      attribute :notes, SweepNotes
+      attribute :notes, SweepNotes, sets: true
 
       # A sweep that checked nothing tested nothing; the `waived` clause makes this a gate, not a
       # wall.
       given("a sweep that checked nothing tested nothing") { made.value.positive? || waived.value.positive? }
 
-      sets :notes
 
       emits "SweepConcluded"
     end
@@ -633,7 +631,7 @@ Hecks.bluebook "QualityControl" do
     # report. They log their own checks through the commands above; none of these queries reads this
     # aggregate's records. `arguments` is the command's own flags as one string, such as `--all`.
     value_object "Words" do
-      attribute :value, String, pattern: '[^\n\r]'
+      attribute :value, String, matches: :single_line
     end
 
     value_object "DomainPath" do
@@ -729,6 +727,11 @@ Hecks.bluebook "QualityControl" do
   aggregate "Bug" do
     description "One thing now known to be wrong, the test that proves it, and how far the fix got."
 
+    acknowledges :key_by_value, "the commit the bug was found at, and a Clearance exists only once CI has run on that commit, so a reference would refuse a commit CI has not seen",
+                 of: :commit
+    acknowledges :orphaned_reference, "a sweep concluding or being abandoned completes the sweep that found the bug and does not end the bug, which stays a true record of what was found",
+                 of: :Sweep
+
     reference_to Sweep
 
     identified_by :reference
@@ -763,7 +766,7 @@ Hecks.bluebook "QualityControl" do
     # demonstration. `no` is the escape hatch for a real but flaky finding (`hecks quality_control bug.log
     # --reproduced no`).
     attribute :reproduced,    one_of("yes", "no"), default: { value: "yes" }
-    # Bugs are claimed like chapters so two agents do not fix the same one. A `given` rather than a
+    # Bugs are claimed like bluebooks so two agents do not fix the same one. A `given` rather than a
     # lifecycle edge: holding a bug is orthogonal to how far the fix got.
     attribute :held_by,       Engineer
     attribute :claimed_at,    Instant
@@ -910,6 +913,7 @@ Hecks.bluebook "QualityControl" do
       transition "Withdraw"    => "withdrawn",     from: ["logged", "investigating", "paused"]
       transition "Regress"     => "investigating", from: ["fixed", "verified"]
       transition "Revisit"     => "investigating", from: "paused"
+      mark :terminal, "withdrawn"
     end
 
     command "Log" do
@@ -943,9 +947,8 @@ Hecks.bluebook "QualityControl" do
       goal "Say what should be dealt with first"
 
       reference_to Bug
-      attribute :order, BugOrder
+      attribute :order, BugOrder, sets: true
 
-      sets :order
 
       emits "BugRanked"
     end
@@ -957,9 +960,8 @@ Hecks.bluebook "QualityControl" do
       goal "Say what kind of thing this bug is, so it can be found with its kind later"
 
       reference_to Bug
-      attribute :tags, list_of(Tag)
+      attribute :tags, list_of(Tag), sets: true
 
-      sets :tags
 
       emits "BugTagged"
     end
@@ -971,14 +973,13 @@ Hecks.bluebook "QualityControl" do
       goal "Write down whether this can be fixed on the spot or needs a bigger judgment"
 
       reference_to Bug
-      attribute :disposition, one_of("self_contained", "bigger")
+      attribute :disposition, one_of("self_contained", "bigger"), sets: true
 
       # The `given` is the fence: an argument named like the record's own `one_of` field coerces
       # against the wider set, so the narrower inline set did not refuse "undecided". Predicates
       # read args first.
       given("a triage decides — self_contained or bigger, never undecided") { disposition.value != "undecided" }
 
-      sets :disposition
 
       emits "BugTriaged"
     end
@@ -990,9 +991,8 @@ Hecks.bluebook "QualityControl" do
       goal "Give a bug a short, memorable slug — at log time or any point after"
 
       reference_to Bug
-      attribute :name, BugName
+      attribute :name, BugName, sets: true
 
-      sets :name
 
       emits "BugNamed"
     end
@@ -1021,7 +1021,7 @@ Hecks.bluebook "QualityControl" do
 
       # Same reason as `Target.Claim`: the window is on the record, not the claimer's to name.
       reference_to Bug
-      attribute :held_by, Engineer
+      attribute :held_by, Engineer, sets: true
       attribute :now,     Instant
       needs :now
 
@@ -1029,7 +1029,6 @@ Hecks.bluebook "QualityControl" do
         held_by.value == "nobody" || claimed_at.value + window.value <= now.value
       end
 
-      sets :held_by
       sets :claimed_at, to: :now
 
       emits "BugClaimed"
@@ -1040,9 +1039,8 @@ Hecks.bluebook "QualityControl" do
       goal "Put a bug back on the queue without finishing it"
 
       reference_to Bug
-      attribute :held_by, Engineer
+      attribute :held_by, Engineer, sets: true
 
-      sets :held_by
 
       emits "BugDropped"
     end
@@ -1052,11 +1050,9 @@ Hecks.bluebook "QualityControl" do
       goal "Name the code that is wrong and say why"
 
       reference_to Bug
-      attribute :site,  BugSite
-      attribute :cause, BugCause
+      attribute :site,  BugSite, sets: true
+      attribute :cause, BugCause, sets: true
 
-      sets :site
-      sets :cause
 
       emits "BugInvestigated"
     end
@@ -1070,9 +1066,8 @@ Hecks.bluebook "QualityControl" do
 
       reference_to Bug
       attribute :reference, BugReference
-      attribute :commit,    CommitRef
+      attribute :commit,    CommitRef, sets: true
 
-      sets :commit
 
       emits "BugFixed"
     end
@@ -1094,11 +1089,9 @@ Hecks.bluebook "QualityControl" do
       goal "Stop on a bug that is real and too large to fix here — why, and what would move it"
 
       reference_to Bug
-      attribute :reason,    BugReason
-      attribute :next_step, NextStep
+      attribute :reason,    BugReason, sets: true
+      attribute :next_step, NextStep, sets: true
 
-      sets :reason
-      sets :next_step
 
       emits "BugPaused"
     end
@@ -1108,9 +1101,8 @@ Hecks.bluebook "QualityControl" do
       goal "Take back a report whose test turned out to prove something else"
 
       reference_to Bug
-      attribute :reason, BugReason
+      attribute :reason, BugReason, sets: true
 
-      sets :reason
 
       emits "BugWithdrawn"
     end
@@ -1285,6 +1277,7 @@ Hecks.bluebook "QualityControl" do
       transition "Investigate" => "investigating", from: "proposed"
       transition "Build"       => "built",         from: "investigating"
       transition "Discard"     => "discarded",     from: ["proposed", "investigating"]
+      mark :terminal, "built", "discarded"
     end
 
     command "Propose" do
@@ -1317,9 +1310,8 @@ Hecks.bluebook "QualityControl" do
       goal "Say what actually came of chasing this lead"
 
       reference_to Angle
-      attribute :resolution, AngleResolution
+      attribute :resolution, AngleResolution, sets: true
 
-      sets :resolution
 
       emits "AngleBuilt"
     end
@@ -1329,9 +1321,8 @@ Hecks.bluebook "QualityControl" do
       goal "Decide a lead is not worth the practice's time, and say why"
 
       reference_to Angle
-      attribute :reason, AngleReason
+      attribute :reason, AngleReason, sets: true
 
-      sets :reason
 
       emits "AngleDiscarded"
     end
@@ -1383,6 +1374,9 @@ Hecks.bluebook "QualityControl" do
   aggregate "Ticket" do
     description "One issue raised in a tracker outside this repository — what it says, whether the tracker took it, and how many times we have asked."
 
+    acknowledges :orphaned_reference, "a Ticket is an issue in an outside tracker, written from what the tracker reports; closing it when its bug is withdrawn would record a close that did not happen there",
+                 of: :Bug
+
     reference_to Bug
 
     identified_by :reference
@@ -1464,6 +1458,7 @@ Hecks.bluebook "QualityControl" do
       transition "Retry"   => "submitting", from: "refused"
       transition "Abandon" => "abandoned",  from: ["raised", "submitting", "refused"]
       transition "Close"   => "closed",     from: "filed"
+      mark :terminal, "abandoned", "closed"
     end
 
     # The port is declared in `quality_control.ports.hecksagon`, where wiring lives.
@@ -1499,11 +1494,9 @@ Hecks.bluebook "QualityControl" do
       goal "Record that the tracker took it, and where it landed"
 
       reference_to Ticket
-      attribute :number, IssueNumber
-      attribute :url,    IssueUrl
+      attribute :number, IssueNumber, sets: true
+      attribute :url,    IssueUrl, sets: true
 
-      sets :number
-      sets :url
 
       emits "TicketFiled"
     end
@@ -1513,9 +1506,8 @@ Hecks.bluebook "QualityControl" do
       goal "Record that the tracker would not take it, and what it said"
 
       reference_to Ticket
-      attribute :refusal, RefusalText
+      attribute :refusal, RefusalText, sets: true
 
-      sets :refusal
       sets :attempts, increment: { value: 1 }
 
       emits "TicketFilingRefused"
@@ -1523,17 +1515,16 @@ Hecks.bluebook "QualityControl" do
 
     # A policy re-enters its target with the event payload verbatim, so `Retry` must accept
     # `refusal` or be refused outright. It is set rather than dropped: an argument taken and
-    # ignored is exactly what this chapter hunts.
+    # ignored is exactly what this bluebook hunts.
     command "Retry" do
       role "System"
       goal "Ask again, up to the limit, carrying what was refused"
 
       reference_to Ticket
-      attribute :refusal, RefusalText
+      attribute :refusal, RefusalText, sets: true
 
       given("a retry is still allowed") { attempts.value < max_attempts.value }
 
-      sets :refusal
 
       emits "TicketRetried"
     end
@@ -1624,6 +1615,11 @@ Hecks.bluebook "QualityControl" do
   aggregate "Patch" do
     description "One pull request opened for a Bug's own fix — number, branch, and the exact commit that makes checking its CI status a lookup instead of a guess."
 
+    acknowledges :key_by_value, "the commit the pull request was opened at, and a Clearance exists only once CI has run on that commit, so a reference would refuse a commit CI has not seen",
+                 of: :commit
+    acknowledges :orphaned_reference, "a Patch is a pull request, written from what GitHub reports; closing it when its bug is withdrawn would record a close that did not happen on GitHub",
+                 of: :Bug
+
     reference_to Bug
 
     identified_by :number
@@ -1675,6 +1671,7 @@ Hecks.bluebook "QualityControl" do
     lifecycle :status, default: "opened" do
       transition "Merge" => "merged", from: "opened"
       transition "Close" => "closed", from: "opened"
+      mark :terminal, "closed", "merged"
     end
 
     # Dispatched only by `hecks quality_control patch.open --bug`, which reads the facts back from `gh pr view`, so
@@ -1773,10 +1770,9 @@ Hecks.bluebook "QualityControl" do
       role "QA engineer"
       goal "Open the day the clock reads, with no slot taken yet"
 
-      attribute :today, Day
+      attribute :today, Day, sets: true
       needs :today
 
-      sets :today
 
       emits "QuotaOpened"
     end
@@ -1815,6 +1811,11 @@ Hecks.bluebook "QualityControl" do
   aggregate "Improvement" do
     description "One pull request landed for deliberate, non-bugfix work — a domain-modeling addition, a tool, an aggregate this very practice needed — number, branch, and the exact commit that makes watching its CI a lookup instead of a guess, the same discipline `Patch` already keeps for a bug's own fix."
 
+    acknowledges :key_by_value, "the commit the work landed at, and a Clearance exists only once CI has run on that commit, so a reference would refuse a commit CI has not seen",
+                 of: :commit
+    acknowledges :orphaned_reference, "an angle being built or discarded completes the lead and does not end the improvement, which stays a true record of what landed",
+                 of: :Angle
+
     # Optional, set only at `Open`: not all deliberate work began as a cited `Angle`, and forcing
     # one would invent a lead after the fact.
     reference_to Angle, optional: true
@@ -1873,6 +1874,7 @@ Hecks.bluebook "QualityControl" do
       transition "Regress" => "needs_fix", from: "landed"
       transition "Merge"   => "merged",   from: ["opened", "landed", "needs_fix"]
       transition "Close"   => "closed",   from: ["opened", "landed", "needs_fix"]
+      mark :terminal, "closed", "merged"
     end
 
     # Dispatched by `hecks quality_control patch.open --improvement`, which then dispatches `Land` in the same run so
@@ -1907,9 +1909,8 @@ Hecks.bluebook "QualityControl" do
 
       reference_to Improvement
       attribute :number, ImprovementNumber
-      attribute :commit, CommitRef
+      attribute :commit, CommitRef, sets: true
 
-      sets :commit
 
       emits "ImprovementLanded"
     end
@@ -1989,6 +1990,7 @@ Hecks.bluebook "QualityControl" do
       mark :failure, "red"
       transition "Passed" => "green", from: "running"
       transition "Failed" => "red",   from: "running"
+      mark :terminal, "green", "red"
     end
 
     command "Start" do
@@ -2005,9 +2007,8 @@ Hecks.bluebook "QualityControl" do
       goal "Record that the suite went green against this commit"
 
       reference_to Clearance
-      attribute :summary, RunSummary
+      attribute :summary, RunSummary, sets: true
 
-      sets :summary
 
       emits "ClearanceGiven"
     end
@@ -2146,7 +2147,7 @@ Hecks.bluebook "QualityControl" do
   # `Raise` and the call are split so a crash leaves a `Ticket.Raised` row rather than a lie.
   policy "FileWhenSubmitted" do
     on      "Ticket.TicketSubmitted"
-    trigger Ticket::IssueTracker::File
+    ask     :file
   end
 
   policy "RecordTheIssue" do
@@ -2167,7 +2168,7 @@ Hecks.bluebook "QualityControl" do
 
   policy "AskOnceMore" do
     on      "Ticket.TicketRetried"
-    trigger Ticket::IssueTracker::File
+    ask     :file
   end
 
   # Nothing reacts to `TicketRaised` on purpose: a ticket waits until somebody submits it.

data/lib/hecks/quality_control/quality_control.hecksagon

@@ -1,13 +1,13 @@
-# The QualityControl chapter, bound so it boots standing alone (a fuzz or model_check boot of this
+# The QualityControl bluebook, bound so it boots standing alone (a fuzz or model_check boot of this
 # directory). The QA ledger binds PostgresEra in qa/bluebook/quality_control.hecksagon, and the
-# Hecks chapter binds it through its world's `default_adapter`; the ports every one of them shares
+# Hecks bluebook binds it through its world's `default_adapter`; the ports every one of them shares
 # are in quality_control.ports.hecksagon.
 Hecks.hecksagon "QualityControl" do
   attaches "Governance"
   persisted_by "Memory"
 end
 
-# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
 Hecks.hecksagon "Governance" do
   persisted_by "Memory"
 end