@zalom/plastic 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/end-intent

@@ -34,13 +34,17 @@
 #      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
-#      the id/title separator on READ (shared matcher, IndexEntry.match);
-#      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.
+#   2. Move the intent's INDEX.md line from `## Active` or `## Future` into
+#      `## Completed` (delivered) or `## Abandoned` (abandoned), dated today,
+#      appending --index-note (if given). Accepts a real em dash OR a plain
+#      hyphen as the id/title separator on READ (shared matcher,
+#      IndexEntry.match); always EMITS the real em dash on write. The move is
+#      resolved before step 1 writes anything (intent 385): an id that
+#      resolves to neither an open section nor the terminal section is a loud
+#      failure (exit 1) that writes nothing, in the dry run too; an id already
+#      correctly in the terminal section is a quiet, idempotent success. A
+#      missing INDEX.md is not a refusal: the move is skipped with a warning,
+#      and the dry run says so.
 #   3. Append the savepoint `Done` bookend (Savepoint.append_terminal_savepoint).
 #   4. Commit the store repo, unless --no-commit.
 #   5. Disarm (intent 188, D2/D16; intent 307): check the code worktree (derived
@@ -56,8 +60,9 @@
 #
 # 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.
+#   1  usage/resolution failure, OR an id that resolves to neither ## Active,
+#      ## Future, nor the terminal section (D11). Deliberately double duty;
+#      see plan.md. Refused before any write.
 #   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 (see step 5 above).
@@ -78,7 +83,7 @@
 #      repo checkout's current branch. Refused before any write: nothing is
 #      merged, written, or released. Merge the branch, then run the close again.
 #
-# --dry-run runs the same refusals as the real close (exits 8, 9, 7 and 5 with
+# --dry-run runs the same refusals as the real close (exits 1, 8, 9, 7 and 5 with
 # a "would refuse" line) and writes nothing: the hollow-report gate is judged
 # on a scratch copy that went through the same outcome generation and
 # backfill.
@@ -113,10 +118,15 @@ DISPOSITIONS = %w[delivered abandoned].freeze
 # (intent 188, D9/D12): see move_index_to_terminal below.
 EM_DASH = "\u2014"
 
-# Raised internally when the INDEX id resolves to neither `## Active` nor the
-# terminal section (D11): the caller (main) rescues this and exits 1.
+# Raised internally when the INDEX id resolves to neither an open section nor
+# the terminal section (D11): the caller (main) rescues this and exits 1.
 class UnresolvedIndexEntry < StandardError; end
 
+# The INDEX sections an intent can still be closed from, searched in order
+# (intent 385): a Future intent is retired through the same path as an
+# Active one.
+OPEN_HEADINGS = ["## Active", "## Future"].freeze
+
 # --- Explicit flag parsing (no eval, no global injection) -------------------
 
 def blank?(value)
@@ -467,19 +477,32 @@ def section_contains_id?(lines, heading_idx, id)
   (heading_idx + 1...stop).any? { |i| active_line_id(lines[i]) == id }
 end
 
-# Remove the entry at entry_idx from the `## Active` section. When no real
+# The first open section holding the id's entry, as [heading, heading_idx,
+# entry_idx], or nil when no open section holds it.
+def find_open_entry(lines, id)
+  OPEN_HEADINGS.each do |heading|
+    start = lines.index { |l| l.rstrip == heading }
+    next unless start
+
+    entry_idx = (start + 1...section_stop(lines, start)).find { |i| active_line_id(lines[i]) == id }
+    return [heading, start, entry_idx] if entry_idx
+  end
+  nil
+end
+
+# Remove the entry at entry_idx from its open section. When no real
 # entries remain, install the canonical "_(none)_" placeholder (the same
 # empty-state convention INDEX.md already uses).
-def remove_active_entry(lines, active_start, entry_idx)
+def remove_open_entry(lines, section_start, entry_idx)
   new_lines = lines.dup
   new_lines.delete_at(entry_idx)
-  stop = section_stop(new_lines, active_start)
-  remaining = (active_start + 1...stop).reject { |i| new_lines[i].strip.empty? }
+  stop = section_stop(new_lines, section_start)
+  remaining = (section_start + 1...stop).reject { |i| new_lines[i].strip.empty? }
   if remaining.empty?
     # Keep the blank-line separator before the next heading (if any); only
     # collapse the section body to the placeholder, never the spacing.
     placeholder = (stop < new_lines.length) ? ["_(none)_\n", "\n"] : ["_(none)_\n"]
-    new_lines[(active_start + 1)...stop] = placeholder
+    new_lines[(section_start + 1)...stop] = placeholder
   end
   new_lines
 end
@@ -503,34 +526,30 @@ def insert_terminal_entry(lines, target_start, new_entry)
   new_lines
 end
 
