hecks 7.0.0 → 7.1.0

data/lib/hecks/ci_speed/ci_speed.bluebook

@@ -981,6 +981,99 @@ Hecks.bluebook "CiSpeed" do
     end
   end
 
+  # How one family of sharded CI jobs (the rspec shards, the postgres io shards) splits its files
+  # among its legs. A plan job asks for the split once; every leg reads that plan, so all legs
+  # agree. The split is balanced by the seconds the newest successful main run recorded for each
+  # file, and by file size when no such run can be read. The chain, never deeper than three:
+  #
+  #   ShardPlanRequested -> TimingsFetched     -> ShardPlanned (source timings)
+  #   ShardPlanRequested -> TimingsUnavailable -> ShardPlanned (source size)
+  #
+  # The `TimingsSource` port finds the previous run's timings and the `Planner` port splits; the
+  # bluebook says neither how. Run the plan job's command line as
+  #
+  #   exe/hecks run lib/hecks/ci_speed '{"steps":[{"verb":"CiSpeed::ShardPlan.Request","args":{
+  #     "name":{"value":"rspec"},"shards":{"value":8},"items_from":{"value":"glob:spec/**/*_spec.rb"},
+  #     "timings_from":{"value":"main"},"out_dir":{"value":"tmp/shard-plan"}}}]}'
+  aggregate "ShardPlan" do
+    description "One family's split of its files among its shard legs, and where the timings behind it came from."
+
+    identified_by :name
+
+    attribute :name,         PlanName
+    attribute :shards,       ShardCount,  optional: true
+    # `glob:<pattern>` splits the files a pattern finds, `list:<path>` the lines of a file.
+    attribute :items_from,   ItemsFrom,   optional: true
+    # A directory of timing logs, or `main` for the newest successful CI run on main.
+    attribute :timings_from, TimingsFrom, optional: true
+    # Where the plan is written: `group-<n>.txt` per leg, `runtimes.log` and `plan.json`.
+    attribute :out_dir,      OutDir,      optional: true
+    # The log one leg timed its own files into, kept as an artifact for the next plan.
+    attribute :recorded_log, OutDir,      optional: true
+
+    # The family: `rspec`, `postgres_io`.
+    value_object "PlanName" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+    end
+
+    value_object "ShardCount" do
+      attribute :value, Integer, default: 1
+      invariant("a family has at least one shard") { value >= 1 }
+    end
+
+    value_object "ItemsFrom" do
+      attribute :value, String, pattern: '^(glob|list):[^ \t\n]+$'
+    end
+
+    value_object "TimingsFrom" do
+      attribute :value, String, pattern: '^[^ \t\n]+$'
+    end
+
+    value_object "OutDir" do
+      attribute :value, String, pattern: '^[^ \t\n]+$'
+    end
+
+    # Where a plan's prices came from: the recorded seconds, or file size.
+    value_object "PlanSource" do
+      attribute :value, String, pattern: '^(timings|size)$'
+    end
+
+    # Lines of `path:seconds`, as the shards' runtime loggers write them.
+    value_object "Timings" do
+      attribute :value, String, default: ""
+    end
+
+    command "Request" do
+      goal "Ask for a family's files to be split among its shards, from the last run's timings when they can be read"
+
+      attribute :name,         PlanName
+      attribute :shards,       ShardCount
+      attribute :items_from,   ItemsFrom
+      attribute :timings_from, TimingsFrom
+      attribute :out_dir,      OutDir
+
+      sets :name
+      sets :shards
+      sets :items_from
+      sets :timings_from
+      sets :out_dir
+
+      emits "ShardPlanRequested"
+    end
+
+    command "RecordTimings" do
+      goal "Say which log one shard leg timed its own files into, so the next plan can read it"
+
+      attribute :name,         PlanName
+      attribute :recorded_log, OutDir
+
+      sets :name
+      sets :recorded_log
+
+      emits "TimingsRecorded"
+    end
+  end
+
   # An experiment runs as soon as it is asked for: the port runs it and answers with the numbers.
   policy "MeasureWhenRequested" do
     on      "Experiment.ExperimentRequested"
@@ -1070,4 +1163,22 @@ Hecks.bluebook "CiSpeed" do
     on      "Budget.MissRunWitnessed"
     trigger Budget::Complete, with: { budget: :name }
   end
