@zalom/plastic 1.14.1 → 2.0.0-alpha.10

package/scripts/end-intent

@@ -28,8 +28,12 @@
 #      file that exists while no session identity resolves from ANY source
 #      also refuses (exit 4) rather than ever reaching Lock.takeover with a
 #      blank session, which would delete the lock file and then crash.
-#   1. Guard outcome.md (exit 2, authors nothing, on any failure), then stamp
-#      the intent file's `## Outcome` section with --outcome-summary if given.
+#   1. Backfill (intent 308): write spec.md, plan.md, actions/ACTION_1.md, and
+#      outcome.md from the record wherever a file is missing or still the
+#      placeholder (BackfillIntent; real content is never touched). Then run
+#      doctor's per-intent structure check and OutcomeGuard as a self-check
+#      that reports on stderr and proceeds. Then stamp the intent file's
+#      `## Outcome` section with --outcome-summary if given.
 #   2. Move the intent's INDEX.md line from `## Active` into `## Completed`
 #      (delivered) or `## Abandoned` (abandoned), dated today, appending
 #      --index-note (if given). Accepts a real em dash OR a plain hyphen as
@@ -37,23 +41,21 @@
 #      always EMITS the real em dash on write. An id that resolves to neither
 #      `## Active` nor the terminal section is a loud failure (exit 1); an id
 #      already correctly in the terminal section is a quiet, idempotent success.
-#   3. Append the savepoint `Done` bookend (Bridge.append_terminal_savepoint).
+#   3. Append the savepoint `Done` bookend (Savepoint.append_terminal_savepoint).
 #   4. Commit the store repo, unless --no-commit.
-#   5. Disarm (intent 188, D2/D16): check the code worktree (resolved from the
-#      bridge) for uncommitted changes first (exit 5 if dirty, unless
-#      --discard-worktree-changes); call the disarm seam (default
-#      Bridge.disarm_auto); verify the durable lock file is actually gone
-#      afterward. The /tmp bridge is only a cache (AGENTS.md): when no bridge
-#      resolves at all (a wiped /tmp, a resumed job under a new session id),
-#      the durable lock file is released directly instead, LOUDLY (a warning
-#      that a worktree may be orphaned), rather than stranding a committed,
-#      terminal intent still holding its lock.
+#   5. Disarm (intent 188, D2/D16; intent 307): check the code worktree (derived
+#      from projects.yml and the intent id, Arm.worktree_block) for uncommitted
+#      changes first (exit 5 if dirty, unless --discard-worktree-changes); call the
+#      disarm seam (default Arm.disarm: worktree released, lock cleared, the session
+#      pointer back on the day ledger); verify the durable lock file is actually gone
+#      afterward, and release it directly when a foreign-keyed disarm left it (the
+#      /tmp bridge this step once read was removed in 2.0, intent 307).
 #
 # Exit codes:
 #   0  ok - the intent is closed and no delivery.lock remains.
 #   1  usage/resolution failure, OR an id that resolves to neither ## Active
 #      nor the terminal section (D11). Deliberately double duty; see plan.md.
-#   2  the outcome.md guard refused; authors nothing.
+#   2  retired in 2.0 (intent 308): the outcome.md guard reports and proceeds.
 #   3  steps 1-4 already committed, but the delivery lock genuinely could not
 #      be cleared (not a bridge cache miss; see step 5 above).
 #   4  pre-flight refusal: a FRESH foreign lock is held by a live,
@@ -63,19 +65,22 @@
 #      (git status itself failed: corrupt index, git missing, not a repo);
 #      refused before removal; pass --discard-worktree-changes to override
 #      deliberately.
