hecks 3.0.5 → 3.1.1

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -9,6 +9,12 @@ module Hecks
     # Rewrites a copied domain's persistence bindings before an ephemeral
     # fuzz/replay boot; a directory copy alone does not isolate Postgres state.
     module IsolatedBoot
+      # A vendored package named by `attaches "name", from: :vendor`.
+      VENDORED_ATTACHED = /attaches\s*\(?\s*"([\w-]+)"\s*\)?\s*,\s*from:\s*:vendor/
+
+      # A vendored package named by the deprecated `uses_embryonaut_bluebook "name"`.
+      VENDORED_DEPRECATED = /uses_embryonaut_bluebook\s*\(?\s*"([\w-]+)"/
+
       module_function
 
       # Copies `domain_path` to a tmpdir, rebinds its persistence to `adapter`, and
@@ -67,7 +73,8 @@ module Hecks
       # `Hecks.boot` only sees the domain directory itself, not `vendor/`.
       def carry_vendored_bluebooks!(source, destination)
         names = Dir.glob(File.join(destination, "**", "*.hecksagon")).flat_map do |path|
-          File.read(path).scan(/uses_embryonaut_bluebook\s*\(?\s*"([\w-]+)"/).flatten
+          text = File.read(path)
+          (text.scan(VENDORED_DEPRECATED) + text.scan(VENDORED_ATTACHED)).flatten
         end
         names.uniq.each do |name|
           package = File.join(File.dirname(source), "vendor", "embryonaut_bluebooks", name)
@@ -161,8 +168,8 @@ module Hecks
       # `:postgres_era` is the only mode that exercises era/lineage-bound SQL; plain
       # `:postgres` never touches that machinery. Unlike `:postgres`, there's no shared
       # scratch constant here — `database:`/`schema:` are required keyword args because
-      # the caller (`hecks quality_control ask run --persistence-parity`) owns that database's
-      # lifecycle.
+      # the caller (`hecks quality_control query sweep.run --persistence-parity`) owns that
+      # database's lifecycle.
       def rebind_to_postgres_era!(copy, database:, schema:)
         require "pg"
         if database.to_s.empty? || schema.to_s.empty?

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -11,8 +11,8 @@ module Hecks
 
       # Replays `steps` on both adapters and lists where the results differ.
       #
-      # Compares the same six fields as `hecks quality_control ask run`'s Ruby-vs-Rust mode. Both
-      # results are JSON-round-tripped so plain data compares equal on both sides.
+      # Compares the same six fields as `hecks quality_control query sweep.run`'s Ruby-vs-Rust mode.
+      # Both results are JSON-round-tripped so plain data compares equal on both sides.
       #
       # @param left [Symbol] an `IsolatedBoot` adapter: `:memory`, `:sqlite`, `:postgres`,
       #   `:postgres_era`

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -16,7 +16,7 @@ module Hecks
       POSTGRES_ERA_VARIABLE = /^\s*([a-z_]\w*)\s*=\s*"PostgresEra"\s*(?:#.*)?$/
 
       # Captures the member a hecksagon attaches; authorization is read off its declaration.
-      FRAMEWORK_ATTACHED = /uses_framework\s*\(?\s*"([^"]+)"/
+      FRAMEWORK_ATTACHED = /(?:attaches|uses_framework)\s*\(?\s*"([^"]+)"/
 
       # A command-level `role "..."`, the only construct a role check can compare a caller against.
       ROLE_GATED = /^\s*role\s+"/
@@ -41,8 +41,8 @@ module Hecks
         wasm_front:                 %w[rust]
       }.freeze
 
-      # The modes `hecks quality_control ask run` can run; one absent here is refused at start, not
-      # resolved.
+      # The modes `hecks quality_control query sweep.run` can run; one absent here is refused at
+      # start, not resolved.
       RUNNABLE_MODES = %i[differential ruby_only self_consistency properties_in_differential
                           structural_skip_report adapter_parity_sqlite persistence_parity
                           era_boundary concurrency].freeze

data/lib/hecks/gate/stages.yml

@@ -27,7 +27,7 @@ pre_push:
       blocked: the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which.
     - id: engine_agreement
       title: engine agreement, every declared comparator on both engines
-      run: [bundle, exec, exe/hecks, check_engine_agreement, --wait]
+      run: [bundle, exec, exe/hecks, conformance_run.check_engine_agreement, --wait]
       blocked: a comparator is missing a shared case or a cross-engine spec.
     - id: model_check
       title: model check, unreachable states, dead transitions and orphaned handlers
