hecks 5.0.0 → 7.0.0

data/lib/hecks/tools/translation_scaffold.rb

@@ -59,13 +59,13 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        Hecks.with_registry(registry) { load_chapters(loading, directory) }
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        Hecks.with_registry(registry) { load_declarations(loading, directory) }
+        bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
         [registry, bluebook, directory]
       end
 
       # Loads the library, the project and the domain's files into the registry in scope.
-      def load_chapters(loading, directory)
+      def load_declarations(loading, directory)
         loading.load_library
         loading.load_project(loading.shared_root(nil, directory))
         # deliberately not translations/*.bluebook: an unresolved edge file refuses to load, and
@@ -73,17 +73,7 @@ module Hecks
         loading.load_each(directory, %w[*.port *.adapter])
         loading.load_bluebooks(directory)
         loading.load_each(directory, %w[*.hecksagon *.world])
-        load_environment_overlay(loading, directory)
-      end
-
-      # A domain that splits `persisted_by` per environment declares none in its base
-      # `.hecksagon`, so resolution fails without this overlay — opt-in via
-      # HECKS_PROJECT_ENVIRONMENT, a no-op otherwise.
-      def load_environment_overlay(loading, directory)
-        target_environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil) or return
-
-        loading.load_each(directory, [File.join("environments", "#{target_environment}.hecksagon")])
-        loading.load_each(directory, [File.join("environments", "#{target_environment}.world")])
+        loading.load_overlay(directory, ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
       end
 
       # @return [Integer] 0
@@ -125,7 +115,7 @@ module Hecks
       # @return [Array] the journal's latest era and the bluebook it held
       def held_era(lineage)
         latest = lineage.eras.last
-        [latest, lineage_manager.shadow(latest[:held_text])]
+        [latest, lineage_manager.held_bluebook(latest)]
       end
 
       # A journal with no era yet holds the bluebook as its first, so there is nothing to scaffold.

data/lib/hecks/tools.rb

@@ -20,9 +20,11 @@ module Hecks
       "standardize_comments_rust"      => ["tools/rust_comment_style", "RustCommentStyle"],
       "regen_codegen_domains"          => ["tools/regeneration_run", "RegenerationRun"],
       "gate"                           => ["tools/gate", "Gate"],
+      "move_disables"                  => ["tools/move_disables", "MoveDisables"],
       "argument_gate_matrix"           => ["tools/argument_gate_matrix", "ArgumentGateMatrix"],
       "project_ci_gates"               => ["tools/ci_gates", "CiGates"],
       "decide_ci_gate"                 => ["tools/ci_gate_decision", "CiGateDecision"],
+      "project_ci_pipeline"            => ["tools/ci_workflows", "CiWorkflows"],
       "project_lanes"                  => ["tools/lanes", "Lanes"],
       "project_tools_doc"              => ["tools/tools_doc", "ToolsDoc"],
       "project_deploy"                 => ["tools/deploy_recipe", "DeployRecipe"],
@@ -44,7 +46,8 @@ module Hecks
       "evolve"                         => ["tools/evolve_run", "EvolveRun"],
       "query_ir"                       => ["tools/query_ir_run", "QueryIrRun"],
       "codemod_hoist_local_givens"     => ["tools/hoist_local_givens", "HoistLocalGivens"],
-      "codemod_implicit_append_fields" => ["tools/drop_implicit_append_fields", "DropImplicitAppendFields"]
+      "codemod_implicit_append_fields" => ["tools/drop_implicit_append_fields", "DropImplicitAppendFields"],
+      "codemod_move_former_name"       => ["tools/move_former_name", "MoveFormerName"]
     }.freeze
 
     module_function

data/lib/hecks/vendoring/git_source.rb

@@ -1,5 +1,6 @@
 require "open3"
 require "tmpdir"
+require_relative "../text"
 require_relative "git_environment"
 
 module Hecks
@@ -56,14 +57,16 @@ module Hecks
       #
       # @param ref [String] the commit-ish to read from
       # @param subtree [String] a repository-relative directory, such as `"payments/bluebook"`
-      # @param glob [String] a `File.fnmatch` pattern the file's own name must match
+      # @param glob [String] a `File.fnmatch` pattern the file's own name must match; braces
+      #   (`"*.{bluebook,adapter}"`) name alternatives
       # @return [Array<String>] repository-relative paths, sorted
       def files(ref, subtree, glob = "*")
         out, _err, status = git("ls-tree", "-r", "--name-only", ref, "--", subtree)
         return [] unless status.success?
 
-        out.lines.map(&:chomp).select do |file|
-          File.dirname(file) == subtree && File.fnmatch(glob, File.basename(file))
+        listed = out.lines.map(&:chomp)
+        listed.select do |file|
+          File.dirname(file) == subtree && File.fnmatch(glob, File.basename(file), File::FNM_EXTGLOB)
         end.sort
       end
 
@@ -89,7 +92,7 @@ module Hecks
 
       def run!(label, *command)
         _out, err, status = Open3.capture3(GitEnvironment.clean, *command)
-        raise Error, "#{label} failed: #{err.lines.first.to_s.strip}" unless status.success?
+        raise Error, "#{label} failed: #{Text.first_line(err)}" unless status.success?
       end
     end
   end

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "5.0.0".freeze # rust/host/HECKS_RELEASE names the same release
+  VERSION = "7.0.0".freeze # rust/host/HECKS_RELEASE names the same release
 end

data/lib/hecks/vocabulary.rb

@@ -62,6 +62,17 @@ module Hecks
         {"symbol"=>"==", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"false"}.freeze,
         {"symbol"=>"!=", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"true"}.freeze
       ].freeze,
+      "DispatchStage" => [
+        {"name"=>"request"}.freeze,
+        {"name"=>"arguments"}.freeze,
+        {"name"=>"role"}.freeze,
+        {"name"=>"references"}.freeze,
+        {"name"=>"state"}.freeze,
+        {"name"=>"givens"}.freeze,
+        {"name"=>"ensures"}.freeze,
+        {"name"=>"invariants"}.freeze,
+        {"name"=>"remote"}.freeze
+      ].freeze,
       "DomainRefusal" => [
         {"name"=>"AbsentArgument"}.freeze,
         {"name"=>"AlreadyExists"}.freeze,
@@ -103,6 +114,53 @@ module Hecks
         {"name"=>"tel", "pattern"=>"phone|\\btel(ephone)?\\b", "resolves_to"=>"html_type"}.freeze,
         {"name"=>"textarea", "pattern"=>"\\b(text|body|note|notes|description|message|comment)\\b", "resolves_to"=>"kind"}.freeze
       ].freeze,
