hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/find/find.bluebook

@@ -0,0 +1,81 @@
+Hecks.bluebook "Hecks" do
+  domain_module "Find" do
+    vision "Read the code: search the checkout's text, read a file, outline what it declares, find where a name is declared."
+
+    aggregate "Codebase" do
+      description "A read of the checkout's text files, answered without changing anything."
+      acknowledges :no_command_surface, "a read of the checkout's files, answered without changing anything"
+
+      attribute :root, CheckoutRoot
+      identified_by :root
+
+      value_object "CheckoutRoot" do
+        attribute :value, String, matches: :present
+      end
+
+      # A regular expression, matched against one line of text at a time.
+      value_object "Pattern" do
+        attribute :value, String, matches: :present
+      end
+
+      # An answer that is one document of text, one `path:line: text` row to a match.
+      value_object "Document" do
+        attribute :text, String
+      end
+
+      query "Search" do
+        description "The lines of the checkout's text files that match a pattern, as path:line: text."
+        attribute :pattern, Pattern
+        attribute :paths, PathList, optional: true
+        attribute :top, Top, optional: true
+        returns Document
+      end
+
+      # A file of the checkout, named from its root.
+      value_object "SourcePath" do
+        attribute :value, String, matches: :present
+      end
+
+      # A line of a file, counted from 1.
+      value_object "LineNumber" do
+        attribute :value, Integer
+
+        invariant("a line is counted from 1") { value > 0 }
+      end
+
+      # The name a construct is declared under, as it stands between the quotes.
+      value_object "DeclaredName" do
+        attribute :value, String, matches: :present
+      end
+
+      # What a declaration is: aggregate, command, query, policy and the rest.
+      value_object "DeclaredKind" do
+        attribute :value, String, pattern: '^[a-z_]+$'
+      end
+
+      query "ReadSource" do
+        description "The numbered lines of one file of the checkout, whole or from one line to another."
+        attribute :path, SourcePath
+        attribute :from, LineNumber, optional: true
+        attribute :to,   LineNumber, optional: true
+        attribute :top,  Top, optional: true
+        returns Document
+      end
+
+      query "Outline" do
+        description "What a file declares, by line: each construct of a bluebook, each definition of Ruby."
+        attribute :path, SourcePath
+        returns Document
+      end
+
+      query "Declaration" do
+        description "Where a named construct is declared across the corpus, as path:from-to, with its text on request."
+        attribute :name,  DeclaredName
+        attribute :kind,  DeclaredKind, optional: true
+        attribute :paths, PathList, optional: true
+        attribute :show,  Switch, optional: true
+        returns Document
+      end
+    end
+  end
+end

data/lib/hecks/hecks/hecks.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Hecks" do
   vision "A release moves tagged, published, verified; the grammar cache moves fresh, stale, fresh."
 
-  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 "Tag records a version as tagged" do
     tests "Tag", on: "Release"

data/lib/hecks/hecks/hecks.bluebook

@@ -1,137 +1,4 @@
 Hecks.bluebook "Hecks" do
   vision "What this install is, what version it runs, and whether its grammar cache can be trusted."
   namespace "Hecks::Domain"