-#   6  the doctor per-intent structure gate refused (checklist incomplete,
-#      links out of projection, intent-file malformed, or a lifecycle artifact
-#      missing/placeholder); named reasons on stderr; authors nothing
-#      (intent 222).
+#   6  retired in 2.0 (intent 308): the structure check reports and proceeds.
+#   7  hollow delivered report refused (317a D7) - intent 308's one deliberate
+#      exception to report-and-proceed; --allow-hollow-report overrides.
 
 require "fileutils"
 require "date"
 require "open3"
 require "pathname"
 require_relative "lib/bridge"
+require_relative "lib/arm"
+require_relative "lib/savepoint"
 require_relative "lib/lock"
 require_relative "lib/intent_validator"
 require_relative "lib/outcome_guard"
+require_relative "lib/report_screen"
+require_relative "lib/backfill_intent"
 
 DISPOSITIONS = %w[delivered abandoned].freeze
 
@@ -97,6 +102,7 @@ def parse_args(argv)
   opts = {
     store: nil, id: nil, disposition: nil, index: nil,
     outcome_summary: nil, index_note: nil, no_commit: false, dry_run: false,
+    allow_hollow_report: false,
     session: nil, discard_worktree_changes: false,
   }
   i = 0
@@ -113,6 +119,7 @@ def parse_args(argv)
     when "--discard-worktree-changes" then opts[:discard_worktree_changes] = true
     when "--no-commit"                then opts[:no_commit] = true
     when "--dry-run"                  then opts[:dry_run] = true
+    when "--allow-hollow-report"      then opts[:allow_hollow_report] = true
     else
       usage_abort("unknown argument #{arg.inspect}")
     end
@@ -169,44 +176,41 @@ def resolve_plastic_home_and_scope(store)
   end
 end
 
-# Doctor's per-intent structure gate (intent 222), a pre-write step: FAIL refuses the close
-# (exit 6, authors nothing), WARN prints an advisory note and proceeds, PASS proceeds
-# silently, and an unexpected exception from the gate call itself is rescued and treated as
-# a skipped gate (fail-open on a crash: a broken gate must never wedge a close).
-#
-# `gate:` is an injected seam (mirrors run_disarm's own bridge_reader:/disarm: pattern
-# below) defaulting to the real Doctor.new(...).run_intent_check(...) call; tests load this
-# script in-process (as test/end_intent_disarm_toctou_test.rb already does for run_disarm)
-# and inject a raising stub to prove the fail-open contract, with no eval/ENV/global seam.
+# Backfill (intent 308): write the judgment documents that are missing or still the
+# placeholder from the record (BackfillIntent). Fail-open: a crash here warns and the
+# close proceeds, the same contract as the structure check below.
+def run_backfill(intent_dir, store:, id:, disposition:, summary:)
+  result = BackfillIntent.run(intent_dir: intent_dir, store: store, id: id,
+                              disposition: disposition, summary: summary)
+  result[:written].each { |rel| warn "end-intent: backfilled #{rel} from the record" }
+  result[:notes].each { |note| warn "end-intent: backfill note: #{note}" }
+rescue StandardError => e
+  warn "end-intent: backfill crashed (#{e.message}); proceeding without it"
+end
+
+# Doctor's per-intent structure check (intent 222; a self-check since intent 308). Runs
+# after the backfill and REPORTS: every FAIL or WARN check prints its named reason on
+# stderr and the close proceeds. Nothing here exits; a gap end-intent cannot write itself
+# (an unchecked box, a malformed intent file, links out of projection) is the owner's to
+# fix afterward, and doctor --intent keeps reporting it. A crash is rescued the same way.
+# Injected `gate:` seam: tests drive the real Doctor against a hermetic home, or a raising
+# stub to prove the fail-open contract, with no eval/ENV/global seam.
 #
