hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/codebase.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Codebase" do
   vision "A request to work on this repository is recorded, the tree is examined, and only a hecks checkout lets it through."
 
-  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "agents.bluebook", "codebase.bluebook", "ledger.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+  loads "hecks.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world", modules: :all
 
   test "ProjectModel reports what the language projects, and keeps the answer" do
     tests "ProjectModel", on: "LanguageRun"
@@ -79,12 +79,56 @@ Hecks.behaviors "Codebase" do
     expect refused: "must match"
   end
 
+  test "RegenerateCorpus refuses a list of domains that is not one" do
+    tests "RegenerateCorpus", on: "RegenerationRun"
+    input run: { value: "domains" }, domains: { value: "Lease Clock" }
+    expect refused: "must match"
+  end
+
+  test "RegenerateCorpus refuses a count of zero workers" do
+    tests "RegenerateCorpus", on: "RegenerationRun"
+    input run: { value: "no_workers" }, workers: { value: 0 }
+    expect refused: "a count is positive"
+  end
+
+  test "RegenerateCorpus keeps a domain that is not there as a faulted request" do
+    tests "RegenerateCorpus", on: "RegenerationRun"
+    input run: { value: "unknown_domain" }, domains: { value: "no_such_domain" }
+    expect emits: %w[RegenerateCorpusRequested RegenerationExamined RegenerationAccepted RegenerationRefused
+                     RegenerationFaulted]
+  end
+
+  test "RegenerateCorpus checks only the domains it is named, and keeps the answer" do
+    tests "RegenerateCorpus", on: "RegenerationRun"
+    input run: { value: "some_domains" }, domains: { value: "lease_clock,nested_pieces" }, check: { value: true }
+    expect emits: %w[RegenerateCorpusRequested RegenerationExamined RegenerationAccepted RegenerationAnswered
+                     RegenerationCompleted]
+  end
+
+  test "GeneratedKey refuses a list of domains that is not one" do
+    tests "GeneratedKey", on: "CorpusRun", kind: :query
+    input domains: { value: "lease clock" }
+    expect refused: "must match"
+  end
+
+  test "GeneratedKey answers one document for the named domains" do
+    tests "GeneratedKey", on: "CorpusRun", kind: :query
+    input domains: { value: "lease_clock,nested_pieces" }
+    expect count: 1
+  end
+
   test "ProjectCiGates refuses a run that is not named" do
     tests "ProjectCiGates", on: "RegenerationRun"
     input run: { value: "" }
     expect refused: "must match"
   end
 
+  test "ProjectCiPipeline refuses a run that is not named" do
+    tests "ProjectCiPipeline", on: "RegenerationRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
   test "ProjectToolsDoc refuses a run that is not named" do
     tests "ProjectToolsDoc", on: "RegenerationRun"
     input run: { value: "" }
@@ -139,6 +183,18 @@ Hecks.behaviors "Codebase" do
     expect emits: %w[RunSpecExampleRequested TestSuiteExamined TestSuiteAccepted TestSuiteRefused TestSuiteFaulted]
   end
 
+  test "RunSpecFiles refuses an isolation that is neither process nor shared" do
+    tests "RunSpecFiles", on: "TestSuiteRun"
+    input files: { value: "spec/a_spec.rb" }, isolation: { value: "fork" }, run: { value: "files" }
+    expect refused: "must match"
+  end
+
+  test "RunImpactedSpecs refuses a cap of zero files" do
+    tests "RunImpactedSpecs", on: "TestSuiteRun"
+    input cap: { value: 0 }, run: { value: "impacted" }
+    expect refused: "a count is positive"
+  end
+
   test "StressConcurrency refuses a count of zero runs" do
     tests "StressConcurrency", on: "TestSuiteRun"
     input runs: { value: 0 }, run: { value: "stress" }
@@ -171,25 +227,25 @@ Hecks.behaviors "Codebase" do
   end
 
   test "Present refuses a port that is not one" do
-    tests "Present", on: "CorpusRun"
+    tests "Present", on: "Server"
     input port: { value: 70_000 }, run: { value: "present" }
     expect refused: "a port is 1 to 65535"
   end
 
   test "Compose refuses a port that is not one" do
-    tests "Compose", on: "CorpusRun"
+    tests "Compose", on: "Server"
     input port: { value: 70_000 }, run: { value: "compose" }
     expect refused: "a port is 1 to 65535"
   end
 
   test "Preview refuses a port that is not one" do
-    tests "Preview", on: "CorpusRun"
+    tests "Preview", on: "Server"
     input directory: { value: "site" }, port: { value: 70_000 }, run: { value: "preview" }
     expect refused: "a port is 1 to 65535"
   end
 
   test "ServeQueryIrMcp refuses a run that is not named" do
