@zalom/plastic 1.14.1 → 2.0.0-alpha.10

package/scripts/lib/installer_core.rb

@@ -9,6 +9,7 @@ require "time"
 require_relative "hook_registry"
 require_relative "agent_models"
 require_relative "harness_text"
+require_relative "compact_instructions"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -33,6 +34,15 @@ class InstallerCore
   # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
   CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
 
+  # Claude CLAUDE.md marked-section markers (intent 312). A pair of its own, not the
+  # Codex literals: the two managed files can be one file (a user who symlinks
+  # ~/.claude/CLAUDE.md at ~/.codex/AGENTS.md, or the reverse), and a shared literal
+  # would let one body silently replace the other and an uninstall of one strip both.
+  # doctor_core.rb matches these literals structurally, so keep the two in sync by hand.
+  CLAUDE_SECTION_BEGIN_PREFIX = "<!-- BEGIN PLASTIC COMPACT"
+  CLAUDE_SECTION_END = "<!-- END PLASTIC COMPACT -->"
+  CLAUDE_SECTION_RE = /^<!-- BEGIN PLASTIC COMPACT.*?-->\n.*?\n<!-- END PLASTIC COMPACT -->\n?/m
+
   # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
   # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
   # a shared file Codex merges from multiple sources, so this block stays a small,
@@ -66,8 +76,25 @@ class InstallerCore
     @agents = agents
   end
 
+  # Reads the package version from `package.json` when present (the source
+  # tree, and any dev checkout), falling back to the bare `VERSION` file the
+  # installer copies to `~/.plastic` (row B, spec 315b): an installed system
+  # carries VERSION but never package.json, so `rollback.rb` and `update.rb`
+  # constructing an InstallerCore with `package_root: ~/.plastic` crashed with
+  # a raw Errno::ENOENT before this fallback existed. Raises a named error,
+  # not a bare ENOENT, when neither file exists, so the caller is not
+  # misdirected toward the wrong missing file.
   def read_package_version(root)
-    File.read(File.join(root, "package.json")).then { |s| JSON.parse(s)["version"] }
+    package_json = File.join(root, "package.json")
+    version_file = File.join(root, "VERSION")
+
+    if File.exist?(package_json)
+      JSON.parse(File.read(package_json))["version"]
+    elsif File.exist?(version_file)
+      File.read(version_file).strip
+    else
+      raise "cannot determine the package version: neither #{package_json} nor #{version_file} exists"
+    end
   end
 
   # --- Channel derivation (the channel is encoded in the version string) ---
@@ -174,13 +201,6 @@ class InstallerCore
     keys.uniq
   end
 
-  def channel_from(argv, default: "latest")
-    return "alpha" if argv.include?("--alpha")
-    return "beta" if argv.include?("--beta")
-    return "latest" if argv.include?("--latest")
-    default
-  end
-
   def prompt_agents(input: $stdin)
     return ["claude"] unless input.tty?
 
@@ -329,25 +349,21 @@ class InstallerCore
       "scripts/write-config" => "scripts/write-config",
       "scripts/select-update-target" => "scripts/select-update-target",
       "scripts/hook-session-start" => "scripts/hook-session-start",
-      "scripts/hook-continue" => "scripts/hook-continue",
-      "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
-      "scripts/hook-gate-check" => "scripts/hook-gate-check",
-      "scripts/hook-savepoint-pre" => "scripts/hook-savepoint-pre",
-      "scripts/hook-power-tools" => "scripts/hook-power-tools",
-      "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
+      "scripts/hook-capture" => "scripts/hook-capture",
+      "scripts/hook-record" => "scripts/hook-record",
+      "scripts/hook-close" => "scripts/hook-close",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
       "scripts/lib/ruby_probe.rb" => "scripts/lib/ruby_probe.rb",
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
       "scripts/lib/config_asks.rb" => "scripts/lib/config_asks.rb",
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
-      "scripts/hook-code-gate" => "scripts/hook-code-gate",
-      "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
-      "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
-      "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/savepoint.rb" => "scripts/lib/savepoint.rb",
+      "scripts/lib/arm.rb" => "scripts/lib/arm.rb",
       "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
       "scripts/plastic-lock" => "scripts/plastic-lock",
       "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