@@ -35,7 +35,7 @@ pre_push:
       blocked: the model checker found something.
     - id: doc_coverage
       title: docs coverage, words with no running example
-      run: [bundle, exec, exe/hecks, measure_doc_coverage, --wait]
+      run: [bundle, exec, exe/hecks, conformance_run.measure_doc_coverage, --wait]
       blocked: the language ships something undocumented; write the missing sections and examples.
     - id: rubocop
       title: rubocop, the static style and correctness gate
@@ -43,13 +43,13 @@ pre_push:
       blocked: rubocop found an offense.
     - id: codegen_drift
       title: codegen drift, the committed rust/src/generated/ must match a fresh regeneration
-      run: [bundle, exec, exe/hecks, regenerate_corpus, --check, --wait]
+      run: [bundle, exec, exe/hecks, regeneration_run.regenerate_corpus, --check, --wait]
       blocked: regenerating hits a diff, so the committed Rust is stale; run `hecks regenerate_corpus --confirm` and commit the result.
     - id: comment_style
       title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
-      run: [bundle, exec, exe/hecks, check_comments, paths=lib/hecks, --wait]
+      run: [bundle, exec, exe/hecks, style_run.check_comments, paths=lib/hecks, --wait]
       blocked: a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check.
     - id: comment_blocks
       title: comment blocks, no run of comment lines past ADR 0075's cap
-      run: [bundle, exec, exe/hecks, check_comments, "paths=lib,spec,examples", only=long_block, --wait]
+      run: [bundle, exec, exe/hecks, style_run.check_comments, "paths=lib,spec,examples", only=long_block, --wait]
       blocked: a comment block ran past the cap; shorten it.

data/lib/hecks/grammar/grammar.hecksagon

@@ -4,13 +4,13 @@
 Hecks.hecksagon "Expression" do
   # Every command here declares `role "Language designer"` — only real
   # access control once Governance can check it against something (S8).
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end
 
 Hecks.hecksagon "Translation" do
   # Same reason as Expression, above — S8.
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end
 

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -18,7 +18,7 @@ module Hecks
       # The `Hecks::Tools` tool an ask runs, by ask.
       SCRIPTS = { generate: "project_deploy", lint: "lint_deploy_recipes", manifest: "project_oidc" }.freeze
 
-      # `hecks deploy project`'s flag for each `Recipe` field it takes.
+      # `hecks deploy recipe.project`'s flag for each `Recipe` field it takes.
       GENERATE_FLAGS = { "--tenant" => :tenant, "--schema" => :schema, "--out" => :out,
                          "--environment" => :environment }.freeze
 
@@ -30,7 +30,7 @@ module Hecks
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
       # Writes a domain's deploy recipe (the template, scripts and Makefile) from its declared
-      # `deployed_to` target, through `hecks deploy project`.
+      # `deployed_to` target, through `hecks deploy recipe.project`.
       #
       # @param held [Hash] the `Recipe` record: `domain`, and `tenant`, `schema`, `out` and
       #   `environment` when set
@@ -43,7 +43,7 @@ module Hecks
       end
 
       # Lints generated deploy Makefiles for prod-touching recipes that hide failure, through
-      # `hecks deploy lint`.
+      # `hecks deploy makefile_check.lint`.
       #
       # @param held [Hash] the `MakefileCheck` record: `makefiles` (comma separated paths; three
       #   generated fixture domains when absent)
@@ -56,7 +56,7 @@ module Hecks
       end
 
       # Projects each domain's OIDC client and scope manifest into its `oidc.json`, through
-      # `hecks deploy project_oidc`.
+      # `hecks deploy oidc_manifest.project_oidc`.
       #
       # @param held [Hash] the `OidcManifest` record: `domains` (comma separated directories; every
       #   domain of the checkout when absent)

data/lib/hecks/hecks/adapters/finding_github.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/finding_github"
+
+Hecks.adapter "FindingGithub" do
+  port "GitHubIssues"
+end