+
+  # A plan is asked for, and the first thing to do is look for the previous run's timings.
+  policy "FetchTimingsWhenPlanRequested" do
+    on      "ShardPlan.ShardPlanRequested"
+    ask     :fetch, with: { name: :name }
+  end
+
+  policy "PlanFromFetchedTimings" do
+    on      "ShardPlan.TimingsFetched"
+    ask     :partition, with: { name: :name, source: { value: "timings" }, timings: :timings }
+  end
+
+  # The fallback: timings that cannot be read are no reason to fail the run, so the files are
+  # split by size instead.
+  policy "PlanBySizeWhenTimingsUnavailable" do
+    on      "ShardPlan.TimingsUnavailable"
+    ask     :partition, with: { name: :name, source: { value: "size" }, timings: { value: "" } }
+  end
 end

data/lib/hecks/ci_speed/ci_speed.ports.hecksagon

@@ -18,4 +18,26 @@ Hecks.hecksagon "CiSpeed" do
       refuses "ExperimentRefused"
     end
   end
+
+  # Finds the timings the newest successful main run recorded for a family's files. The adapter
+  # reads a directory of logs or downloads them through `gh`, and refuses when it finds none; the
+  # bluebook never says which.
+  CiSpeed::ShardPlan.port "TimingsSource" do
+    asks "Fetch", to: ShardPlan do
+      attribute :name, PlanName
+      answers "TimingsFetched"
+      refuses "TimingsUnavailable"
+    end
+  end
+
+  # Splits a family's files among its shards by price (timings, or size) and writes the plan.
+  CiSpeed::ShardPlan.port "Planner" do
+    asks "Partition", to: ShardPlan do
+      attribute :name,    PlanName
+      attribute :source,  PlanSource
+      attribute :timings, Timings
+      answers "ShardPlanned"
+      refuses "PlanRefused"
+    end
+  end
 end

data/lib/hecks/ci_workflows/ci_workflows.bluebook

@@ -64,6 +64,9 @@ Hecks.bluebook "CiWorkflows" do
 
       member workflow: "ci-rspec.yml", name: "ci_attestation_rspec", runner: "ubuntu-latest", timeout_minutes: 10,
              note: "Separate job because a job-level `if:` cannot read a step output from its own job.\nLets `rspec_shard` skip wholesale when a local run attested this tree.\nSafe to skip on push: `rspec_shard` never reads this result on that trigger."
+      member workflow: "ci-rspec.yml", name: "shard_plan", runner: "ubuntu-latest", timeout_minutes: 10,
+             condition: "always() && (needs.ci_attestation_rspec.result != 'success' || needs.ci_attestation_rspec.outputs.attested != 'true')",
+             note: "Splits the spec files among the shards once, so every leg reads the same plan. It runs the\nCiSpeed bluebook's ShardPlan: the seconds the newest successful run on main recorded for each file\nbalance the legs, and file size does when that run cannot be read. The events of the plan, and the\npolicy that reacted to each, are in the job summary and the shard-plan-trace-rspec artifact."
       member workflow: "ci-rspec.yml", name: "rspec_shard", runner: "ubuntu-latest", timeout_minutes: 20,
              condition: "always() && (needs.ci_attestation_rspec.result != 'success' || needs.ci_attestation_rspec.outputs.attested != 'true')",
              shard_total: 8, shard_axis: "group",
@@ -75,7 +78,9 @@ Hecks.bluebook "CiWorkflows" do
       attribute :job,      String
       attribute :needs,    String
 
+      member workflow: "ci-rspec.yml", job: "shard_plan", needs: "ci_attestation_rspec"
       member workflow: "ci-rspec.yml", job: "rspec_shard", needs: "ci_attestation_rspec"
+      member workflow: "ci-rspec.yml", job: "rspec_shard", needs: "shard_plan"
     end
 
     value_object "Output" do
@@ -93,6 +98,9 @@ Hecks.bluebook "CiWorkflows" do
       attribute :job,      String
       attribute :key,      String
       attribute :value,    String
+
+      member workflow: "ci-rspec.yml", job: "shard_plan", key: "GH_TOKEN", value: "${{ github.token }}"
+      member workflow: "ci-rspec.yml", job: "rspec_shard", key: "GH_TOKEN", value: "${{ github.token }}"
     end
 
     value_object "Step" do