-# Disposition is deliberately NOT passed to the real gate call (intent 222 executor
-# decision): the existing outcome-only guard immediately following this call already owns
-# disposition-matching (exit 2), and intent_lifecycle_artifacts unconditionally checks
-# outcome.md PRESENCE via Bridge.stage_file_present? regardless of disposition, so passing
-# it here would make this gate re-check the SAME disposition match the old guard already
-# owns, needlessly widening which exit-2 fixtures become exit-6. doctor.rb --intent called
-# directly (with --disposition) still exercises the fold-in per D2/acceptance criteria.
-def run_structure_gate(id, store:, gate: ->(gate_home, gate_scope) {
+# Disposition is deliberately NOT passed to the real gate call: OutcomeGuard.reason,
+# called right after this in main, already owns disposition-matching, and
+# intent_lifecycle_artifacts checks outcome.md PRESENCE regardless of disposition.
+def run_structure_check(id, store:, gate: ->(gate_home, gate_scope) {
   require_relative "doctor"
   Doctor.new(plastic_home: gate_home).run_intent_check(id, store: gate_scope)
 })
   gate_home, gate_scope = resolve_plastic_home_and_scope(store)
-  gate_verdict = gate.call(gate_home, gate_scope)
-  case gate_verdict[:status]
-  when "fail"
-    gate_verdict[:checks].select { |c| c[:status] == "fail" }.each do |c|
-      detail = Array(c[:details]).any? ? " (#{Array(c[:details]).join("; ")})" : ""
-      warn "end-intent: structure gate refused: #{c[:name]}: #{c[:message]}#{detail}"
-    end
-    exit 6
-  when "warn"
-    gate_verdict[:checks].select { |c| c[:status] == "warn" }.each do |c|
-      detail = Array(c[:details]).any? ? " (#{Array(c[:details]).join("; ")})" : ""
-      warn "end-intent: structure gate warning (proceeding): #{c[:name]}: #{c[:message]}#{detail}"
-    end
+  verdict = gate.call(gate_home, gate_scope)
+  verdict[:checks].select { |c| %w[fail warn].include?(c[:status]) }.each do |c|
+    detail = Array(c[:details]).any? ? " (#{Array(c[:details]).join("; ")})" : ""
+    warn "end-intent: structure check: #{c[:name]}: #{c[:message]}#{detail}"
   end
 rescue StandardError => e
-  warn "end-intent: structure gate crashed (#{e.message}); proceeding without it"
+  warn "end-intent: structure check crashed (#{e.message}); proceeding without it"
 end
 
 # outcome.md guard: see OutcomeGuard.reason (scripts/lib/outcome_guard.rb, extracted intent 222)
@@ -216,7 +220,75 @@ end
 # Replace the body of the intent file's `## Outcome` section with `summary`,
 # leaving every other section and the frontmatter untouched. No-op (returns
 # content unchanged) when summary is blank or the section is not found.
+# 317a S9 (D7): the self-render gate. Renders the delivered screen's sources on
+# the intent's own record and names what would come out hollow. This is intent
+# 308's ONE deliberate exception to report-and-proceed: a hollow DELIVERED
+# close is refused with exit 7 (--allow-hollow-report overrides), because 317
+# closed exactly this way and the owner read a screen full of "not recorded".
+# Abandoned closes and machine-backfilled outcomes (the backfill marker) are
+# exempt: the reader cannot expect labels the writer never had.
+def hollow_report_reason(intent_dir, disposition)
+  return nil unless disposition == "delivered"
+
+  outcome = File.join(intent_dir, "outcome.md")
+  return nil unless File.exist?(outcome)
+  text = File.read(outcome)
+  return nil if text.include?("<!-- backfilled from the record by end-intent on ")
+
+  # The gate's evidence bar (A7/B7): it judges only records that CLAIM the
+  # modern convention - at least one actions/*.md heading carrying an S-label.
+  # A terse legacy close with no labeled matrix stays report-and-proceed.
+  heading_labels = Dir.glob(File.join(intent_dir, "actions", "*.md")).sort.flat_map do |path|
+    ReportScreen.split_by_headings(File.read(path)).filter_map do |heading, _body|
+      heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/).find { |tok| tok.match?(/\AS\d+\z/) }
+    end
+  end.uniq
+  return nil if heading_labels.empty?
+
+  rows = ReportScreen.delivered_rows(intent_dir)
+  return "outcome.md ## Delivered renders no rows although a labeled action matrix exists" if rows.empty?
+
+  needs = ReportScreen.section_of(text, "## Needs you").gsub(/<!--.*?-->/m, "").strip
+  if !needs.empty? && needs != "None" && ReportScreen.needs_you_rows(intent_dir).empty?
+    return "## Needs you has content that would render as None"
+  end
+
+  labels = rows.map { |r| r[:label] }
+  if (labels & heading_labels).empty?
+    return "delivered row labels (#{labels.first(3).join(', ')}...) match no action-file heading (#{heading_labels.first(3).join(', ')}...)"
+  end
+  if rows.all? { |r| ReportScreen.proven_by(intent_dir, r[:label]) == ReportScreen::NOT_RECORDED }
+    return "every Proven-by cell renders not recorded although labeled action headings exist"
+  end
+
+  nil
+rescue StandardError => e
+  warn "end-intent: hollow-report gate crashed (#{e.message}); proceeding without it"
+  nil
+end
+
+# 317a S7 (D5, A8): stamp the live lock's run_mode into outcome.md frontmatter
+# INSIDE the close step - after the gate, before the INDEX move and the store
+# commit - so the stamped file rides the close commit and mode survives disarm.
+def stamp_outcome_mode(intent_dir)
+  data = Lock.read(intent_dir)
+  run_mode = data && data["run_mode"].to_s
+  return if run_mode.nil? || run_mode.empty?
+
+  path = File.join(intent_dir, "outcome.md")
+  return unless File.exist?(path)
+  text = File.read(path)
+  return unless text.start_with?("---")
+  head, body = text[3..].split("---", 2)
+  return if body.nil? || head.match?(/^mode:/)
+
+  File.write(path, "---#{head}mode: #{run_mode}\n---#{body}")
+rescue StandardError => e
+  warn "end-intent: mode stamp failed (#{e.message}); proceeding without it"
+end
+
 def stamp_outcome_summary(content, summary)
+
   return content if summary.nil? || summary.to_s.strip.empty?
 
   lines = content.lines
@@ -459,21 +531,21 @@ end
 
 # --- step 5: disarm (D2/D16, intent 188) ------------------------------------
 #
-# Injected seams (D2): bridge_reader defaults to the real Bridge.read (so the
-# dirty-worktree check can resolve the code worktree path without disarming
-# first), disarm defaults to the real Bridge.disarm_auto. Tests may inject
+# Injected seams (D2, re-pointed by intent 307): worktree_reader defaults to
+# Arm.worktree_block (so the dirty-worktree check can resolve the code worktree
+# path without disarming first), disarm defaults to Arm.disarm. Tests may inject
 # fakes for in-process unit coverage of this function; the subprocess-driven
 # end-to-end tests exercise the real defaults against a hermetic tmp home.
 #
 # Returns :ok, :dirty (exit 5), or :lock_remains (exit 3). A blank session
 # (D3's "no lock at all" fallback case) is a clean no-op: :ok, nothing touched.
 def run_disarm(intent_dir, id, session, discard_worktree_changes:,
-               bridge_reader: ->(sess, iid) { Bridge.read(sess, intent_id: iid) },
-               disarm: ->(sess, iid) { Bridge.disarm_auto(sess, intent_id: iid) })
+               worktree_reader: ->(dir) { Arm.worktree_block(intent_dir: dir) },
+               disarm: ->(sess, dir) { Arm.disarm(intent_dir: dir, session: sess) })
   return :ok if Bridge.blank?(session)
 