+      "scripts/lib/compact_instructions.rb" => "scripts/lib/compact_instructions.rb",
       "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/insight-append" => "scripts/insight-append",
@@ -380,16 +396,13 @@ class InstallerCore
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
-      "scripts/hook-create-gate" => "scripts/hook-create-gate",
-      "scripts/hook-links-gate" => "scripts/hook-links-gate",
-      "scripts/lib/links_gate.rb" => "scripts/lib/links_gate.rb",
-      "scripts/lib/edit_gates.rb" => "scripts/lib/edit_gates.rb",
-      "scripts/hook-edit-gates" => "scripts/hook-edit-gates",
       "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
-      "scripts/lib/codex_edit_gates.rb" => "scripts/lib/codex_edit_gates.rb",
       "scripts/lib/harness_text.rb" => "scripts/lib/harness_text.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
+      "scripts/lib/report_screen.rb" => "scripts/lib/report_screen.rb",
+      "scripts/report-screen" => "scripts/report-screen",
+      "scripts/savepoint-note" => "scripts/savepoint-note",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/project_validator.rb" => "scripts/lib/project_validator.rb",
@@ -401,24 +414,47 @@ class InstallerCore
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
       "scripts/rollback.rb" => "scripts/rollback.rb",
       "scripts/lib/outcome_guard.rb" => "scripts/lib/outcome_guard.rb",
-      "scripts/lib/spec_header.rb" => "scripts/lib/spec_header.rb",
       "scripts/lib/scaffold_intent.rb" => "scripts/lib/scaffold_intent.rb",
+      "scripts/lib/backfill_intent.rb" => "scripts/lib/backfill_intent.rb",
       "scripts/scaffold-intent" => "scripts/scaffold-intent",
       "scripts/lib/verify_intent.rb" => "scripts/lib/verify_intent.rb",
       "scripts/verify-intent" => "scripts/verify-intent",
-      "scripts/lib/start_intent.rb" => "scripts/lib/start_intent.rb",
-      "scripts/start-intent" => "scripts/start-intent",
       "scripts/lib/exec_worktree.rb" => "scripts/lib/exec_worktree.rb",
       "scripts/exec-worktree" => "scripts/exec-worktree",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
       "scripts/lib/rule_catalog.rb" => "scripts/lib/rule_catalog.rb",
       "scripts/lib/doctor_exclusions.rb" => "scripts/lib/doctor_exclusions.rb",
+      "scripts/lib/doctor_session_ledger.rb" => "scripts/lib/doctor_session_ledger.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
       "scripts/skill-lint" => "scripts/skill-lint",
       "scripts/lib/skill_lint.rb" => "scripts/lib/skill_lint.rb",
       "scripts/feedback-report" => "scripts/feedback-report",
       "scripts/lib/feedback_report.rb" => "scripts/lib/feedback_report.rb",
