@zalom/plastic 2.0.0-alpha.9 → 2.0.1

package/scripts/lib/cli/scope.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "../store_layout"
+require_relative "../index_entry"
+require_relative "../store_discovery"
+
+# Plastic::CLI::Scope (intent 363) - which store a command works on. Six skills
+# used to restate this rule in prose; it is stated here once.
+#
+# A named project wins. With no name, the project whose repository holds the
+# working directory wins, longest path first, so a repository nested inside
+# another resolves to the inner one. With neither, the global store answers.
+#
+# Every path comes from the injected environment and home directory, so a test
+# points at a temporary store and never at the real ~/.plastic.
+module Plastic
+  class CLI
+    class Scope
+      UnknownProject = Class.new(StandardError)
+
+      GLOBAL = "global"
+
+      def initialize(env:, home:, slug: nil, directory: Dir.pwd)
+        @env = env
+        @home = home
+        @requested = slug
+        @directory = canonical_path(File.expand_path(directory))
+      end
+
+      def plastic_home
+        @plastic_home ||= @env["PLASTIC_HOME"] || File.join(@home, ".plastic")
+      end
+
+      def stores
+        @stores ||= StoreDiscovery.discover(plastic_home)[:stores]
+      end
+
+      def slug
+        @slug ||= resolve_slug
+      end
+
+      def root
+        @root ||= found&.fetch(:root) || plastic_home
+      end
+
+      def store
+        File.join(root, "store")
+      end
+
+      def index_path
+        File.join(root, "INDEX.md")
+      end
+
+      def roadmaps_dir
+        File.join(root, "roadmaps")
+      end
+
+      def active_entries
+        return [] unless File.exist?(index_path)
+
+        section(File.read(index_path)).filter_map do |line|
+          match = IndexEntry.match(line)
+          match && [match[1], match[2]]
+        end
+      end
+
+      def active_ids
+        active_entries.map(&:first)
+      end
+
+      def intent_dir(id)
+        Dir.glob(File.join(store, "#{id}--*")).min
+      end
+
+      def directory_project
+        @directory_project = project_for_directory unless defined?(@directory_project)
+        @directory_project
+      end
+
+      def known_slugs
+        stores.map { |store| store[:slug] }.sort
+      end
+
+      private
+
+      def found
+        stores.find { |store| store[:slug] == slug }
+      end
+
+      def resolve_slug
+        return requested_slug if @requested
+
+        directory_project || GLOBAL
+      end
+
+      def requested_slug
+        return @requested if known_slugs.include?(@requested)
+
+        raise UnknownProject,
+          "no project named #{@requested.inspect}; this machine has #{known_slugs.join(", ")}"
+      end
+
+      def project_for_directory
+        (repositories + stores.map { |store| [store[:slug], store[:root]] })
+          .select { |_slug, path| inside?(path) }
+          .max_by { |_slug, path| path.length }
+          &.first
+      end
+
+      def inside?(path)
+        path = canonical_path(File.expand_path(path))
+        @directory == path || @directory.start_with?("#{path}#{File::SEPARATOR}")
+      end
+
+      def canonical_path(path)
+        return File.realpath(path) if File.exist?(path)
+
+        File.join(canonical_path(File.dirname(path)), File.basename(path))
+      end
+
+      def repositories
+        StoreProvisioning.load_projects(plastic_home).filter_map do |slug, info|
+          path = info.is_a?(Hash) ? info["path"].to_s : ""
+          [slug, path] unless path.empty?
+        end
+      end
+
+      def section(text)
+        body = text.match(/^##\s+Active\s*$(.*?)(?=^##\s|\z)/m)
+        body ? body[1].lines.map(&:strip) : []
+      end
+    end
+  end
+end

package/scripts/lib/cli/table.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Plastic::CLI::TABLE (intent 363) - the whole command line in one frozen hash:
+# a command name mapped to the file that holds it, the class inside
+# Plastic::CLI::Commands, and the one line `plastic help` prints beside it.
+#
+# Adding a command is one row here plus one file. `plastic help` reads this
+# hash and loads nothing, so listing the commands costs no command file.
+# test/cli/table_test.rb walks every row, so a half-wired command cannot ship.
+module Plastic
+  class CLI
+    TABLE = {
+      "auto brief" => ["commands/auto_brief", "AutoBrief", "Print an intent's spawn preamble, and the advisor shapes for --role advisor"],
+      "auto lock" => ["commands/auto_lock", "AutoLock", "Inspect, repair, or release an intent's delivery lock"],
+      "auto report" => ["commands/auto_report", "AutoReport", "Print an intent's completion report, then the review-by-risk rules"],
+      "auto take" => ["commands/auto_take", "AutoTake", "Arm an intent's delivery lock for this session"],
+      "auto" => ["commands/auto", "Auto", "List the auto subcommands"],
+      "backup" => ["commands/backup", "Backup", "Write one archive of the three databases and the config"],
+      "checkout" => ["commands/checkout", "Checkout", "Restore missing store files from the databases"],
+      "continue" => ["commands/continue", "Continue", "Show where one project stands and what runs next"],
+      "doctor" => ["commands/doctor", "Doctor", "Diagnose Plastic installation health"],
+      "feedback" => ["commands/feedback", "Feedback", "File a feedback report, body on standard input"],
+      "help" => ["commands/help", "Help", "List the commands and help topics, or show one usage"],
+      "hook" => ["commands/hook", "Hook", "Run one harness hook event through its launcher"],
+      "index" => ["commands/index", "Index", "Rebuild the search index from every markdown file in the stores"],
+      "install" => ["commands/install", "Install", "Install Plastic into this machine's agents"],
+      "intent" => ["commands/intent", "Intent", "List the intent subcommands"],
+      "intent answer" => ["commands/intent_answer", "IntentAnswer", "Answer an intent's needs_decision node"],
+      "intent end" => ["commands/intent_end", "IntentEnd", "Close an intent as delivered or abandoned"],
+      "intent new" => ["commands/intent_new", "IntentNew", "Create a new intent"],
+      "intent note" => ["commands/intent_note", "IntentNote", "Append a savepoint note to an intent"],
+      "intent rule" => ["commands/intent_rule", "IntentRule", "Record a ruling in an intent's Insights"],
+      "intent show" => ["commands/intent_show", "IntentShow", "Print an intent's state screen"],
+      "intent spec" => ["commands/intent_spec", "IntentSpec", "Print an intent's state screen, then the speccing rules"],
+      "intent step" => ["commands/intent_step", "IntentStep", "Run the next ready step of an intent's graph"],
+      "intent verify" => ["commands/intent_verify", "IntentVerify", "Run an intent's merge-gate checks"],
+      "migrate" => ["commands/migrate", "Migrate", "List the migrate subcommands"],
+      "migrate stores" => ["commands/migrate_stores", "MigrateStores", "Move the stores under stores/, behind a full copy of the home"],
+      "next" => ["commands/next", "Next", "Print the next action in one line"],
+      "project" => ["commands/project", "Project", "List the project subcommands"],
+      "project links" => ["commands/project_links", "ProjectLinks", "Project every store's Links sections from frontmatter"],
+      "project list" => ["commands/project_list", "ProjectList", "List every store this machine holds"],
+      "project new" => ["commands/project_new", "ProjectNew", "Register, provision and validate a new project"],
+      "query" => ["commands/query", "Query", "Run one read-only SQL statement on the index"],
+      "render" => ["commands/render", "Render", "Print one markdown file as an HTML page"],
+      "roadmap" => ["commands/roadmap", "Roadmap", "List the roadmap subcommands"],
+      "roadmap check" => ["commands/roadmap_check", "RoadmapCheck", "Check a roadmap's graph for cycles and dangling ids"],
+      "roadmap log" => ["commands/roadmap_log", "RoadmapLog", "Append a savepoint line to a roadmap's ledger"],
+      "roadmap migrate" => ["commands/roadmap_migrate", "RoadmapMigrate", "Write a roadmap's Graph section from its batches"],
+      "roadmap next" => ["commands/roadmap_next", "RoadmapNext", "Name the roadmap most worth continuing"],
+      "roadmap show" => ["commands/roadmap_show", "RoadmapShow", "Print a roadmap's state screen"],
+      "rollback" => ["commands/rollback", "Rollback", "Move to a Plastic version this machine has run before"],
+      "search" => ["commands/search", "Search", "Find text in the stores, ranked, with one excerpt each"],
+      "session commit" => ["commands/session_commit", "SessionCommit", "Commit one verified checklist item"],
+      "session handoff" => ["commands/session_handoff", "SessionHandoff", "Write this session's hand-off into the day ledger"],
+      "session summary" => ["commands/session_summary", "SessionSummary", "Print the day ledger's open items and recent activity"],
+      "session" => ["commands/session", "Session", "List the session subcommands"],
+      "status" => ["commands/status", "Status", "Show active work in every store"],
+      "sync" => ["commands/sync", "Sync", "Bring the store files and the three databases level"],
+      "uninstall" => ["commands/uninstall", "Uninstall", "Remove Plastic from this machine's agents"],
+      "update" => ["commands/update", "Update", "Move Plastic to the next version on its channel"],
+      "version" => ["commands/version", "Version", "Print the installed Plastic version"]
+    }.freeze
+  end
+end

package/scripts/lib/cli.rb

@@ -0,0 +1,94 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "did_you_mean"
+require_relative "cli/table"
+require_relative "cli/command"
+require_relative "cli/output"
+
+# Plastic::CLI (intent 363) - the dispatcher behind bin/plastic. It reads the
+# command table, matches the longest command name the arguments begin with,
+# requires that one file, and calls it. Nothing else is loaded, which is what
+# keeps a call at about 20 milliseconds with RubyGems off.
+#
+# No arguments, or --help, print the command list. --version prints the
+# version. A command's own --help prints that command's usage line, read from
+# the class without building it. An unknown name exits 2 and names the closest
+# command, so a typo never becomes a stack trace.
+module Plastic
+  class CLI
+    FLAGS = {"--version" => "version", "-v" => "version",
+             "--help" => "help", "-h" => "help"}.freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, env: ENV, home: Dir.home,
+      directory: Dir.pwd, table: TABLE)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @env = env
+      @home = home
+      @directory = directory
+      @table = table
+    end
+
+    def call
+      matched = match(expanded)
+      return unknown(expanded.first) unless matched
+
+      name, rest = matched
+      return usage(name, rest) if help?(rest)
+
+      command(name).call(rest, out: @out, err: @err, env: @env, home: @home,
+        directory: @directory)
+    end
+
+    def match(argv)
+      [2, 1].each do |width|
+        name = argv.first(width).join(" ")
+        return [name, argv.drop(width)] if @table.key?(name)
+      end
+      nil
+    end
+
+    private
+
+    def expanded
+      return ["help"] if @argv.empty?
+
+      [FLAGS.fetch(@argv.first, @argv.first)] + @argv.drop(1)
+    end
+
+    def help?(rest)
+      rest.any? { |argument| FLAGS[argument] == "help" }
+    end
+
+    def usage(name, rest)
+      Output.new(out: @out, err: @err)
+        .row("usage", command(name)::USAGE_LINE)
+        .flush(json: rest.include?("--json"))
+      Command::OK
+    end
+
+    def command(name)
+      file, const, = @table.fetch(name)
+      require_relative "cli/#{file}"
+      Commands.const_get(const)
+    end
+
+    def unknown(name)
+      suggestions = closest(name)
+      @err.puts "plastic: no command named #{name.inspect}"
+      @err.puts "Closest: #{suggestions.join(", ")}" unless suggestions.empty?
+      @err.puts "Run `plastic help` for the command list."
+      Command::USAGE
+    end
+
+    def closest(name)
+      DidYouMean::SpellChecker.new(dictionary: @table.keys).correct(name)
+    end
+  end
+end

