hecks 3.1.0 → 3.1.1

data/lib/hecks/tickets/bluebook/tickets.bluebook

@@ -0,0 +1,331 @@
+# The Tickets chapter: what a maintainer observed about Hecks that needs a decision or a fix, the
+# and the decisions that settle them.
+#
+# QualityControl has its own Ticket, the issue raised for a Bug in an outside tracker, and the
+# Hecks domain has its own Release, the record of a gem version. A Finding sits before both: it is
+# any observation, not yet a proven bug, and it needs no sweep or failing test to be recorded.
+#
+# A Finding is the record. A gap, a parity divergence, a QA finding and an idea are kinds of it, not
+# separate aggregates. Hecks owns the finding's state; GitHub is driven from it through the
+# GitHubIssues port, which a hecksagon binds (nothing here reads GitHub back). A finding exists whether
+# or not GitHub answers: each lifecycle event asks the port, and a refused ask is recorded on the
+# finding as a sync failure that a later run retries.
+#
+# An Adr is a decision record with its own lifecycle, linked to the finding it settles.
+Hecks.bluebook "Tickets" do
+  vision "Track what Hecks needs, decide it, ship it, and drive GitHub from the record."
+
+  aggregate "Finding" do
+    description "One thing observed about Hecks that needs a decision or a fix: reported, triaged, then resolved or dismissed."
+
+    attribute :finding,         FindingKey
+    attribute :title,          Title
+    attribute :body,           Body, optional: true
+    attribute :kind,           Kind, optional: true
+    attribute :severity,       Severity, optional: true
+    attribute :source,         Source
+    attribute :fingerprint,    Fingerprint, optional: true
+    attribute :issue_number,   Number, optional: true
+    attribute :fix_pr_number,  Number, optional: true
+    attribute :dismissal,      Body, optional: true
+    attribute :sync_failure,   Body, optional: true
+    identified_by :finding
+
+    value_object "FindingKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a finding is named") { !value.to_s.empty? }
+    end
+
+    value_object "Title" do
+      attribute :value, String
+
+      invariant("a finding has a title") { !value.to_s.empty? }
+    end
+
+    value_object "Body" do
+      attribute :value, String
+    end
+
+    # What the finding is: a `gap` Hecks cannot yet express, a `parity` divergence between the Ruby
+    # and Rust runtimes, a `qa` finding from the QA loop, or an `idea`.
+    value_object "Kind" do
+      attribute :value, String, one_of: ["gap", "parity", "qa", "idea"]
+    end
+
+    value_object "Severity" do
+      attribute :value, String, one_of: ["low", "medium", "high"]
+    end
+
+    # Where it came from: the QA loop, work for a client, a parity check, or a maintainer by hand.
+    value_object "Source" do
+      attribute :value, String, one_of: ["qa_loop", "client_work", "parity_check", "maintainer"]
+    end
+
+    # The same finding refiled by the QA loop carries the same fingerprint, so a report of it while an
+    # open finding holds it changes nothing.
+    value_object "Fingerprint" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    value_object "Number" do
+      attribute :value, Integer
+
+      invariant("a number is positive") { value.positive? }
+    end
+
+    lifecycle :status, default: "reported" do
+      transition "Triage"  => "triaged",   from: %w[reported triaged]
+      transition "Resolve" => "resolved",  from: "triaged"
+      transition "Dismiss" => "dismissed", from: %w[reported triaged]
+      transition "Reopen"  => "triaged",   from: %w[resolved dismissed]
+    end
+
+    command "Report" do
+      goal "Record something observed about Hecks as a finding"
+
+      attribute :finding,      FindingKey
+      attribute :title,       Title
+      attribute :body,        Body, optional: true
+      attribute :source,      Source
+      attribute :fingerprint, Fingerprint, optional: true
+
+      sets :finding
+      sets :title
+      sets :body
+      sets :source
+      sets :fingerprint
+
+      emits "FindingReported"
+    end
+
+    # A failed Codebase run reports itself: the run's key names the finding and doubles as its
+    # fingerprint, so the same run failing again while its finding is open changes nothing.
+    command "ReportFailedRun" do
+      goal "Record a failed conformance or gate run as a finding"
+
+      attribute :finding, FindingKey
+      attribute :body,   Body
+
+      sets :finding
+      sets :body
+      sets :fingerprint, to: "run"
+      sets :title,  to: "A Codebase run failed"
+      sets :source, to: "qa_loop"
+
+      emits "RunFindingReported"
+    end
+
+    command "Triage" do
+      role "Maintainer"
+      goal "Give a finding its kind and severity"
+
+      reference_to Finding
+      attribute :kind,     Kind
+      attribute :severity, Severity
+
+      sets :kind
+      sets :severity
+
+      emits "FindingTriaged"
+    end
+
+    command "LinkFix" do
+      role "Maintainer"
+      goal "Record the pull request that fixes a triaged finding"
+
+      reference_to Finding
+      attribute :fix_pr_number, Number
+
+      sets :fix_pr_number
+
+      emits "FixLinked"
+    end
+
+    command "Resolve" do
+      role "Maintainer"
+      goal "Close a triaged finding as resolved"
+
+      reference_to Finding
+
+      emits "FindingResolved"
+    end
+
+    command "Dismiss" do
+      role "Maintainer"
+      goal "Close a finding without a fix, with the reason"
+
+      reference_to Finding
+      attribute :dismissal, Body
+
+      sets :dismissal
+
+      emits "FindingDismissed"
+    end
+
+    command "Reopen" do
+      role "Maintainer"
+      goal "Take a resolved or dismissed finding back to triaged, as when a fix regresses"
+
+      reference_to Finding
+
+      emits "FindingReopened"
+    end
+
+    command "RecordIssue" do
+      goal "Record the GitHub issue number once the issue is opened"
+
+      reference_to Finding
+      attribute :issue_number, Number
+
+      sets :issue_number
+
+      emits "IssueRecorded"
+    end
+
+    command "RecordSyncFailure" do
+      goal "Record that GitHub could not be driven, so a later run retries"
+
+      reference_to Finding
+      attribute :sync_failure, Body
+
+      sets :sync_failure
+
+      emits "SyncFailed"
+    end
+
+    query "Open" do
+      description "Every finding not yet resolved or dismissed."
+      where(status: { in: "reported,triaged" })
+      order_by :finding
+    end
+  end
+
+  aggregate "Adr" do
+    description "A decision record: drafted, accepted, and possibly superseded, linked to the tickets it settles."
+
+    attribute :adr,       AdrNumber
+    attribute :title,     AdrTitle
+    attribute :supersedes, AdrNumber, optional: true
+    attribute :settles,   FindingKey, optional: true
+    identified_by :adr
+
+    value_object "AdrNumber" do
+      attribute :value, String, pattern: '\A[0-9]{4}\z'
+    end
+
+    value_object "AdrTitle" do
+      attribute :value, String
+
+      invariant("a decision has a title") { !value.to_s.empty? }
+    end
+
+    value_object "FindingKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    lifecycle :status, default: "draft" do
+      transition "Accept"    => "accepted",   from: "draft"
+      transition "Supersede" => "superseded", from: "accepted"
+    end
+
+    command "Draft" do
+      role "Maintainer"
+      goal "Open a decision record, optionally for the finding it settles"
+
+      attribute :adr,       AdrNumber
+      attribute :title,     AdrTitle
+      attribute :settles,   FindingKey, optional: true
+
+      sets :adr
+      sets :title
+      sets :settles
+
+      emits "AdrDrafted"
+    end
+
+    command "Accept" do
+      role "Maintainer"
+      goal "Record that the decision was accepted"
+
+      reference_to Adr
+
+      emits "AdrAccepted"
+    end
+
+    command "Supersede" do
+      role "Maintainer"
+      goal "Record that a later decision replaces this one"
+
+      reference_to Adr
+      attribute :supersedes, AdrNumber
+
+      sets :supersedes
+
+      emits "AdrSuperseded"
+    end
+
+    query "Standing" do
+      description "Every decision that is accepted and not superseded."
+      where(status: "accepted")
+      order_by :adr
+    end
+  end
+
+  # Each lifecycle event drives GitHub. A finding's own state never waits on the answer.
+  policy "OpenIssueWhenReported" do
+    on      "Finding.FindingReported"
+    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+  end
+
+  policy "OpenIssueWhenRunReported" do
+    on      "Finding.RunFindingReported"
+    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+  end
+
+  policy "LabelIssueWhenTriaged" do
+    on      "Finding.FindingTriaged"
+    trigger Finding::GitHubIssues::LabelIssue, with: { finding: :finding }
+  end
+
+  policy "CommentWhenFixLinked" do
+    on      "Finding.FixLinked"
+    trigger Finding::GitHubIssues::CommentOnIssue, with: { finding: :finding }
+  end
+
+  policy "CloseIssueWhenResolved" do
+    on      "Finding.FindingResolved"
+    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+  end
+
+  policy "CloseIssueWhenDismissed" do
+    on      "Finding.FindingDismissed"
+    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+  end
+
+  policy "ReopenIssueWhenReopened" do
+    on      "Finding.FindingReopened"
+    trigger Finding::GitHubIssues::ReopenIssue, with: { finding: :finding }
+  end
+
+  # A conformance or gate run that faults files its own finding.
+  policy "ReportWhenConformanceFaulted" do
+    on      "ConformanceRun.ConformanceFaulted"
+    trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
+  end
+
+  policy "ReportWhenGateFaulted" do
+    on      "GateRun.GateFaulted"
+    trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
+  end
+
+  policy "RecordTheIssue" do
+    on      "Finding.IssueOpened"
+    trigger Finding::RecordIssue, with: { issue_number: :issue_number }
+  end
+
+  policy "RecordTheSyncFailure" do
+    on      "Finding.GitHubRefused"
+    trigger Finding::RecordSyncFailure, with: { sync_failure: :refusal }
+  end
+end

