hecks 5.0.0 → 7.0.0

data/lib/hecks/ci_speed/ci_speed.hecksagon

@@ -0,0 +1,11 @@
+# The CiSpeed bluebook, bound so it boots standing alone (a behaviors or model_check boot of this
+# directory). The ports it shares with every attaching hecksagon are in ci_speed.ports.hecksagon.
+Hecks.hecksagon "CiSpeed" do
+  attaches "Governance"
+  persisted_by "Memory"
+end
+
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

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

@@ -0,0 +1,21 @@
+# The ports CiSpeed declares, for every hecksagon that attaches the bluebook. The bluebook names the
+# question it asks of GitHub and the one it asks of this machine, and never says how either is
+# answered; an adapter binds each.
+Hecks.hecksagon "CiSpeed" do
+  # Answers with one run's record as GitHub reports it. The adapter runs the `gh` commands; the
+  # bluebook takes back the document and records it through `Run::Observe`.
+  CiSpeed::Run.port "CiReader" do
+    answers_query "Reading"
+  end
+
+  # Runs an experiment's steps in two checkouts, interleaved, and answers with the numbers. The
+  # adapter makes the checkouts, times the steps and removes the checkouts; the bluebook takes back
+  # the answer and records it through `Experiment::Complete`, or the refusal through `Fault`.
+  CiSpeed::Experiment.port "LocalRunner" do
+    asks "Measure", to: Experiment do
+      attribute :name, ExperimentName
+      answers "ExperimentAnswered"
+      refuses "ExperimentRefused"
+    end
+  end
+end

data/lib/hecks/ci_workflows/ci_workflows.behaviors

@@ -0,0 +1,13 @@
+Hecks.behaviors "CiWorkflows" do
+  vision "Hecks's own workflows are rows of this bluebook, which attaches CiPipeline for the shape of a row."
+
+  # The hecksagon attaches CiPipeline and Governance, so a boot of these files holds the shapes the
+  # rows are read against, and the memory-only guard and the role check pass.
+  loads "ci_workflows.bluebook", "ci_workflows.hecksagon"
+
+  test "Name names the pipeline whose rows these are" do
+    tests "Name", on: "Pipeline"
+    input name: { value: "hecks" }
+    expect emits: ["PipelineNamed"]
+  end
+end

data/lib/hecks/ci_workflows/ci_workflows.bluebook