package/scripts/lib/codex_adapter.rb

@@ -0,0 +1,198 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "timeout"
+require "tmpdir"
+require_relative "runner_policy"
+
+# CodexAdapter (intent 340b, G7c, n6): the argv `codex exec` needs for one
+# node's kind, and the mechanics of running it once - a bounded subprocess
+# whose stdin carries the node input, whose stdout and `--output-last-message`
+# file are the only two places a return can come from, and whose timeout
+# kills the whole process group rather than one pid.
+#
+# Pure where it can be: sandbox_mode, git_dir_for_worktree, add_dir_args and
+# build_argv touch nothing but the filesystem read they are explicitly given
+# (the worktree's own `.git` file), never a git call and never a guess at a
+# repository root. #execute is the one place this module actually spawns a
+# child process; scripts/node-run is the only caller.
+module CodexAdapter
+  module_function
+
+  # Verify and research get NO write access at all (spec D9): read-only, no
+  # `--add-dir`. Everything else - work, and any kind this table has never
+  # heard of - gets the widest treatment, matching RunnerPolicy's own
+  # unknown-kind-falls-back-to-work rule (matrix row 6.10).
+  READ_ONLY_KINDS = %w[verify research].freeze
+
+  def sandbox_mode(kind)
+    READ_ONLY_KINDS.include?(kind.to_s) ? "read-only" : "workspace-write"
+  end
+
+  # The repository's OWN `.git` directory, derived from `worktree`'s `.git`
+  # FILE (a git worktree never carries a real `.git` directory of its own -
+  # spec) rather than any guess at how many path segments separate a
+  # worktree from its repo (matrix row 6.6). `.git` reads
+  # `gitdir: <repo>/.git/worktrees/<name>`; two directories up from that
+  # target is the repository's real `.git`. Returns nil when `worktree` is
+  # not a git worktree at all (no `.git` file, or `.git` is a directory,
+  # meaning `worktree` is a repository's own primary checkout) - callers
+  # treat that as "no `--add-dir` to add", never as a reason to guess.
+  def git_dir_for_worktree(worktree)
+    gitfile = File.join(worktree.to_s, ".git")
+    return nil unless File.file?(gitfile)
+
+    content = File.read(gitfile)
+    m = content.match(/\Agitdir:\s*(.+?)\s*\z/m)
+    return nil unless m
+
+    worktrees_entry = File.expand_path(m[1], worktree.to_s)
+    File.dirname(File.dirname(worktrees_entry))
+  end
+
+  # [] for a read-only kind (matrix row 6.4): `-C` already makes the
+  # worktree writable, and `--add-dir` on top of `--sandbox read-only` would
+  # contradict the sandbox mode itself. Exactly one `--add-dir`, the
+  # repository's own `.git`, for every other kind (matrix row 6.5) - nil
+  # when the worktree's own gitdir pointer cannot be resolved, so a caller
+  # handed a plain (non-worktree) directory never gets a bogus argument.
+  def add_dir_args(kind:, worktree:)
+    return [] if READ_ONLY_KINDS.include?(kind.to_s)
+
+    git_dir = git_dir_for_worktree(worktree)
+    git_dir ? ["--add-dir", git_dir] : []
+  end
+
+  # The whole `codex exec` argv for one node (matrix rows 6.1-6.9): `-C` at
+  # the worktree given (row 6.8), the sandbox mode and `--add-dir` this
+  # kind's row calls for and nothing else (row 6.7 - never the intent
+  # worktree, never `~/.plastic`), `--output-last-message` at the path the
+  # caller names, and a bare `-` so the prompt is read from stdin (row 6.9) -
+  # the node input itself never rides in this array.
+  def build_argv(kind:, worktree:, output_last_message:, model: nil, effort: nil)
+    argv = [
+      "codex", "exec",
+      "-C", worktree.to_s,
+      "--sandbox", sandbox_mode(kind),
+      *add_dir_args(kind: kind, worktree: worktree),
+    ]
+    argv += ["--model", model.to_s] unless model.to_s.strip.empty?
+    argv += ["--config", %(model_reasoning_effort="#{effort}")] unless effort.to_s.strip.empty?
+    argv + ["--output-last-message", output_last_message.to_s, "-"]
+  end
+
+  # matrix row 6.23: the wall-clock bound comes from the KIND's own lease
+  # length (RunnerPolicy.lease_minutes), never one shared constant - a long
+  # `work` build must not be capped as tightly as a quick `verify` pass.
+  def timeout_seconds(kind)
+    RunnerPolicy.lease_minutes(kind) * 60
+  end
+
+  # The return text (matrix rows 6.18/6.19): `output_last_message_path`'s
+  # own content when it exists and is non-blank (row 6.18 - stdout is never
+  # even inspected on this path), else the last YAML document found in
+  # `stdout` (row 6.19), else nil (no return anywhere - row 6.20 is the
+  # caller's problem, not this method's).
+  def read_return(output_last_message_path:, stdout:)
+    from_file = file_present_content(output_last_message_path)
+    return from_file unless from_file.nil?
+
+    stdout_fallback(stdout)
+  end
+
+  # The LAST YAML document in `text` that parses to a mapping, or nil when
+  # none does (row 6.20's other half). Documents are separated the ordinary
+  # YAML way, a line holding only `---`; a stream with no such separator at
+  # all is treated as one candidate document. Every candidate is tried from
+  # the end, so three documents (one row names explicitly) still resolve to
+  # the last one, and prose or a fragment that never parses to a mapping is
+  # skipped rather than returned as the "document".
+  def stdout_fallback(text)
+    return nil if text.to_s.strip.empty?
+
+    segments = text.to_s.split(/^---[ \t]*$/m).map(&:strip).reject(&:empty?)
+    segments = [text.to_s.strip] if segments.empty?
+
+    segments.reverse_each do |segment|
+      return segment if safe_yaml(segment).is_a?(Hash)
+    end
+    nil
+  end
+
+  # Runs `argv` once, feeding `stdin_data` on stdin through a scratch file
+  # (never a pipe - the same "never deadlock the read side" reasoning
+  # HookReplay.run_bounded already carries), bounded to `timeout_seconds`.
+  # `argv`'s own child becomes its own process group (`pgroup: true`) so a
+  # timeout can kill every child `codex exec` spawned along the way, not
+  # just the pid this call started (matrix row 6.24) - `codex exec` itself
+  # spawns shells for the commands it runs, and those would otherwise
+  # outlive a plain `Process.kill` on the parent alone, holding the
+  # worktree.
+  #
+  # Returns {exit_code:, timed_out:, stdout:, message:}. `message` is
+  # #read_return's result, computed only when the call did not time out - a
+  # timed-out child's partial output is never trusted (matrix row 6.22).
+  def execute(argv, stdin_data:, timeout_seconds:, output_last_message_path:)
+    Dir.mktmpdir("plastic-node-run-") do |scratch|
+      in_path = File.join(scratch, "stdin")
+      out_path = File.join(scratch, "stdout")
+      err_path = File.join(scratch, "stderr")
+      File.binwrite(in_path, stdin_data.to_s)
+
+      pid = Process.spawn(*argv.map(&:to_s), in: in_path, out: out_path, err: err_path, pgroup: true)
+      timed_out = false
+      exit_code =
+        begin
+          Timeout.timeout(timeout_seconds) do
+            Process.wait(pid)
+            $?.exitstatus
+          end
+        rescue Timeout::Error
+          timed_out = true
+          kill_group(pid)
+          nil
+        end
+
+      stdout = File.exist?(out_path) ? File.read(out_path) : ""
+      message = timed_out ? nil : read_return(output_last_message_path: output_last_message_path, stdout: stdout)
+
+      { exit_code: exit_code, timed_out: timed_out, stdout: stdout, message: message }
+    end
+  end
+
+  # --- internals ---------------------------------------------------------------
+
+  def file_present_content(path)
+    return nil if path.nil? || !File.exist?(path)
+
+    content = File.read(path)
+    content.strip.empty? ? nil : content
+  end
+  private_class_method :file_present_content
+
+  def safe_yaml(text)
+    YAML.safe_load(text, aliases: false, permitted_classes: [])
+  rescue Psych::Exception, ArgumentError
+    nil
+  end
+  private_class_method :safe_yaml
+
+  # Kills the whole process GROUP `pid` leads, not just `pid` itself (matrix
+  # row 6.24): a negative pid signals the group. Rescued and reaped exactly
+  # like HookReplay.kill_and_reap - a process that exited in the race
+  # between the timeout firing and this call raises Errno::ESRCH on the kill
+  # or Errno::ECHILD on the wait, neither of which should ever propagate.
+  def kill_group(pid)
+    Process.kill("KILL", -pid)
+  rescue StandardError
+    nil
+  ensure
+    begin
+      Process.wait(pid)
+    rescue StandardError
+      nil
+    end
+  end
+  private_class_method :kill_group
+end