+      "GateCheck" => [
+        {"name"=>"rspec", "id"=>"rspec", "title"=>"rspec (parallel)", "runs_in"=>"ci", "argv"=>"", "script"=>"# Workers are grouped by this machine's own last timings, kept under the git directory\n# (shared by every worktree, never committed). CI's committed baseline leaves out the io\n# specs this run includes, so it only seeds the first run; each run then rewrites the log.\nlog=\"$(git rev-parse --git-common-dir)/hecks_rspec_runtime.log\"\n[ -f \"$log\" ] || cp .github/rspec_runtime_baseline.log \"$log\"\nbundle exec parallel_rspec spec -n {workers} --group-by runtime --runtime-log \"$log\" --allowed-missing 100 \\\n  -o \"--format progress --format ParallelTests::RSpec::RuntimeLogger --out $log\"\n", "blocked"=>"the suite is red."}.freeze,
+        {"name"=>"fuzzing", "id"=>"fuzzing", "title"=>"spec/fuzzing, which the parallel run above excludes", "argv"=>"bundle exec rspec spec/fuzzing --tag fuzzing", "script"=>"", "blocked"=>"spec/fuzzing is red."}.freeze,
+        {"name"=>"query_agreement", "id"=>"query_agreement", "title"=>"adapter agreement, one declared query and every engine giving the same answer", "argv"=>"bundle exec rspec spec/adapters/query_agreement_spec.rb --tag io", "script"=>"", "blocked"=>"the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which."}.freeze,
+        {"name"=>"engine_agreement", "id"=>"engine_agreement", "title"=>"engine agreement, every declared comparator on both engines", "argv"=>"bundle exec exe/hecks conformance_run.check_engine_agreement! --wait", "script"=>"", "blocked"=>"a comparator is missing a shared case or a cross-engine spec."}.freeze,
+        {"name"=>"shape_ledger", "id"=>"shape_ledger", "title"=>"shape ledger, every bluebook's storage shape held by the ledger or reached by a translation edge", "argv"=>"bundle exec exe/hecks conformance_run.check_shape_ledger! --wait", "script"=>"", "blocked"=>"a bluebook's storage shape moved with no translation edge from the shape the ledger holds; the failure prints the edge to commit. A change that only adds is settled in one step with `hecks conformance_run.check_shape_ledger! --confirm --additive --wait`, which writes the empty edge and moves the ledger; a change that renames or reshapes data needs rules first."}.freeze,
+        {"name"=>"model_check", "id"=>"model_check", "title"=>"model check, unreachable states, dead transitions and orphaned handlers", "argv"=>"bundle exec exe/hecks ModelCheckRun.model_check! --wait", "script"=>"", "blocked"=>"the model checker found something."}.freeze,
+        {"name"=>"doc_coverage", "id"=>"doc_coverage", "title"=>"docs coverage, words with no running example", "argv"=>"bundle exec exe/hecks conformance_run.measure_doc_coverage! --wait", "script"=>"", "blocked"=>"the language ships something undocumented; write the missing sections and examples."}.freeze,
+        {"name"=>"rubocop", "id"=>"rubocop", "title"=>"rubocop, the static style and correctness gate", "argv"=>"bundle exec rubocop -c .rubocop.yml", "script"=>"", "blocked"=>"rubocop found an offense."}.freeze,
+        {"name"=>"codegen_drift", "id"=>"codegen_drift", "title"=>"codegen drift, rust/src/generated/ must match a fresh regeneration", "argv"=>"bundle exec exe/hecks regeneration_run.regenerate_corpus! --check --wait", "script"=>"", "blocked"=>"regenerating hits a diff. The whole generated tree is committed, so run `hecks regeneration_run.regenerate_corpus! --confirm` and commit what it changed."}.freeze,
+        {"name"=>"comment_style", "id"=>"comment_style", "title"=>"comment style, every comment under lib/hecks and spec against docs/COMMENT_STYLE_GUIDE.md", "argv"=>"bundle exec exe/hecks style_run.check_comments! paths=lib/hecks spec --wait", "script"=>"", "blocked"=>"a comment breaks the style guide, such as a line past 100 characters; `hecks StyleRun.fix_comments!` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check."}.freeze,
+        {"name"=>"comment_blocks", "id"=>"comment_blocks", "title"=>"comment blocks, no run of comment lines past ADR 0075's cap", "argv"=>"bundle exec exe/hecks style_run.check_comments! paths=lib,spec,examples only=long_block --wait", "script"=>"", "blocked"=>"a comment block ran past the cap; shorten it."}.freeze,
+        {"name"=>"command_names", "id"=>"command_names", "title"=>"command names, every launcher name a workflow, hook, gate row, spec or guide invokes still resolves", "argv"=>"bundle exec exe/hecks conformance_run.check_command_names! --wait", "script"=>"", "blocked"=>"a file invokes a launcher name the launcher no longer accepts (a renamed command, or a write without its !), so what runs it runs nothing. The failure names each file:line and the nearest valid name. Mark an invocation that is shown and not run with `dead-name-check: skip` on its line or the one before, a fence with `skip`, `historical` or `illustrative` after its language, or a whole page with `dead-name-check: skip-file` in its first lines."}.freeze,
+        {"name"=>"workflow_pagination", "id"=>"workflow_pagination", "title"=>"workflow pagination, no step counts or waits for GitHub list items from the first page alone", "argv"=>"bundle exec exe/hecks conformance_run.check_workflow_pagination! --wait", "script"=>"", "blocked"=>"a workflow step counts or waits for the items of a list call (artifacts, runs, jobs, issues, releases, pulls, commits) and reads only the first 30. Add --paginate and count the lines it prints, or filter the path with ?name=."}.freeze,
+        {"name"=>"secret_output", "id"=>"secret_output", "title"=>"secret output, no value a world hands an adapter as a secret reaches what a launcher prints", "argv"=>"bundle exec rspec spec/secret_output_spec.rb", "script"=>"", "blocked"=>"a declared secret, or a database URL's password, reached a refusal, a note or a result. Hold it through `Hecks::Secrets` where the world hands it over, and print through a guarded stream."}.freeze,
+        {"name"=>"adapter_words", "id"=>"adapter_words", "title"=>"adapter words, no domain name equal to a technology word the adapters are named for", "argv"=>"bundle exec rspec spec/adapter_words_spec.rb", "script"=>"", "blocked"=>"a domain name (a module, aggregate, command or query) equals a technology word listed in lib/hecks/hecks/adapter_words.json. The failure names each one; rename the domain name, not the adapter."}.freeze,
+        {"name"=>"rust_fmt", "id"=>"rust_fmt", "title"=>"rustfmt, every Rust crate laid out as `cargo fmt` would", "argv"=>"", "script"=>"# The main crate's generated modules are not committed, so cargo fmt would stop at a\n# missing file on a fresh checkout; its hand-written entry points are named instead.\nrustfmt --check --edition 2021 rust/src/main.rs rust/src/kernel/mod.rs rust/tests/*.rs\nfor crate in parser codegen lsp host web build; do\n  cargo fmt --check --manifest-path \"rust/$crate/Cargo.toml\"\ndone\n", "blocked"=>"a Rust file is not laid out as rustfmt has it; run `cargo fmt` in its crate (rust/src/exemplar is exempt, it is text templates). Generated Rust is laid out by its generators, so fix the generator, not the output."}.freeze,
+        {"name"=>"rust_io", "id"=>"rust_io", "title"=>"rust io specs, conformance, coercion, has_many, semantics corpus, corpus regeneration and feature exclusivity", "argv"=>"", "script"=>"# Building the banking crate makes banking the default feature and rewrites the module\n# list, both tracked. They are put back on the way out, and the check will not start over\n# a person's uncommitted edits to them.\nrewritten=\"rust/Cargo.toml rust/src/generated/mod.rs\"\nif [ -n \"$(git status --porcelain -- $rewritten)\" ]; then\n  echo \"uncommitted changes in $rewritten; commit or discard them first\" >&2\n  exit 1\nfi\ntrap 'git checkout -q -- $rewritten' EXIT\nenv -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus! --confirm --wait\nbundle exec exe/hecks build.project_rust! domain=examples/banking --wait\nbundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb\nbundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb\nbundle exec rspec --tag io --profile 8 spec/rust_build_regeneration_order_spec.rb spec/rust_build_regeneration_subset_spec.rb\n", "blocked"=>"a Rust io spec failed, or skipped; the crate it built is under rust/target."}.freeze,
+        {"name"=>"ci_codegen_drift", "id"=>"codegen_drift", "title"=>"codegen drift, the committed generated Rust must match the regeneration this job holds", "argv"=>"git diff --exit-code --stat -- rust/src/generated rust/Cargo.toml", "script"=>"", "blocked"=>"regenerating hits a diff. The whole generated tree is committed, so run `hecks regeneration_run.regenerate_corpus! --confirm` and commit what it changed."}.freeze,
+        {"name"=>"generated_tree", "id"=>"generated_tree", "title"=>"whole-tree specs, the examples tagged generated_all against every domain's generated Rust", "argv"=>"bundle exec rspec --tag generated_all", "script"=>"", "blocked"=>"a spec that reads the whole generated tree failed; run `hecks regeneration_run.regenerate_corpus! --confirm` to materialize every domain, then `bundle exec rspec --tag generated_all`."}.freeze,
+        {"name"=>"rust_clippy", "id"=>"rust_clippy", "title"=>"clippy, every Rust crate with its warnings as errors", "argv"=>"", "script"=>"for crate in . parser codegen lsp host web build; do\n  cargo clippy --all-targets --manifest-path \"rust/$crate/Cargo.toml\" -- -D warnings\ndone\n", "blocked"=>"clippy found a warning in a Rust crate, under the strict `[lints.clippy]` table of its Cargo.toml. The main crate needs rust/src/generated, so run `hecks regeneration_run.regenerate_corpus! --confirm` first on a fresh checkout. Fix the code, or allow a lint at the one site with a line saying why; a warning in generated Rust is fixed in its generator."}.freeze,
+        {"name"=>"lint_deploy_recipes", "id"=>"lint_deploy_recipes", "title"=>"generated deploy recipes, a command with no checked exit status or no echo", "argv"=>"bundle exec exe/hecks deploy MakefileCheck.lint! --wait", "script"=>"", "blocked"=>"a generated deploy Makefile has an unchecked command, or real AWS or database work with no echo telling the person running it what is about to happen."}.freeze,
+        {"name"=>"fuzz_1_of_3", "id"=>"fuzz_1_of_3", "title"=>"fuzz, shard 1 of 3 of the example domains on the Memory adapter", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! shard=1/3 --wait", "script"=>"", "blocked"=>"a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."}.freeze,
+        {"name"=>"fuzz_2_of_3", "id"=>"fuzz_2_of_3", "title"=>"fuzz, shard 2 of 3 of the example domains on the Memory adapter", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! shard=2/3 --wait", "script"=>"", "blocked"=>"a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."}.freeze,
+        {"name"=>"fuzz_3_of_3", "id"=>"fuzz_3_of_3", "title"=>"fuzz, shard 3 of 3 of the example domains on the Memory adapter", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! shard=3/3 --wait", "script"=>"", "blocked"=>"a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."}.freeze,
+        {"name"=>"fuzz_sqlite_1_of_3", "id"=>"fuzz_sqlite_1_of_3", "title"=>"fuzz, shard 1 of 3 on a real on-disk SQLite database", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! adapter=sqlite seeds=6 shard=1/3 --wait", "script"=>"", "blocked"=>"the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."}.freeze,
+        {"name"=>"fuzz_sqlite_2_of_3", "id"=>"fuzz_sqlite_2_of_3", "title"=>"fuzz, shard 2 of 3 on a real on-disk SQLite database", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! adapter=sqlite seeds=6 shard=2/3 --wait", "script"=>"", "blocked"=>"the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."}.freeze,
+        {"name"=>"fuzz_sqlite_3_of_3", "id"=>"fuzz_sqlite_3_of_3", "title"=>"fuzz, shard 3 of 3 on a real on-disk SQLite database", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! adapter=sqlite seeds=6 shard=3/3 --wait", "script"=>"", "blocked"=>"the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."}.freeze,
+        {"name"=>"fuzz_shards", "id"=>"fuzz_shards", "title"=>"fuzz shards, the three shards together hold every domain of the sweep once", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! list_shards=3 --wait", "script"=>"", "blocked"=>"the split of the fuzz sweep into three shards drops or repeats a domain, or cannot be listed; a shard would then sweep less than the sweep it stands for. Read the refusal, and fix lib/hecks/tools/fuzz_sweep/shards.rb or the cost table spec/fuzzing/fuzz_runtime_baseline.log."}.freeze,
+        {"name"=>"fuzz_postgres_1_of_2", "id"=>"fuzz_postgres_1_of_2", "title"=>"fuzz, shard 1 of 2 on real Postgres (each run in its own scratch schema)", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! adapter=postgres seeds=3 steps=20 shard=1/2 --wait", "script"=>"", "blocked"=>"the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD."}.freeze,
+        {"name"=>"fuzz_postgres_2_of_2", "id"=>"fuzz_postgres_2_of_2", "title"=>"fuzz, shard 2 of 2 on real Postgres (each run in its own scratch schema)", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz! adapter=postgres seeds=3 steps=20 shard=2/2 --wait", "script"=>"", "blocked"=>"the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD."}.freeze,
+        {"name"=>"vocabulary_drift", "id"=>"vocabulary_drift", "title"=>"vocabulary, the reserved-name tables regenerated must match the committed ones", "argv"=>"", "script"=>"bundle exec exe/hecks language_run.project_vocabulary! --confirm --wait\nbundle exec exe/hecks language_run.project_reserved_names! --confirm --wait\ngit diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs\n", "blocked"=>"a generated vocabulary file is stale; the check rewrote it, so commit the result."}.freeze,
+        {"name"=>"ci_gates", "id"=>"ci_gates", "title"=>"ci gates, the CiGate rows must match the marked regions of the workflows", "argv"=>"bundle exec exe/hecks regeneration_run.project_ci_gates! --wait", "script"=>"", "blocked"=>"a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates! --confirm`."}.freeze,
+        {"name"=>"ci_pipeline", "id"=>"ci_pipeline", "title"=>"ci pipeline, the workflow rows must match the files they project", "argv"=>"bundle exec exe/hecks regeneration_run.project_ci_pipeline! --wait", "script"=>"", "blocked"=>"a workflow row changed with no projection, or a projected workflow was edited by hand; run `hecks regeneration_run.project_ci_pipeline! --confirm`."}.freeze,
+        {"name"=>"tools_doc", "id"=>"tools_doc", "title"=>"tools doc, docs/tools.md must match the RetiredScript rows", "argv"=>"bundle exec exe/hecks regeneration_run.project_tools_doc! --wait", "script"=>"", "blocked"=>"a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc! --confirm`."}.freeze,
+        {"name"=>"rust_coverage", "id"=>"rust_coverage", "title"=>"rust coverage, every generated module", "argv"=>"bundle exec exe/hecks query corpus_run.corpus_rust_coverage --wait", "script"=>"", "blocked"=>"a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted."}.freeze,
+        {"name"=>"rust_coverage_codegen", "id"=>"rust_coverage_codegen", "title"=>"rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta", "argv"=>"", "script"=>"for module in pizzas governance identity banking meta; do\n  bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait\ndone\n", "blocked"=>"hecks-codegen generated nothing for a construct a domain declares."}.freeze,
+        {"name"=>"kernel_coverage", "id"=>"kernel_coverage", "title"=>"rust kernel coverage, every capability variant has a kernel file", "argv"=>"bundle exec exe/hecks kernel_run.measure_kernel_coverage! --wait", "script"=>"", "blocked"=>"a capability's enum variant has no rust/src/kernel file behind it."}.freeze,
+        {"name"=>"rust_vocabulary_drift", "id"=>"rust_vocabulary_drift", "title"=>"rust vocabulary, the kernel vocab tables regenerated must match the committed ones", "argv"=>"", "script"=>"bundle exec exe/hecks language_run.project_rust_vocabulary! --confirm --wait\ngit diff --exit-code -- rust/src/kernel/vocab/\nuntracked=\"$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)\"\nif [ -n \"$untracked\" ]; then\n  echo \"rust/src/kernel/vocab has uncommitted generated files:\" >&2\n  echo \"$untracked\" >&2\n  exit 1\nfi\n", "blocked"=>"the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result."}.freeze
+      ].freeze,
+      "GateStage" => [
+        {"name"=>"pre_push", "env"=>"HECKS_ENVIRONMENT=memory HECKS_PROCESS_SPECS=1", "checks"=>"fuzzing,query_agreement,engine_agreement,shape_ledger,model_check,doc_coverage,rubocop,codegen_drift,comment_style,comment_blocks,rust_fmt"}.freeze,
+        {"name"=>"ci_suite", "env"=>"HECKS_ENVIRONMENT=memory HECKS_PROCESS_SPECS=1", "checks"=>"rspec"}.freeze,
+        {"name"=>"quick", "env"=>"HECKS_ENVIRONMENT=memory", "checks"=>"shape_ledger,rubocop,comment_style,comment_blocks,secret_output,adapter_words"}.freeze,
+        {"name"=>"rust_io", "env"=>"CI=true HECKS_ENVIRONMENT=memory", "checks"=>"rust_io"}.freeze,
+        {"name"=>"ci", "env"=>"", "checks"=>"model_check,shape_ledger,engine_agreement,doc_coverage,rubocop,comment_style,comment_blocks,ci_codegen_drift,generated_tree,rust_fmt,rust_clippy,lint_deploy_recipes,command_names,workflow_pagination,fuzz_1_of_3,fuzz_2_of_3,fuzz_3_of_3,fuzz_sqlite_1_of_3,fuzz_sqlite_2_of_3,fuzz_sqlite_3_of_3,fuzz_postgres_1_of_2,fuzz_postgres_2_of_2,fuzz_shards,vocabulary_drift,ci_gates,ci_pipeline,tools_doc,rust_coverage,rust_coverage_codegen,kernel_coverage,rust_vocabulary_drift"}.freeze
+      ].freeze,
       "IncludeHaystack" => [
         {"type"=>"Array", "strategy"=>"membership"}.freeze,
         {"type"=>"String", "strategy"=>"substring"}.freeze
@@ -117,7 +175,8 @@ module Hecks
         {"glob"=>"*.bluebook"}.freeze,
         {"glob"=>"translations/*.bluebook"}.freeze,
         {"glob"=>"*.hecksagon"}.freeze,
-        {"glob"=>"*.world"}.freeze
+        {"glob"=>"*.world"}.freeze,
+        {"glob"=>"*.contextmap"}.freeze
       ].freeze,
       "MutationOp" => [
         {"name"=>"set", "sign"=>""}.freeze,
@@ -136,7 +195,8 @@ module Hecks
         {"name"=>"scale_call"}.freeze
       ].freeze,
       "PrebuiltBinary" => [
-        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze
+        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze,
+        {"name"=>"host-arm64", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"aarch64-unknown-linux-gnu", "runner"=>"ubuntu-22.04-arm"}.freeze
       ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,
@@ -147,12 +207,12 @@ module Hecks
       ].freeze,
       "QaDial" => [
         {"name"=>"cadence_seconds", "type"=>"Integer", "meaning"=>"Minimum gap in seconds between one tick's report and the next dispatch; 0 is immediately. Read by the `/loop hecks_qa` caller, not by any script."}.freeze,
-        {"name"=>"pr_cap_per_day", "type"=>"Integer", "meaning"=>"Most PRs (Patch plus Improvement) `hecks quality_control patch.open` opens per calendar day; 0 is uncapped."}.freeze,
+        {"name"=>"pr_cap_per_day", "type"=>"Integer", "meaning"=>"Most PRs (Patch plus Improvement) `hecks quality_control Patch.open!` opens per calendar day; 0 is uncapped."}.freeze,
         {"name"=>"widening_tiers", "type"=>"Array", "meaning"=>"Fuzz depth by `Target.clean_streak`, in three discrete tiers, read by `SweepDepth.for_streak`. The last row (`upto: Float::INFINITY`) is the ceiling."}.freeze,
         {"name"=>"sweep_max_parallel", "type"=>"Integer", "meaning"=>"How many `hecks quality_control query sweep.run <target>` children `--all` keeps running at once."}.freeze,
         {"name"=>"liveness_fallback_seconds", "type"=>"Integer", "meaning"=>"How long the `/loop hecks_qa` caller waits for a tick's report before assuming it stalled."}.freeze,
-        {"name"=>"draft_only", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control patch.open` opens its PR as a draft; false opens it ready for review."}.freeze,
-        {"name"=>"auto_merge", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control patch.open` queues the PR for auto-merge once it is open."}.freeze,
+        {"name"=>"draft_only", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control Patch.open!` opens its PR as a draft; false opens it ready for review."}.freeze,
+        {"name"=>"auto_merge", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control Patch.open!` queues the PR for auto-merge once it is open."}.freeze,
         {"name"=>"adversarial_fraction", "type"=>"Numeric", "meaning"=>"Fraction (0.0..1.0) of generated command steps mutated adversarially; 0 turns the layer off. Higher finds refusal-ordering splits sooner but reaches deep state less often."}.freeze,
         {"name"=>"guided_generation", "type"=>"Boolean", "meaning"=>"Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`)."}.freeze,
         {"name"=>"corpus_splice_probability", "type"=>"Numeric", "meaning"=>"Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage. Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost."}.freeze,
@@ -172,7 +232,15 @@ module Hecks
         {"name"=>"generated_domains_per_tick", "type"=>"Integer", "meaning"=>"How many generated domains one `hecks quality_control sweep.tick` checks after the rotation sweep; 0 skips the step."}.freeze,
         {"name"=>"generated_domains_rust", "type"=>"Boolean", "meaning"=>"Whether generated domains are also compared against a compiled Rust binary built in a scratch copy."}.freeze,
         {"name"=>"generated_domain_seeds", "type"=>"Integer", "meaning"=>"Generated sequences run per generated domain."}.freeze,
-        {"name"=>"structural_refusal_boundary", "type"=>"Array", "meaning"=>"Construct families a skipped query verb may belong to. A skip inside the list is logged Held, one outside it Surprised. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails when a family here is declared by no committed manifest."}.freeze
+        {"name"=>"mutation_files", "type"=>"Array", "meaning"=>"Rust files `hecks quality_control target.mutate --from-dials` mutates, and so the files one `hecks quality_control sweep.tick` mutation-tests after the generated domains; empty skips the step."}.freeze,
+        {"name"=>"mutation_equivalent", "type"=>"Array", "meaning"=>"Mutants that behave the same as the original code, by the name `cargo mutants --list` gives them without the file and line; never run, so they cannot be reported as survivors."}.freeze,
+        {"name"=>"structural_refusal_boundary", "type"=>"Array", "meaning"=>"Construct families a skipped query verb may belong to. A skip inside the list is logged Held, one outside it Surprised. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails when a family here is declared by no committed manifest."}.freeze,
+        {"name"=>"red_main_check", "type"=>"Boolean", "meaning"=>"Whether each `hecks quality_control sweep.tick` runs the quick gate on local main as its last finding step, logging each red check as a bug and fixing the self-contained ones; false skips the step."}.freeze,
+        {"name"=>"event_pump", "type"=>"Boolean", "meaning"=>"Whether each `hecks quality_control sweep.tick` runs the event pump as its last step: each attached domain's policies react to the events past their cursors, and every refusal is named. false skips the step; `hecks quality_control event_pump.pump!` runs it regardless."}.freeze,
+        {"name"=>"push_nudge", "type"=>"Boolean", "meaning"=>"Whether each `hecks quality_control sweep.tick` checks once whether a push of local main is due and files, revises or finishes the one `push-due` Work row; false skips the check. The thresholds are the QualityControl world's `push_nudge` setting."}.freeze,
+        {"name"=>"quiesced", "type"=>"Boolean", "meaning"=>"Whether each `hecks quality_control sweep.tick` runs no step at all: every step prints `quiesced: skipped <step>` and the tick exits 0, so a mint window sees a quiet ledger. The setting is read once at the start of a tick; `hecks qa_quiesce.hold!` writes a marker file every step checks as well, which a tick already running notices before its next step."}.freeze,
+        {"name"=>"main_maintenance", "type"=>"Boolean", "meaning"=>"Whether each `hecks quality_control sweep.tick` runs the main-maintenance chain after the main-check step: the quick gate on main, the reconcile plan, and the push through the train when origin is behind. false skips the chain."}.freeze,
+        {"name"=>"maintenance_confirm", "type"=>"Boolean", "meaning"=>"Whether the main-maintenance chain's reconcile writes after its plan (`Era.Reconcile` with confirm); false leaves the reconcile a dry run that writes nothing."}.freeze
       ].freeze,
       "QueryComparator" => [
         {"name"=>"eq"}.freeze,
@@ -185,6 +253,40 @@ module Hecks
         {"name"=>"contains"}.freeze,
         {"name"=>"none_in_state"}.freeze
       ].freeze,
+      "Reducer" => [
+        {"name"=>"count", "identity"=>"0", "combine"=>"add", "inverse"=>"subtract"}.freeze,
+        {"name"=>"sum", "identity"=>"0", "combine"=>"add", "inverse"=>"subtract"}.freeze,
+        {"name"=>"avg", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"min", "identity"=>"null", "combine"=>"min", "inverse"=>""}.freeze,
+        {"name"=>"max", "identity"=>"null", "combine"=>"max", "inverse"=>""}.freeze,
+        {"name"=>"median", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"percentile", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"any", "identity"=>"false", "combine"=>"or", "inverse"=>""}.freeze,
+        {"name"=>"all", "identity"=>"true", "combine"=>"and", "inverse"=>""}.freeze
+      ].freeze,
+      "RefusalClass" => [
+        {"name"=>"AbsentArgument", "kind"=>"absent_argument", "stage"=>"arguments"}.freeze,
+        {"name"=>"AlreadyExists", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"AttributeAbsent", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"EnsuresNotMet", "kind"=>"refused", "stage"=>"ensures"}.freeze,
+        {"name"=>"GivenNotMet", "kind"=>"refused", "stage"=>"givens"}.freeze,
+        {"name"=>"InvariantViolation", "kind"=>"refused", "stage"=>"invariants"}.freeze,
+        {"name"=>"LifecycleRefused", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"NothingToCorrect", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"NotFound", "kind"=>"not_found", "stage"=>"state"}.freeze,
+        {"name"=>"ProjectionAbsent", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"RemoteRefusal", "kind"=>"refused", "stage"=>"remote"}.freeze,
+        {"name"=>"TypeMismatch", "kind"=>"refused", "stage"=>"arguments"}.freeze,
+        {"name"=>"Unauthorized", "kind"=>"unauthorized", "stage"=>"role"}.freeze,
+        {"name"=>"UnknownArgument", "kind"=>"refused", "stage"=>"arguments"}.freeze,
+        {"name"=>"UnknownVerb", "kind"=>"refused", "stage"=>"request"}.freeze
+      ].freeze,
+      "RefusalKind" => [
+        {"name"=>"refused"}.freeze,
+        {"name"=>"not_found"}.freeze,
+        {"name"=>"unauthorized"}.freeze,
+        {"name"=>"absent_argument"}.freeze
+      ].freeze,
       "RefusalSiteArgument" => [
         {"refusal"=>"NotFound", "site"=>"creating_no_identity", "argument"=>"command", "shape"=>"scalar", "quoting"=>"none", "separator"=>"", "sorted"=>"false", "when_empty"=>""}.freeze,
         {"refusal"=>"NotFound", "site"=>"creating_no_identity", "argument"=>"aggregate", "shape"=>"scalar", "quoting"=>"none", "separator"=>"", "sorted"=>"false", "when_empty"=>""}.freeze,
@@ -359,7 +461,7 @@ module Hecks
         {"refusal"=>"InvariantViolation", "site"=>"closed_set_member", "template"=>"{type} admits {admitted} — got {offered}"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"value_object_invariant", "template"=>"{name} invariant violated — {description} (given {offered})"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"admits_declared_set", "template"=>"{name} admits {admits} — {admitted} — got {offered}"}.freeze,
-        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this bluebook does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"group_by_collision", "template"=>"{read_model} groups by {fields}, but rows {ids} share {key} — a group_by leaf holds one row; add a field that tells them apart"}.freeze,
         {"refusal"=>"Unauthorized", "site"=>"tenant_required", "template"=>"{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to"}.freeze,
         {"refusal"=>"Unauthorized", "site"=>"role_mismatch", "template"=>"{command} refused — role: {role}, and the caller stated {caller_role}"}.freeze,
@@ -367,6 +469,14 @@ module Hecks
         {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
         {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
       ].freeze,
+      "RehearsalScope" => [
+        {"name"=>"quick", "stages"=>"quick"}.freeze,
+        {"name"=>"deep", "stages"=>"quick,impacted"}.freeze
+      ].freeze,
+      "RehearsalStage" => [
+        {"name"=>"quick", "kind"=>"gate", "argument"=>"quick"}.freeze,
+        {"name"=>"impacted", "kind"=>"impacted", "argument"=>""}.freeze
+      ].freeze,
       "ReleaseFile" => [
         {"path"=>"lib/hecks/version.rb", "lines"=>"^\\s*VERSION = \"[0-9]+\\.[0-9]+\\.[0-9]+\"\\.freeze$"}.freeze,
         {"path"=>"CHANGELOG.md", "lines"=>""}.freeze,
@@ -416,7 +526,7 @@ module Hecks
         {"script"=>"heki_compact", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"compact_heki"}.freeze,
         {"script"=>"vendor_bluebook", "section"=>"Custodian", "aggregate"=>"Package", "verb"=>"vendor", "note"=>"waits: a refusal exits 1 with its reason on stderr"}.freeze,
         {"script"=>"project_cli", "section"=>"Custodian", "aggregate"=>"Launch", "verb"=>"project_cli"}.freeze,
-        {"script"=>"hecks_mcp_door", "section"=>"Custodian", "aggregate"=>"Launch", "verb"=>"serve_mcp"}.freeze,
+        {"script"=>"hecks_mcp_door", "section"=>"Custodian", "aggregate"=>"Server", "verb"=>"serve_mcp"}.freeze,
         {"script"=>"project_rust", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"project_rust"}.freeze,
         {"script"=>"project_wasm", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_wasm"}.freeze,
         {"script"=>"project_host", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_host"}.freeze,
@@ -443,6 +553,7 @@ module Hecks
         {"script"=>"project_refusal_wording", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_refusal_wording"}.freeze,
         {"script"=>"project_reserved_names", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_reserved_names"}.freeze,
         {"script"=>"project_parser_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_parser_table"}.freeze,
+        {"script"=>"project_phrase_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_phrase_table"}.freeze,
         {"script"=>"project_bootstrap_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_bootstrap_table"}.freeze,
         {"script"=>"project_field_hints", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_field_hints"}.freeze,
         {"script"=>"expression_projection", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_expression_tables"}.freeze,
@@ -474,6 +585,7 @@ module Hecks
         {"script"=>"canonicalise", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"canonicalise"}.freeze,
         {"script"=>"codemod_hoist_local_givens", "section"=>"Codebase", "aggregate"=>"CodemodRun", "verb"=>"hoist_local_givens"}.freeze,
         {"script"=>"codemod_implicit_append_fields", "section"=>"Codebase", "aggregate"=>"CodemodRun", "verb"=>"drop_implicit_append_fields"}.freeze,
+        {"script"=>"codemod_move_former_name", "section"=>"Codebase", "aggregate"=>"CodemodRun", "verb"=>"move_former_name"}.freeze,
         {"script"=>"rspec_shard_files", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"shard_specs"}.freeze,
         {"script"=>"rspec_io_parallel_files", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"list_io_parallel_specs"}.freeze,
         {"script"=>"rspec_io_parallel_files", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"write_io_parallel_spec_list"}.freeze,
@@ -489,12 +601,13 @@ module Hecks
         {"script"=>"query_ir", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"ir_constructs"}.freeze,
         {"script"=>"query_ir", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"ir_duplicates"}.freeze,
         {"script"=>"query_ir", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"ir_impact"}.freeze,
-        {"script"=>"hecks_query_ir_mcp", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"serve_query_ir_mcp"}.freeze,
-        {"script"=>"present", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"present"}.freeze,
+        {"script"=>"hecks_query_ir_mcp", "section"=>"Codebase", "aggregate"=>"Server", "verb"=>"serve_query_ir_mcp"}.freeze,
+        {"script"=>"present", "section"=>"Codebase", "aggregate"=>"Server", "verb"=>"present"}.freeze,
         {"script"=>"release", "section"=>"Codebase", "aggregate"=>"PublishingRun", "verb"=>"publish", "note"=>"without --confirm, the old --dry-run"}.freeze,
         {"script"=>"release_gem", "section"=>"Codebase", "aggregate"=>"PublishingRun", "verb"=>"publish_gem"}.freeze,
         {"script"=>"(new)", "section"=>"Codebase", "aggregate"=>"GateRun", "verb"=>"gate"}.freeze,
         {"script"=>"qa_tick", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"tick"}.freeze,
+        {"script"=>"qa_event_pump", "section"=>"QualityControl", "aggregate"=>"EventPump", "verb"=>"pump"}.freeze,
         {"script"=>"qa_sweep", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"run", "passes"=>"--all --seeds N --steps N --adversarial F --role-draw F --dry-run F --self-consistency BOOL --modes a,b --persistence-parity --no-parity"}.freeze,
         {"script"=>"qa_sweep", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"release"}.freeze,
         {"script"=>"qa_pr_check", "section"=>"QualityControl", "aggregate"=>"Clearance", "verb"=>"check_pull_requests"}.freeze,
@@ -505,10 +618,13 @@ module Hecks
         {"script"=>"qa_seed_targets", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"seed"}.freeze,
         {"script"=>"qa_generated_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"check_generated_domains", "passes"=>"--domains 3 --start N --forms a,b --seeds 5 --steps 25 --adversarial 0.3 --rust --shrink-budget 200 --domain-shrink-budget 40 --promote dir --name N --from-dials --blueprint F --source F"}.freeze,
         {"script"=>"qa_mine_combinations", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"mine_combinations", "passes"=>"--candidates 3 --rust --seeds 5 --steps 25 --adversarial 0.3 --repair-rounds 1 --agent CMD --from DIR --against PATH --brief"}.freeze,
+        {"script"=>"(new)", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"mutate", "passes"=>"--file rust/src/… --from-dials"}.freeze,
         {"script"=>"qa_domain_novelty", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"judge_novelty", "passes"=>"--against PATH …"}.freeze,
         {"script"=>"qa_discover_external_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"discover_external_domains", "passes"=>"--projects-dir ~/Projects --max-depth 3 --known-path PATH …"}.freeze,
         {"script"=>"qa_postgres_migrate", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"migrate_ledger_from_heki", "passes"=>"[aggregate …] --force", "note"=>"a dry run without --force"}.freeze,
         {"script"=>"qa_postgres_role", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"create_ledger_role"}.freeze,
+        {"script"=>"qa_main_gate", "section"=>"QualityControl", "aggregate"=>"MainCheck", "verb"=>"check_main"}.freeze,
+        {"script"=>"qa_fix_main_bug", "section"=>"QualityControl", "aggregate"=>"Bug", "verb"=>"fix_and_land", "passes"=>"--bug BUG#n"}.freeze,
         {"script"=>"qa_concurrency_racer", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"race", "note"=>"not user-facing; ProcessPool starts it"}.freeze
       ].freeze,
       "RustReservedWord" => [
@@ -574,6 +690,27 @@ module Hecks
         {"type"=>"String"}.freeze,
         {"type"=>"Hash"}.freeze
       ].freeze,
+      "StepStage" => [
+        {"step"=>"decode_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_unknown_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_absent_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"normalize_args", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_role_mismatch", "stage"=>"role"}.freeze,
+        {"step"=>"resolve_references", "stage"=>"references"}.freeze,
+        {"step"=>"hydrate", "stage"=>"state"}.freeze,
+        {"step"=>"hydrate_parent", "stage"=>"state"}.freeze,
+        {"step"=>"locate_element", "stage"=>"state"}.freeze,
+        {"step"=>"enforce_givens", "stage"=>"givens"}.freeze,
+        {"step"=>"admissible_transition", "stage"=>"state"}.freeze,
+        {"step"=>"assign_creation_attributes", "stage"=>"state"}.freeze,
+        {"step"=>"apply_mutations", "stage"=>"state"}.freeze,
+        {"step"=>"advance_lifecycle", "stage"=>"state"}.freeze,
+        {"step"=>"delegate_to_entity", "stage"=>"state"}.freeze,
+        {"step"=>"enforce_ensures", "stage"=>"ensures"}.freeze,
+        {"step"=>"enforce_invariants", "stage"=>"invariants"}.freeze,
+        {"step"=>"save", "stage"=>"state"}.freeze,
+        {"step"=>"emit", "stage"=>"state"}.freeze
+      ].freeze,
       "ToStringType" => [
         {"type"=>"String"}.freeze,
         {"type"=>"Integer"}.freeze,

data/lib/hecks/workflow_pagination/judge.rb

@@ -0,0 +1,48 @@
+module Hecks
+  module WorkflowPagination
+    # Whether a GitHub API call can take its answer from one page and still be right.
+    #
+    # A list endpoint answers 30 items a page. A call that counts or waits for items, and reads that
+    # one page, is right until the list grows past it and then fails without a word.
+    module Judge
+      # The last path segment of an endpoint that answers an array, or an object holding one.
+      LISTS = %w[artifacts runs jobs issues releases pulls commits comments tags branches labels workflows
+                 check-runs check-suites reviews assets].freeze
+
+      # Query terms that narrow a list to the item asked for.
+      FILTERS = /(?:\A|&)(?:name|head_sha|sha)=/
+
+      # A call that counts what it reads, or looks one item up by a test.
+      COUNTING = /\|\s*length\b|'length'|"length"|wc -l|grep -c|\bcount\b/
+
+      # A call that waits for an item to show among those it reads.
+      WAITING = /select\(|grep -q|startswith|contains\(/
+
+      # The words that open a loop which polls.
+      LOOP = /\b(?:until|while|seq)\b/
+
+      # A comparison to a fixed number, which bounds how many items the call can need.
+      BOUNDED = /(?:=|==|-eq|-ge|-gt|-lt|-le)\s*"?\d+"?/
+
+      module_function
+
+      # @param call [Statement] one API call
+      # @return [String, nil] what is wrong with it, or nil when one page is enough
+      def fault(call)
+        return unless LISTS.include?(call.route.split("/").last) && reads_items?(call)
+        return if call.text.include?("--paginate") || call.query.match?(FILTERS)
+        return if call.query.include?("per_page=100") && call.after.match?(BOUNDED)
+
+        "counts or waits for the items of #{call.route} from its first page (30 items); " \
+          "add --paginate and count the lines it prints, or filter the path with ?name="
+      end
+
+      # @return [Boolean] whether the call counts the items or waits for one among them
+      def reads_items?(call)
+        return true if call.text.match?(COUNTING)
+
+        call.text.match?(WAITING) && call.before.match?(LOOP)
+      end
+    end
+  end
+end

data/lib/hecks/workflow_pagination/statement.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module WorkflowPagination
+    # One GitHub API call written in a workflow: the line it starts on and its text, with the lines
+    # a trailing backslash joins, and the lines around it that say what it is used for.
+    class Statement
+      # What the call is for, read from the lines around it.
+      Setting = Struct.new(:before, :after)
+
+      # How far around a call the lines that say what it is for reach.
+      REACH = 6
+
+      # A GitHub API path: the part after the host, up to the quote or space that ends it.
+      PATH = %r{(?:api\.github\.com/)?\b((?:repos|orgs|user|search|enterprises)/[^\s"'\\)]+)}
+
+      attr_reader :line, :text
+
+      # @param lines [Array<String>] the file's lines
+      # @param index [Integer] where the call starts
+      def initialize(lines, index)
+        @line = index + 1
+        @lines = lines
+        @text = joined(index)
+        @index = index
+      end
+
+      # @return [String, nil] the path the call reads, with its query
+      def path = @text[PATH, 1]
+
+      # @return [String] the path without its query
+      def route = path.to_s.partition("?").first
+
+      # @return [String] the query of the path
+      def query = path.to_s.partition("?").last
+
+      # @return [String] the lines after the call, where its answer is compared
+      def after = @lines[(@index + 1)..(@index + REACH)].to_a.join
+
+      # @return [String] the lines before the call, where a loop opens
+      def before = @lines[[@index - REACH, 0].max...@index].join
+
+      private
+
+      def joined(index)
+        text = @lines[index].dup
+        text << @lines[index += 1] while text.rstrip.end_with?("\\") && @lines[index + 1]
+        text
+      end
+    end
+  end
+end

data/lib/hecks/workflow_pagination.rb

@@ -0,0 +1,58 @@
+require_relative "workflow_pagination/statement"
+require_relative "workflow_pagination/judge"
+
+module Hecks
+  # Finds the GitHub list calls in a workflow that count or wait for items and read only the first
+  # page of them.
+  #
+  # The artifact wait of a CI run counted four named artifacts among a run's list, and went on
+  # waiting its full time once the run held 35, because the list pages at 30 and the fourth sat on
+  # the second page.
+  #
+  # @example
+  #   WorkflowPagination.check(root: ".")
+  module WorkflowPagination
+    # The files that hold workflow steps.
+    GLOBS = %w[.github/workflows/*.yml .github/workflows/*.yaml .github/actions/**/*.yml .github/actions/**/*.yaml].freeze
+
+    # The clean verdict.
+    CLEAN = "no workflow counts a GitHub list from its first page".freeze
+
+    # The words that start an API call in a step.
+    CALL = /gh api|api\.github\.com/
+
+    # Raised with every finding.
+    class Failure < StandardError; end
+
+    module_function
+
+    # @param root [String] the checkout
+    # @return [String] the clean verdict
+    # @raise [Failure] with a line for each call that reads one page
+    def check(root:)
+      found = findings(root)
+      raise Failure, found.join("\n") unless found.empty?
+
+      CLEAN
+    end
+
+    # @return [Array<String>] `file:line: fault` for each call that reads one page
+    def findings(root)
+      GLOBS.flat_map { |glob| Dir.glob(File.join(root, glob)) }.sort.flat_map do |file|
+        faults(file).map { |line, fault| "#{file.delete_prefix("#{root}/")}:#{line}: #{fault}" }
+      end
+    end
+
+    # @return [Array<Array(Integer, String)>] the line and the fault of each bad call in a file
+    def faults(file)
+      lines = File.readlines(file, encoding: "UTF-8")
+      lines.each_index.filter_map do |index|
+        next if lines[index].lstrip.start_with?("#") || !lines[index].match?(CALL)
+
+        call = Statement.new(lines, index)
+        fault = Judge.fault(call)
+        [call.line, fault] if fault
+      end
+    end
+  end
+end