-  data = bridge_reader.call(session, id)
-  worktree_code = data.is_a?(Hash) ? data.dig("worktree", "code") : nil
+  block = worktree_reader.call(intent_dir)
+  worktree_code = block.is_a?(Hash) ? block["code"] : nil
 
   if worktree_code && Dir.exist?(worktree_code)
     begin
@@ -505,16 +577,15 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
     end
   end
 
-  disarm.call(session, id)
+  disarm.call(session, intent_dir)
 
-  # The /tmp bridge is only a cache; the durable lock file is the truth
-  # (AGENTS.md). `disarm_auto` no-ops entirely when no bridge resolves (a wiped
-  # /tmp, a resumed job under a new session id), which would otherwise strand a
-  # committed, terminal intent still holding its lock: the exact stalled
-  # completion this intent forbids. Pre-flight has already established that this
-  # session is the owner, a delegate, or the post-takeover owner, so clearing
-  # the durable lock directly IS safe, PROVIDED the lock actually present here
-  # is still ours to clear.
+  # The durable lock file is the truth (AGENTS.md). Arm.disarm releases as the
+  # lock's recorded owner, so a lock a delegate or a post-takeover owner is
+  # closing under a different key can survive it; that would strand a committed,
+  # terminal intent still holding its lock, the exact stalled completion this
+  # intent forbids. Pre-flight has already established that this session is the
+  # owner, a delegate, or the post-takeover owner, so clearing the durable lock
+  # directly IS safe, PROVIDED the lock actually present here is still ours to clear.
   #
   # TOCTOU fix (post-review hardening, intent 188): the first version of this
   # fallback read the lock's OWN recorded owner and handed it straight back to