package/scripts/lib/compact_instructions.rb

@@ -19,23 +19,31 @@ require "digest"
 #
 # Library only: no CLI, no ENV, no I/O.
 module CompactInstructions
-  # 35 and 50 percent of a 1M window.
-  OFFER_TOKENS = 350_000
-  INSIST_TOKENS = 500_000
+  # 15 and 25 percent of a 1M window (intent 355, n5, D7).
+  OFFER_TOKENS = 150_000
+  INSIST_TOKENS = 250_000
 
   # Static on purpose. A body rendered from the user's config would change its hash
   # every time they edited config.yml, and doctor would then report a correct install
   # as stale, so the block states the shipped numbers and names the two keys as the
   # override instead. It names the hand-off in words and never by path, so it reads
   # correctly whether or not the hand-off writer is installed.
+  # The `@` line is a Claude Code import: the harness reads the named file into the
+  # session. It is the whole of ruling D43, that PLASTIC.md is the only instruction text
+  # Plastic carries. It names the installed copy under the Plastic home, because a bare
+  # `@PLASTIC.md` would resolve against ~/.claude, where no such file exists.
   BODY = <<~MD.freeze
+    Plastic runs from one command, `plastic`. Its instructions are one page, imported here:
+
+    @~/.plastic/PLASTIC.md
+
     Plastic watches this session's context. When the harness reports how much of the
     window is used:
 