-
-  aggregate "Release" do
-    description "One gem version: the record of what is running and what was shipped."
-
-    attribute :version,    Version
-    attribute :ir_version, Version
-    attribute :ships_from, Checkout, optional: true
-    # The findings the version settled, by the key the Tickets bluebook gives them.
-    attribute :closes,     list_of(FindingKey), optional: true
-
-    identified_by :version
-
-    value_object "FindingKey" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "Version" do
-      attribute :value, String, matches: :version
-
-      invariant("a version is present") { !value.to_s.empty? }
-    end
-
-    value_object "Checkout" do
-      attribute :path, String
-
-      invariant("a checkout is a working tree with hecks.gemspec beside lib/") { !path.to_s.empty? }
-    end
-
-    lifecycle :state, default: "tagged" do
-      transition "MarkPublished" => "published", from: "tagged"
-      transition "Verify"        => "verified",  from: %w[published verified]
-    end
-
-    command "Tag" do
-      role "Maintainer"
-      goal "Record a version as tagged, with the IR version it carries"
-
-      attribute :version,    Version, sets: true
-      attribute :ir_version, Version, sets: true
-      attribute :ships_from, Checkout, sets: true
-
-
-      emits Tagged
-    end
-
-    command "MarkPublished", from: "tagged" do
-      role "Maintainer"
-      goal "Record that a tagged version reached the gem registry"
-
-      reference_to Release
-
-      emits Published
-    end
-
-    command "Verify", from: %w[published verified] do
-      role "Maintainer"
-      goal "Record that the published version installs and boots"
-
-      reference_to Release
-
-      emits Verified
-    end
-
-    command "CloseFindings" do
-      role "Maintainer"
-      goal "Record the findings this version settled"
-
-      reference_to Release
-      attribute :closes, list_of(FindingKey), sets: true
-
-
-      emits FindingsClosed
-    end
-
-    query "Shipped" do
-      description "Every version that was tagged, published and verified."
-      where(state: "verified")
-      order_by :version
-    end
-  end
-
-  aggregate "SyntaxBootCache" do
-    description "The grammar bluebooks' on-disk boot cache, keyed by a digest of the bluebooks it was built from."
-
-    attribute :digest, Digest
-
-    identified_by :digest
-
-    value_object "Digest" do
-      attribute :value, String, matches: :present
-
-      invariant("a digest is present") { !value.to_s.empty? }
-    end
-
-    lifecycle :state, default: "fresh" do
-      transition "Invalidate" => "stale", from: "fresh"
-      transition "Rebuild"    => "fresh", from: "stale"
-    end
-
-    command "Record" do
-      role "Maintainer"
-      goal "Record a boot cache as built from the grammar bluebooks that hash to this digest"
-
-      attribute :digest, Digest, sets: true
-
-
-      emits CacheRecorded
-    end
-
-    command "Invalidate", from: "fresh" do
-      role "Maintainer"
-      goal "Record that the grammar changed under the cache"
-
-      reference_to SyntaxBootCache
-
-      emits CacheInvalidated
-    end
-
-    command "Rebuild", from: "stale" do
-      role "Maintainer"
-      goal "Record that the cache was rebuilt from the current grammar"
-
-      reference_to SyntaxBootCache
-
-      emits CacheRebuilt
-    end
-
-    query "Stale" do
-      description "Every cache whose grammar changed under it and is not yet rebuilt."
-      where(state: "stale")
-      order_by :digest
-    end
-  end
 end

data/lib/hecks/hecks/hecks.contextmap

@@ -18,6 +18,8 @@ Hecks.context_map "Hecks" do
   context "Tickets"
   context "Composer"
   context "QualityControl"
+  context "Coder"
+  context "Fixer"
 
   # Deploy's `Tenant` is a validated request; Tenancy's `Tenant` is a fact. Tenancy's hecksagon
   # translates Deploy's `TenantProvisioned` into its own `Register`, so Deploy's model never reaches it.

data/lib/hecks/hecks/hecks.hecksagon

@@ -2,8 +2,10 @@ Hecks.hecksagon "Hecks" do
   attaches "Governance"
 
   # The bluebooks the gem carries: the language declared in itself (Paging comes with Bluebook),
-  # Expression, Tenancy, Deploy, Site, Tickets, Composer and QualityControl (the last three bring their own ports).
-  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets Composer QualityControl]
+  # Expression, Tenancy, Deploy, Site, Tickets, Composer and QualityControl (the last three bring
+  # their own ports), and Coder and Fixer, whose events Tickets and QualityControl react to.
+  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets Composer QualityControl
+     Coder Fixer]
     .each { |declaration| attaches declaration }
   # Persistence is not bound here, so the domain is in Memory. A copy opts in with a
   # hecks.local.hecksagon whose `persisted_by` the attached bluebooks inherit (ADR 0136).
