hecks 3.0.3 → 3.0.5

data/lib/hecks/hecks/codebase.bluebook

@@ -960,6 +960,7 @@ Hecks.bluebook "Hecks" do
     attribute :operation, Operation, optional: true
     attribute :confirm,   Switch, optional: true
     attribute :check,     Switch, optional: true
+    attribute :gate,      GateName, optional: true
     attribute :checkout,  Switch, optional: true
     attribute :report,    Report, optional: true
     attribute :refusal,   Report, optional: true
@@ -983,6 +984,11 @@ Hecks.bluebook "Hecks" do
       attribute :value, String
     end
 
+    # A `CiGate` row of the Vocabulary chapter, by name.
+    value_object "GateName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
     lifecycle :status, default: "requested" do
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
@@ -1005,6 +1011,36 @@ Hecks.bluebook "Hecks" do
       emits RegenerateCorpusRequested
     end
 
+    command "ProjectCiGates" do
+      role "Maintainer"
+      goal "Project the CiGate rows into the workflows' marked detector jobs, or with check only compare them"
+
+      attribute :check,   Switch, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :check
+      sets :run
+      sets :confirm
+      sets :operation, to: "project_ci_gates"
+
+      emits ProjectCiGatesRequested
+    end
+
+    command "DecideCiGate" do
+      role "Maintainer"
+      goal "Say whether this run's change touches what a CiGate row guards, as the gated job's detector"
+
+      attribute :gate, GateName
+      attribute :run,  RunKey
+
+      sets :gate
+      sets :run
+      sets :operation, to: "decide_ci_gate"
+
+      emits DecideCiGateRequested
+    end
+
     # What the tree reported about itself, held against every request: nothing here runs
     # outside a hecks checkout (hecks.gemspec beside lib/).
     command "Accept" do
@@ -1064,6 +1100,16 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
   end
 
+  policy "ExamineWhenProjectCiGatesRequested" do
+    on      "RegenerationRun.ProjectCiGatesRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenDecideCiGateRequested" do
+    on      "RegenerationRun.DecideCiGateRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
   policy "AcceptRegenerationWhenExamined" do
     on      "RegenerationRun.RegenerationExamined"
     trigger RegenerationRun::Accept, with: { checkout: :checkout }
@@ -1090,6 +1136,154 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::Fault, with: { refusal: :refusal }
   end
 
+  # Gate: the checks a stage holds a change against before it is let through. The checks are data
+  # (lib/hecks/gate/stages.yml), run together, and a red one faults the run, so `--wait` fails the
+  # push or the build that asked, and the journal keeps when the gate went red.
+  aggregate "GateRun" do
+    description "One run of a stage's checks: every check of the stage, or the ones named."
+
+    attribute :run,       RunKey
+    attribute :operation, Operation, optional: true
+    attribute :stage,     Stage
+    attribute :only,      CheckList, optional: true
+    attribute :checkout,  Switch, optional: true
+    attribute :report,    Report, optional: true
+    attribute :refusal,   Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    value_object "Operation" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    value_object "Stage" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+
+      invariant("a stage is named") { !value.to_s.empty? }
+    end
+
+    value_object "CheckList" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*(,[a-z][a-z0-9_]*)*$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Accept"   => "accepted",  from: "requested"
+      transition "Complete" => "completed", from: "accepted"
+      transition "Fault"    => "faulted",   from: %w[requested accepted]
+    end
+
+    command "Gate" do
+      role "Maintainer"
+      goal "Run every check of a stage, or the ones named, and keep whether the gate is green"
+
+      attribute :stage, Stage
+      attribute :only,  CheckList, optional: true
+      attribute :run,   RunKey
+
+      sets :stage
+      sets :only
+      sets :run
+      sets :operation, to: "gate"
+
+      emits GateRequested
+    end
+
+    command "Accept" do
+      role "System"
+      goal "Let a request through only when the working tree is a hecks checkout"
+
+      reference_to GateRun
+      attribute :checkout, Switch
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+
+      sets :checkout
+
+      emits GateAccepted
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that every check passed, and which"
+
+      reference_to GateRun
+      attribute :report, Report
+
+      sets :report
+
+      emits GateCompleted
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that a check was red or the run could not be made, and why"
+
+      reference_to GateRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits GateFaulted
+    end
+
+    query "GateOutcome" do
+      description "How one run ended: its status, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "GateFaulted" do
+      description "Every run that went red or could not be made."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenGateRequested" do
+    on      "GateRun.GateRequested"
+    trigger GateRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "AcceptGateWhenExamined" do
+    on      "GateRun.GateExamined"
+    trigger GateRun::Accept, with: { checkout: :checkout }
+  end
+
+  policy "FaultGateWhenNotAccepted" do
+    on      "GateRun.GateExamined"
+    where   { !checkout.value }
+    trigger GateRun::Fault, with: { refusal: "needs a hecks checkout: hecks.gemspec stands beside lib/" }
+  end
+
+  policy "PerformGateWhenAccepted" do
+    on      "GateRun.GateAccepted"
+    trigger GateRun::SourceTree::Perform, with: { run: :run }
+  end
+
+  policy "RecordGateOutcome" do
+    on      "GateRun.GateAnswered"
+    trigger GateRun::Complete, with: { report: :report }
+  end
+
+  policy "RecordGateFault" do
+    on      "GateRun.GateRefused"
+    trigger GateRun::Fault, with: { refusal: :refusal }
+  end
+
   # Style: the comment style guides (Ruby and Rust) and the canonical form of a JSON document. A
   # check finds every violation; a fix rewrites files, so it lists what it would rewrite unless
   # it is confirmed. The baseline of tolerated long blocks is written only when confirmed.