@@ -0,0 +1,173 @@
+# Hecks's own workflows as rows: the client of the CiPipeline bluebook. Each workflow file listed
+# here is written by `hecks regeneration_run.project_ci_pipeline!` from these rows and is never
+# edited by hand; the other files under .github/workflows are still hand-written and move here one
+# at a time.
+#
+# The rows are flat and joined by workflow name and job name. A `Workflow` row is one file, and a
+# `Trigger` row one event that starts it. A `Secret` row is one secret a called workflow takes. A
+# `Job` row is one job, a `Need` row one job it waits for, an `Output` row one value it hands on
+# and an `Env` row one variable its steps see. A `Step` row is one step, in the order written, and
+# a `StepInput` row one `with:` input of the step whose handle it names. The fields a row may carry
+# and the closed sets their values come from are the CiPipeline bluebook's Workflow, JobSpec and
+# Step aggregates (lib/hecks/ci_pipeline/ci_pipeline.bluebook).
+#
+# A value is a YAML scalar as written: `14` is the number, `false` the boolean, and anything else
+# the string, quoted by the projector only where YAML needs it. Text in a `note` becomes comments.
+Hecks.bluebook "CiWorkflows" do
+  vision "Hecks's own GitHub Actions workflows, declared once as rows and projected into .github/workflows."
+
+  aggregate "Pipeline" do
+    description "The rows of the workflows Hecks projects for itself."
+
+    attribute :name, PipelineName
+    identified_by :name
+
+    value_object "PipelineName" do
+      attribute :value, String
+    end
+
+    value_object "Workflow" do
+      attribute :name,         String
+      attribute :display_name, String
+      attribute :note,         String
+
+      member name: "ci-rspec.yml", display_name: "CI rspec (reusable)",
+             note: "Reusable rspec gate behind the `rspec` required check; called from ci.yml.\n\nOne file per required check: a called workflow reports a single `.result` to its caller.\nSecrets are declared, not inherited: ci.yml must pass HECKS_CI_ATTEST_KEY and\nHECKS_JOURNAL_DATABASE at the call site."
+    end
+
+    value_object "Trigger" do
+      attribute :workflow, String
+      attribute :event,    String
+
+      member workflow: "ci-rspec.yml", event: "workflow_call"
+    end
+
+    value_object "Secret" do
+      attribute :workflow, String
+      attribute :name,     String
+      attribute :required, Boolean
+
+      member workflow: "ci-rspec.yml", name: "HECKS_CI_ATTEST_KEY", required: false
+      member workflow: "ci-rspec.yml", name: "HECKS_JOURNAL_DATABASE", required: false
+    end
+
+    value_object "Job" do
+      attribute :workflow,        String
+      attribute :name,            String
+      attribute :runner,          String
+      attribute :timeout_minutes, Integer
+      attribute :permissions,     String
+      attribute :condition,       String
+      attribute :shard_total,     Integer
+      attribute :shard_axis,      String
+      attribute :note,            String
+
+      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: "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",
+             note: "The suite is split across shards, each running parallel workers, to cut wall-clock time.\n\n`always()` and the `.result` check are both required: a failed detector would otherwise\nskip this required check instead of running it. Also skipped on push (cache warming\nneeds only the postgres_io_parallel shards) and when the tree is attested.\n\nNo Postgres service: specs that boot examples/pizzas against PostgresEra are tagged\n`io: true` and run in rspec_postgres_io. An untagged one fails here with\nPG::ConnectionBad."
+    end
+
+    value_object "Need" do
+      attribute :workflow, String
+      attribute :job,      String
+      attribute :needs,    String
+
+      member workflow: "ci-rspec.yml", job: "rspec_shard", needs: "ci_attestation_rspec"
+    end
+
+    value_object "Output" do
+      attribute :workflow, String
+      attribute :job,      String
+      attribute :key,      String
+      attribute :value,    String
+
+      member workflow: "ci-rspec.yml", job: "ci_attestation_rspec", key: "attested",
+             value: "${{ steps.attest.outputs.attested }}"
+    end
+
+    value_object "Env" do
+      attribute :workflow, String
+      attribute :job,      String
+      attribute :key,      String
+      attribute :value,    String
+    end
+
+    value_object "Step" do
+      attribute :workflow,  String
+      attribute :job,       String
+      attribute :name,      String
+      attribute :title,     String
+      attribute :id,        String
+      attribute :uses,      String
+      attribute :run,       String
+      attribute :condition, String
+      attribute :note,      String
+
+      member workflow: "ci-rspec.yml", job: "ci_attestation_rspec", name: "checkout", uses: "actions/checkout@v4"
+      member workflow: "ci-rspec.yml", job: "ci_attestation_rspec", name: "attest", id: "attest",
+             uses: "./.github/actions/check-attestation"
+
+      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",
+             title: "Install zsh",
+             run: "sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends zsh\n",
+             note: "cli_completion_spec checks the zsh completion script with `zsh -n`; CI has no zsh,\nand the skip backstop turns an unrouted skip into a failure."
+      member workflow: "ci-rspec.yml", job: "rspec_shard", name: "environment",
+             uses: "./.github/actions/hecks-environment"
+      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: "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."
+      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."
+      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=)",
+             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."
+    end
+
+    value_object "StepInput" do
+      attribute :workflow, String
+      attribute :job,      String
+      attribute :step,     String
+      attribute :key,      String
+      attribute :value,    String
+
+      member workflow: "ci-rspec.yml", job: "ci_attestation_rspec", step: "attest", key: "checks", value: "rspec"
+      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: "rspec_shard", step: "environment", key: "database",
+             value: "${{ secrets.HECKS_JOURNAL_DATABASE }}"
+      member workflow: "ci-rspec.yml", job: "rspec_shard", step: "generated_rust", key: "domains",
+             value: "lease_clock nested_pieces"
+
+      member workflow: "ci-rspec.yml", job: "rspec_shard", step: "upload_log", key: "name",
+             value: "rspec-runtime-group-${{ matrix.group }}"
+      member workflow: "ci-rspec.yml", job: "rspec_shard", step: "upload_log", key: "path",
+             value: "tmp/runtime_rspec.log"
+      member workflow: "ci-rspec.yml", job: "rspec_shard", step: "upload_log", key: "retention-days", value: "14"
+      member workflow: "ci-rspec.yml", job: "rspec_shard", step: "upload_log", key: "if-no-files-found",
+             value: "ignore"
+    end
+
+    command "Name" do
+      goal "Name the pipeline whose rows these are"
+
+      attribute :name, PipelineName
+
+      sets :name
+
+      emits "PipelineNamed"
+    end
+  end
+end