@@ -556,8 +627,8 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
   end
 
   unless File.exist?(Lock.path(intent_dir))
-    if data.nil?
-      warn "end-intent: no bridge resolved for session #{session.inspect} (intent #{id}); " \
+    if block.nil?
+      warn "end-intent: no worktree block could be derived for intent #{id}; " \
            "the delivery lock was cleared directly from disk, but any worktree this intent " \
            "provisioned was NOT removed. Run /plastic-doctor to check for an orphaned worktree."
     end
@@ -621,16 +692,10 @@ def main(argv)
     exit 4
   end
 
-  run_structure_gate(id, store: store)
-
-  reason = OutcomeGuard.reason(intent_dir, disposition)
-  if reason
-    warn "end-intent: #{reason}"
-    exit 2
-  end
-
   if opts[:dry_run]
     puts "end-intent: dry run for #{File.basename(intent_dir)} (#{disposition})"
+    targets = BackfillIntent.targets_for(intent_dir)
+    puts "  would backfill: #{targets.empty? ? "(nothing)" : targets.join(", ")}"
     puts "  would stamp ## Outcome: #{opts[:outcome_summary].inspect}" if opts[:outcome_summary]
     puts "  would move INDEX.md entry from ## Active to #{index_target_heading(disposition)} (#{index_path})"
     puts "  would append index note: #{opts[:index_note].inspect}" if opts[:index_note]
@@ -653,9 +718,38 @@ def main(argv)
     end
   end
 
+  # 1. Backfill from the record (intent 308), then the structure self-check and the
+  # outcome guard, both report-only since 308.
+  run_backfill(intent_dir, store: store, id: id, disposition: disposition,
+               summary: opts[:outcome_summary])
+  run_structure_check(id, store: store)
+
+  reason = OutcomeGuard.reason(intent_dir, disposition)
+  warn "end-intent: outcome.md: #{reason} (proceeding; doctor --intent #{id} reports it)" if reason
+
+  # 1a2. The self-render gate (317a S9, D7): refuse a hollow delivered close
+  # BEFORE any terminal mutation - INDEX, savepoint, and store stay untouched
+  # on exit 7 (A9).
+  hollow = hollow_report_reason(intent_dir, disposition)
+  if hollow
+    if opts[:allow_hollow_report]
+      warn "end-intent: hollow delivered report overridden (--allow-hollow-report): #{hollow}"
+    else
+      warn "end-intent: refusing a hollow delivered close: #{hollow}"
+      warn "end-intent: write outcome.md's ## Delivered as the labeled | Row | What | table " \
+           "matching the action-file headings (templates/outcome.md shows the shape), " \
+           "or pass --allow-hollow-report to close anyway"
+      exit 7
+    end
+  end
+
+  # 1a3. Mode stamp (317a S7, D5): run_mode into outcome frontmatter while the
+  # lock still exists, so the stamped file rides the close commit.
+  stamp_outcome_mode(intent_dir)
+
   # 1b. Intent-file `## Outcome` summary stamp (no-op unless given).
   if opts[:outcome_summary]