data/lib/hecks/hecks/custodian.bluebook

@@ -460,6 +460,8 @@ Hecks.bluebook "Hecks" do
 
     # A launcher answers once, so a follow is a bounded poll: it answers the entries past `since`
     # and a `cursor` to pass as the next `since`, waiting up to `wait` seconds for the first one.
+    # `hecks follow <domain> --stream` asks again from each cursor and prints every entry as it
+    # arrives, until interrupted (the world's `launcher` setting lists the question under `streams`).
     query "Follow" do
       description "A domain's persisted event log past a cursor, for tailing it call by call."
       attribute :domain,    Subject

data/lib/hecks/hecks/hecks.hecksagon

@@ -229,6 +229,20 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
+  Hecks::GateRun.port "SourceTree" do
+    asks "Examine", to: GateRun do
+      attribute :run, RunKey
+      answers "GateExamined"
+      refuses "GateRefused"
+    end
+
+    asks "Perform", to: GateRun do
+      attribute :run, RunKey
+      answers "GateAnswered"
+      refuses "GateRefused"
+    end
+  end
+
   Hecks::StyleRun.port "SourceTree" do
     asks "Examine", to: StyleRun do
       attribute :run, RunKey

data/lib/hecks/hecks/hecks.world

@@ -26,7 +26,9 @@
 # `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
 # chapter's lifecycles declare), `names` gives a command the launcher name clients type,
 # `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
-# `exe/hecks`), and `legacy` names the verbs that launcher hands to `Hecks::CLI` in the
+# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_verbs` names
+# the verbs that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
+# `hecks console` needs no database), and `legacy` names the verbs it hands to `Hecks::CLI` in the
 # positional forms ADR 0066 shipped.
 Hecks.world "Hecks" do
   realm "Hecks"
@@ -36,7 +38,9 @@ Hecks.world "Hecks" do
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
                        names: { "mcp" => "serve_mcp", "console" => "open_console" },
+                       streams: %w[Follow],
                        executable: "exe/hecks",
+                       memory_verbs: %w[console],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]
 end

data/lib/hecks/language/bluebook/command.bluebook

@@ -21,6 +21,8 @@ Hecks.bluebook "Bluebook" do
     attribute :givens,     list_of(Rule)
     # Postconditions: same Rule shape as givens, checked after the mutations.
     attribute :ensures,    list_of(Rule)
+    # Outside facts the runtime supplies before any given runs (ADR 0081): `needs :now`.
+    attribute :needs,      list_of(Need)
     attribute :mutations,  list_of(Change)
     attribute :provenance, CommandText
     # Lifecycle guard as a literal (`from: "open"` or `from: ["open", "frozen"]`); ADR 0025.