data/lib/hecks/tickets/bluebook/tickets.hecksagon

@@ -0,0 +1,11 @@
+# The Tickets domain, bound so it boots standing alone (a fuzz or model_check boot of this
+# directory). The GitHubIssues port every attaching hecksagon shares is in tickets.ports.hecksagon.
+Hecks.hecksagon "Tickets" do
+  attaches "Governance"
+  persisted_by "Memory"
+end
+
+# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/tickets/bluebook/tickets.ports.hecksagon

@@ -0,0 +1,26 @@
+# The port Tickets declares, for every hecksagon that attaches the chapter (`Chapters` loads this
+# file with it). Each lifecycle event of a finding asks the GitHubIssues port, which the Hecks domain
+# binds (lib/hecks/hecks/adapters/finding_github.rb): the outside a finding reaches. The ask is
+# answered with the record's own arguments or refused with a reason, and a refusal is recorded on the
+# finding and never blocks it. The port has to be declared even where no adapter binds it, so the
+# policies have a target and model_check's deaf-policy check can see it.
+#
+# Only OpenIssue answers with the issue number, so only its answer is recorded on the finding; the
+# other asks answer with a line saying what was done.
+Hecks.hecksagon "Tickets" do
+  Tickets::Finding.port "GitHubIssues" do
+    asks "OpenIssue", to: Finding do
+      attribute :finding, FindingKey
+      answers "IssueOpened"
+      refuses "GitHubRefused"
+    end
+
+    %w[LabelIssue CommentOnIssue CloseIssue ReopenIssue].each do |ask|
+      asks ask, to: Finding do
+        attribute :finding, FindingKey
+        answers "GitHubAnswered"
+        refuses "GitHubRefused"
+      end
+    end
+  end
+end

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.1.0".freeze
+  VERSION = "3.1.1".freeze
 end