+      "scripts/append-ledger" => "scripts/append-ledger",
+      "scripts/lib/session_ledger.rb" => "scripts/lib/session_ledger.rb",
+      "scripts/session-commit" => "scripts/session-commit",
+      "scripts/file-session-intent" => "scripts/file-session-intent",
+      "scripts/promote-session-item" => "scripts/promote-session-item",
+      "scripts/lib/session_backfill.rb" => "scripts/lib/session_backfill.rb",
+      "scripts/lib/session_close.rb" => "scripts/lib/session_close.rb",
+      "scripts/lib/session_git.rb" => "scripts/lib/session_git.rb",
+      "scripts/lib/handoff.rb" => "scripts/lib/handoff.rb",
+      "scripts/lib/day_summary.rb" => "scripts/lib/day_summary.rb",
+      "scripts/write-handoff" => "scripts/write-handoff",
+      "scripts/day-summary" => "scripts/day-summary",
+      "scripts/lib/intent_screen.rb" => "scripts/lib/intent_screen.rb",
+      "scripts/intent-screen" => "scripts/intent-screen",
+      "scripts/hook-savepoint" => "scripts/hook-savepoint",
+      # Intent 316a: hooks/* only glob-copies scripts/*, never scripts/lib/*
+      # (see hook_files above), so the two lib files a require_relative
+      # between themselves are unguarded there — these three literal
+      # entries are their only protection (test/install_sync_test.rb:23-29
+      # greps installer_core.rb's own source text for "scripts/<name>").
+      "scripts/lib/intent_screen_ansi.rb" => "scripts/lib/intent_screen_ansi.rb",
+      "scripts/lib/screen_paint.rb" => "scripts/lib/screen_paint.rb",
+      "scripts/lib/message_display.rb" => "scripts/lib/message_display.rb",
+      "scripts/hook-message-display" => "scripts/hook-message-display",
     }
   end
 
@@ -432,6 +468,8 @@ class InstallerCore
       version: 3
       execution_mode: subagent-driven
       stale_threshold_days: 3
+      context_offer_tokens: 350000
+      context_insist_tokens: 500000
       hash_length: 6
       hash_algorithm: sha256-base36
       max_slug_words: 5
@@ -718,7 +756,7 @@ class InstallerCore
   end
 
   # `install_skills_flat` relocates any top-level underscore-prefixed markdown
-  # fragment (today: `_active-intent-gate.md`, `_decision-tables.md`) out of the
+  # fragment (today: `_decision-tables.md`) out of the
   # per-agent skills tree and into `plastic_home` directly, then lists them in
   # `installed`, so they are manifest-tracked and eligible for prune. But
   # `install_for_agent`'s prune roots are `[config[:dir], config[:home_dir]]`,
@@ -790,6 +828,11 @@ class InstallerCore
     choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
     merge_claude_hooks(settings_path, choice: choice)
 
+    # Instruction injection (intent 312): the compact-instructions block into
+    # ~/.claude/CLAUDE.md. A partial-ownership user file, so it is NOT manifest-tracked
+    # (stripped surgically on uninstall), the same treatment ~/.codex/AGENTS.md gets.
+    inject_claude_compact_md(File.join(config[:dir], "CLAUDE.md"))
+
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
     write_manifest(installed, manifest_path)
@@ -1012,7 +1055,7 @@ class InstallerCore
 
   # Copy each skills/<name>/ to <skills_root>/plastic-<name>/ (flat, namespaced by
   # directory name -- the only personal-skill namespacing Claude Code supports).
-  # Any top-level underscore-prefixed markdown fragment (e.g. `_active-intent-gate.md`,
+  # Any top-level underscore-prefixed markdown fragment (e.g. `_decision-tables.md`,
   # `_decision-tables.md`) is a shared non-skill fragment and relocates to ~/.plastic/
   # instead, so every skill can read it from one shared location. `exclude` skips
   # named top-level skill directories entirely (intent 185: the agent-advisor skill
@@ -1273,8 +1316,8 @@ class InstallerCore
     plastic_hooks.each do |event, group|
       hooks[event] ||= []
 
-      # An event may map to a LIST of plastic groups (PreToolUse carries the
-      # code-gate AND the create-gate). The purge pass above already removed all
+      # An event may map to a LIST of plastic groups (none does since the edit-path
+      # gates left in 2.0, intent 302; the shape stays). The purge pass above already removed all
       # prior plastic groups, so appending each desired group fresh is idempotent
       # across re-runs and never collapses two matchers into one group.
       groups = group.is_a?(Array) ? group : [group]
@@ -1355,14 +1398,28 @@ class InstallerCore
     raise e
   end
 