@@ -48,6 +50,10 @@ Hecks.bluebook "Bluebook" do
       attribute :name, String
     end
 
+    value_object "Need" do
+      attribute :fact, String
+    end
+
     value_object "Argument" do
       attribute :name,    String
       attribute :type,    String
@@ -254,6 +260,23 @@ Hecks.bluebook "Bluebook" do
       emits AnnouncementNamed
     end
 
+    command "Need" do
+      role "Language"
+      goal "Name an outside fact the runtime supplies before any given runs"
+
+      attribute :fact, FactName
+
+      given("a fact is named") { !fact.value.to_s.empty? }
+
+      sets :needs, append: { fact: :fact }
+
+      emits NeedNamed
+    end
+
+    value_object "FactName" do
+      attribute :value, String
+    end
+
     # Keyword rows for this chapter; SyntaxBoot discovers aggregate-local seed tables.
     value_object "KeywordSeed" do
       attribute :word,          String
@@ -283,6 +306,8 @@ Hecks.bluebook "Bluebook" do
       member word: "state",           context: "Command", body: "none",   inner: "", opens: "", fills: "mutations"
       member word: "attribute",       context: "Command", body: "none",   inner: "", opens: "", fills: "attributes", calls: "attribute_impl"
       member word: "ensures", context: "Command", body: "source", inner: "", opens: "", fills: "ensures"
+      # An outside fact the runtime supplies before any given runs (ADR 0081; CommandBuilder#needs_impl).
+      member word: "needs",           context: "Command", body: "none",   inner: "", opens: "", fills: "needs", calls: "needs_impl"
       # Amends a specific past event. Stored as a mutation so it round-trips with the other
       # mutation words (CommandBuilder#corrects_impl).
       member word: "corrects",        context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "corrects_impl"
@@ -314,6 +339,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "reference_to",    context: "Command", at: "",  named: "optional",  kind: "flag",     required: "false", fills: "optional"
       member keyword: "given",           context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "description"
       member keyword: "ensures",         context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "description"
+      member keyword: "needs",           context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "fact"
       member keyword: "sets",            context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "target"
       member keyword: "sets",            context: "Command", at: "",  named: "to",        kind: "literal",  required: "false", fills: "source", selects: "op=set"
       member keyword: "sets",            context: "Command", at: "",  named: "append",    kind: "literal",  required: "false", fills: "source", selects: "op=append"

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -73,7 +73,7 @@ Hecks.bluebook "Bluebook" do
 
     # Expression::CanonicalForm::STRATEGIES
     value_object "NormalisationStrategy" do
-      attribute :name, String, one_of: ["collapse_whitespace", "replace"]
+      attribute :name, String, one_of: ["collapse_whitespace", "replace", "scale_call"]
     end
 
     # Ops Runtime::CommandInterpreter applies. `sign` is the arithmetic delta
@@ -602,6 +602,34 @@ Hecks.bluebook "Bluebook" do
       member name: "textarea", pattern: '\b(text|body|note|notes|description|message|comment)\b', resolves_to: "kind"
     end
 
+    # The path gates the workflows run before an expensive job: one detector job
+    # per row, answering `touched` from the diff of the change against its base.
+    # hecks project_ci_gates writes each row into the marked region of its
+    # `workflow` (.github/workflows/<workflow>), and the job it writes runs
+    # `hecks decide_ci_gate gate=<name>`, which makes the decision from the row.
+    #
+    # `mode` is how `pattern` (an extended regex over changed paths) decides:
+    # `touches` runs the job when any changed path matches, `skips_unless` runs it
+    # when any changed path does NOT match (the pattern is the safe-to-skip list).
+    # `push` is what a push event does: `skip` leaves the gate out of push runs,
+    # `before_sha` diffs against the push's `before` commit.
+    value_object "CiGate" do
+      attribute :name,     String
+      attribute :workflow, String
+      attribute :mode,     String
+      attribute :pattern,  String
+      attribute :push,     String
+      attribute :label,    String
+
+      member name: "runtime_changed", workflow: "ci.yml", mode: "touches",
+             pattern: '^lib/hecks/runtime/', push: "skip",
+             label: "does this change touch lib/hecks/runtime/**?"
+      member name: "postgres_io_relevant_changed", workflow: "ci-postgres-io-parallel.yml", mode: "skips_unless",
+             pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests|project)/|rust/project\.rb$|rust/project_rust_pipeline\.rb$|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
+             push: "before_sha",
+             label: "does this change touch anything rspec_postgres_io_parallel covers?"
+    end
+
     # Rust keywords (strict + reserved) a generated identifier must not
     # collide with. RustProjection::Projector::RUST_KEYWORDS reads this;
     # hecks project_reserved_names projects it into