data/lib/hecks.rb

@@ -29,6 +29,7 @@ require_relative "hecks/projector"
 require_relative "hecks/projections"
 # After `Projector`, which dispatches against the `:cli` projection.
 require_relative "hecks/doors/cli_door"
+require_relative "hecks/doors/usage_cache"
 require_relative "hecks/doors/cli_runner"
 require_relative "hecks/storehouse"
 require_relative "hecks/mcp_stdio_guard"

data/rust/codegen/src/json_codec.rs

@@ -44,6 +44,7 @@ pub fn scalar_json_accessor(scalar_type: &str) -> &'static str {
         "String" => "as_str",
         "Integer" => "as_i64",
         "Float" => "as_f64",
+        "TrueClass" | "FalseClass" => "as_bool",
         other => panic!("no JSON accessor for scalar type {other:?}"),
     }
 }
@@ -77,6 +78,7 @@ pub fn scalar_to_json_expr(scalar_type: &str, rust_expr: &str) -> String {
         "String" => format!("crate::kernel::Json::Str({rust_expr}.clone())"),
         "Integer" => format!("crate::kernel::Json::int({rust_expr})"),
         "Float" => format!("crate::kernel::Json::Float({rust_expr})"),
+        "TrueClass" | "FalseClass" => format!("crate::kernel::Json::Bool({rust_expr})"),
         other => panic!("no to_json expr for scalar type {other:?}"),
     }
 }