data/lib/hecks/hecks/adapters/finding_github.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Adapters
+    # The `GitHubIssues` port's adapter: drives one GitHub issue from a `Tickets::Finding` with
+    # `gh`.
+    #
+    # Nothing is opened until a repository is named, by the `repository` setting or the
+    # `HECKS_FINDINGS_REPO` environment variable (`owner/name`); without one every ask is refused,
+    # and the runtime records the refusal on the finding. An ask that needs the issue before one
+    # was opened is refused the same way, so a finding never blocks on GitHub.
+    class FindingGithub
+      # The environment variable that names the repository when no setting does.
+      REPOSITORY_VARIABLE = "HECKS_FINDINGS_REPO"
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `repository:` names the `owner/name` to drive
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @repository = settings[:repository]
+      end
+
+      # Opens an issue for the finding the runtime hands over (its whole held state).
+      #
+      # @param held [Hash] the finding's fields; `title` and `body` are value objects or strings
+      # @return [Hash{Symbol => Hash}] `issue_number:` of the new issue, the shape
+      #   `Finding.RecordIssue` takes
+      # @raise [RuntimeError] when no repository is named, `gh` exits non-zero, or prints no
+      #   issue URL
+      def open_issue(**held)
+        out = gh("issue", "create", "--title", plain(held[:title]).to_s, "--body", plain(held[:body]).to_s)
+        number = out.lines.last.to_s.strip[%r{/issues/(\d+)\z}, 1]
+        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+
+        { issue_number: { value: number.to_i } }
+      end
+
+      # Puts the finding's kind and severity on its issue as labels.
+      #
+      # @param held [Hash] the finding's fields
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def label_issue(**held)
+        labels = [["kind", held[:kind]], ["severity", held[:severity]]]
+                 .map { |name, field| "#{name}:#{plain(field)}" unless plain(field).to_s.empty? }.compact
+        return said("no kind or severity to label") if labels.empty?
+
+        gh("issue", "edit", issue(held), "--add-label", labels.join(","))
+        said("labelled #{labels.join(', ')}")
+      end
+
+      # Comments on the issue with the pull request that fixes the finding.
+      #
+      # @param held [Hash] the finding's fields
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def comment_on_issue(**held)
+        gh("issue", "comment", issue(held), "--body", "A fix is proposed in ##{plain(held[:fix_pr_number])}")
+        said("commented with the fix")
+      end
+
+      # Closes the issue: as completed for a resolved finding, as not planned for a dismissed one.
+      #
+      # @param held [Hash] the finding's fields, `status` among them
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def close_issue(**held)
+        reason = plain(held[:status]) == "dismissed" ? "not planned" : "completed"
+        gh("issue", "close", issue(held), "--reason", reason)
+        said("closed as #{reason}")
+      end
+
+      # Reopens the issue of a finding taken back to triaged.
+      #
+      # @param held [Hash] the finding's fields
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def reopen_issue(**held)
+        gh("issue", "reopen", issue(held))
+        said("reopened")
+      end
+
+      private
+
+      def gh(*arguments)
+        out, err, status = Open3.capture3("gh", *arguments, "--repo", repository)
+        raise "gh #{arguments.first(2).join(' ')} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        out
+      end
+
+      def repository
+        name = @repository || ENV.fetch(REPOSITORY_VARIABLE, nil)
+        return name unless name.to_s.strip.empty?
+
+        raise "no repository named: set the `repository` setting or #{REPOSITORY_VARIABLE} to owner/name"
+      end
+
+      def issue(held)
+        number = plain(held[:issue_number])
+        raise "the finding has no GitHub issue yet" if number.to_s.empty?
+
+        number.to_s
+      end
+
+      def said(line) = { output: { value: line } }
+
+      # A materialized value object (`{value: x}`, symbol or string keys) or the value itself.
+      def plain(field)
+        return field unless field.is_a?(Hash)
+
+        field.key?(:value) ? field[:value] : field["value"]
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/host_http.rb

@@ -42,16 +42,17 @@ module Hecks
       # allow-list file. A mismatch is an answer, not a refusal: the record keeps what was found.
       #
       # @param held [Hash] the `Host` record: `host` (the base URL), `expected` (the allow-list
-      #   file) and `timeout` (seconds; 10 when absent)
+      #   file) and `timeout` (seconds; the command's declared default fills it when none is named)
       # @return [Hash{Symbol => Hash}] `era:`, `version:`, `verdict:` (`match`, `unlisted` or
       #   `mismatch`) and `report:` (the sentence `hecks check_era` prints)