data/lib/hecks/language/oidc.json

@@ -111,6 +111,11 @@
       "verb": "Bluebook::Command.Ensure",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:command.need",
+      "verb": "Bluebook::Command.Need",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:command.reference",
       "verb": "Bluebook::Command.Reference",

data/lib/hecks/ports/clock.rb

@@ -3,7 +3,9 @@ require_relative "../runtime/registry"
 module Hecks
   module Ports
     # What time it is, as one registry-wide adapter answers it.
-    # Predicates cannot read the clock (replays must be deterministic), so the door fills `now`.
+    # Predicates cannot read the clock (replays must be deterministic), so a command that declares
+    # `needs :now` has the runtime read it once, before any given runs, into the command's own
+    # `now` argument (ADR 0081). The recorded argument is what a replay sees.
     module Clock
       NAME = "clock".freeze
 

data/lib/hecks/ports/persistence/plugins/era/postgres_era.rb

@@ -123,7 +123,8 @@ module Hecks
         raise unless defined?(PG::Error) && e.is_a?(PG::Error)
 
         raise Runtime::WiringError,
-              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
+              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip} " \
+              "-- to run without a database, set HECKS_ENVIRONMENT=memory (a domain needs an environments/memory overlay)"
       end
 
       # Joins the process's shared connection for the declared database and schema, so every

data/lib/hecks/projections/deploy/lambda.rb

@@ -85,7 +85,9 @@ module Hecks
                 memory:   { value: deploy_settings.fetch(:memory, 512) },
                 timeout:  { value: deploy_settings.fetch(:timeout, 10) },
                 database: { value: deploy_settings.fetch(:database, "Postgres") },
-                web: { value: deploy_settings.fetch(:web, "None") }
+                web: { value: deploy_settings.fetch(:web, "None") },
+                **%i[dispatch handler_module secret_env].select { |key| deploy_settings.key?(key) }
+                                                        .to_h { |key| [key, { value: deploy_settings[key].to_s }] }
               }
             ).instance
           rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
@@ -105,9 +107,6 @@ module Hecks
           # The module name `lambda_handler.rb` actually defines; named here
           # since `dispatch "None"` domains may each pick their own.
           webhook_handler_module = deploy_settings.fetch(:handler_module, "WebLambdaHandler")
-          if dispatch_none && !deploy_settings.key?(:handler_module)
-            raise ArgumentError, "#{world_file}'s deployed_to(\"AwsLambda\") declares dispatch \"None\" but no handler_module — add handler_module \"YourModuleName\" naming the module #{domain}/lambda_handler.rb defines."
-          end
 
           # Scans every loaded chapter, not just this domain's own — a
           # `uses_framework`-attached chapter can itself declare a cross-domain

data/lib/hecks/projector/cli_projector.rb

@@ -206,6 +206,7 @@ module Hecks
 
         { verb: fqn(bluebook, aggregate, command, entity), kind: :command,
           summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
+          group: aggregate.hecks_name, internal: command.role.to_s == "System",
           creates: command.creates?,
           receiver: receiver, legacy_receiver: (receiver == :aggregate ? :id : nil),
           legacy_arguments: legacy_arguments,
@@ -230,7 +231,7 @@ module Hecks
                 else
                   "#{port.name} telling #{aggregate.hecks_name}"
                 end,
-          role_gated: false,
+          role_gated: false, group: aggregate.hecks_name, internal: true,
           summary: port_summary(port, operation), arguments: arguments }
       end
 
@@ -257,13 +258,30 @@ module Hecks
           summary: model.description, arguments: arguments }
       end
 