-  def codex_section(body: CODEX_AGENTS_MD_BODY)
+  # A managed instruction file may be a symlink into a dotfiles repo. write_text_atomic
+  # renames a temp file over its argument, which would replace the link with a regular
+  # file and silently detach it, so every read and write resolves the link first and the
+  # change lands on its target (intent 312).
+  def resolve_managed_path(path)
+    File.symlink?(path) ? File.realpath(path) : path
+  rescue Errno::ENOENT
+    path
+  end
+
+  def marked_section(body: CODEX_AGENTS_MD_BODY, begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                     end_marker: CODEX_SECTION_END)
     hash = Digest::SHA256.hexdigest(body)[0, 12]
-    "#{CODEX_SECTION_BEGIN_PREFIX} hash:#{hash} -->\n#{body.strip}\n#{CODEX_SECTION_END}\n"
+    "#{begin_prefix} hash:#{hash} -->\n#{body.strip}\n#{end_marker}\n"
   end
 
   # Returns :created / :appended / :replaced / :refused. Never raises on a normal user file.
-  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
-    section = codex_section(body: body)
+  def inject_marked_section(path, body: CODEX_AGENTS_MD_BODY,
+                            begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                            end_marker: CODEX_SECTION_END, section_re: CODEX_SECTION_RE)
+    section = marked_section(body: body, begin_prefix: begin_prefix, end_marker: end_marker)
+    path = resolve_managed_path(path)
 
     unless File.exist?(path)
       FileUtils.mkdir_p(File.dirname(path))
@@ -1371,14 +1428,14 @@ class InstallerCore
     end
 
     content = File.read(path)
-    has_begin = content.include?(CODEX_SECTION_BEGIN_PREFIX)
-    has_end = content.include?(CODEX_SECTION_END)
+    has_begin = content.include?(begin_prefix)
+    has_end = content.include?(end_marker)
 
     # 22a safety rule: never write if the existing section cannot be parsed.
     return :refused if has_begin && !has_end
 
     if has_begin
-      write_text_atomic(path, content.sub(CODEX_SECTION_RE, section))
+      write_text_atomic(path, content.sub(section_re, section))
       :replaced
     else
       base = content.end_with?("\n") ? content : content + "\n"
@@ -1387,18 +1444,41 @@ class InstallerCore
     end
   end
 
+  # --- The two blocks Plastic ships, each with its own marker pair ---
+
+  def codex_section(body: CODEX_AGENTS_MD_BODY)
+    marked_section(body: body)
+  end
+
+  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
+    inject_marked_section(path, body: body)
+  end
+
+  # The compact-instructions block for ~/.claude/CLAUDE.md (intent 312).
+  def claude_compact_section(body: CompactInstructions::BODY)
+    marked_section(body: body, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                   end_marker: CLAUDE_SECTION_END)
+  end
+
+  def inject_claude_compact_md(path, body: CompactInstructions::BODY)
+    inject_marked_section(path, body: body, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                          end_marker: CLAUDE_SECTION_END, section_re: CLAUDE_SECTION_RE)
+  end
+
   # Remove exactly Plastic's managed section from a user-owned AGENTS.md. Preserve all other
   # content. Delete the file only if Plastic created it and nothing else remains. Returns the
   # path when it acted, nil on no-op. Mirrors remove_claude_hooks: dedicated surgical strip,
   # never the manifest whole-file-delete path.
-  def strip_codex_section(path)
+  def strip_marked_section(path, begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                           section_re: CODEX_SECTION_RE)
+    path = resolve_managed_path(path)
     return nil unless File.exist?(path)
     content = File.read(path)
-    return nil unless content.include?(CODEX_SECTION_BEGIN_PREFIX)
+    return nil unless content.include?(begin_prefix)
 
     # Remove the section plus the single separator newline the append introduced, so a
     # standard user file round-trips byte-identical.