-# Move the intent's `## Active` line into the terminal section. Returns the
-# new INDEX.md content on success. Raises UnresolvedIndexEntry (D11) when the
-# id resolves to NEITHER `## Active` NOR the terminal section (including the
-# degenerate case where one of the two headings is missing from INDEX.md
-# entirely); returns the content UNCHANGED (a quiet, idempotent success) when
-# the id is already correctly present in the terminal section, whether or not
-# a stray duplicate also still sits under `## Active` (that duplicate is
-# cleaned up too, when found, matching the pre-188 idempotent-cleanup
-# behavior for the ordinary already-moved re-run case).
+# Move the intent's `## Active` or `## Future` line into the terminal
+# section. Returns the new INDEX.md content on success. Raises
+# UnresolvedIndexEntry (D11) when the id resolves to NEITHER an open section
+# NOR the terminal section (including the degenerate case where the headings
+# are missing from INDEX.md entirely); returns the content UNCHANGED (a quiet,
+# idempotent success) when the id is already correctly present in the
+# terminal section, whether or not a stray duplicate also still sits in an
+# open section (that duplicate is cleaned up too, when found, matching the
+# pre-188 idempotent-cleanup behavior for the ordinary already-moved re-run
+# case).
 def move_index_to_terminal(content, id, disposition, today:, index_note: nil)
   target_heading = index_target_heading(disposition)
   lines = content.lines
 
   target_start = lines.index { |l| l.rstrip == target_heading }
-  active_start = lines.index { |l| l.rstrip == "## Active" }
   already_in_target = target_start && section_contains_id?(lines, target_start, id)
 
-  entry_idx = nil
-  if active_start
-    active_stop = section_stop(lines, active_start)
-    entry_idx = (active_start + 1...active_stop).find { |i| active_line_id(lines[i]) == id }
-  end
+  _heading, source_start, entry_idx = find_open_entry(lines, id)
 
   if entry_idx.nil?
     return content if already_in_target # true idempotency (D11): quiet success
     raise UnresolvedIndexEntry,
-          "intent #{id} could not be resolved: not found under ## Active, and not already " \
-          "present in #{target_heading} (check INDEX.md for a malformed or missing entry)"
+          "intent #{id} could not be resolved: not found under #{OPEN_HEADINGS.join(" or ")}, and not " \
+          "already present in #{target_heading} (check INDEX.md for a malformed or missing entry)"
   end
 
   if target_start.nil?
@@ -542,7 +561,7 @@ def move_index_to_terminal(content, id, disposition, today:, index_note: nil)
   note_suffix = (index_note && !index_note.to_s.strip.empty?) ? " #{index_note.to_s.strip}" : ""
   new_entry = "- [#{id} #{EM_DASH} #{title}](#{link}) #{EM_DASH} #{today}#{note_suffix}\n"
 
-  lines = remove_active_entry(lines, active_start, entry_idx)
+  lines = remove_open_entry(lines, source_start, entry_idx)
   target_start = lines.index { |l| l.rstrip == target_heading }
   lines = insert_terminal_entry(lines, target_start, new_entry) unless already_in_target
 
@@ -563,7 +582,27 @@ def warn_if_active_duplicate_remains(content, id)
 
   warn "end-intent: intent #{id} still has an entry under ## Active after the move " \
        "(a duplicate ## Active line for this id); INDEX.md needs manual cleanup. Check " \
-       "INDEX.md directly, or run /plastic-doctor."
+       "INDEX.md directly, or run `plastic doctor`."
+end
+
+# The dry-run line for the INDEX move the close will make, resolved on the
+# current INDEX.md before anything is written (intent 385), so the preview
+# and the real close refuse the same unresolvable entry. Exits 1 on
+# UnresolvedIndexEntry, exactly as step 2 would, but before step 1 writes.
+def preflight_index_move(index_path, id, disposition, today:, index_note:)
+  target = index_target_heading(disposition)
+  return "INDEX.md not found at #{index_path}, would skip the terminal move" unless File.exist?(index_path)
+
+  content = File.read(index_path)
+  move_index_to_terminal(content, id, disposition, today: today, index_note: index_note)
+  source, = find_open_entry(content.lines, id)
+  return "INDEX.md entry already in #{target}, would leave it (#{index_path})" unless source
+
+  "would move INDEX.md entry from #{source} to #{target} (#{index_path})"
+rescue UnresolvedIndexEntry => e
+  warn "end-intent: #{e.message}"
+  warn "end-intent: nothing was written"
+  exit 1
 end
 
 # --- store auto-commit (D2 step 4) ------------------------------------------
@@ -731,7 +770,7 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
         # let the caller sort it out.
         warn "end-intent: the delivery lock at #{Lock.path(intent_dir)} is now held by " \
              "#{current['owner_session'].inspect}, which acquired it during this close; " \
-             "refusing to delete another session's lock. Run /plastic-doctor to check the " \
+             "refusing to delete another session's lock. Run `plastic doctor` to check the " \
              "lock status."
       end
       # current.nil? here means the lock is corrupt/unparseable; nothing to