+      # A question that only reads the aggregate's own records back: it returns no document and
+      # filters on nothing but the record's identity ("how one request ended") or its lifecycle
+      # status ("every request that was refused"). Each journaled run has such a pair, which a
+      # person reads through `hecks <verb> --wait` rather than asking for by name, so the help
+      # sets them apart with the bookkeeping verbs. A query that returns a document, or filters
+      # on anything else, is a real question. Only an aggregate that journals its own runs (it has
+      # system-role commands, the ones `internal` verbs are made of) has such a pair: a release's
+      # "every version that was shipped" is a question worth asking by name.
+      def bookkeeping_query?(aggregate, query)
+        return false if query.returns || query.wheres.empty?
+        return false unless aggregate.commands.any? { |command| command.role.to_s == "System" }
+
+        own = Array(aggregate.identified_by).map(&:to_s) + [aggregate.lifecycle&.field.to_s]
+        query.wheres.all? { |clause| own.include?(clause.field.to_s) }
+      end
+
       def query_spec(bluebook, aggregate, entity, query)
         arguments = Array(query.to_h[:attributes]).flat_map do |declared|
           attribute = query.attributes.find { |a| a.name.to_s == declared[:name].to_s }
           attribute ? options_for(attribute, entity || aggregate, aggregate) : []
         end
 
-        { verb: fqn(bluebook, aggregate, query, entity), kind: :query,
+        { verb: fqn(bluebook, aggregate, query, entity), kind: :query, group: aggregate.hecks_name,
+          internal: entity.nil? && bookkeeping_query?(aggregate, query),
           summary: query.description, arguments: arguments, returns: query.returns }
       end
 
@@ -373,16 +391,57 @@ module Hecks
                "  #{program} ask <question> [name=value …]  read something", ""]
 
         out << "verbs:"
-        verbs.each_value { |spec| out << "  #{spec[:short].ljust(width)}  #{spec[:summary]}" }
+        out.concat(listing(verbs, width) { |spec| spec[:summary] })
         out << ""
         out << "questions (nothing here changes anything):"
-        questions.each_value { |spec| out << "  #{spec[:short].ljust(width)}  #{first_sentence(spec[:summary])}" }
+        out.concat(listing(questions, width) { |spec| first_sentence(spec[:summary]) })
         out << ""
         out << "  #{program} <verb> --help       what one verb wants, and every way it refuses"
         out << "  a verb can always be spelled in full — #{example_qualified(verbs)}"
         out.join("\n")
       end
 
+      # The verb or question lines of the help. A domain with more than one aggregate is listed
+      # under a heading per aggregate, so related verbs sit together; the bookkeeping a run records
+      # about itself (`internal`: system-role commands and port operations) is set apart as names
+      # only, since a person never types them. A single-aggregate domain keeps the plain list.
+      def listing(specs, width)
+        shown, internal = specs.values.partition { |spec| !spec[:internal] }
+        groups = shown.group_by { |spec| spec[:group] }
+        lines = []
+        if groups.length > 1
+          groups.each do |group, members|
+            lines << "  #{heading(group)}" if group
+            members.each { |spec| lines << "    #{spec[:short].ljust(width)}  #{yield(spec)}" }
+          end
+        else
+          shown.each { |spec| lines << "  #{spec[:short].ljust(width)}  #{yield(spec)}" }
+        end
+        lines.concat(internal_lines(internal)) unless internal.empty?
+        lines
+      end
+
+      # "LanguageRun" reads "Language": the Run suffix names the journaled-command shape all of
+      # these aggregates share, so it adds nothing under a heading ("Test suite", "Model check").
+      def heading(group)
+        words = Naming.snake(group.sub(/Run\z/, "")).tr("_", " ")
+        "#{words.capitalize}:"
+      end
+
+      # The internal verbs as bare names, wrapped, under one line saying what they are.
+      def internal_lines(specs)
+        lines = ["  internal — what a run records about itself, named here only (`--help` still works):"]
+        line = "   "
+        specs.map { |spec| spec[:short] }.each do |name|
+          if line.length + name.length + 1 > 98
+            lines << line
+            line = "   "
+          end
+          line += " #{name}"
+        end
+        lines << line
+      end
+
       # One verb whose full spelling differs from its short one, or `""` when none does.
       def example_qualified(verbs)
         name, spec = verbs.find { |key, value| key != value[:short] } || verbs.first