@@ -565,6 +567,7 @@ pub fn emit_closed_set_table_codec(exemplar: &Exemplar, vo: &Json) -> String {
                 Some("String") => format!("crate::kernel::Json::Str(self.{ident}.to_string())"),
                 Some("Integer") => format!("crate::kernel::Json::int(self.{ident})"),
                 Some("Float") => format!("crate::kernel::Json::Float(self.{ident})"),
+                Some("TrueClass" | "FalseClass") => format!("crate::kernel::Json::Bool(self.{ident})"),
                 _ => String::new(),
             };
             exemplar.render("to_json_field", &[("\"tmpl_field_name\"", naming::ruby_inspect_string(&key)), ("tmpl_json_value_placeholder()", value_expr)])

data/rust/codegen/src/naming.rs

@@ -7,6 +7,7 @@ pub fn scalar_rust_type(type_name: &str) -> Option<&'static str> {
         "String" => Some("String"),
         "Integer" => Some("i64"),
         "Float" => Some("f64"),
+        "TrueClass" | "FalseClass" => Some("bool"),
         _ => None,
     }
 }
@@ -29,6 +30,8 @@ pub fn effective_scalar_type(type_name: &str) -> Option<&'static str> {
         "String" => Some("String"),
         "Integer" => Some("Integer"),
         "Float" => Some("Float"),
+        "TrueClass" => Some("TrueClass"),
+        "FalseClass" => Some("FalseClass"),
         _ => None,
     }
 }
@@ -250,6 +253,7 @@ pub fn scalar_to_value(type_name: &str, rust_expr: &str) -> Option<String> {
         "String" => Some(format!("Value::Str({rust_expr}.clone())")),
         "Integer" => Some(format!("Value::Int({rust_expr})")),
         "Float" => Some(format!("Value::Float({rust_expr})")),
+        "TrueClass" | "FalseClass" => Some(format!("Value::Bool({rust_expr})")),
         _ => None,
     }
 }

data/rust/codegen/src/types.rs