-    tests "ServeQueryIrMcp", on: "CorpusRun"
+    tests "ServeQueryIrMcp", on: "Server"
     input run: { value: "" }
     expect refused: "must match"
   end

data/lib/hecks/hecks/composer.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Composer" do
   vision "A draft is opened, revised, judged by its check and talked about with an agent, one recorded step at a time."
 
-  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "agents.bluebook", "codebase.bluebook", "ledger.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+  loads "hecks.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world", modules: :all
 
   test "Begin opens a bluebook for editing" do
     tests "Begin", on: "Draft"

data/lib/hecks/hecks/context_map.hecksagon

@@ -9,6 +9,6 @@ end
 # The attached bluebooks (hecks.hecksagon `attaches`): each is a bounded context whose store is the
 # one the Hecks domain's own `persisted_by` gives it, so a copy that opts the Hecks bluebook in
 # opts them all in.
-%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets Composer QualityControl].each do |bluebook|
+%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets Composer QualityControl Coder Fixer].each do |bluebook|
   Hecks.hecksagon(bluebook) { attaches "Governance" }
 end

data/lib/hecks/hecks/custodian.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Custodian" do
   vision "A check and an operation are recorded as requested before anything outside is asked."
 
-  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "agents.bluebook", "codebase.bluebook", "ledger.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+  loads "hecks.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world", modules: :all
 
   test "ModelCheck records the request, runs the analysis and keeps a clean verdict" do
     tests "ModelCheck", on: "ModelCheckRun"
@@ -64,20 +64,40 @@ Hecks.behaviors "Custodian" do
   end
 
   test "Board keeps a checkout that is not there as a faulted push" do
-    tests "Board", on: "PushTrain"
-    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }
+    tests "Board", on: "SendTrain"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }, confirm: { value: true }
     expect emits: %w[BoardingRequested TrainRefused PushFaulted]
   end
 
   test "Land keeps a checkout that is not there as a refused landing" do
     tests "Land", on: "Landing"
-    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }, confirm: { value: true }
     expect emits: %w[LandingRequested MergeRefused LandingRefused]
   end
 
+  test "Rehearse keeps a checkout that is not there as a declined rehearsal" do
+    tests "Rehearse", on: "PushRehearsal"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }
+    expect emits: %w[PushRehearsalRequested PushRehearsalRefused PushRehearsalDeclined]
+  end
+
+  test "Make keeps a checkout that is not there as a declined commit" do
+    tests "Make", on: "Revision"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" },
+          message: { value: "say ok" }
+    expect emits: %w[CommitRequested CommitRefused CommitDeclined]
+  end
+
+  test "Make refuses a commit that says nothing" do
+    tests "Make", on: "Revision"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" },
+          message: { value: "  " }
+    expect refused: "a commit says what it commits"
+  end
+
   test "Retire keeps a checkout that is not there as a declined retirement" do
     tests "Retire", on: "Landing"
-    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }, confirm: { value: true }
     expect emits: %w[RetirementRequested RemovalRefused RetirementDeclined]
   end
 
@@ -143,8 +163,8 @@ Hecks.behaviors "Custodian" do
     expect emits: %w[RailsRequested LaunchRefused LaunchStopped]
   end
 
-  test "ServeMcp refuses a launch that is not named" do
-    tests "ServeMcp", on: "Launch"
+  test "ServeMcp refuses a server run that is not named" do
+    tests "ServeMcp", on: "Server"
     input run: { value: "" }
     expect refused: "must match"
   end
@@ -245,6 +265,12 @@ Hecks.behaviors "Custodian" do
     expect refused: "must match"
   end
 
+  test "BuildParser refuses a build that is not named" do
+    tests "BuildParser", on: "Build"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
   test "BuildHost refuses a target that is not a triple" do
     tests "BuildHost", on: "Build"
     input domain: { value: "examples/pizzas" }, run: { value: "host" }, target: { value: "arm64" }

data/lib/hecks/hecks/delegate/delegate.bluebook