data/lib/hecks/quality_control/quality_control.bluebook

@@ -238,6 +238,7 @@ Hecks.bluebook "QualityControl" do
       reference_to Target
       attribute :held_by,    Engineer
       attribute :now,        Instant
+      needs :now
 
       given("a live claim is not taken from the agent holding it") do
         status != "held" || claimed_at.value + window.value <= now.value
@@ -265,6 +266,7 @@ Hecks.bluebook "QualityControl" do
       # carry it. Required, so an omitted streak can neither blank the counter nor guess at it.
       reference_to Target
       attribute :now,          Instant
+      needs :now
       attribute :next_streak,  CleanStreak
       # Required: an in-process dispatch does not fill defaults for absent arguments, so an omitted
       # list refuses rather than blanks. `capabilities.value=""` is an honest value.
@@ -1115,6 +1117,7 @@ Hecks.bluebook "QualityControl" do
       reference_to Bug
       attribute :held_by, Engineer
       attribute :now,     Instant
+      needs :now
 
       given("a live claim is not taken from the agent holding it") do
         held_by.value == "nobody" || claimed_at.value + window.value <= now.value
@@ -1388,6 +1391,7 @@ Hecks.bluebook "QualityControl" do
       attribute :proposer,  Proposer
       # `now:` is filled from the clock port, as in `Target.Claim`; an explicit value wins.
       attribute :now,       Instant
+      needs :now
 
       sets :proposed_at, to: :now
 
@@ -1784,6 +1788,7 @@ Hecks.bluebook "QualityControl" do
       attribute :commit, CommitRef
       attribute :title,  PatchTitle
       attribute :now,    Instant
+      needs :now
 
       given("the branch is one this practice recognises as its own") { branch.value.start_with?("qa/") }
       given("the bug is fixed") { bug.status == "fixed" }
@@ -1921,6 +1926,7 @@ Hecks.bluebook "QualityControl" do
       attribute :branch, ImprovementBranch
       attribute :title,  ImprovementTitle
       attribute :now,    Instant
+      needs :now
 
       given("the branch is one this practice recognises as its own") { branch.value.start_with?("qa/") }
       given("the angle is under investigation") { angle.unset? || angle.status == "investigating" }

data/lib/hecks/runtime/command_interpreter.rb

@@ -83,10 +83,12 @@ module Hecks
 
       private
 
-      # No-op: `Routing` has already handed `call` a decoded argument hash,
-      # so there is nothing left to decode here yet. Kept as a step so the
-      # generated step enum has a slot to move the real decoder into later.
-      def step_decode_arguments(_ctx); end
+      # `Routing` has already handed `call` a decoded argument hash, so the one thing left to do
+      # here is answer the outside facts the command `needs`, before any refusal or given reads
+      # its arguments. Not traced: the step has always been invisible to a trace observer.
+      def step_decode_arguments(ctx)
+        ctx.args = enrich_arguments(ctx.command, ctx.args)
+      end
 
       def step_refuse_unknown_arguments(ctx)
         step(:refuse_unknown_arguments) { refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args) }
@@ -241,6 +243,8 @@ module Hecks
         target_args = ctx.args.merge(
           delegation.source.to_h { |target_key, source_key| [target_key.to_sym, ctx.args[source_key]] }
         )
+        # The target is dispatched as if called directly, so its needs and defaults are filled too.
+        target_args = enrich_arguments(target_command, target_args)
 
         refuse_unknown_arguments(ctx.domain, ctx.aggregate, target_command, target_args,
                                  extra_identity_heads: entity.identity_heads)

data/lib/hecks/runtime/entity_interpreter.rb

@@ -133,8 +133,11 @@ module Hecks
 
       private
 
-      # No-op — entities have no `decode_arguments` step of their own.
-      def step_decode_arguments(_ctx); end
+      # Answers the outside facts the entity command `needs`, as the aggregate interpreter does;
+      # the arguments are otherwise already decoded.
+      def step_decode_arguments(ctx)
+        ctx.args = enrich_arguments(ctx.command, ctx.args)
+      end
 
       # `extra_identity_heads:` covers every entity in `ctx.chain`, not just
       # the root — each hop is addressed by its own identity fields, which