@zalom/plastic 2.0.0-alpha.3 → 2.0.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.4",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/intent-screen

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+# intent-screen (intent 316) - prints the intent screen for one intent directory:
+# the title, the field table (Store, Status, Stage, Savepoint, Progress, Next,
+# Insight, each with a note), and the Steps table, filled from the record by
+# scripts/lib/intent_screen.rb. The session adds the What-this-means bullets and
+# the close; it never edits the numbers.
+#
+# Usage:
+#   intent-screen <intent_dir> [--template <path>]
+#
+# The store root is the directory two levels above the intent (<root>/store/<id--slug>);
+# the template defaults to templates/intent-screen.md next to this script's dir,
+# in-repo (<repo>/scripts -> <repo>/templates) and installed (~/.plastic/scripts ->
+# ~/.plastic/templates) alike.
+#
+# Exit codes:
+#   0 - the screen is on stdout
+#   2 - usage error, or the path is not an intent directory (one line on stderr)
+
+require_relative "lib/intent_screen"
+
+def usage_abort(message)
+  warn "intent-screen: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+template_path = nil
+positional = []
+while (arg = args.shift)
+  case arg
+  when "--template"
+    template_path = args.shift or usage_abort("--template needs a path")
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+usage_abort("usage: intent-screen <intent_dir> [--template <path>]") unless positional.length == 1
+intent_dir = File.expand_path(positional.first)
+usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+
+store_root = File.expand_path("../..", intent_dir)
+template_path ||= File.expand_path("../templates/intent-screen.md", __dir__)
+usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+
+$stdout.write IntentScreen.render(intent_dir: intent_dir, store_root: store_root,
+                                  template: File.read(template_path))
+exit 0

package/scripts/lib/installer_core.rb

@@ -423,6 +423,8 @@ class InstallerCore
       "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",
     }
   end

package/scripts/lib/intent_screen.rb

@@ -0,0 +1,221 @@
+# 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.
+module IntentScreen
+  BAR_WIDTH = 20
+  ON = "█"
+  OFF = "░"
+  PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
+  SECTIONS = %w[Active Future Completed Abandoned].freeze
+  ITEM_RE = /^\s*- \[([ xX])\]\s+(.*)$/
+  STEP_PREFIX_RE = /\A(?:Step|S)\s*\d+\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/
+
+  # 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)
+    fields["meaning"] = ""
+    fields["close"] = ""
+
+    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?) : []
+    last = lines.reverse.map { |l| l.match(SAVEPOINT_RE) }.compact.first
+    unless last
+      return { "stage" => "Why", "stage.note" => "no savepoint line yet",
+               "savepoint" => "none", "savepoint.note" => "" }
+    end
+
+    ts, stage, milestone = last[1], last[2], last[3]
+    landing = landing_stage(stage, milestone)
+    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
+
+  def self.next_fields(items, status, checklist_present:)
+    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])
+    { "next" => "S#{idx + 1} · #{escape(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(item[:text])} |"
+    end.join("\n")
+  end
+
+  def self.escape(text)
+    text.gsub("|", "\\|")
+  end
+
+  # --- ## Insights ----------------------------------------------------------------
+
+  def self.insight_fields(intent_text)
+    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)
+    note = tail.empty? ? human_time(ts) : "#{human_time(ts)} · #{tail}"
+    { "insight" => escape(head), "insight.note" => escape(note) }
+  end
+
+  def self.split_first_clause(text)
+    m = text.match(/\A(.+?)[.;](\s+.*|\z)/m)
+    head = m ? m[1] : text
+    tail = m ? m[2].to_s.strip : ""
+    if head.length > 60
+      cut = head[0, 60].rindex(" ") || 60
+      tail = "#{head[cut..].strip} #{tail}".strip
+      head = head[0, cut].strip
+    end
+    [head, tail]
+  end
+end

package/skills/intent-continuing/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   where we left off", "where was I", "what should I work on", names a specific intent to
   resume (by id or description, or `--intent {id}`), or names a roadmap or delivery batch to
   resume (`--roadmap {slug}`, "where is the roadmap", "where did that batch land"). Presents
-  state and resumes at the last delivered station; it never asks auto or guided, never boots
+  state and resumes at the last delivered stage; it never asks auto or guided, never boots
   (the SessionStart hook owns boot), and never drives work autonomously (plastic-auto does).
   Absorbs the former continuing, project-continuing, and roadmap-continuing skills and the
   read half of the former intent-starting skill (intent 304).
@@ -79,19 +79,20 @@ QMD-first when the intent is named by description: run
 authoritative intent file. The command is a no-op when QMD is absent; fall back to
 `INDEX.md`.
 
-If the intent is terminal (`## Completed` or `## Abandoned` in `INDEX.md`): report only.
-Summarize its `outcome.md` and ask what is next; never reopen it.
+If the intent is terminal (`## Completed` or `## Abandoned` in `INDEX.md`): print the
+intent screen (Status shows the terminal section, Next is empty), summarize its
+`outcome.md`, and ask what is next; never reopen it.
 
 For a live intent's directory:
 
 1. **Read `savepoint.md` first.** It is a deterministic, append-only ledger, one line per
-   event, newest at the bottom: `{utc-iso8601}  {Stage}  {milestone}`. Classify the station
+   event, newest at the bottom: `{utc-iso8601}  {Stage}  {milestone}`. Classify the stage
    from the last line alone (the table in `references/boarding-matrix.md`, read when
    classifying), then verify only that line's artifact is real (sentinel-aware:
    `Savepoint.stage_file_present?`). Do not re-probe every lifecycle file.
-2. **Drift.** When the last line disagrees with the files on disk, rebuild the ledger from
+2. **Stale ledger.** When the last line disagrees with the files on disk, rebuild the ledger from
    disk and note the correction. A rebuilt ledger is the file-landing skeleton, which still