@@ -110,6 +118,25 @@ Hecks.bluebook "CiWorkflows" do
       member workflow: "ci-rspec.yml", job: "ci_attestation_rspec", name: "attest", id: "attest",
              uses: "./.github/actions/check-attestation"
 
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "checkout", uses: "actions/checkout@v4"
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "ruby", uses: "./.github/actions/setup-ruby",
+             note: "The plan boots the CiSpeed bluebook and splits spec files; it builds no Rust."
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "environment",
+             uses: "./.github/actions/hecks-environment"
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "plan",
+             title: "Plan the shards: ShardPlan.Request, from the last main run's timings or file size",
+             run: "mkdir -p tmp/shard-plan-trace\ncat > tmp/shard-plan-steps.json <<'JSON'\n{\"steps\":[{\"verb\":\"CiSpeed::ShardPlan.Request\",\"args\":{\"name\":{\"value\":\"rspec\"},\"shards\":{\"value\":8},\"items_from\":{\"value\":\"glob:spec/**/*_spec.rb\"},\"timings_from\":{\"value\":\"main\"},\"out_dir\":{\"value\":\"tmp/plan\"}}}]}\nJSON\nbundle exec exe/hecks Operation.run! subject.value=lib/hecks/ci_speed script.value=tmp/shard-plan-steps.json --wait \\\n  > tmp/shard-plan-trace/run.json \\\n  || echo \"::warning::the shard plan failed; every leg splits by file size\"\n",
+             note: "`shards` is the rspec_shard matrix's group count. A plan that cannot be made leaves tmp/plan empty and\neach leg then splits by file size on its own, so a missing plan never fails the run."
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "trace",
+             title: "Publish the plan's events and the policies that reacted",
+             condition: "always()",
+             run: "jq -r -f .github/shard-plan-trace.jq tmp/shard-plan-trace/run.json \\\n  | tee tmp/shard-plan-trace/trace.md >> \"$GITHUB_STEP_SUMMARY\" \\\n  || echo \"::warning::no shard plan trace to publish\"\n"
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "upload_plan",
+             title: "Upload the plan every leg reads",
+             condition: "always()", uses: "actions/upload-artifact@v4"
+      member workflow: "ci-rspec.yml", job: "shard_plan", name: "upload_trace",
+             title: "Upload the plan's event trace",
+             condition: "always()", uses: "actions/upload-artifact@v4"
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "checkout", uses: "actions/checkout@v4"
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "ruby", uses: "./.github/actions/setup-ruby"
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "zsh",
@@ -121,18 +148,22 @@ Hecks.bluebook "CiWorkflows" do
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "generated_rust",
              uses: "./.github/actions/generated-rust",
              note: "rust/src/generated is committed, so the whole tree is in the checkout and this step only checks it.\nA shard reads only the domains named below (rust_build_kernel_input_spec); the input names them and\nchanges nothing. Specs that read the whole tree are tagged `generated_all` and run in the drift job,\nwhich regenerates every domain."
+      member workflow: "ci-rspec.yml", job: "rspec_shard", name: "download_plan",
+             title: "Read the plan",
+             run: "mkdir -p tmp/plan\ngh run download ${{ github.run_id }} --name shard-plan-rspec --dir tmp/plan \\\n  || echo \"::warning::no shard plan to read; this leg splits by file size\"\n",
+             note: "Every leg reads the one plan the shard_plan job made, so the legs agree on the partition.\nA plan that cannot be read is no reason to fail: the leg splits by file size on its own."
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "file_list",
              title: "Determine this shard's own file list",
-             run: "mkdir -p tmp\nbundle exec exe/hecks query test_suite_run.shard_specs group=${{ matrix.group }} groups=%{shard_total} runtime_log=.github/rspec_runtime_baseline.log \\\n  > tmp/rspec_shard_files.txt\n",
-             note: "`io: true` specs run elsewhere: rspec_rust_io (cargo/wasm) and rspec_postgres_io.\nEvery shard must compute its file list from identical inputs or the lists stop\npartitioning the suite, so grouping reads only the committed baseline, never a cache."
+             run: "if [ -s \"tmp/plan/group-${{ matrix.group }}.txt\" ]; then\n  cp \"tmp/plan/group-${{ matrix.group }}.txt\" tmp/rspec_shard_files.txt\nelse\n  bundle exec exe/hecks test_suite_run.shard_specs group=${{ matrix.group }} groups=%{shard_total} \\\n    > tmp/rspec_shard_files.txt\nfi\n",
+             note: "`io: true` specs run elsewhere: rspec_rust_io (cargo/wasm) and rspec_postgres_io."
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "parallel",
              title: "rspec: parallel (this shard's own file list only)",