@@ -746,13 +785,13 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
     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."
+           "provisioned was NOT removed. Run `plastic doctor` to check for an orphaned worktree."
     end
     return :ok
   end
 
   warn "end-intent: the delivery lock at #{Lock.path(intent_dir)} is still present after " \
-       "disarm and a direct release attempt. Run /plastic-doctor to check the lock status."
+       "disarm and a direct release attempt. Run `plastic doctor` to check the lock status."
   :lock_remains
 end
 
@@ -954,7 +993,7 @@ def main(argv)
     warn "end-intent: a delivery lock exists at #{Lock.path(intent_dir)} but no session " \
          "identity could be resolved (--session, CLAUDE_CODE_SESSION_ID, and the lock's " \
          "own recorded owner are all blank); refusing rather than guessing. Pass " \
-         "--session explicitly, or run /plastic-doctor check the lock status."
+         "--session explicitly, or run `plastic doctor` to check the lock status."
     exit 4
   end
 
@@ -962,7 +1001,7 @@ def main(argv)
 
   if verdict == :refuse
     warn "end-intent: delivery lock for #{id} is held by a live session " \
-         "(#{lock_data['owner_session']}); refusing to close. Run /plastic-doctor check " \
+         "(#{lock_data['owner_session']}); refusing to close. Run `plastic doctor` to check " \
          "the lock status"
     exit 4
   end
@@ -970,7 +1009,7 @@ def main(argv)
   if verdict == :refuse_corrupt
     warn "end-intent: the delivery lock at #{Lock.path(intent_dir)} exists and is fresh, " \
          "but its content will not parse (corrupt); refusing to close since another " \
-         "session may be actively heartbeating it. Run /plastic-doctor check the lock " \
+         "session may be actively heartbeating it. Run `plastic doctor` to check the lock " \
          "status, or plastic-lock fix once it is confirmed safe."
     exit 4
   end
@@ -994,6 +1033,11 @@ def main(argv)
     end
   end
 
+  # Resolve the INDEX move before any write (intent 385), in the dry run and the
+  # real close alike: an entry the move cannot find refuses here, not after the
+  # backfill has already written into the intent directory.
+  index_move = preflight_index_move(index_path, id, disposition, today: today, index_note: opts[:index_note])
+
   if opts[:dry_run]
     hollow = predicted_hollow_reason(intent_dir, store: store, id: id, disposition: disposition,
                                                  summary: opts[:outcome_summary])
@@ -1014,7 +1058,7 @@ def main(argv)
     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 "  #{index_move}"
     puts "  would append index note: #{opts[:index_note].inspect}" if opts[:index_note]
     puts "  would append savepoint bookend: Done  #{disposition}"
     puts(opts[:no_commit] ? "  would skip store commit (--no-commit)" : "  would commit the store repo")
@@ -1030,7 +1074,7 @@ def main(argv)
     takeover_status, = Lock.takeover(intent_dir, session: session)
     unless takeover_status == :taken
       warn "end-intent: could not take over the stale delivery lock for #{id} " \
-           "(status: #{takeover_status}); run /plastic-doctor fix the lock"
+           "(status: #{takeover_status}); run `plastic doctor` to inspect the lock"
       exit 4
     end
   end

package/scripts/lib/cli/commands/intent_end.rb

@@ -42,7 +42,7 @@ module Plastic
           if options[:dry_run]
             @output.next_step("none", because: "the dry run wrote nothing and found nothing that would refuse the close")
           else
-            @output.next_step("plastic status", because: "the intent moved out of Active")
+            @output.next_step("plastic status", because: "the intent is now closed")
           end
         end
 

package/scripts/lib/revisions_writer.rb

@@ -3,8 +3,7 @@
 
 # RevisionsWriter - the shared append-only revisions.md writer (intent 107's convention,
 # generalized from restore_intent_v1.rb's proven pattern, intent 197). Every tool that
-# performs structural maintenance on an intent (project-links, rebuild-graph,
-# restore-intent-v1) must record it here: PLASTIC.md's `revisions.md` contract is that a
+# uses this writer (project-links, rebuild-graph, or rebuild-savepoint) records changes here: PLASTIC.md's `revisions.md` contract is that a
 # structural change and its receipt are never separated. This module owns rendering ONE
 # entry's text and appending it correctly; it does no git operations (that is
 # lib/maintenance_git.rb's job) and never overwrites a prior entry.

package/skills/_decision-tables.md

@@ -1,10 +1,10 @@
 ## Numbered Decision Tables
 
 The shared procedure for collecting owner rulings during any stage (Why, How, Exec).
-Any stage skill that needs the owner to choose between options or rule on a batch of
-open questions follows this procedure instead of improvising its own format.
+An agent that needs the owner to choose between options or rule on a batch of open
+questions follows this procedure instead of improvising its own format.
 
-Read this when a stage skill's own text says to.
+The installer copies this file to `~/.plastic/_decision-tables.md`.
 
 ### The procedure