@@ -80,38 +82,95 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
-  Hecks::PushTrain.port "Train" do
-    asks "Carry", to: PushTrain do
+  Hecks::SendTrain.port "Train" do
+    asks "Carry", to: SendTrain do
       attribute :run, RunKey
       answers "TrainAnswered"
       refuses "TrainRefused"
     end
 
-    asks "Tally", to: PushTrain do
+    asks "Tally", to: SendTrain do
       attribute :run, RunKey
       answers "SurveyAnswered"
       refuses "SurveyRefused"
     end
   end
 
-  Hecks::PushTrain.port "Alerts" do
-    asks "Announce", to: PushTrain do
+  Hecks::PushRehearsal.port "Rehearsing" do
+    asks "Trial", to: PushRehearsal do
       attribute :run, RunKey
+      answers "PushRehearsalAnswered"
+      refuses "PushRehearsalRefused"
+    end
+
+    answers_query "Due"
+  end
+
+  Hecks::QaQuiesce.port "Quiescing" do
+    asks "Mark", to: QaQuiesce do
+      attribute :run, RunKey
+      answers "QuiesceAnswered"
+      refuses "QuiesceRefused"
+    end
+
+    asks "Clear", to: QaQuiesce do
+      attribute :run, RunKey
+      answers "QuiesceAnswered"
+      refuses "QuiesceRefused"
+    end
+
+    answers_query "Status"
+  end
+
+  Hecks::SendTrain.port "Alerts" do
+    asks "Announce", to: SendTrain do
+      attribute :run, RunKey
+      attribute :pushed, Word
       answers "DeployReadyAnnounced"
       refuses "AnnouncementRefused"
     end
   end
 
-  Hecks::Checkout.port "Reading" do
+  Hecks::Workspace.port "Reading" do
     answers_query "Status"
     answers_query "Changes"
-    answers_query "Log"
+    answers_query "History"
   end
 
-  Hecks::Checkout.port "Settings" do
+  Hecks::Workspace.port "Settings" do
     answers_query "Settings"
   end
 
+  Hecks::Workspace.port "Doctor" do
+    answers_query "Doctor"
+  end
+
+  Hecks::Workspace.port "Where" do
+    answers_query "Where"
+  end
+
+  Hecks::Revision.port "Committing" do
+    asks "Commit", to: Revision do
+      attribute :run, RunKey
+      answers "CommitAnswered"
+      refuses "CommitRefused"
+    end
+  end
+
+  Hecks::LinkedTree.port "WorktreeAdding" do
+    asks "Create", to: LinkedTree do
+      attribute :run, RunKey
+      answers "CreateAnswered"
+      refuses "CreateRefused"
+    end
+
+    asks "Pull", to: LinkedTree do
+      attribute :run, RunKey
+      answers "PullAnswered"
+      refuses "PullRefused"
+    end
+  end
+
   Hecks::Landing.port "Worktrees" do
     asks "Merge", to: Landing do
       attribute :run, RunKey
@@ -119,6 +178,18 @@ Hecks.hecksagon "Hecks" do
       refuses "MergeRefused"
     end
 
+    asks "FinishBranch", to: Landing do
+      attribute :run, RunKey
+      answers "MergeAnswered"
+      refuses "MergeRefused"
+    end
+
+    asks "Convene", to: Landing do
+      attribute :run, RunKey
+      answers "ConveneAnswered"
+      refuses "ConveneRefused"
+    end
+
     asks "Remove", to: Landing do
       attribute :run, RunKey
       answers "RemovalAnswered"
@@ -128,6 +199,47 @@ Hecks.hecksagon "Hecks" do
     answers_query "Unlanded"
   end
 