-    - At 350,000 tokens, offer to compact. Say that the hand-off in today's day ledger
+    - At 150,000 tokens, offer to compact. Say that the hand-off in today's day ledger
       is written and current, and take no for an answer: a task that is nearly done
       does not need the interruption.
-    - At 500,000 tokens, insist. Take no new work, write the hand-off in today's day
+    - At 250,000 tokens, insist. Take no new work, write the hand-off in today's day
       ledger, and compact before continuing.
     - After a compaction, say continue. The day summary at boot and the hand-off carry
       the state; do not rebuild it by re-reading files.

package/scripts/lib/core_integrity.rb

@@ -0,0 +1,71 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+# CoreIntegrity (intent 340, G7, n1): re-hashes the files an installed
+# ~/.plastic/manifest.json lists, so the runner's own "am I running trusted
+# code" check has one implementation. scripts/doctor.rb's
+# Doctor#check_install_integrity does this same arithmetic inline today,
+# per-agent (Codex/Hermes/Claude), against each agent's own manifest; this
+# module is not a refactor of that (out of scope for this node), it exists
+# so the runner - and a later node that points doctor at it - never have to
+# reimplement the same hashing loop a third time.
+#
+# Pure and side-effect-free: `check` takes plastic_home: and never raises
+# across its boundary. A missing, unreadable, or non-JSON manifest.json is a
+# named refusal (`reason:`), never an exception. A manifest-listed file that
+# no longer exists is reported under `missing`, distinct from `drifted` (a
+# file that exists but no longer hashes to the manifest's recorded value).
+module CoreIntegrity
+  module_function
+
+  def check(plastic_home:)
+    manifest_path = File.join(plastic_home.to_s, "manifest.json")
+    return refusal("manifest.json not found at #{manifest_path}") unless File.exist?(manifest_path)
+
+    raw = begin
+      File.read(manifest_path)
+    rescue StandardError => e
+      return refusal("manifest.json is unreadable: #{e.message}")
+    end
+
+    data = begin
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      return refusal("manifest.json is not valid JSON: #{e.message}")
+    end
+
+    files = data.is_a?(Hash) ? data["files"] : nil
+    return refusal("manifest.json's files: is not a mapping") unless files.is_a?(Hash)
+
+    drifted = []
+    missing = []
+    files.each do |path, expected_hash|
+      unless File.exist?(path)
+        missing << path
+        next
+      end
+
+      # v1 minor 6/row 11.16: a tracked file that exists but cannot be read
+      # (permissions changed under this process) must never raise out of a
+      # module whose whole contract is "never raises across its boundary" -
+      # unreadable is reported the same way a hash mismatch is: this
+      # process cannot confirm the file matches what the manifest expects,
+      # which is exactly what `drifted` already means.
+      actual_hash = begin
+        Digest::SHA256.file(path).hexdigest
+      rescue SystemCallError
+        nil
+      end
+      drifted << path if actual_hash.nil? || actual_hash != expected_hash
+    end
+
+    { ok: drifted.empty? && missing.empty?, drifted: drifted, missing: missing, reason: nil }
+  end
+
+  def refusal(reason)
+    { ok: false, drifted: [], missing: [], reason: reason }
+  end
+end