-      # @raise [ArgumentError] if no allow-list file was named
+      # @raise [ArgumentError] if no allow-list file or timeout was given
       # @raise [Errno::ENOENT] if the allow-list file cannot be read
       # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
       # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
       def fetch(**held)
         file = plain(held[:expected]) or raise ArgumentError, "no allow-list file to compare the era with"
-        finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: (plain(held[:timeout]) || 10).to_f)
+        timeout = plain(held[:timeout]) or raise ArgumentError, "no timeout to wait for the host with"
+        finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: timeout.to_f)
 
         { era: { value: finding.verdict.era }, version: { value: finding.version },
           verdict: { value: finding.verdict.status.to_s }, report: { value: finding.line } }

data/lib/hecks/hecks/adapters/local_files.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require_relative "console_capture"
 require "hecks/cli/project_cli"
+require "hecks/cli/domain_stub"
 
 module Hecks
   module Adapters
@@ -38,9 +40,66 @@ module Hecks
         { output: { value: text } }
       end
 
+      # Writes the stub files of a new domain (ADR 0087) into the named directory, or into the
+      # snake-cased name under the current one, and prints what it wrote and what to type next.
+      # Nothing is replaced: every file is checked before the first is written, and a directory
+      # that already holds a bluebook is refused.
+      #
+      # @param held [Hash] the `Door` record: `name`, and optionally `adapter` and `dir`
+      # @return [Hash{Symbol => Hash}] `output:` the report that was printed
+      # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file exists
+      def scaffold(**held)
+        name   = plain(held[:name])
+        files  = stub_files(name, plain(held[:adapter]))
+        target = File.expand_path(plain(held[:dir]) || CLI::DomainStub.directory(name), Dir.pwd)
+        refuse_existing!(target, files.keys)
+        warn "warning: #{target} is inside the hecks clone; keep a service you deploy outside it." if inside_clone?(target)
+
+        files.each do |path, text|
+          full = File.join(target, path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.write(full, text)
+        end
+        report = scaffold_report(target, files.keys, plain(held[:adapter]))
+        puts report
+        { output: { value: report } }
+      end
+
       private
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def stub_files(name, adapter)
+        CLI::DomainStub.files(name: name, adapter: adapter)
+      rescue ArgumentError => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      def refuse_existing!(target, paths)
+        taken = paths.map { |path| File.join(target, path) }.select { |full| File.exist?(full) }
+        taken |= Dir.glob(File.join(target, "bluebook", "*.bluebook"))
+        return if taken.empty?
+
+        raise ConsoleCapture::Failure,
+              "nothing written; already there: #{taken.map { |full| shown(full) }.join(', ')}"
+      end
+
+      def inside_clone?(target)
+        root = File.expand_path("../../../..", __dir__)
+        File.directory?(File.join(root, ".git")) && target.start_with?("#{root}/")
+      end
+
+      def shown(full) = full.delete_prefix("#{Dir.pwd}/")
+
+      def scaffold_report(target, paths, adapter)
+        where = shown(target)
+        lines = ["wrote #{paths.length} files in #{where}/:"] + paths.sort.map { |path| "  #{path}" }
+        lines << "" << "next:" << "  hecks docs #{where}/bluebook" << "  hecks console subject=#{where}"
+        unless %w[Postgres PostgresEra].include?(adapter)
+          lines << "" << "a Lambda deployment needs Postgres: run again with --adapter=Postgres."
+        end
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/hecks/hecks/adapters/site_toolchain.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/site_toolchain"
+
+Hecks.adapter "SiteToolchain" do
+  port "SiteToolchain"
+end

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "codebase/tree"
+require_relative "codebase/ruby_child"
+
+module Hecks
+  module Adapters
+    # The `SiteToolchain` port's adapter: projects a site's route table into its `routes.ts`, or
+    # checks the file on disk is current.
+    #
+    # The projection runs the `project_site` tool in a child of the checkout, with its printing and
+    # exit status captured: a tool that ends non-zero is a refusal whose reason is what it printed.
+    # Outside a hecks checkout the ask is refused with "needs a hecks checkout".
+    class SiteToolchain
+      # The `Hecks::Tools` tool the ask runs, by ask.
+      SCRIPTS = { project: "project_site" }.freeze
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
+      #
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out` and `check` when set
+      # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
+      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, the route table is
+      #   refused (an unknown cache class, a duplicate path), or under `check` a file is out of date
+      def project(**held)
+        flags = []
+        flags << "--out=#{plain(held[:out])}" unless plain(held[:out]).nil?
+        flags << "--check" if plain(held[:check]) == true
+        tree = Codebase::Tree.new
+        tree.require_checkout!
+        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(:project), *flags, plain(held[:domain]))
+        raise ConsoleCapture::Failure, message_of(result) unless result.ok?
+
+        { output: { value: result.out } }
+      end
+
+      private
+
+      def message_of(result)
+        text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
+        text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/terminal.rb

@@ -66,6 +66,21 @@ module Hecks
         raise ConsoleCapture::Failure, "the mcp door refused to start (status #{e.status}); see stderr"
       end
 
+      # Holds an interview at the terminal and writes the domain it drafts (ADR 0088). Asking is IO,
+      # so it happens here and nowhere else; the journal records that one was held, not its words.
+      #
+      # @param held [Hash] the `Door` record: `name`; optionally `adapter`, `dir`, `expert`, `no_ai`
+      # @return [Hash{Symbol => Hash}] `output:` what the interview wrote, or that it wrote nothing
+      # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file is there
+      def converse(**held)
+        require "hecks/cli/interview_run"
+        report = CLI::InterviewRun.call(name: plain(held[:name]), adapter: plain(held[:adapter]), dir: plain(held[:dir]),
+                                        expert: plain(held[:expert]), use_ai: !plain(held[:no_ai]))
+        { output: { value: report.empty? ? "no interview was written" : report } }
+      rescue ArgumentError => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
       private
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument

data/lib/hecks/hecks/codebase.bluebook

@@ -1864,7 +1864,7 @@ Hecks.bluebook "Hecks" do
       role "Maintainer"
       goal "Regenerate the committed runtime baselines the sharded jobs group from"
 
-      attribute :workers,  Count, optional: true
+      attribute :workers,  Count, default: 6
       attribute :from_run, RunId, optional: true
       attribute :run,      RunKey
       attribute :confirm,  Switch, optional: true
@@ -1898,9 +1898,10 @@ Hecks.bluebook "Hecks" do
       role "Maintainer"
       goal "Rerun the thread-safety specs under many seeds, several processes at a time"
 
-      attribute :runs,       Count, optional: true
+      attribute :runs,       Count, default: 30
+      # The machine's own core count when none is named, which no fixed default can say.
       attribute :parallel,   Count, optional: true
-      attribute :seed_start, Count, optional: true
+      attribute :seed_start, Count, default: 1
       attribute :run,        RunKey
 
       sets :runs

data/lib/hecks/hecks/context_map.hecksagon

@@ -8,6 +8,6 @@ end
 
 # The attached chapters (hecks.hecksagon `attaches`): each is a bounded context whose store comes
 # from hecks.world's `default_adapter`, so the memory overlay swaps them with the Hecks chapter.
-%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy QualityControl].each do |chapter|
-  Hecks.hecksagon(chapter) { uses_framework "Governance" }
+%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets QualityControl].each do |chapter|
+  Hecks.hecksagon(chapter) { attaches "Governance" }
 end

data/lib/hecks/hecks/custodian.bluebook

@@ -564,7 +564,7 @@ Hecks.bluebook "Hecks" do
       transition "Lose"    => "unreachable", from: "requested"
     end
 
-# `hecks check_era <url> expected=era-file [timeout=10]` records the first check of a host under
+# `hecks check_era <url> expected=era-file [timeout=]` records the first check of a host under
 # its URL. A host is one record, and a creating command cannot repeat an identity, so a later
 # check of the same host is `hecks recheck <url> expected=era-file`. Both are read with
 # `hecks standing <url>`.
@@ -574,7 +574,7 @@ command "CheckEra" do
 
       attribute :host,     Address
       attribute :expected, ExpectedFile
-      attribute :timeout,  Seconds, optional: true
+      attribute :timeout,  Seconds, default: 10
 
       sets :host
       sets :expected
@@ -589,7 +589,7 @@ command "Recheck" do
 
   reference_to Host
   attribute :expected, ExpectedFile
-  attribute :timeout,  Seconds, optional: true
+  attribute :timeout,  Seconds, default: 10
 
   sets :expected
   sets :timeout
@@ -1277,6 +1277,11 @@ policy "RecordTheEra" do
     attribute :run,     DoorKey
     attribute :domains, DomainList, optional: true
     attribute :stdio,   Switch,     optional: true
+    attribute :name,    DomainName, optional: true
+    attribute :adapter, AdapterName, optional: true
+    attribute :dir,     TargetDir,  optional: true
+    attribute :expert,  ExpertName, optional: true
+    attribute :no_ai,   Switch,     optional: true
     attribute :output,  Note,       optional: true
     attribute :refusal, Note,       optional: true
     identified_by :run
@@ -1296,6 +1301,26 @@ policy "RecordTheEra" do
       attribute :value, Boolean
     end
 
+    # What a new domain is called, as its bluebook spells it: a capital and then letters and digits.
+    value_object "DomainName" do
+      attribute :value, String, pattern: '[A-Z][A-Za-z0-9]*'
+    end
+
+    # A persistence adapter a stub can be bound to; `Hecks::CLI::DomainStub` names the ones it knows.
+    value_object "AdapterName" do
+      attribute :value, String, pattern: '[A-Za-z]+'
+    end
+
+    # Where the new domain goes; the domain's snake-cased name under the current directory when absent.
+    value_object "TargetDir" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Who is interviewed; asked for at the terminal when absent.
+    value_object "ExpertName" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
     value_object "Note" do
       attribute :value, String
     end
@@ -1320,6 +1345,49 @@ policy "RecordTheEra" do
       emits LaunchersRequested
     end
 
+    # Writes the stub files of a new domain (ADR 0087). It asks nothing and replaces nothing: a
+    # directory that already holds any file it would write is refused, with that file named.
+    command "Init" do
+      role "Operator"
+      goal "Write the stub files of a new domain"
+
+      attribute :run,     DoorKey
+      attribute :name,    DomainName
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,   optional: true
+
+      sets :run
+      sets :name
+      sets :adapter
+      sets :dir
+
+      emits StubRequested
+    end
+
+    # Holds an interview with a subject matter expert and drafts a first domain from it (ADR 0088).
+    # The Terminal adapter runs the conversation, as it runs a console; the journal records that one
+    # was held and how it ended, not what was said. `--no-ai` leaves the model out.
+    command "Interview" do
+      role "Operator"
+      goal "Hold an interview with a subject matter expert and draft a first domain from it"
+
+      attribute :run,     DoorKey
+      attribute :name,    DomainName
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,   optional: true
+      attribute :expert,  ExpertName,  optional: true
+      attribute :no_ai,   Switch,      optional: true
+
+      sets :run
+      sets :name
+      sets :adapter
+      sets :dir
+      sets :expert
+      sets :no_ai
+
+      emits InterviewRequested
+    end
+
     # A stdio server runs until its client closes stdin, so it cannot be asked and answered
     # quickly like the others. The command records that the door was started; the Terminal
     # adapter hands the process over to the door and answers when it closes, as OpenConsole
@@ -1381,6 +1449,16 @@ policy "RecordTheEra" do
     trigger Door::Workspace::Write, with: { run: :run }
   end
 
+  policy "ScaffoldWhenRequested" do
+    on      "Door.StubRequested"
+    trigger Door::Workspace::Scaffold, with: { run: :run }
+  end
+
+  policy "ConverseWhenRequested" do
+    on      "Door.InterviewRequested"
+    trigger Door::Terminal::Converse, with: { run: :run }
+  end
+
   policy "ServeWhenRequested" do
     on      "Door.McpRequested"
     trigger Door::Terminal::Serve, with: { run: :run }

data/lib/hecks/hecks/hecks.bluebook

@@ -8,9 +8,15 @@ Hecks.bluebook "Hecks" do
     attribute :version,    Version
     attribute :ir_version, Version
     attribute :ships_from, Checkout, optional: true
+    # The findings the version settled, by the key the Tickets chapter gives them.
+    attribute :closes,     list_of(FindingKey), optional: true
 
     identified_by :version
 
+    value_object "FindingKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
     value_object "Version" do
       attribute :value, String, pattern: '^[0-9]+[.][0-9]+[.][0-9]+'
 
@@ -61,6 +67,18 @@ Hecks.bluebook "Hecks" do
       emits Verified
     end
 
+    command "CloseFindings" do
+      role "Maintainer"
+      goal "Record the findings this version settled"
+
+      reference_to Release
+      attribute :closes, list_of(FindingKey)
+
+      sets :closes
+
+      emits FindingsClosed
+    end
+
     query "Shipped" do
       description "Every version that was tagged, published and verified."
       where(state: "verified")