+  # The Tickets row a landed branch was cut for: the port reads the Work rows and answers the open
+  # one the branch names, refusing when there is none.
+  Hecks::Landing.port "LandedWork" do
+    asks "FindLandedWork", to: Landing do
+      attribute :branch, Word
+      answers "LandedWorkFound"
+      refuses "NoLandedWork"
+    end
+  end
+
+  Hecks::ReviewRequest.port "GitHubPullRequests" do
+    asks "Create", to: ReviewRequest do
+      attribute :run, RunKey
+      answers "OpenAnswered"
+      refuses "OpenRefused"
+    end
+
+    asks "Squash", to: ReviewRequest do
+      attribute :run, RunKey
+      answers "SquashAnswered"
+      refuses "SquashRefused"
+    end
+
+    answers_query "Status"
+  end
+
+  # The outside a filling of the queue reaches: the Work rows, the machine's load and the freeze.
+  Hecks::Dispatch.port "Dispatching" do
+    asks "Choose", to: Dispatch do
+      attribute :run, DispatchKey
+      answers "DispatchReported"
+      refuses "DispatchRefused"
+    end
+
+    asks "Conclude", to: Dispatch do
+      attribute :run, DispatchKey
+      answers "DispatchReported"
+      refuses "DispatchRefused"
+    end
+  end
+
   # The outside an agent run reaches: it finds the directory, starts the background session, and
   # reports the state the session is in. The state is judged in the bluebook, not here.
   Hecks::AgentRun.port "Agents" do
@@ -163,9 +275,10 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
-  Hecks::PushTrain.port "Launcher" do
-    asks "Refresh", to: PushTrain do
+  Hecks::SendTrain.port "Launcher" do
+    asks "Refresh", to: SendTrain do
       attribute :run, RunKey
+      attribute :pushed, Word
       answers "LauncherRefreshed"
       refuses "LauncherRefreshRefused"
     end
@@ -184,10 +297,24 @@ Hecks.hecksagon "Hecks" do
       refuses "EraRefused"
     end
 
+    asks "Mint", to: Era do
+      attribute :run, RunKey
+      answers "Minted"
+      refuses "MintRefused"
+    end
+
     answers_query "ScaffoldTranslation"
     answers_query "AuditTranslation"
+    answers_query "ComposeTranslation"
+    answers_query "ReconcilePlan"
     answers_query "Attestation"
     answers_query "Compaction"
+    answers_query "BootStatus"
+    answers_query "SqliteStatus"
+    answers_query "EventTrace"
+    answers_query "MintPlan"
+    answers_query "BootResolution"
+    answers_query "ProjectionAudit"
   end
 
   Hecks::Era.port "Ledger" do
@@ -247,13 +374,15 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
-  Hecks::Launch.port "Terminal" do
-    asks "Serve", to: Launch do
-      attribute :run, LaunchKey
-      answers "LaunchAnswered"
-      refuses "LaunchRefused"
+  Hecks::Server.port "Terminal" do
+    asks "Serve", to: Server do
+      attribute :run, RunKey
+      answers "ServerAnswered"
+      refuses "ServerRefused"
     end
+  end
 
+  Hecks::Launch.port "Terminal" do
     asks "Converse", to: Launch do
       attribute :run, LaunchKey
       answers "LaunchAnswered"
@@ -286,6 +415,12 @@ Hecks.hecksagon "Hecks" do
       refuses "BuildRefused"
     end
 
+    asks "Parser", to: Build do
+      attribute :run, BuildKey
+      answers "BuildAnswered"
+      refuses "BuildRefused"
+    end
+
     asks "Conform", to: Build do
       attribute :run, BuildKey
       answers "BuildAnswered"
@@ -339,6 +474,20 @@ Hecks.hecksagon "Hecks" do
 
   # Codebase: every ask goes to the SourceTree port, which examines the working tree before it
   # carries a request out.
+  Hecks::ScriptRun.port "SourceTree" do
+    asks "Examine", to: ScriptRun do
+      attribute :run, RunKey
+      answers "ScriptExamined"
+      refuses "ScriptRefused"
+    end
+
+    asks "Perform", to: ScriptRun do
+      attribute :run, RunKey
+      answers "ScriptAnswered"
+      refuses "ScriptRefused"
+    end
+  end
+
   Hecks::LanguageRun.port "SourceTree" do
     asks "Examine", to: LanguageRun do
       attribute :run, RunKey
@@ -441,6 +590,9 @@ Hecks.hecksagon "Hecks" do
       refuses "InspectionRefused"
     end
 