-    intent_file = Bridge.intent_file(intent_dir)
+    intent_file = Savepoint.intent_file(intent_dir)
     if File.exist?(intent_file)
       original = File.read(intent_file)
       updated = stamp_outcome_summary(original, opts[:outcome_summary])
@@ -682,7 +776,7 @@ def main(argv)
   end
 
   # 3. Savepoint Done bookend (idempotent).
-  Bridge.append_terminal_savepoint(intent_dir, disposition)
+  Savepoint.append_terminal_savepoint(intent_dir, disposition)
 
   # 4. Store auto-commit, unless --no-commit. Scoped to this intent's own paths (D17):
   # never git add -A.

package/scripts/exec-worktree

@@ -2,8 +2,9 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# exec-worktree (intent 213, group 2) - finish an intent's code worktree: an order
-# precondition, then Worktree.finish (delivered merges + removes, abandoned removes only).
+# exec-worktree (intent 213, group 2) - finish an intent's code worktree: the dirty-worktree
+# guard, then Worktree.finish (delivered merges + removes, abandoned removes only). The order
+# precondition it once ran first was removed in 2.0 with the gates (intent 302).
 #
 # Usage:
 #   exec-worktree --store <path> --id <intent_id> --home <plastic_home> \
@@ -18,26 +19,17 @@
 # Steps performed:
 #   0. Resolve inputs: the intent dir, normalize --home, resolve the calling session
 #      (--session, else CLAUDE_CODE_SESSION_ID, else the existing delivery.lock's own
-#      recorded owner_session when non-blank, else nil; unlike start-intent, the
-#      lock-owner fallback IS used here, matching end-intent's teardown resolution order).
-#      Load the bridge (Bridge.read); a nil bridge means there is nothing to finish (exit
-#      0, loud: the worktree this intent provisioned, if any, was NOT removed). No
-#      worktree.code on the bridge means nothing was provisioned (exit 0).
-#   1. The order precondition (delivered only): calls the EXISTING
-#      Bridge.code_gate_decision predicate exactly as it exists. On an auto bridge that
-#      has not reached How, this BLOCKS (exit 2). Bridge.code_gate_decision returns nil
-#      UNCONDITIONALLY on a guided bridge (build.auto != true), so on a guided bridge
-#      this precondition is ADVISORY ONLY: it always passes and the run proceeds. This
-#      script is NOT the enforcement point either way; the hook layer
-#      (scripts/lib/bridge.rb code_gate_decision, wired through scripts/lib/edit_gates.rb)
-#      remains the actual gate. See scripts/lib/exec_worktree.rb's module doc for why the
-#      auto-only condition is never relaxed and never duplicated here.
-#   2. The dirty-worktree guard (delivered only): git status --porcelain on the code
+#      recorded owner_session when non-blank, else nil; the lock-owner fallback IS
+#      used here, matching end-intent's teardown resolution order).
+#      Derive the worktree block from projects.yml and the intent id (Arm.worktree_block;
+#      the /tmp bridge this once read was removed in 2.0, intent 307). No code worktree on
+#      disk means nothing was provisioned (exit 0).
+#   1. The dirty-worktree guard (delivered only): git status --porcelain on the code
 #      worktree. Not clean, or the check itself fails, fails CLOSED (exit 3), mirroring
 #      end-intent's dirty-worktree handling. abandoned skips this guard entirely: the
 #      branch survives and can be reclaimed, so a dirty worktree is not a reason to
 #      refuse.