package/scripts/lib/dashboard_screen.rb

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "report_screen"
+
+# DashboardScreen (intent 331d) - the presentation half of the dashboard
+# screen. scripts/dashboard.rb's screen_fields sources every fact (Active, In
+# delivery, Delivered, Roadmap, Sessions, Changed, the two capped row lists)
+# through the same helpers report-screen and DaySummary already use, turning
+# a missing source into "not recorded" or "none" before it ever reaches
+# here; this module carries no data-sourcing logic of its own, only layout,
+# exactly like ReportScreen.render_state and IntentScreen.render do for
+# their own screens.
+module DashboardScreen
+  module_function
+
+  TEMPLATE_PATH = File.expand_path("../../templates/dashboard-screen.md", __dir__)
+
+  def render(fields, template: nil)
+    out = (template || File.read(TEMPLATE_PATH)).dup
+    out = out.gsub("{{scope}}", fields.fetch(:scope).to_s)
+    out = out.gsub("{{active}}", fields.fetch(:active).to_s)
+    out = out.gsub("{{in_delivery}}", fields.fetch(:in_delivery).to_s)
+    out = out.gsub("{{delivered}}", fields.fetch(:delivered).to_s)
+    out = out.gsub("{{roadmap}}", fields.fetch(:roadmap).to_s)
+    out = out.gsub("{{sessions}}", fields.fetch(:sessions).to_s)
+    out = out.gsub("{{changed}}", fields.fetch(:changed).to_s)
+    out = out.gsub("{{where_we_are.rows}}", where_we_are_rows(fields.fetch(:where_we_are, [])))
+    out = out.gsub("{{where_we_go_next.rows}}", where_we_go_next_rows(fields.fetch(:where_we_go_next, [])))
+    ReportScreen.fit_screen(out.gsub(/\n{3,}/, "\n\n"))
+  end
+
+  def where_we_are_rows(rows)
+    rows.map { |r| "| #{r[:graph_id]} | #{r[:intent]} | #{r[:stage]} | #{r[:progress]} | #{r[:lead]} |" }.join("\n")
+  end
+
+  def where_we_go_next_rows(rows)
+    rows.map { |r| "| #{r[:rank]} | #{r[:graph_id]} | #{r[:intent]} | #{r[:reason]} |" }.join("\n")
+  end
+end