@@ -0,0 +1,355 @@
+Hecks.bluebook "Hecks" do
+  domain_module "Delegate" do
+    vision "Hand work to a background session."
+
+    # Agents: handing one brief to a background Claude session (ADR 0141). A dispatch is a run like
+    # the Custodian `*Run`s: it is requested, the outside is asked, and what came back is judged by
+    # the givens and reactions below.
+    #
+    # The bluebook decides everything: a brief must say something, an agent name cannot be mistaken
+    # for a flag, the directory must be one the `Agents` port finds, and a session that reports
+    # `done` or `stopped` has finished while `busy` and `idle` have not. The port only looks and
+    # starts: it finds a directory, starts the session, and reports the state the session is in.
+
+    aggregate "AgentRun" do
+      description "One brief handed to a background Claude session: started and tracked, or refused with the reason."
+
+      attribute :run,       RunKey
+      attribute :repo,      Path
+      attribute :brief,     Brief
+      attribute :agent,     AgentName, optional: true
+      attribute :session,   SessionId, optional: true
+      attribute :condition, Condition, optional: true
+      attribute :refusal,   Report,    optional: true
+      attribute :tidied_at, Moment,    optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # The directory the session works in.
+      value_object "Path" do
+        attribute :value, String, matches: :not_empty
+      end
+
+      # What the session is asked to do. It may span lines; the dispatch refuses one that is blank.
+      value_object "Brief" do
+        attribute :value, String
+      end
+
+      # A custom agent's name. It starts with a letter or digit, so it cannot be taken for a flag.
+      value_object "AgentName" do
+        attribute :value, String, pattern: '\A[A-Za-z0-9][A-Za-z0-9._-]*\z'
+      end
+
+      value_object "SessionId" do
+        attribute :value, String, matches: :present
+      end
+
+      # What a session reported about itself the last time it was asked.
+      value_object "Condition" do
+        attribute :value, String
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      # When the outside removed a session, as the port reports it.
+      value_object "Moment" do
+        attribute :value, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "refused"
+        transition "Begin"   => "started",  from: "requested"
+        transition "Decline" => "refused",  from: "requested"
+        transition "Finish"  => "finished", from: "started"
+        transition "Tidied"  => "tidied",   from: "finished"
+        mark :terminal, "tidied", "refused"
+      end
+
+      command "Dispatch" do
+        role "Operator"
+        goal "Hand one brief to a background Claude session working in a directory"
+
+        attribute :run,   RunKey, sets: true
+        attribute :repo,  Path, sets: true
+        attribute :brief, Brief, sets: true
+        attribute :agent, AgentName, optional: true, sets: true
+
+        given("a brief says something") { !brief.value.to_s.strip.empty? }
+
+
+        emits AgentRunRequested
+      end
+
+      command "Begin" do
+        role "System"
+        goal "Record the session the directory's agent started"
+
+        reference_to AgentRun
+        attribute :session, SessionId, sets: true
+
+
+        emits AgentRunStarted
+      end
+
+      command "Decline" do
+        role "System"
+        goal "Record why no session was started"
+
+        reference_to AgentRun
+        attribute :refusal, Report, sets: true
+
+
+        emits AgentRunDeclined
+      end
+
+      command "Check", from: "started" do
+        role "Operator"
+        goal "Ask whether a started session is still working"
+
+        reference_to AgentRun
+
+        emits AgentCheckRequested
+      end
+
+      command "Finish" do
+        role "System"
+        goal "Record that the session has ended, and how it ended"
+
+        reference_to AgentRun
+        attribute :condition, Condition, sets: true
+
+
+        emits AgentRunFinished
+      end
+
+      # A finished run's session is removed only when it ended `done`; a session still `working`,
+      # `blocked` or `stopped` is kept, and so is one a person has taken over (the port says so).
+      command "Tidy", from: "finished" do
+        role "Operator"
+        goal "Remove the finished session of one run, unless it is unfinished or a person took it over"
+
+        reference_to AgentRun
+
+        given("the session ended done: a working, blocked or stopped session is kept") { condition.value == "done" }
+
+        emits TidyRequested
+      end
+
+      command "Tidied" do
+        role "System"
+        goal "Record that the session was removed, and when"
+
+        reference_to AgentRun
+        attribute :tidied_at, Moment, sets: true
+
+
+        emits AgentRunTidied
+      end
+
+      command "Retain" do
+        role "System"
+        goal "Record why a finished session was kept"
+
+        reference_to AgentRun
+        attribute :refusal, Report, sets: true
+
+
+        emits AgentRunRetained
+      end
+
+      query "Tidyable" do
+        description "Every finished run, oldest key first; `Tidy` keeps those that did not end done."
+        where(status: "finished")
+        order_by :run
+      end
+
+      query "Running" do
+        description "Every run whose session was started and is not known to have ended, oldest key first."
+        where(status: "started")
+        order_by :run
+      end
+
+      query "Declined" do
+        description "Every run that no session was started for, with the reason."
+        where(status: "refused")
+        order_by :run
+      end
+    end
+
+    # Filling the Work queue is one run too: the Work rows that may start a session now are chosen
+    # from the queue, the machine's load and the freeze, and without `confirm` that is all it does.
+    # The choosing and the starting are the port's; whether a start is allowed stays with `Work`.
+    aggregate "Dispatch" do
+      description "One filling of the Work queue: the planned rows that start a session now, and why each other waits."
+
+      attribute :run,            DispatchKey
+      attribute :repo,           Directory
+      attribute :confirm,        Switch, optional: true
+      attribute :budget_minutes, Minutes, optional: true
+      attribute :report,         Outcome, optional: true
+      attribute :refusal,        Outcome, optional: true
+      identified_by :run
+
+      value_object "DispatchKey" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Directory" do
+        attribute :value, String, matches: :not_empty
+      end
+
+      value_object "Switch" do
+        attribute :value, Boolean
+      end
+
+      value_object "Minutes" do
+        attribute :value, Integer
+        invariant("a time budget is positive") { value.positive? }
+      end
+
+      value_object "Outcome" do
+        attribute :value, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "refused"
+        transition "Record"  => "answered", from: "requested"
+        transition "Decline" => "refused",  from: "requested"
+        mark :terminal, "answered", "refused"
+      end
+
+      command "Fill" do
+        role "Operator"
+        goal "Choose the planned Work rows that start a session now and, with confirm, start them; without it, say what would start"
+
+        attribute :run,            DispatchKey, sets: true
+        attribute :repo,           Directory, sets: true
+        attribute :budget_minutes, Minutes, optional: true, sets: true
+        attribute :confirm,        Switch, optional: true, sets: true
+
+        emits FillRequested
+      end
+
+      command "Settle" do
+        role "Operator"
+        goal "Check the started sessions and finish the row of each that is done, or yield the row of one that stopped"
+
+        attribute :run,  DispatchKey, sets: true
+        attribute :repo, Directory, sets: true
+
+        emits SettleRequested
+      end
+
+      command "Record" do
+        role "System"
+        goal "Record what the filling or settling did"
+
+        reference_to Dispatch
+        attribute :report, Outcome, sets: true
+
+        emits DispatchAnswered
+      end
+
+      command "Decline" do
+        role "System"
+        goal "Record why the queue could not be read"
+
+        reference_to Dispatch
+        attribute :refusal, Outcome, sets: true
+
+        emits DispatchDeclined
+      end
+    end
+
+    policy "ChooseWhenFilling" do
+      on      "Dispatch.FillRequested"
+      ask     :choose, with: { run: :run }
+    end
+
+    policy "ConcludeWhenSettling" do
+      on      "Dispatch.SettleRequested"
+      ask     :conclude, with: { run: :run }
+    end
+
+    policy "RecordTheDispatch" do
+      on      "Dispatch.DispatchReported"
+      trigger Dispatch::Record, with: { report: :report }
+    end
+
+    policy "RecordTheDeclinedDispatch" do
+      on      "Dispatch.DispatchRefused"
+      trigger Dispatch::Decline, with: { refusal: :refusal }
+    end
+
+    # The directory is looked for first, so a brief is never handed to a session that has nowhere to work.
+    policy "LocateTheRepo" do
+      on      "AgentRun.AgentRunRequested"
+      ask     :locate, with: { run: :run }
+    end
+
+    policy "StartWhenTheRepoIsThere" do
+      on      "AgentRun.RepoLocated"
+      ask     :start, with: { run: :run }
+    end
+
+    policy "RecordTheSession" do
+      on      "AgentRun.AgentStarted"
+      trigger AgentRun::Begin, with: { session: :session }
+    end
+
+    policy "RecordTheMissingRepo" do
+      on      "AgentRun.RepoMissing"
+      trigger AgentRun::Decline, with: { refusal: :refusal }
+    end
+
+    policy "RecordTheRefusedStart" do
+      on      "AgentRun.StartRefused"
+      trigger AgentRun::Decline, with: { refusal: :refusal }
+    end
+
+    policy "AskTheSession" do
+      on      "AgentRun.AgentCheckRequested"
+      ask     :examine, with: { run: :run }
+    end
+
+    # The session is looked at before it is removed; the port says whether a person took it over.
+    policy "ReviewBeforeTidy" do
+      on      "AgentRun.TidyRequested"
+      ask     :review, with: { run: :run }
+    end
+
+    policy "RemoveWhenNobodyTookOver" do
+      on      "AgentRun.SessionReviewed"
+      where   { taken_over == false }
+      ask     :remove, with: { run: :run }
+    end
+
+    policy "KeepWhenAPersonTookOver" do
+      on      "AgentRun.SessionReviewed"
+      where   { taken_over != false }
+      trigger AgentRun::Retain, with: { refusal: :note }
+    end
+
+    policy "RecordTheRemoval" do
+      on      "AgentRun.SessionRemoved"
+      trigger AgentRun::Tidied, with: { tidied_at: :removed_at }
+    end
+
+    policy "RecordTheKeptSession" do
+      on      "AgentRun.RemoveRefused"
+      trigger AgentRun::Retain, with: { refusal: :refusal }
+    end
+
+    # `done` and `stopped` are a session's two ways of ending; `busy` and `idle` are not.
+    policy "FinishWhenTheSessionEnded" do
+      on      "AgentRun.SessionChecked"
+      where   { condition == "done" || condition == "stopped" }
+      trigger AgentRun::Finish, with: { condition: :condition }
+    end
+  end
+end