-#   3. Finish: Worktree.finish(bridge_data, home:, runner:, merge: disposition ==
+#   2. Finish: Worktree.finish(bridge_data, home:, runner:, merge: disposition ==
 #      "delivered"). Worktree.finish is fail-open and never raises, so failure is
 #      detected by checking, for a delivered disposition only, whether the worktree
 #      directory still exists on disk afterward (release removes it on success).
@@ -49,8 +41,7 @@
 #   0  finished (merged or removed per disposition), or nothing to finish (no bridge
 #      resolved, or no code worktree recorded on the bridge)
 #   1  usage or path-resolution failure
-#   2  the order precondition blocked a delivered disposition (auto bridge, How not
-#      reached)
+#   2  retired in 2.0 (intent 302): was the order precondition; never emitted, never reused
 #   3  the worktree is not clean, or the merge/removal did not complete (delivered only)
 #   4  lock or session resolution failure
 

package/scripts/file-session-intent

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# file-session-intent (intent 301): backfill and close one session day ledger,
+# carrying its open items into a target day.
+#
+# Usage:
+#   file-session-intent --day <YYYYMMDD> [--carry-to <YYYYMMDD>] [--store <dir>]
+#                       [--templates <dir>] [--author <name>]
+#
+# --store defaults to $PLASTIC_HOME/store ($PLASTIC_HOME defaults to ~/.plastic).
+# Prints one line: `filed <day>` or `skipped <day>: closed`. Exit 0 on success
+# and on any filing error (reported on stderr; the next boot tries again), 2 on
+# a usage error.
+
+require_relative "lib/session_ledger"
+require_relative "lib/session_backfill"
+
+def usage_abort(message)
+  warn "file-session-intent: #{message}"
+  exit 2
+end
+
+def next_value!(argv, i, flag)
+  value = argv[i + 1]
+  usage_abort("#{flag} needs a value") if value.nil? || value.start_with?("--")
+  value
+end
+
+opts = { day: nil, carry_to: nil, store: nil, templates: nil, author: "session" }
+i = 0
+while i < ARGV.length
+  case ARGV[i]
+  when "--day"       then opts[:day] = next_value!(ARGV, i, "--day"); i += 1
+  when "--carry-to"  then opts[:carry_to] = next_value!(ARGV, i, "--carry-to"); i += 1
+  when "--store"     then opts[:store] = next_value!(ARGV, i, "--store"); i += 1
+  when "--templates" then opts[:templates] = next_value!(ARGV, i, "--templates"); i += 1
+  when "--author"    then opts[:author] = next_value!(ARGV, i, "--author"); i += 1
+  else usage_abort("unknown argument #{ARGV[i].inspect}")
+  end
+  i += 1
+end
+
+usage_abort("--day is required") if opts[:day].nil?
+usage_abort("--day must be a real calendar date, YYYYMMDD") unless SessionLedger.valid_day_id?(opts[:day])
+if opts[:carry_to] && !SessionLedger.valid_day_id?(opts[:carry_to])
+  usage_abort("--carry-to must be a real calendar date, YYYYMMDD")
+end
+
+store = opts[:store] || File.join(File.expand_path(ENV.fetch("PLASTIC_HOME", "~/.plastic")), "store")
+templates = opts[:templates] || File.expand_path("../templates", __dir__)
+
+begin
+  result = SessionBackfill.file_day(store: store, day: opts[:day], templates: templates,
+                                    author: opts[:author], carry_to: opts[:carry_to])
+  puts(result == :closed ? "skipped #{opts[:day]}: closed" : "filed #{opts[:day]}")
+rescue StandardError => e
+  warn "file-session-intent: #{opts[:day]} not filed: #{e.class}: #{e.message}"
+end
+exit 0