-             run: "FILES=()\nwhile IFS= read -r line; do FILES+=(\"$line\"); done < tmp/rspec_shard_files.txt\nbundle exec parallel_rspec \"${FILES[@]}\" \\\n  --group-by runtime --runtime-log .github/rspec_runtime_baseline.log --allowed-missing 100 \\\n  -o \"--tag ~io --tag ~fuzzing --tag ~generated_all --profile 15 --format documentation --format ParallelTests::RSpec::RuntimeLogger --out tmp/runtime_rspec.log\"\n",
-             note: "--group-by runtime: without it parallel_rspec splits by file size and one worker can\ndraw the slowest files. --allowed-missing: spec files newer than the baseline get the\naverage cost instead of failing."
+             run: "if [ -s tmp/plan/runtimes.log ]; then\n  GROUPING=(--group-by runtime --runtime-log tmp/plan/runtimes.log --allowed-missing 100)\nelse\n  GROUPING=(--group-by filesize)\nfi\nFILES=()\nwhile IFS= read -r line; do FILES+=(\"$line\"); done < tmp/rspec_shard_files.txt\nbundle exec parallel_rspec \"${FILES[@]}\" \"${GROUPING[@]}\" \\\n  -o \"--tag ~io --tag ~fuzzing --tag ~generated_all --profile 15 --format documentation --format ParallelTests::RSpec::RuntimeLogger --out tmp/runtime_rspec.log\"\n",
+             note: "Grouping by runtime keeps one worker from drawing the slowest files; the plan's runtimes.log\nprices every file, so none is missing. Without a plan the workers group by file size."
       member workflow: "ci-rspec.yml", job: "rspec_shard", name: "upload_log",
-             title: "Upload this shard's runtime log (for hecks TestSuiteRun.refresh_runtime_baseline! from_run=)",
+             title: "Upload this shard's runtime log (the next run's plan reads it)",
              condition: "always()", uses: "actions/upload-artifact@v4",
-             note: "Artifact only, never restored: `hecks TestSuiteRun.refresh_runtime_baseline! from_run= <run-id>`\nrebuilds the committed baseline from CI timings."
+             note: "Artifact only, never restored by this run: the shard_plan job of the next run downloads\nthe artifacts of the newest successful run on main and balances the legs by these seconds."
     end
 
     value_object "StepInput" do
@@ -146,6 +177,19 @@ Hecks.bluebook "CiWorkflows" do
       member workflow: "ci-rspec.yml", job: "ci_attestation_rspec", step: "attest", key: "hmac-key",
              value: "${{ secrets.HECKS_CI_ATTEST_KEY }}"
 
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_plan", key: "name", value: "shard-plan-rspec"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_plan", key: "path", value: "tmp/plan"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_plan", key: "retention-days", value: "14"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_plan", key: "if-no-files-found",
+             value: "ignore"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_trace", key: "name",
+             value: "shard-plan-trace-rspec"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_trace", key: "path",
+             value: "tmp/shard-plan-trace"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_trace", key: "retention-days", value: "14"
+      member workflow: "ci-rspec.yml", job: "shard_plan", step: "upload_trace", key: "if-no-files-found",
+             value: "ignore"
+
       member workflow: "ci-rspec.yml", job: "rspec_shard", step: "environment", key: "database",
              value: "${{ secrets.HECKS_JOURNAL_DATABASE }}"
       member workflow: "ci-rspec.yml", job: "rspec_shard", step: "generated_rust", key: "domains",

data/lib/hecks/coder/coder.bluebook

@@ -301,6 +301,7 @@ Hecks.bluebook "Coder" do
     attribute :detail,       BriefDetail, optional: true
     attribute :area,         list_of(AreaWord), optional: true
     attribute :rules,        BriefRules
+    attribute :review,       BriefRules, optional: true
     attribute :verification, BriefVerification
     attribute :workflow,     BriefRules, optional: true
     attribute :landing,      BriefRules, optional: true
@@ -355,10 +356,11 @@ Hecks.bluebook "Coder" do
       attribute :area,    list_of(AreaWord), optional: true, sets: true
 
       sets :rules, to: "Map the whole picture before acting. Act on everything within the area. Stop only for (a) a risk of losing data, (b) an action the owner alone may take: a push, a mint, a release, deleting something that is not yours, or (c) a change outside the area. When stopped, report what was stuck first, then finish everything that does not depend on the stuck part."