data/lib/hecks/ci_workflows/ci_workflows.hecksagon

@@ -0,0 +1,15 @@
+Hecks.hecksagon "CiWorkflows" do
+  attaches "CiPipeline"
+end
+
+# The sibling hecksagons of the attached bluebooks: they decide where their aggregates are kept, as
+# a project does for every bluebook it attaches. CiPipeline's commands name a role, so its hecksagon
+# attaches Governance to check the roles against.
+Hecks.hecksagon "CiPipeline" do
+  attaches "Governance"
+  persisted_by "Memory"
+end
+
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/codemod.rb

@@ -16,7 +16,7 @@ module Hecks
                       Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
                       Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
 
-    # Boots the lightweight, in-memory path — a codemod only reads a chapter's
+    # Boots the lightweight, in-memory path — a codemod only reads a bluebook's
     # own declared IR, never a stored record, so it has no reason to need Postgres.
     PERSISTENCE_PORT = File.join(ROOT, "lib/hecks/ports/persistence.port")
     EXTRACTION_PORT  = File.join(ROOT, "lib/hecks/ports/extraction.port")
@@ -135,8 +135,8 @@ module Hecks
 
     # Walks nested entities recursively too, not just each aggregate's own commands.
     def self.each_command(registry)
-      registry.bluebooks.each_value do |chapter|
-        chapter.aggregates.each do |aggregate|
+      registry.bluebooks.each_value do |declaration|
+        declaration.aggregates.each do |aggregate|
           walk = lambda do |construct|
             construct.commands.each { |command| yield construct, command }
             construct.entities.each(&walk) if construct.respond_to?(:entities)

data/lib/hecks/coder/coder.bluebook