+  end
+
+  Hecks::Codebase.port "SourceTree" do
     answers_query "Search"
     answers_query "ReadSource"
     answers_query "Outline"
@@ -480,26 +632,29 @@ Hecks.hecksagon "Hecks" do
   end
 
   Hecks::CorpusRun.port "SourceTree" do
-    asks "Examine", to: CorpusRun do
-      attribute :run, RunKey
-      answers "CorpusExamined"
-      refuses "CorpusRefused"
-    end
-
-    asks "Perform", to: CorpusRun do
-      attribute :run, RunKey
-      answers "CorpusAnswered"
-      refuses "CorpusRefused"
-    end
-
     answers_query "RustDomains"
     answers_query "RegenOrder"
     answers_query "CorpusRustCoverage"
+    answers_query "GeneratedKey"
     answers_query "IrConstructs"
     answers_query "IrDuplicates"
     answers_query "IrImpact"
   end
 
+  Hecks::Server.port "SourceTree" do
+    asks "Examine", to: Server do
+      attribute :run, RunKey
+      answers "ServerExamined"
+      refuses "ServerRefused"
+    end
+
+    asks "Perform", to: Server do
+      attribute :run, RunKey
+      answers "ServerAnswered"
+      refuses "ServerRefused"
+    end
+  end
+
   Hecks::PublishingRun.port "SourceTree" do
     asks "Examine", to: PublishingRun do
       attribute :run, RunKey
@@ -687,6 +842,7 @@ Hecks.hecksagon "Hecks" do
     answers_query "Stores"
     answers_query "History"
     answers_query "Statements"
+    answers_query "Undo"
     answers_query "Narrate"
     answers_query "Relationships"
     answers_query "ContextMap"

data/lib/hecks/hecks/hecks.world

@@ -33,15 +33,37 @@
 # by the process that made it, so `request` waits and prints the whole outcome), `executable` is where `hecks project_cli` writes this bluebook's launcher (the
 # gem's `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_commands` names
 # the commands that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
-# `hecks console` needs no database), and `legacy` names the commands it hands to `Hecks::CLI` in the
-# positional forms ADR 0066 shipped. `maintainer` names the aggregates only someone working on a hecks
+# `hecks console` needs no database), and the retired positional forms (ADR 0066) are refused by name, so no `legacy` list remains. `maintainer` names the aggregates only someone working on a hecks
 # checkout runs (Codebase, and releasing hecks itself): the help leaves them out anywhere else and
 # `--maintainer` lists them; `bluebooks` names the attached bluebooks the help points at, one line each
 # (`hecks deploy`), and `maintainer_bluebooks` the language's own, added inside a checkout.
 # `newcomer` names the only commands the help lists in a folder holding no bluebook yet
 # (`hecks --all` lists the rest), so a first run shows how to start and nothing else.
+# `everyday` names the commands and queries the help lists first, under its own heading, each
+# spelled as the call to type, for anyone the aggregate is not hidden from (ADR 0163).
+#
+# **test_scope** `suite_runs_in` names where the full suite runs ("ci": a local run of it is refused by name) and
+# `spec_files_limit` is the most spec files one local `run_spec_files!` or `run_impacted_specs!` call runs.
+#
+# **landing** `stale_minutes` is how long a landing's ticket may go without a heartbeat before the next one treats
+# it as abandoned and removes it (30 when absent); `wait_minutes` is how long a landing waits for its turn in the
+# line before it gives up (40 when absent); `shell_lock` names a lock directory an older brief makes by hand,
+# which a landing honours as the holder while it exists. Landings run one at a time, first come first served.
 Hecks.world "Hecks" do
   realm "Hecks"