+      sets :review, to: "Before you edit anything, have your plan reviewed. Write the plan: what you will build, which aggregates, commands, policies, ports, adapters and files it touches, and how it will be checked. Give it to the architect agent (the Agent tool, subagent type architect) and act on its verdict. Sound: build it. Sound with changes: revise the plan as its findings say, then build it. Rethink: edit nothing, hand the row back with exe/hecks tickets Work.yield! to={work} reason.value=\"architect: rethink. <its verdict and first finding>\" --wait, and end. Quote the verdict and each finding you acted on or set aside, with your reason, in your report."
       sets :verification, to: "Run named specs only through the launcher: exe/hecks test_suite_run.run_spec_example! file.value=<spec> \"example.value= \" --wait. Do not run the full suite: it runs only in CI. Run at most {limit} spec files per call locally (test_suite_run.run_spec_files!), never a whole family. Never use git stash. Keep the quick gate green (exe/hecks gate_run.gate! stage=quick --wait) and RuboCop strict (methods at most 10 lines). Run the quick gate, specs and builds each as ONE blocking command with an explicit Bash timeout of up to 600000 ms; never as a background command with a monitor or poll loop. Run exe/hecks style_run.check_comments! paths=<one file> --wait for each Ruby file you touch."
       sets :workflow, to: "Pull main first, always: fetch origin, bring local main up to date, then cut the branch. Work in your own worktree named for the row: step 1 is exe/hecks LinkedTree.add! branch.value={work} --wait, which pulls main (a fast-forward, or a rebase of local main's unpushed commits when both moved; it refuses by name when the checkout is dirty) and cuts the branch from it. A session the harness started in a worktree (EnterWorktree cuts from origin/main, not local main) checks git merge-base --is-ancestor origin/main HEAD and rebases onto local main if not, after exe/hecks LinkedTree.pull_main! --wait. Rebase onto local main before landing: local main can hold work that is not pushed, and landing refuses a branch whose base is behind origin/main. Put no Claude attribution trailer in a commit message: no Co-Authored-By line and no Claude-Session line. A worktree that holds ignored files is kept after landing and reported: remove it by hand."
       sets :landing, to: "Regenerate only if a bluebook, hecksagon, Vocabulary row or generator changed: exe/hecks regeneration_run.regenerate_corpus! --confirm --wait, then --check. Run exe/hecks conformance_run.check_shape_ledger! --wait; a purely additive move uses --confirm --additive, any other move: stop and report it. Land with exe/hecks landing.finish! --confirm: one step that rebases onto local main, runs the quick gate, lands through the queue and removes the worktree and branch. It refuses by name at the first failure (unsaved work, conflict, gate red, queue busy): fix that and run it again. If landing refuses because a landing is in flight, run it again once; it queues. Never poll or sleep on a lock, and never run a lock file by hand."
-      sets :restraints, to: "Do not push. Never set HECKS_OWNER_PUSH and never use --no-verify: main is pushed only by boarding the push train. Do not mint an era. While main CI is red, only a push that fixes a red-* Work row goes out (exe/hecks tickets query Work.undone lists them), through the push train; everything else lands locally with landing.land! and waits until CI on origin/main is green. Do not run the full spec suite locally; it runs in CI. Do not write to a live database (tickets.db, agent_run.db or any other under ~/.claude): use Memory or a temp file in specs. Never touch a local database that may hold client data."
+      sets :restraints, to: "Do not push. Never set HECKS_OWNER_PUSH and never use --no-verify: main is pushed only by boarding the push train. Do not mint an era. A red main raises a red flag (the RedFlagRaised event; exe/hecks RedFlag.status says whether one stands, and `exe/hecks Operation.follow domain.value=Hecks aggregate.value=RedFlag from_now=true wait=600` is the one line that listens, and it returns when RedFlagRaised or RedFlagCleared is recorded). On RedFlagRaised stop feature work and check in with exe/hecks RedFlag.check_in! session.value=<you> taking.value=<a red-* Work row or a cause> (exe/hecks tickets Work.undone lists the rows); Landing and the push train then refuse everything except the fix of a red-* row, by name (main is red: flag <id>), and a red-* row's fix goes out through the push train. Resume on RedFlagCleared, when CI on main is green again. Do not run the full spec suite locally; it runs in CI. Do not write to a live database (tickets.db, agent_run.db or any other under ~/.claude): use Memory or a temp file in specs. Never touch a local database that may hold client data."
       sets :report, to: "End with a report: what changed, each with file:line; the spec counts (examples and failures); the shape-ledger action you took; and the sha you landed, or why nothing landed."
       sets :coordination, to: "COORDINATION: other sessions are working in these areas. Do not edit them:"
       sets :freeze, to: "FREEZE: the persisted shape of these may not move. If your change moves one, commit and hold, do not land, and report 'ready, held for the freeze':"