-   pins the station:
+   pins the stage:
    ```bash
    ruby -r ~/.plastic/scripts/lib/savepoint -e 'Savepoint.rebuild_savepoint("<intent_dir>")'
    ```
@@ -99,18 +100,16 @@ For a live intent's directory:
    else the newest prior day) is the prior session's own account of where things stand; read
    it after the ledger, never instead of it.
 4. **Derive the next step:** the first unchecked item in `checklist.md` when it exists, else
-   the next thing the station needs (see the matrix). The newest `## Insights` entry supplies
+   the next thing the stage needs (see the matrix). The newest `## Insights` entry supplies
    the human-readable context; an entry marked `(autonomous)` means an auto team was
    delivering it, so say so and offer to hand back to `plastic-auto`.
-5. **Announce, then continue at that station:**
-   ```
-   Resuming intent [ID] - [name]
-   Store: [global | project:<slug>]
-   Station: [from the ledger's last line]
-   Next step: [first unchecked checklist item | what the station needs]
-   Context: [newest ## Insights entry | hand-off summary]
-   Drift: [none | ledger rebuilt from disk]
-   ```
+5. **Print the intent screen, then continue at that stage.** Run
+   `ruby ~/.plastic/scripts/intent-screen <intent_dir>` and print its output as it is: the
+   title, the field table, and the Steps table come from the record, never by eye. Under it
+   write **What this means** as two to four bullets in plain words (what the intent is for,
+   what has landed, what is left, any defect named by step), then close with
+   **needs input:** naming the first open step. The screen's shape is
+   `~/.plastic/templates/intent-screen.md`; the script fills it, the session never edits the numbers.
    Then continue the work in the session's current mode. In auto mode the running team
    already holds the delivery lock; if a lock is held by a session that is gone, the
    `plastic-doctor` skill's lock section repairs or reclaims it.
@@ -141,6 +140,6 @@ For a live intent's directory:
 | Trigger | Read |
 |---|---|
 | Filling the board on the project route | `references/board-fill.md` |
-| Classifying the station from the ledger's last line | `references/boarding-matrix.md` |
+| Classifying the stage from the ledger's last line | `references/boarding-matrix.md` |
 | Explaining why one roadmap ranked above another | `references/liveness-ranking.md` |
 | Saving or restoring context across a long session, or debugging a resume | `references/context-management.md` |

package/skills/intent-continuing/references/boarding-matrix.md

@@ -1,8 +1,8 @@
-# Boarding matrix: which station a resume lands at
+# Boarding matrix: which stage a resume lands at
 
-The station is derived from `savepoint.md`'s last line plus the real artifacts on disk.
+The stage is derived from `savepoint.md`'s last line plus the real artifacts on disk.
 Classify from the last line alone, then verify only that line's artifact is real
-(sentinel-aware). On drift, rebuild the ledger from disk and note it.
+(sentinel-aware). When the ledger is stale, rebuild it from disk and note it.
 
 | savepoint last line | latest delivered | lands at | continue with |
 |---|---|---|---|
@@ -10,11 +10,11 @@ Classify from the last line alone, then verify only that line's artifact is real
 | `Why  started` (spec still sentinel) | What | **Why** | continue the conversation; rulings land as insights |
 | `Why  spec.md created` | Why | **How** | the action files, `plan.md`, `checklist.md` |
 | `How  started` / `How  plan.md created` | (How in progress) | **How** | finish `plan.md` and `checklist.md` |
-| `How  checklist.md created` / `Exec  started` | How | **Exec** | do the work, tick the checklist |
+| `How  checklist.md created` / `Exec  started` | How | **Exec** | do the work, check off the checklist |
 | `Exec  outcome.md created` | Exec | **ready to complete** | the ending procedure (`plastic-intent-ending`) |
 | `Done  delivered` / `Done  abandoned` | terminal | **report only** | immutable; ask what is next |
 
-## Per-station behaviour (what "continue" means)
+## Per-stage behaviour (what "continue" means)
 
 - **Why**: continue the conversation, or run the work directly when the request is already
   clear; every ruling is recorded as it lands.

package/skills/intent-continuing/references/context-management.md

@@ -19,7 +19,7 @@ step looks stale):
    (see `SKILL.md`'s `## Conditional Ledger-Resume` for the full state table).
 2. Confirm the artifact that line implies (`plan.md`, `checklist.md`, `outcome.md`, ...) is
    present and non-empty on disk.
-3. If the two disagree, the ledger has drifted: rebuild it rather than hand-editing:
+3. If the two disagree, the ledger is stale: rebuild it rather than hand-editing:
    `ruby -r ~/.plastic/scripts/lib/savepoint -e 'Savepoint.rebuild_savepoint("<intent_dir>")'`
 4. Re-read the rebuilt last line and re-derive the next step from `checklist.md`'s first
    unchecked item.

package/templates/intent-screen.md

@@ -0,0 +1,22 @@
+## ▶ {{id}} · {{name}}
+
+| | | |
+| --- | --- | --- |
+| **Store** | {{store}} | {{store.note}} |
+| **Status** | {{status}} | {{status.note}} |
+| **Stage** | {{stage}} | {{stage.note}} |
+| **Savepoint** | {{savepoint}} | {{savepoint.note}} |
+| **Progress** | {{progress.bar}} {{progress.done}} / {{progress.total}} | {{progress.note}} |
+| **Next** | {{next}} | {{next.note}} |
+| **Insight** | {{insight}} | {{insight.note}} |
+
+**What this means**
+{{meaning}}
+
+**Steps**
+
+| Step | Status | What |
+| --- | --- | --- |
+{{steps.rows}}
+
+{{close}}