+  # The tables the renamed aggregates keep: Workspace was Checkout, Revision was Commit, SendTrain was
+  # PushTrain and ReviewRequest was PullRequest, and their rows stay where they were written.
+  # A boot that found them empty beside the old tables' rows would refuse by name.
+  stored_as Workspace: "checkout", Revision: "commit", SendTrain: "push_train", ReviewRequest: "pull_request"
+  # The command whose own record an unminted boot is let write: a mint cannot start from a boot whose
+  # shape no era holds yet. This domain's PostgresEra binding lives in uncommitted local files, so the
+  # name is said here, where every copy reads it.
+  minting commands: ["Era.MintHeld"]
+  landing "Queue", stale_minutes: 30, wait_minutes: 40
+  # Owner decision: the full spec suite runs only in CI (the Vocabulary `rspec` check is `runs_in: "ci"`).
+  # Locally `test_suite_run.run_suite!` is refused, and `run_spec_files!` and `run_impacted_specs!` run at
+  # most `spec_files_limit` files per call; CI is detected by the environment (`CI`, `GITHUB_ACTIONS`).
+  test_scope "Local", suite_runs_in: "ci", spec_files_limit: 25
   launcher "Launcher", run_keys: true,
                        settled: %w[package.vendor package.revendor package.release
                                   operation.bootstrap_admin smoke_run.run
@@ -49,22 +71,26 @@ Hecks.world "Hecks" do
                                   data_copy.verify bluebook_diff.run preview_run.name
                                   preview_run.url preview_run.list preview_run.deploy
                                   preview_run.destroy preview_run.login companion_roll.run
-                                  handover.clear rehearsal_run.request push_train.board
-                                  landing.land landing.retire agent_run.dispatch agent_run.check],
+                                  handover.clear rehearsal_run.request send_train.board
+                                  landing.land landing.train landing.retire agent_run.dispatch agent_run.check],
                        unknown_runs: %w[rehearsal_run.rehearsal_outcome],
-                       names: { "config" => "checkout.settings", "mcp" => "launch.serve_mcp", "console" => "operation.open_console", "init" => "launch.init",
+                       renamed: { "push_train.push" => "send_train.send", "pull_request.merge" => "review_request.take", "checkout.log" => "workspace.history" },
+                       names: { "config" => "workspace.settings", "doctor" => "workspace.doctor", "mcp" => "server.serve_mcp", "console" => "operation.open_console", "init" => "launch.init",
                                 "interview" => "launch.interview", "package.check" => "registry.check",
                                 "package.digest" => "registry.digest",
                                 "package.release" => "registry.release" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
                        maintainer: %w[LanguageRun KernelRun ConformanceRun RegenerationRun GateRun StyleRun InspectionRun
-                                      CodemodRun TestSuiteRun CorpusRun PublishingRun PromotionRun Release
+                                      CodemodRun TestSuiteRun CorpusRun Server PublishingRun PromotionRun Release ScriptRun
                                       SyntaxBootCache],
                        newcomer: %w[launch.init launch.interview operation.open_console],
+                       everyday: %w[operation.run operation.open_console gate_run.gate
+                                    test_suite_run.run_changed test_suite_run.run_spec_example
+                                    test_suite_run.run_spec_files test_suite_run.run_impacted_specs
+                                    build.build_host shipment.ship landing.land send_train.board
+                                    workspace.status codebase.search],
                        bluebooks: %w[Deploy Governance Tenancy Site Tickets Composer QualityControl],
                        maintainer_bluebooks: %w[Bluebook Hecksagon World Adapter Port Translation Expression],
-                       memory_commands: %w[console init interview],
-                       legacy: %w[run docs narrate ir stores model_check smoke_test
-                                  project_diagrams project_cli mcp]
+                       memory_commands: %w[console init interview]
 end

data/lib/hecks/hecks/implicit_moves.json

@@ -0,0 +1,24 @@
+{
+  "QualityControl": [
+    {
+      "from": "e6b119",
+      "to": "541955"
+    },
+    {
+      "from": "541955",
+      "to": "7005ea"
+    },
+    {
+      "from": "7005ea",
+      "to": "316ef0"
+    },
+    {
+      "from": "316ef0",
+      "to": "8cdb9d"
+    },
+    {
+      "from": "8cdb9d",
+      "to": "bbe061"
+    }
+  ]
+}