-    stripped = content.sub(/\n?#{CODEX_SECTION_RE}/, "")
+    stripped = content.sub(/\n?#{section_re}/, "")
 
     if stripped.strip.empty?
       File.delete(path)                 # Plastic-created file: nothing else left
@@ -1409,6 +1489,15 @@ class InstallerCore
     path
   end
 
+  def strip_codex_section(path)
+    strip_marked_section(path)
+  end
+
+  def strip_claude_compact_section(path)
+    strip_marked_section(path, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                         section_re: CLAUDE_SECTION_RE)
+  end
+
   # --- Uninstall ---
 
   def handle_uninstall(uninstall_agents)
@@ -1435,6 +1524,7 @@ class InstallerCore
     puts "     ls ~/.claude/skills | grep '^plastic-'      # → no output"
     puts "     ls ~/.claude/hooks | grep '^plastic-'       # → no output"
     puts "     grep -c plastic ~/.claude/settings.json     # → only hook refs gone"
+    puts "     grep 'PLASTIC COMPACT' ~/.claude/CLAUDE.md  # → no output"
     puts "\n  To also delete your intent store: rm -rf #{tilde(plastic_home)}\n\n"
   end
 
@@ -1481,6 +1571,11 @@ class InstallerCore
       settings_path = File.join(config[:dir], "settings.json")
       remove_claude_hooks(settings_path) if File.exist?(settings_path)
       removed.concat(migrate_legacy_plugin(config[:dir]))
+
+      # The compact-instructions block in the user-owned CLAUDE.md (intent 312): a
+      # surgical strip, never the manifest whole-file-delete path above.
+      stripped = strip_claude_compact_section(File.join(config[:dir], "CLAUDE.md"))
+      removed << stripped if stripped
     end
 
     # Codex: surgically strip Plastic's marked section from the user-owned AGENTS.md

package/scripts/lib/intent_screen.rb

@@ -0,0 +1,309 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+# IntentScreen (intent 316) - fills templates/intent-screen.md from one intent's
+# record: the intent file, the tier's INDEX.md, savepoint.md and checklist.md.
+# Every number on the screen comes from here so the session never writes one by
+# eye. Pure: explicit paths in, a Markdown string out; no ENV, no Dir.pwd.
+#
+# Intent 316a fixed three defects the field code inherited into both the plain
+# renderer and the ANSI renderer (scripts/lib/intent_screen_ansi.rb): the
+# Insight row dumping a multi-clause remainder into the note column, an empty
+# "What this means" heading rendering bold with nothing under it, and step
+# text cut mid-sentence. `step_text`, `insight_fields` and `next_fields` are
+# public so the ANSI renderer reuses the exact same trims (D3) rather than
+# re-deriving them and drifting.
+#
+# Harness-agnostic core: no harness assumption lives here.
+module IntentScreen
+  BAR_WIDTH = 20
+  ON = "█"
+  OFF = "░"
+  PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
+  SECTIONS = %w[Active Future Completed Abandoned].freeze
+  ITEM_RE = /^\s*- \[([ xX])\]\s+(.*)$/
+  # Em dash and en dash added (intent 316a O1e): a checklist item written
+  # "S1 — text" (the em dash every checklist this intent writes, and the one a
+  # reviewer reads, uses) kept its prefix under the old character class and
+  # rendered "S1  [ open ]  S1 — text" on screen. Intent 317a (A1) made the
+  # separator optional with required whitespace: "S1 text" (the shape real
+  # checklists use) kept its label and doubled in next_fields; a bare "S1"
+  # has no following text and stays prose.
+  STEP_PREFIX_RE = /\A(?:Step|S)\s*\d+\s*(?:[-:·—–]\s*|\s+)(?=\S)/i
+  INSIGHT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s+·\s+\S+\s+·\s+.+?\s+—\s+(.+)\z/
+  SAVEPOINT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s{2,}(\S+)\s{2,}(.+?)\s*\z/
+  # Intent 317, D6: field-2 tokens that are genuine lifecycle stages. A ledger
+  # can also carry non-lifecycle lines (`Lock  takeover: ...`, and 317's own
+  # `Review`/`Commit`); those must never be mistaken for the current stage.
+  # Placed here, clear of STEP_PREFIX_RE above (316a edits that one).
+  LIFECYCLE_STAGES = %w[What Why How Exec Done].freeze
+
+  # True iff a raw savepoint ledger line's field 2 is a genuine lifecycle
+  # stage (post-execution-review finding 5: centralizes what spawn-preamble
+  # and agent-report used to each copy-paste beside the constant above).
+  def self.lifecycle_line?(line)
+    parts = line.to_s.split(/\s{2,}/)
+    parts.length >= 2 && LIFECYCLE_STAGES.include?(parts[1])
+  end
+
+  # Word-boundary truncation caps (intent 316a D3/O1a/O1c). Never a clause
+  # trim: a clause trim on step text destroys a pinned `OPEN:` row
+  # (test/intent_screen_test.rb:171-178) that a mid-sentence cut would eat.
+  INSIGHT_VALUE_MAX = 72
+  INSIGHT_NOTE_MAX = 96
+  NEXT_VALUE_MAX = 72
+  STEP_TEXT_MAX = 110
+
+  # Where a resume lands, from the ledger's last line (the boarding matrix).
+  def self.landing_stage(stage, milestone)
+    case stage
+    when "Done" then "Done"
+    when "What" then "Why"
+    when "Why" then milestone.to_s.include?("spec.md") ? "How" : "Why"
+    when "How" then milestone.to_s.include?("checklist.md") ? "Exec" : "How"
+    when "Exec" then milestone.to_s.include?("outcome.md") ? "ready to complete" : "Exec"
+    else "Why"
+    end
+  end
+
+  def self.intent_dir?(dir)
+    return false unless dir && File.directory?(dir)
+
+    base = File.basename(dir)
+    return false unless base.match?(/\A[0-9][0-9a-z]*--[\w-]+\z/)
+
+    File.exist?(File.join(dir, "#{base}.md"))
+  end
+
+  def self.render(intent_dir:, store_root:, template:)
+    base = File.basename(intent_dir)
+    id = base.split("--", 2).first
+    intent_text = File.read(File.join(intent_dir, "#{base}.md"))
+
+    fields = {}
+    fields.merge!(store_fields(store_root))
+    status, title = index_fields(store_root, id)
+    fields["status"] = status
+    fields["status.note"] = status == "unlisted" ? "no INDEX.md line names this id" : "listed under ## #{status} in INDEX.md"
+    fields["id"] = id
+    fields["name"] = title || fallback_name(intent_text)
+    fields.merge!(savepoint_fields(intent_dir, intent_text))
+    items = checklist_items(intent_dir)
+    fields.merge!(progress_fields(items))
+    fields.merge!(next_fields(items, status, checklist_present: items_present?(intent_dir)))
+    fields.merge!(insight_fields(intent_text))
+    fields["steps.rows"] = steps_rows(items)
+
+    out = template.dup
+    fields.each { |k, v| out = out.gsub("{{#{k}}}", v.to_s) }
+    out.gsub(/\n{3,}/, "\n\n")
+  end
+
+  # --- store ---------------------------------------------------------------------
+
+  def self.store_fields(store_root)
+    parent = File.basename(File.dirname(store_root))
+    if parent == "projects"
+      slug = File.basename(store_root)
+      { "store" => "project:#{slug}", "store.note" => "the #{slug} project store" }
+    else
+      { "store" => "global", "store.note" => "the global store" }
+    end
+  end
+
+  # --- INDEX.md -----------------------------------------------------------------
+
+  def self.index_fields(store_root, id)
+    path = File.join(store_root, "INDEX.md")
+    return ["unlisted", nil] unless File.exist?(path)
+
+    section = nil
+    File.foreach(path) do |line|
+      if line.start_with?("## ")
+        name = line[3..].strip
+        section = SECTIONS.include?(name) ? name : nil
+        next
+      end
+      next unless section && line.strip.start_with?("- [")
+
+      m = line.match(/\A\s*- \[#{Regexp.escape(id)}\s+[-—]\s+(.+?)\]\(/)
+      return [section, m[1].strip] if m
+    end
+    ["unlisted", nil]
+  end
+
+  def self.fallback_name(intent_text)
+    m = intent_text.match(/^intent:\s*["']?(.+?)["']?\s*$/)
+    text = m ? m[1] : ""
+    text.length > 60 ? "#{text[0, 57]}..." : text
+  end
+
+  # --- savepoint.md ---------------------------------------------------------------
+
+  def self.savepoint_fields(intent_dir, intent_text)
+    path = File.join(intent_dir, "savepoint.md")
+    lines = File.exist?(path) ? File.readlines(path).map(&:strip).reject(&:empty?) : []
+    matched = lines.reverse.map { |l| l.match(SAVEPOINT_RE) }.compact
+    last = matched.first
+    unless last
+      return { "stage" => "Why", "stage.note" => "no savepoint line yet",
+               "savepoint" => "none", "savepoint.note" => "" }
+    end
+
+    # D6: the STAGE PICK is guarded to the last LIFECYCLE line (What/Why/How/
+    # Exec/Done), so a trailing Lock/Review/Commit line cannot be mistaken for
+    # the stage. The Savepoint field below still shows the TRUE last line,
+    # whatever its kind - that is what a savepoint is.
+    lifecycle_last = matched.find { |m| LIFECYCLE_STAGES.include?(m[2]) }
+    stage_source = lifecycle_last || last
+
+    ts, stage, milestone = last[1], last[2], last[3]
+    landing = landing_stage(stage_source[2], stage_source[3])
+    delivered = lines.map { |l| l.match(SAVEPOINT_RE) }.compact.map { |m| m[2] }.uniq
+    delivered &= %w[What Why How Exec]
+    note = if landing == "Done"
+             "delivered; the record is immutable"
+           elsif landing == "ready to complete"
+             "outcome.md is real; run the ending procedure"
+           else
+             "#{delivered.join(', ')} delivered; the work is open"
+           end
+    { "stage" => landing, "stage.note" => note,
+      "savepoint" => "#{stage} · #{milestone}", "savepoint.note" => human_time(ts) }
+  end
+
+  def self.human_time(ts)
+    m = ts.match(/\A(\d{4}-\d\d-\d\d)T(\d\d:\d\d)/)
+    m ? "#{m[1]} #{m[2]} UTC" : ts
+  end
+
+  # --- checklist.md --------------------------------------------------------------
+
+  def self.items_present?(intent_dir)
+    path = File.join(intent_dir, "checklist.md")
+    return false unless File.exist?(path)
+
+    !File.read(path).lstrip.start_with?(PLACEHOLDER_SENTINEL)
+  end
+
+  def self.checklist_items(intent_dir)
+    return [] unless items_present?(intent_dir)
+
+    File.readlines(File.join(intent_dir, "checklist.md")).filter_map do |line|
+      m = line.match(ITEM_RE)
+      next unless m
+
+      text = m[2].strip
+      next if text == "..."
+
+      { done: m[1] != " ", text: text.sub(STEP_PREFIX_RE, "") }
+    end
+  end
+
+  def self.progress_fields(items)
+    total = items.length
+    done = items.count { |i| i[:done] }
+    on = total.zero? ? 0 : (done * BAR_WIDTH) / total
+    bar = (ON * on) + (OFF * (BAR_WIDTH - on))
+    note = if total.zero?
+             "no checklist yet"
+           elsif done == total
+             "all steps done"
+           else
+             "#{total - done} steps open"
+           end
+    { "progress.bar" => bar, "progress.done" => done.to_s, "progress.total" => total.to_s,
+      "progress.note" => note }
+  end
+
+  # `escape_pipes:` (intent 316a O1d, default true) keeps the plain Markdown
+  # table's pipe-escaping; the ANSI renderer, which never emits a table,
+  # passes `escape_pipes: false` to get the raw value instead of a literal
+  # `\|`. Named to not shadow the module's own `escape` method.
+  def self.next_fields(items, status, checklist_present:, escape_pipes: true)
+    return { "next" => "", "next.note" => "" } if %w[Completed Abandoned].include?(status)
+    return { "next" => "write checklist.md", "next.note" => "How" } unless checklist_present
+
+    idx = items.index { |i| !i[:done] }
+    return { "next" => "", "next.note" => "all steps done" } unless idx
+
+    head, = split_first_clause(items[idx][:text])
+    head = truncate_words(head, NEXT_VALUE_MAX)
+    head = escape(head) if escape_pipes
+    { "next" => "S#{idx + 1} · #{head}", "next.note" => "first open step" }
+  end
+
+  def self.steps_rows(items)
+    return "| | | no steps yet |" if items.empty?
+
+    items.each_with_index.map do |item, i|
+      "| S#{i + 1} | #{item[:done] ? 'done' : 'open'} | #{escape(step_text(item[:text]))} |"
+    end.join("\n")
+  end
+
+  # Public (intent 316a O1c) so the ANSI renderer trims step text identically:
+  # word-boundary truncation only, never a clause trim, at STEP_TEXT_MAX.
+  def self.step_text(text)
+    truncate_words(text, STEP_TEXT_MAX)
+  end
+
+  def self.escape(text)
+    text.gsub("|", "\\|")
+  end
+
+  # --- ## Insights ----------------------------------------------------------------
+
+  def self.insight_fields(intent_text, escape_pipes: true)
+    section = intent_text.split(/^## Insights\s*$/, 2)[1].to_s.split(/^## /, 2)[0].to_s
+    entry = section.lines.map(&:strip).reverse.map { |l| l.match(INSIGHT_RE) }.compact.first
+    return { "insight" => "none yet", "insight.note" => "" } unless entry
+
+    ts, text = entry[1], entry[2].strip
+    head, tail = split_first_clause(text)
+    value = truncate_words(head, INSIGHT_VALUE_MAX)
+    tail = tail.empty? ? "" : truncate_words(tail, INSIGHT_NOTE_MAX)
+    note = tail.empty? ? human_time(ts) : "#{human_time(ts)} · #{tail}"
+    if escape_pipes
+      { "insight" => escape(value), "insight.note" => escape(note) }
+    else
+      { "insight" => value, "insight.note" => note }
+    end
+  end
+
+  # First clause of `text`, and at most one following clause as the tail.
+  # Anything past the second clause is discarded (intent 316a O1a): the old
+  # behavior dumped the ENTIRE remainder into the note (an 800-character
+  # real-world tail starting mid-list). Boundary is a `.` or `;` immediately
+  # followed by whitespace-then-more or end of string, so "alpha.2" and "2.0"
+  # are never mistaken for clause ends.
+  def self.split_first_clause(text)
+    head, rest = clause_and_rest(text)
+    return [head, ""] unless rest
+
+    second, more = clause_and_rest(rest)
+    tail = more ? second : rest
+    [head, tail]
+  end
+
+  # Returns [clause_without_terminal_punctuation, remainder_or_nil]. `nil` for
+  # the remainder means either no boundary exists at all, or the boundary
+  # sits at the absolute end of `text` (a single trailing clause with nothing
+  # after it) — both cases where there is no SECOND clause to fold in.
+  def self.clause_and_rest(text)
+    m = text.match(/\A(.+?)[.;](\s+(.*)|\z)/m)
+    return [text, nil] unless m
+
+    remainder = m[2].to_s.strip
+    remainder.empty? ? [m[1], nil] : [m[1], remainder]
+  end
+
+  # Word-boundary truncation with a trailing "…" when cut, never mid-word and
+  # never a clause trim (intent 316a D3).
+  def self.truncate_words(text, max)
+    return text if text.length <= max
+    return "…" if max <= 1
+
+    cut = text[0, max - 1].rindex(" ")
+    cut = max - 1 if cut.nil? || cut.zero?
+    "#{text[0, cut].rstrip}…"
+  end
+end