@@ -0,0 +1,385 @@
+# Coder: the coder side of the QA loop. It works the bugs QualityControl logs, and when a fix is
+# not ready it records a Stub, a named temporary workaround that lets the QA rotation keep moving
+# while the bug stays open.
+# Cross-domain wiring to QualityControl's Bug events is deliberately NOT in this first cut.
+
+Hecks.bluebook "Coder" do
+  vision "Every bug QA logs is worked by one coder at a time, and a bug that cannot be fixed yet is still never hidden: it is stubbed, named, and retired once the fix lands."
+
+  core
+
+  # One assignment per QA bug, keyed by the bug's reference. A claim is a lifecycle edge, so two
+  # coders racing for the same bug see one win and one refusal.
+  aggregate "Assignment" do
+    description "One QA bug, the coder working it, and how far the fix got."
+
+    identified_by :bug
+
+    attribute :bug,        BugReference
+    attribute :held_by,    Holder
+    # A number, not a timestamp type: the predicate sublanguage compares only numbers.
+    attribute :claimed_at, Instant
+    attribute :window,     StaleAfter
+
+    value_object "BugReference" do
+      attribute :value, String, matches: :present
+      invariant("an assignment names the bug it works") { !value.to_s.empty? }
+    end
+
+    # `nobody` when unclaimed, as QualityControl's `Engineer` is.
+    value_object "Holder" do
+      attribute :value, String, default: "nobody"
+    end
+
+    value_object "Instant" do
+      attribute :value, Integer, default: 0
+      invariant("an instant is not before the epoch") { !value.negative? }
+    end
+
+    # Mirrors `QualityControl::Target::StaleAfter`: a claim older than this may be taken over.
+    value_object "StaleAfter" do
+      attribute :value, Integer, default: 900
+      invariant("a staleness window is positive") { value.positive? }
+    end
+
+    # `stubbed` is a bug held by a coder with a Stub in place. Both held states can be taken over
+    # once stale, so a coder who goes quiet does not strand the bug.
+    lifecycle :status, default: "waiting" do
+      transition "Claim"   => "claimed",  from: ["waiting", "released", "claimed", "stubbed"]
+      transition "Stub"    => "stubbed",  from: "claimed"
+      transition "Fix"     => "fixed",    from: ["claimed", "stubbed"]
+      transition "Release" => "released", from: ["claimed", "stubbed"]
+      mark :terminal, "fixed"
+    end
+
+    # Creates the assignment in `waiting` when QualityControl logs a bug. Nothing is held yet, so
+    # the holder and claim time keep their defaults. Without this, no assignment could ever exist
+    # for `Claim` to take.
+    command "Offer" do
+      role "Coder"
+      goal "Put a newly logged QA bug on the queue"
+
+      attribute :bug, BugReference
+
+      emits "AssignmentOffered"
+    end
+
+    # `from` includes the held states on purpose: without them the staleness rule below could never
+    # apply, because a claim that went quiet sits in `claimed` and no edge would leave it.
+    # Same arithmetic as QualityControl's `Bug.Claim`: `+` stands for `now - claimed_at >= window`.
+    command "Claim" do
+      role "Coder"
+      goal "Take a bug off the queue, or one whose holder has gone quiet"
+
+      reference_to Assignment
+      attribute :held_by, Holder, sets: true
+      attribute :now,     Instant
+      needs :now
+
+      given("a live claim is not taken from the coder holding it") do
+        held_by.value == "nobody" || claimed_at.value + window.value <= now.value
+      end
+
+      sets :claimed_at, to: :now
+
+      emits "AssignmentClaimed"
+    end
+
+    # The Stub is recorded by its own command; this only moves the assignment into `stubbed`.
+    command "Stub" do
+      role "Coder"
+      goal "Record that the bug is held open behind a temporary workaround"
+
+      reference_to Assignment
+
+      emits "AssignmentStubbed"
+    end
+
+    # `bug` is restated so `AssignmentFixed` carries it: an event holds only its dispatched arguments,
+    # and `RetireStubOnFix` needs the bug to find the Stub it retires.
+    command "Fix" do
+      role "Coder"
+      goal "Record that the bug no longer happens"
+
+      reference_to Assignment
+      attribute :bug, BugReference
+
+      emits "AssignmentFixed"
+    end
+
+    # Dropping a claim hands the bug back to the queue; the caller passes `nobody` as the holder.
+    command "Release" do
+      role "Coder"
+      goal "Put a bug back on the queue without finishing it"
+
+      reference_to Assignment
+      attribute :held_by, Holder, sets: true
+
+      emits "AssignmentReleased"
+    end
+  end
+
+  # The workaround that lets the QA rotation keep moving while the bug stays open. One Stub per bug,
+  # so its reference is the bug's reference, and `RetireStubOnFix` can name it from the fix alone.
+  aggregate "Stub" do
+    description "A named temporary workaround for a bug whose fix is not ready, with the QA target it keeps moving."
+
+    identified_by :reference
+
+    attribute :reference, StubReference
+    attribute :bug,       StubBug
+    attribute :target,    StubTarget
+    attribute :reason,    StubReason
+
+    value_object "StubReference" do
+      attribute :value, String, matches: :present
+      invariant("a stub is referenced") { !value.to_s.empty? }
+    end
+
+    value_object "StubBug" do
+      attribute :value, String, matches: :present
+      invariant("a stub says which bug it stands in for") { !value.to_s.empty? }
+    end
+
+    # The QA target name, such as `ledger_ordering`, that this stub lets keep moving.
+    value_object "StubTarget" do
+      attribute :value, String, matches: :present
+      invariant("a stub says which target it keeps moving") { !value.to_s.empty? }
+    end
+
+    # Required: a workaround that does not say why it exists is a silent failure.
+    value_object "StubReason" do
+      attribute :value, String, matches: :present
+      invariant("a stub says why it exists") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "active" do
+      transition "Retire" => "retired", from: "active"
+      mark :terminal, "retired"
+    end
+
+    command "Record" do
+      role "Coder"
+      goal "Stand a named workaround in for a bug whose fix is not ready"
+
+      attribute :reference, StubReference
+      attribute :bug,       StubBug
+      attribute :target,    StubTarget
+      attribute :reason,    StubReason
+
+      emits "StubRecorded"
+    end
+
+    # Retire has no `given` on the bug's state: a Stub cannot read Assignment. The only path to
+    # this command is `RetireStubOnFix`, which fires on `AssignmentFixed`, so the bug is fixed by
+    # construction.
+    command "Retire" do
+      role "Coder"
+      goal "Take a workaround out once the bug it stood in for is fixed"
+
+      reference_to Stub
+
+      emits "StubRetired"
+    end
+  end
+
+  # The coder side only submits. `Submit` records that a branch at a commit is ready for QA and
+  # maintenance to take from here; it lands nothing and pushes nothing. The event
+  # `WorkSubmitted(branch, sha)` is the contract those policies read.
+  aggregate "Submission" do
+    description "One branch at one commit, handed to QA and maintenance to land."
+
+    identified_by :branch
+
+    attribute :branch, SubmissionBranch
+    attribute :sha,    SubmissionSha
+
+    value_object "SubmissionBranch" do
+      attribute :value, String, matches: :present
+      invariant("a submission names its branch") { !value.to_s.empty? }
+    end
+
+    # 7 to 40 hex, as Patch's CommitRef is: a submission of a commit that is not a sha is refused.
+    value_object "SubmissionSha" do
+      attribute :value, String, matches: :git_sha
+    end
+
+    command "Submit" do
+      role "Coder"
+      goal "Hand a branch at a commit to QA and maintenance, and land nothing from here"
+
+      attribute :branch, SubmissionBranch
+      attribute :sha,    SubmissionSha
+
+      emits "WorkSubmitted"
+    end
+  end
+
+  # A Patch is one pull request opened for a bug's fix, recorded so its CI status is a lookup.
+  # Named `Patch`, as QualityControl names its own; `identified_by :number` keeps it a lookup.
+  aggregate "Patch" do
+    description "One pull request opened for a bug's fix: number, branch, and the commit it was opened at."
+
+    identified_by :number
+
+    attribute :number, PatchNumber
+    attribute :bug,    PatchBug
+    attribute :branch, PatchBranch
+    attribute :commit, CommitRef
+
+    value_object "PatchNumber" do
+      attribute :value, Integer
+      invariant("a patch is numbered") { value.positive? }
+    end
+
+    value_object "PatchBug" do
+      attribute :value, String, matches: :present
+      invariant("a patch says which bug it fixes") { !value.to_s.empty? }
+    end
+
+    value_object "PatchBranch" do
+      attribute :value, String, matches: :present
+      invariant("a patch says which branch it is on") { !value.to_s.empty? }
+    end
+
+    # 7 to 40 hex: a fix that lives only in a working tree is not a fix.
+    value_object "CommitRef" do
+      attribute :value, String, matches: :git_sha
+    end
+
+    # Both endings are terminal, as QualityControl's Patch has them.
+    lifecycle :status, default: "opened" do
+      transition "Merge" => "merged", from: "opened"
+      transition "Close" => "closed", from: "opened"
+      mark :terminal, "closed", "merged"
+    end
+
+    command "Open" do
+      role "Coder"
+      goal "Record that a fix has been opened as a pull request"
+
+      attribute :number, PatchNumber
+      attribute :bug,    PatchBug
+      attribute :branch, PatchBranch
+      attribute :commit, CommitRef
+
+      emits "PatchOpened"
+    end
+
+    # `bug` and `commit` are restated so `PatchMerged` carries them: an event holds only its
+    # dispatched arguments, and QualityControl's `Bug.Fix` needs the commit that made the fix.
+    command "Merge" do
+      role "Coder"
+      goal "Record that GitHub merged it"
+
+      reference_to Patch
+      attribute :bug,    PatchBug
+      attribute :commit, CommitRef
+
+      emits "PatchMerged"
+    end
+
+    command "Close" do
+      role "Coder"
+      goal "Record that GitHub closed it without merging"
+
+      reference_to Patch
+
+      emits "PatchClosed"
+    end
+  end
+
+  # The brief a coder session reads for one Work row: the outcome it asks for, the area it may edit,
+  # and the standing rules every brief carries. The rules are set here, once, so no agent prompt
+  # restates them. `area` is optional: a row that names none gets a brief with no area section.
+  aggregate "Brief" do
+    description "What one coder session is told: the outcome, the area it may edit, and the standing rules."
+    created_by "Brief.compose!"
+
+    attribute :work,         BriefWork
+    attribute :outcome,      BriefOutcome
+    attribute :detail,       BriefDetail, optional: true
+    attribute :area,         list_of(AreaWord), optional: true
+    attribute :rules,        BriefRules
+    attribute :verification, BriefVerification
+    attribute :workflow,     BriefRules, optional: true
+    attribute :landing,      BriefRules, optional: true
+    attribute :restraints,   BriefRules, optional: true
+    attribute :report,       BriefRules, optional: true
+    attribute :coordination, BriefRules, optional: true
+    attribute :freeze,       BriefRules, optional: true
+    identified_by :work
+
+    value_object "BriefWork" do
+      attribute :value, String, matches: :present
+      invariant("a brief names the work it briefs") { !value.to_s.empty? }
+    end
+
+    # The Work row's title: the outcome the session is to reach, not the steps to take.
+    value_object "BriefOutcome" do
+      attribute :value, String, matches: :present
+      invariant("a brief states an outcome") { !value.to_s.empty? }
+    end
+
+    value_object "BriefDetail" do
+      attribute :value, String
+    end
+
+    # One path or module name the session may edit.
+    value_object "AreaWord" do
+      attribute :value, String, matches: :present
+    end
+
+    value_object "BriefRules" do
+      attribute :value, String
+    end
+
+    value_object "BriefVerification" do
+      attribute :value, String
+    end
+
+    # The brief a coder session reads for the next planned row: the Brief keyed by that row.
+    query "For" do
+      description "The brief composed for one Work row, by the row's key."
+      attribute :row, BriefWork
+      where(work: :row)
+    end
+
+    command "Compose" do
+      role "Coder"
+      goal "Build the brief for a Work row from its outcome and area, with the standing rules"
+
+      attribute :work,    BriefWork, sets: true
+      attribute :outcome, BriefOutcome, sets: true
+      attribute :detail,  BriefDetail, optional: true, sets: true
+      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 :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 :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':"
+
+      emits "BriefComposed"
+    end
+  end
+
+  # A planned Work row is briefed when it is planned: the title is the outcome, and the detail and the
+  # area come with it. A session reads the brief of `Work.next_planned` with `Brief.for`.
+  policy "ComposeBriefWhenPlanned" do
+    on      "Work.WorkPlanned"
+    trigger Brief::Compose, with: { work: :work, outcome: :title, detail: :detail, area: :area }
+  end
+
+  # The one automatic reaction. A fix retires the workaround standing in for it: the stub is only
+  # needed while the bug is open, so it is retired by policy rather than inline in `Fix`, which
+  # would couple two aggregates in one command. `Assignment.Fix` emits `AssignmentFixed`, and the
+  # bug is the Stub's reference, so `stub: :bug` names the right one.
+  policy "RetireStubOnFix" do
+    on      "Assignment.AssignmentFixed"
+    trigger Stub::Retire, with: { stub: :bug }
+  end
+end

data/lib/hecks/coder/coder.hecksagon

@@ -0,0 +1,12 @@
+Hecks.hecksagon "Coder" do
+  attaches "Governance"
+  persisted_by "Memory"
+
+  # A planned Work row, which ComposeBriefWhenPlanned briefs.
+  subscribe "Tickets.WorkPlanned"
+end
+
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end