data/lib/hecks/command_names/index.rb

@@ -21,7 +21,7 @@ module Hecks
         typed = rest.drop(asking ? 1 : 0).first
         return if typed.nil? || free?(scope, typed)
 
-        Resolution.new(scope, typed, asking).problem
+        Resolution.new(scope, typed, asking, old_spelling: rest.first == "query").problem
       end
 
       private

data/lib/hecks/command_names/resolution.rb

@@ -15,13 +15,15 @@ module Hecks
 
       # @param scope [Hash] one scope of `CliRunner.name_index`
       # @param typed [String] the word, with its `!` if it has one
-      # @param asking [Boolean] whether `query` came before it
-      def initialize(scope, typed, asking)
+      # @param asking [Boolean] whether `query` (or `ask`) came before it
+      # @param old_spelling [Boolean] whether the word before it was `query`, the old spelling
+      def initialize(scope, typed, asking, old_spelling: false)
         @scope = scope
         @cli = { names: { command: scope["command"], question: scope["question"] } }
         @typed = typed.chomp("!")
         @bang = typed.end_with?("!")
         @asking = asking
+        @old_spelling = old_spelling
         @name = RUNNER.canonical_name(@cli, @typed)
       end
 
@@ -29,7 +31,7 @@ module Hecks
       def problem
         return unknown unless command || question
 
-        bare_command || banged_query || query_of_command
+        bare_command || banged_query || query_of_command || query_word
       end
 
       private
@@ -47,7 +49,15 @@ module Hecks
       def banged_query
         return unless @bang && !@asking && !command && question
 
-        Problem.new("#{@typed}! is a query and reads; write it without the !", "query #{question}")
+        Problem.new("#{@typed}! is a query and reads; write it without the !", question.to_s)
+      end
+
+      # A query is written bare (ADR 0163 rule 6); `query` stays only where a command shares the
+      # name.
+      def query_word
+        return unless @old_spelling && question && !command
+
+        Problem.new("query is the old spelling; write #{@typed} bare", question.to_s)
       end
 
       def query_of_command
@@ -74,7 +84,7 @@ module Hecks
       def listed(near)
         return "#{@scope["command"][near]}!" if @scope["command"][near]
 
-        "query #{@scope["question"][near]}"
+        @scope["question"][near].to_s
       end
     end
   end

data/lib/hecks/composer/toolbox.rb

@@ -157,7 +157,8 @@ module Hecks
         Hecks.boot(File.join(Parse::ROOT, "lib/hecks/hecks"), install_driving: false, environment: "memory")
       end
 
-      # A safe-listed command writes through the runner only with its bang; the list names bare commands.
+      # A safe-listed command writes through the runner only with its bang; the list names bare
+      # commands.
       def writing(argv)
         return argv unless argv.first && SAFE_COMMANDS.include?(argv.first)
 

data/lib/hecks/corpus.rb

@@ -28,6 +28,10 @@ module Hecks
       # The Coder and Fixer domains keep their bluebook beside their hecksagon in their own folder.
       coder:     "lib/hecks/coder",
       fixer:     "lib/hecks/fixer",
+      # The PipelineBoard domain keeps its bluebook beside its hecksagon and adapters.
+      board:     "lib/hecks/pipeline_board",
+      # The Pipeline domain: one passage per change, moved by the other domains' events.
+      pipeline:  "lib/hecks/pipeline",
       # A package vendored via `attaches ... from: :vendor` — nested inside the
       # consuming example's own checkout, not this gem's own framework/bluebook/.
       vendored:  "examples/*/vendor/embryonaut_bluebooks/*"

data/lib/hecks/doc/reference/readme.rb

@@ -44,7 +44,7 @@ module Hecks
         def diagram_showcase(root)
           lifecycle = File.read(File.join(root, "docs/generated/diagrams/pizzas/Order_lifecycle.mmd")).strip
           <<~MARKDOWN.strip