@@ -360,3 +360,48 @@ pub fn emit_projected_field_table(aggregate: &Json) -> String {
         .collect();
     format!("pub static {name}_PROJECTED_FIELDS: &[crate::kernel::ProjectedFieldSpec] = &[\n{}\n];\n", rows.join("\n"))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A value object with one attribute per Ruby spelling of a boolean.
+    fn flag_value_object() -> Json {
+        Json::parse(
+            r#"{
+              "name":"Entry",
+              "attributes":[
+                {"name":"on","type":"TrueClass","list":false,"optional":false,"default":false},
+                {"name":"off","type":"FalseClass","list":false,"optional":false}
+              ]
+            }"#,
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn boolean_attributes_are_rust_bool_not_a_type_named_for_the_ruby_class() {
+        let vo = flag_value_object();
+        let generated = emit_value_object(&Exemplar::load(), &vo, &HashMap::new(), &HashMap::new());
+
+        assert!(generated.contains("pub on: bool,"));
+        assert!(generated.contains("pub off: bool,"));
+        assert!(generated.contains("Value::Bool(self.on)"));
+        assert!(!generated.contains("TrueClass,"));
+        assert!(!generated.contains("FalseClass,"));
+    }
+
+    #[test]
+    fn boolean_attributes_round_trip_through_json_as_bool() {
+        let vo = flag_value_object();
+        let attributes = vo.get("attributes").map(Json::each).unwrap_or(&[]);
+        let by_name = HashMap::new();
+        let exemplar = Exemplar::load();
+        let from_json = crate::json_codec::emit_from_json_flat(&exemplar, "Entry", attributes, &by_name, None, None, false, false, None);
+        let to_json = crate::json_codec::emit_to_json_flat(&exemplar, "Entry", attributes, &by_name, false, &[], None);
+
+        assert!(from_json.contains("x.as_bool()"));
+        assert!(!from_json.contains("TrueClass::from_json"));
+        assert!(to_json.contains("crate::kernel::Json::Bool(self.on)"));
+    }
+}

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.1.0
+3.1.1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -216,10 +216,14 @@ files:
 - lib/hecks/cli/doc_coverage.rb
 - lib/hecks/cli/document.rb
 - lib/hecks/cli/domain_stub.rb
+- lib/hecks/cli/domain_writer.rb
 - lib/hecks/cli/expression_projection.rb
 - lib/hecks/cli/follow.rb
 - lib/hecks/cli/history.rb
+- lib/hecks/cli/interview_agent.rb
 - lib/hecks/cli/interview_draft.rb
+- lib/hecks/cli/interview_run.rb
+- lib/hecks/cli/interview_session.rb
 - lib/hecks/cli/ir.rb
 - lib/hecks/cli/mcp.rb
 - lib/hecks/cli/model_check.rb
@@ -264,6 +268,7 @@ files:
 - lib/hecks/doors/ruby_door.rb
 - lib/hecks/doors/ruby_door/aggregate_door.rb
 - lib/hecks/doors/ruby_door/chapter.rb
+- lib/hecks/doors/usage_cache.rb
 - lib/hecks/embryonaut_bluebook.rb
 - lib/hecks/embryonaut_bluebook/lock.rb
 - lib/hecks/embryonaut_bluebook/shape.rb
@@ -369,6 +374,8 @@ files:
 - lib/hecks/hecks/adapters/console_capture.rb
 - lib/hecks/hecks/adapters/deploy_toolchain.adapter
 - lib/hecks/hecks/adapters/deploy_toolchain.rb
+- lib/hecks/hecks/adapters/finding_github.adapter
+- lib/hecks/hecks/adapters/finding_github.rb
 - lib/hecks/hecks/adapters/git.adapter
 - lib/hecks/hecks/adapters/git.rb
 - lib/hecks/hecks/adapters/host_http.adapter
@@ -533,7 +540,10 @@ files:
 - lib/hecks/projections/deploy/box/templates/deploy-box.sh.tmpl
 - lib/hecks/projections/deploy/box/templates/fetch-secrets.sh
 - lib/hecks/projections/deploy/box/templates/rds.yaml.tmpl
+- lib/hecks/projections/deploy/box/templates/render-compose-taskdef.sh.tmpl
 - lib/hecks/projections/deploy/box/templates/render-compose.sh.tmpl
+- lib/hecks/projections/deploy/box/templates/restore-to-rds.sh.tmpl
+- lib/hecks/projections/deploy/box/templates/verify-copy.sh.tmpl
 - lib/hecks/projections/deploy/fargate.rb
 - lib/hecks/projections/deploy/fargate/assembly.rb
 - lib/hecks/projections/deploy/fargate/cdn.rb
@@ -763,6 +773,9 @@ files:
 - lib/hecks/tenancy/bluebook/tenancy.hecksagon
 - lib/hecks/three_zero.rb
 - lib/hecks/three_zero/forms.yml
+- lib/hecks/tickets/bluebook/tickets.bluebook
+- lib/hecks/tickets/bluebook/tickets.hecksagon
+- lib/hecks/tickets/bluebook/tickets.ports.hecksagon
 - lib/hecks/tools.rb
 - lib/hecks/tools/argument_gate_matrix.rb
 - lib/hecks/tools/ci_gate_decision.rb