-            `hecks query introspection.project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
+            `hecks introspection.project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
 
             ```mermaid
             #{lifecycle}

data/lib/hecks/framework_bluebooks.rb

@@ -7,7 +7,7 @@ require_relative "sentence_form"
 module Hecks
   # The bluebooks the gem carries that a hecksagon can attach by name (ADR 0080): the language
   # declared in itself, Expression, Tenancy, Deploy, Site, Tickets, Composer, QualityControl,
-  # Fixer, Coder, Bulk and CiPipeline.
+  # Fixer, Coder, Bulk, CiPipeline, PipelineBoard and Pipeline.
   # Framework members stay in `Framework`; `table` and `attach!` find a name across both.
   #
   # A bluebook is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
@@ -19,7 +19,8 @@ module Hecks
     GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
                deploy/bluebook/*.bluebook site/bluebook/*.bluebook rails_app/bluebook/*.bluebook tickets/bluebook/*.bluebook
                composer/bluebook/*.bluebook quality_control/*.bluebook fixer/*.bluebook coder/*.bluebook
-               bulk/bluebook/*.bluebook ci_pipeline/*.bluebook].freeze
+               bulk/bluebook/*.bluebook ci_pipeline/*.bluebook pipeline_board/*.bluebook
+               pipeline/*.bluebook].freeze
 
     # A `Hecks.bluebook "Name"` header line, capturing the bluebook's name.
     BLUEBOOK_HEADER = /\A\s*Hecks\.bluebook\s+"([^"]+)"/

data/lib/hecks/fuzzing/differential.rb

@@ -11,7 +11,7 @@ require_relative "differential/wire_comparison"
 module Hecks
   module Fuzzing
     # The Ruby-vs-Rust comparison of one generated sequence, shared by the QualityControl sweep
-    # (`hecks quality_control query sweep.run`) and `hecks quality_control
+    # (`hecks quality_control sweep.run`) and `hecks quality_control
     # target.check_generated_domains --rust`.
     #
     # `differ` is duck-typed (the `RustConformanceHelpers` comparison helpers plus a

data/lib/hecks/fuzzing/era_boundary.rb

@@ -9,7 +9,7 @@ module Hecks
 
       # `kind:` on a `checked: false` result distinguishes a target with no
       # lineage to audit (`:not_applicable`) from an audit that failed to
-      # run (`:error`) — `hecks quality_control query sweep.run` holds the first and surfaces the
+      # run (`:error`) — `hecks quality_control sweep.run` holds the first and surfaces the
       # second as a finding, instead of treating both as a clean audit.
       def diverged_ancestor_writes(domain_path)
         registry, directory = load_registry(domain_path)

data/lib/hecks/fuzzing/isolated_boot/postgres_scratch.rb

@@ -51,7 +51,7 @@ module Hecks
         # `:postgres_era` is the only mode that exercises era/lineage-bound SQL; plain
         # `:postgres` never touches that machinery. Unlike `:postgres`, there's no shared
         # scratch constant here — `database:`/`schema:` are required keyword args because
-        # the caller (`hecks quality_control query sweep.run --persistence-parity`) owns that
+        # the caller (`hecks quality_control sweep.run --persistence-parity`) owns that
         # database's lifecycle.
         def rebind_to_postgres_era!(copy, database:, schema:, disposable: true)
           require "pg"

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -11,7 +11,7 @@ module Hecks
 
       # Replays `steps` on both adapters and lists where the results differ.
       #
-      # Compares the same six fields as `hecks quality_control query sweep.run`'s Ruby-vs-Rust mode.
+      # Compares the same six fields as `hecks quality_control sweep.run`'s Ruby-vs-Rust mode.
       # Both results are JSON-round-tripped so plain data compares equal on both sides.
       #
       # @param left [Symbol] an `IsolatedBoot` adapter: `:memory`, `:sqlite`, `:postgres`,

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -41,7 +41,7 @@ module Hecks
         wasm_front:                 %w[rust]
       }.freeze
 
-      # The modes `hecks quality_control query sweep.run` can run; one absent here is refused at
+      # The modes `hecks quality_control sweep.run` can run; one absent here is refused at
       # start, not resolved.
       RUNNABLE_MODES = %i[differential ruby_only self_consistency properties_in_differential
                           structural_skip_report adapter_parity_sqlite persistence_parity

data/lib/hecks/hecks/adapters/ci_runs.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/ci_runs"
+
+Hecks.adapter "CiRuns" do
+  port "CiRuns"
+end

data/lib/hecks/hecks/adapters/ci_runs.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "console_capture"
+require_relative "main_integration/command_runner"
+
+module Hecks
+  module Adapters
+    # The `CiRuns` port's adapter for `Integration.Observe`: reads, through `gh`, the CI run of a
+    # push of main at a landed commit. It answers `running` while there is no run yet or it has not
+    # completed, `passed` when it succeeded, and `failed` with the jobs that did not succeed.
+    class CiRuns
+      # The workflow whose run is read, as GitHub names it.
+      WORKFLOW = "CI"
+
+      # Job conclusions that are not a failure.
+      CLEAN = %w[success skipped neutral].freeze
+
+      class << self
+        # @return [#call, nil] takes `(argv, chdir:)` and answers `[ok, output]`; the command
+        #   runner when nil. A spec replaces it with a fake GitHub.
+        attr_accessor :runner
+      end
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param held [Hash] the `Integration` record: `landed` and `checkout`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`running`, `passed` or `failed`) and `report:`
+      # @raise [ConsoleCapture::Failure] when `gh` cannot be read
+      def watch(**held)
+        landed = plain(held[:landed]).to_s
+        @checkout = plain(held[:checkout]) || Dir.pwd
+        run = latest_run(landed)
+        return answer("running", "#{landed[0, 10]}: no #{WORKFLOW} run yet") unless run
+        return answer("running", "#{landed[0, 10]}: #{WORKFLOW} run #{run["databaseId"]} is #{run["status"]}") unless
+          run["status"] == "completed"
+
+        verdict(landed, run)
+      end
+
+      private
+
+      def latest_run(landed)
+        gh("run", "list", "--workflow", WORKFLOW, "--branch", "main", "--event", "push", "--commit", landed,
+           "--json", "databaseId,status,conclusion", "--limit", "1").first
+      end
+
+      def verdict(landed, run)
+        id = run["databaseId"]
+        return answer("passed", "#{landed[0, 10]}: #{WORKFLOW} run #{id} passed") if run["conclusion"] == "success"
+
+        answer("failed", "#{landed[0, 10]}: #{WORKFLOW} run #{id} #{run["conclusion"]}; failed jobs: #{failed_jobs(id)}")
+      end
+
+      def failed_jobs(id)
+        jobs = gh("run", "view", id.to_s, "--json", "jobs").fetch("jobs", [])
+        names = jobs.reject { |job| CLEAN.include?(job["conclusion"].to_s) }.map { |job| job["name"] }
+        names.empty? ? "none named" : names.join(", ")
+      end
+
+      def gh(*args)
+        ok, output = runner.call(["gh", *args], chdir: @checkout)
+        raise ConsoleCapture::Failure, "gh #{args.first(2).join(" ")} failed: #{output.to_s.strip}" unless ok
+
+        JSON.parse(output)
+      rescue JSON::ParserError
+        raise ConsoleCapture::Failure, "gh #{args.first(2).join(" ")} answered no JSON"
+      end
+
+      def answer(outcome, report) = { outcome: { value: outcome }, report: { value: report }, checkout: { value: @checkout } }
+
+      def runner = self.class.runner || MainIntegration::CommandRunner.new
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/claude_agent_list.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The agent types the `claude` command can start in a directory: the built-in ones, the user's
+    # and the directory's own.
+    #
+    # `claude` has no listing of its own, but it names every available agent when asked for one it
+    # does not have, and then stops before it starts anything. The list is read from that answer,
+    # in the directory a session would work in, so the directory's own agents are counted. An
+    # answer that names no list is refused with what `claude` said, so a reworded message is seen at
+    # once, not taken for an empty list.
+    class ClaudeAgentList
+      # An agent name no one gives an agent, asked for only to make `claude` name the real ones.
+      PROBE = "hecks-probe-not-an-agent"
+
+      # How `claude` names the agents it has, after refusing one it has not.
+      AVAILABLE = /Available agents:\s*(.+)$/
+
+      # @param command [String] the program that starts sessions
+      # @param shell [Shell] runs it
+      def initialize(command, shell: Shell.new)
+        @command = command
+        @shell = shell
+      end
+
+      # @param directory [String] where a session would work
+      # @return [Array<String>] the agent names `claude` lists there
+      # @raise [ConsoleCapture::Failure] when its answer names no list
+      def names(directory)
+        result = @shell.capture(@command, "--agent", PROBE, "-p", "list the agents", chdir: directory)
+        said = "#{result.out}\n#{result.err}"
+        listed = said[AVAILABLE, 1]
+        raise ConsoleCapture::Failure, "#{@command} listed no agents: #{said.strip[0, 300]}" unless listed
+
+        listed.split(",").map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end