@zalom/plastic 1.14.0 → 2.0.0-alpha.1

package/scripts/session-commit

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# session-commit (intent 300) - makes one commit for a verified checklist
+# item on the right branch of the repo that contains `--cwd`, applying the
+# branch model and per-repo flow settings in `scripts/lib/session_git.rb`.
+# Idempotent and fail-open: no repository, a detached HEAD, a clean tree, an
+# agent-owned branch, a refused push, a missing `gh`, or a rejected
+# commit-msg hook all degrade to no commit plus a Note savepoint line,
+# never a non-zero exit (spec D1).
+#
+# Usage:
+#   session-commit --cwd <dir> --summary <text> [--session <id>] [--day <YYYYMMDD>]
+#                   [--store <dir>] [--plastic-home <dir>]
+#
+# Exit codes:
+#   0 - always, except a usage error
+#   2 - usage error (missing --cwd or --summary); nothing is written
+
+require "fileutils"
+require_relative "lib/session_git"
+require_relative "lib/session_ledger"
+
+def usage_abort(message)
+  warn "session-commit: #{message}"
+  exit 2
+end
+
+def next_value!(argv, i, flag)
+  usage_abort("#{flag} requires a value") if i + 1 >= argv.length
+  argv[i + 1]
+end
+
+def parse_args(argv)
+  opts = { cwd: nil, summary: nil, session: nil, day: nil, store: nil, plastic_home: nil }
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--cwd"          then opts[:cwd] = next_value!(argv, i, arg); i += 1
+    when "--summary"      then opts[:summary] = next_value!(argv, i, arg); i += 1
+    when "--session"      then opts[:session] = next_value!(argv, i, arg); i += 1
+    when "--day"          then opts[:day] = next_value!(argv, i, arg); i += 1
+    when "--store"        then opts[:store] = next_value!(argv, i, arg); i += 1
+    when "--plastic-home" then opts[:plastic_home] = next_value!(argv, i, arg); i += 1
+    else
+      usage_abort("unknown flag #{arg.inspect}")
+    end
+    i += 1
+  end
+  opts
+end
+
+def expand(path)
+  File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+end
+
+# Sibling of this script's dir, matching append-ledger's own resolution:
+# in-repo (<repo>/scripts/session-commit -> <repo>/templates) and installed
+# (~/.plastic/scripts/session-commit -> ~/.plastic/templates).
+def default_templates_dir
+  File.expand_path("../templates", __dir__)
+end
+
+# The fail-open guarantee (spec D1: exit 0 always, except a usage error)
+# must survive a store or ledger failure too (review R2), not only a git
+# failure: a read-only store, a damaged install missing templates/, or any
+# other write failure used to sit outside every rescue, so the CLI could
+# exit 1 with a raw Ruby backtrace on stderr and zero savepoint lines, even
+# after the git commit itself had already landed. `main`'s own body is
+# wrapped so nothing here can turn into a crash; the ledger write is a
+# second, inner rescue so a lost savepoint line never also swallows the
+# result the caller already needs on stdout.
+def main(argv)
+  opts = parse_args(argv)
+  usage_abort("--cwd is required") if opts[:cwd].nil?
+  usage_abort("--summary is required") if opts[:summary].nil?
+
+  plastic_home = expand(opts[:plastic_home] || ENV.fetch("PLASTIC_HOME", "~/.plastic"))
+  store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
+  cwd = expand(opts[:cwd])
+
+  day = opts[:day] || SessionLedger.day_id
+  session = SessionLedger.short_session_id(opts[:session], ENV["CLAUDE_CODE_SESSION_ID"])
+  project = SessionLedger.project_slug(cwd, plastic_home: plastic_home)
+
+  begin
+    templates = default_templates_dir
+    SessionLedger.open_day(store: store, day: day, templates: templates, author: session) if Dir.exist?(templates)
+  rescue StandardError => e
+    warn "session-commit: could not open the day ledger: #{e.message}"
+  end
+
+  result = SessionGit.commit!(cwd: cwd, summary: opts[:summary], day: day, session: session,
+                               plastic_home: plastic_home, store: store)
+
+  begin
+    # Does not depend on open_day having run: a damaged install with no
+    # templates/, or a store error above, must not also block the append.
+    savepoint_path = SessionLedger.savepoint_path(store, day)
+    FileUtils.mkdir_p(File.dirname(savepoint_path))
+    line = SessionLedger.savepoint_line(result.event, session, project, result.message, now: Time.now)
+    SessionLedger.append_line(savepoint_path, line, header: nil)
+  rescue StandardError => e
+    warn "session-commit: could not write the savepoint line: #{e.message}"
+  end
+
+  puts result.message
+  exit 0
+rescue StandardError => e
+  warn "session-commit: #{e.message}"
+  exit 0
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/spawn-preamble

@@ -22,7 +22,7 @@
 #
 # Exit codes: 0 (preamble emitted), 2 (usage).
 
-require_relative "lib/bridge"
+require_relative "lib/savepoint"
 require_relative "lib/worktree"
 
 # Verbatim honoring instruction. Kept as one constant so the contract doc and the
@@ -56,7 +56,7 @@ REPORT_CONTRACT =
   "insights field carrying 0..N durable nuggets (what I discovered worth keeping, " \
   "the most interesting residue of this turn; none if there were none); plus a " \
   "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
-  "(for example the planner explains the plan back to the orchestrator). Populate " \
+  "(for example the executor reports what was built and the test result). Populate " \
   "the insights field even when you cannot write the intent file yourself: a " \
   "background or dispatched agent carries each nugget home in the report and the " \
   "orchestrator persists it via scripts/insight-append, so an insight never " \
@@ -90,7 +90,7 @@ end
 # id/intent we report match what the rest of Plastic sees. Returns a Hash (possibly
 # empty) — never raises.
 def frontmatter_for(intent_dir)
-  ifile = Bridge.intent_file(intent_dir)
+  ifile = Savepoint.intent_file(intent_dir)
   return {} unless File.exist?(ifile)
 
   content = File.read(ifile)
@@ -116,12 +116,12 @@ STAGE_LABELS = {
 }.freeze
 
 def current_stage(intent_dir)
-  ledger = File.join(intent_dir, Bridge::SAVEPOINT_FILE)
+  ledger = File.join(intent_dir, Savepoint::SAVEPOINT_FILE)
   if File.exist?(ledger)
     last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
     return last if last
   end
-  STAGE_LABELS.fetch(Bridge.derive_stage(intent_dir), Bridge.derive_stage(intent_dir))
+  STAGE_LABELS.fetch(Savepoint.derive_stage(intent_dir), Savepoint.derive_stage(intent_dir))
 end
 
 intent_dir_arg, role, step = parse_args(ARGV)

package/scripts/update.rb

@@ -3,7 +3,7 @@
 # frozen_string_literal: true
 
 # Plastic — `update` verb. Runs via `npx @zalom/plastic update` (bin/plastic.js) or directly.
-# Usage: ruby scripts/update.rb [--beta|--latest|--alpha] [--claude|--codex|--hermes|--all] [--help]
+# Usage: ruby scripts/update.rb [--beta|--latest|--alpha] [--yes] [--claude|--codex|--hermes|--all] [--help]
 #
 # Forward-only version transitions, sourced from npm dist-tags:
 #   - no flag                = next version on the CURRENT channel (derived from VERSION)
@@ -62,7 +62,7 @@ class Update < InstallerCore
       warn "No published version on the #{requested} channel."
       return 1
     when :ok
-      if res[:kind] == :cross_bleeding && !confirm_bleeding(iv, res[:target])
+      if res[:kind] == :cross_bleeding && !confirm_bleeding(iv, res[:target], argv)
         puts "Aborted."
         return 1
       end
@@ -222,7 +222,10 @@ class Update < InstallerCore
     nil
   end
 
-  def confirm_bleeding(current, target)
+  # --yes (intent 310) answers the bleeding-edge question without a tty, so a script or an
+  # agent can run `update --alpha --yes`; without it a non-tty run aborts as before.
+  def confirm_bleeding(current, target, argv = [])
+    return true if argv.include?("--yes")
     return false unless $stdin.tty?
     print "Switch from #{current} to the less-stable #{target}? [y/N]: "
     ($stdin.gets&.strip || "").downcase.start_with?("y")
@@ -248,6 +251,7 @@ class Update < InstallerCore
         --latest      Switch to / advance the stable channel
         --beta        Switch to / advance the beta channel
         --alpha       Switch to / advance the alpha channel (bleeding edge — confirmed)
+        --yes         Confirm a switch toward bleeding edge without a prompt (scripts, agents)
 
       Agent options (default: --claude):
         --claude --codex --hermes --all

package/skills/agent-advisor/SKILL.md

@@ -33,7 +33,7 @@ when the ordering decides where you spend the next day.
 Never buy a consultation for: anything a tool can answer (search, reading code, running
 tests, documentation), writing code at volume, confirming a decision you already made,
 style or naming a linter would settle, or anything reversible and cheap you have not
-tried first. The full buy/never-buy list, the tier table, and the entry test live in
+tried first. The full buy/never-buy list, the effort table, and the entry test live in
 `references/advisor-protocol.md`; read it before writing a brief for the first time in
 a session.
 
@@ -50,7 +50,7 @@ a session.
    advisor is disabled and point at "Setting the default" below.
 4. Dispatch the resolved agent with a brief built per `references/advisor-protocol.md`
    section 4 (natural prose, the block is a completeness check, not a form to fill).
-   State TIER (S, M, or L) and EFFORT explicitly; classify low and prove your way up,
+   State EFFORT and the answer shape explicitly; classify low and prove your way up,
    never open high "to be safe".
 5. Consume the answer per the protocol's section 5: run the Operating Manual's
    five-question self-test on the advisor's plan before executing it. Advice is input,
@@ -86,7 +86,7 @@ the new default back to the user in one line.
 ## References
 
 - `references/advisor-protocol.md`: the full shipped Advisor Protocol (what to buy,
-  tiers and effort, the entry test, how to write a brief that earns its cost, the
+  effort and answer shape, the entry test, how to write a brief that earns its cost, the
   answer contract, session economics, anti-patterns). Read it before the first
   consultation in a session; the second consultation in the same advisor thread costs a
   fraction of the first, so keep follow-ups on one thread rather than opening a new one.

package/skills/agent-advisor/references/advisor-protocol.md

@@ -5,9 +5,9 @@
 *Adapted for Plastic (intent 185): this is the shipped reference copy the
 `plastic-agent-advisor` skill teaches from. Two named agents carry it,
 `plastic-advisor` (the real advisor) and `plastic-faux-advisor` (the cheaper
-imitation, the same discipline at a fraction of the cost); TIER and EFFORT
-below shape the brief and the answer on whichever one you dispatch, never
-which file to pick, since there is no longer one file per tier. The
+imitation, the same discipline at a fraction of the cost); EFFORT and the
+answer shape below shape the brief and the answer on whichever one you
+dispatch, never which file to pick. The
 `plastic-agent-advisor` skill reads harness-scoped config
 (`advisor.claude.default`, falling back to `secondary`, then to
 `plastic-faux-advisor`) to route your consultation automatically; name a
@@ -53,26 +53,26 @@ You own the work and the outcome. Fable owns the hardest thinking, on demand.
 
 ---
 
-## 2. Tiers and effort
+## 2. Effort and answer shape
 
-Classify every consultation before sending it. Default to S and prove your way
-up. Never open at a higher effort "to be safe": effort follows the cost of being
+Classify every consultation before sending it. Default to the smallest shape and
+prove your way up. Never open at a higher effort "to be safe": effort follows the cost of being
 wrong, not the importance the task feels like it has.
 
-| Tier | Coding | Business | Research | Effort | Brief size | Expected return |
+| Shape | Coding | Business | Research | Effort | Brief size | Expected return |
 |------|--------|----------|----------|--------|------------|-----------------|
-| **S** | Verdict on one step; choose between two named implementations | Pick between two options you already compared (vendor, pricing point) | Judge whether one source or result is trustworthy enough to build on | `low` | Under 300 words | Verdict, one paragraph of reasoning, the single biggest risk |
-| **M** | Plan a feature inside one system; review a full plan for holes; design one interface; rank root causes | Positioning or pricing decision from a compiled evidence pack; review a proposal before sending it | Design a research plan for a bounded question; rank competing explanations of the data you gathered | `medium`, or `high` if an irreversible step is inside | Up to one page | Decision, numbered plan with per-step checks, risk map |
-| **L** | Cross-system architecture; migration with one-way doors; deadlock after two failed attempts; security-critical design | Build-vs-buy, market entry, or any commitment measured in months; strategy where reversal is expensive | Synthesis across many sources where the conclusion drives a large bet; contested questions with conflicting evidence | `xhigh`; `max` only when being wrong means data loss, a broken contract, or weeks of rework | Full evidence brief | Decision, plan, risk register, kill criteria, list of what could not be verified |
+| **Verdict** | Verdict on one step; choose between two named implementations | Pick between two options you already compared (vendor, pricing point) | Judge whether one source or result is trustworthy enough to build on | `low` | Under 300 words | Verdict, one paragraph of reasoning, the single biggest risk |
+| **Plan** | Plan a feature inside one system; review a full plan for holes; design one interface; rank root causes | Positioning or pricing decision from a compiled evidence pack; review a proposal before sending it | Design a research plan for a bounded question; rank competing explanations of the data you gathered | `medium`, or `high` if an irreversible step is inside | Up to one page | Decision, numbered plan with per-step checks, risk map |
+| **Architecture** | Cross-system architecture; migration with one-way doors; deadlock after two failed attempts; security-critical design | Build-vs-buy, market entry, or any commitment measured in months; strategy where reversal is expensive | Synthesis across many sources where the conclusion drives a large bet; contested questions with conflicting evidence | `xhigh`; `max` only when being wrong means data loss, a broken contract, or weeks of rework | Full evidence brief | Decision, plan, risk register, kill criteria, list of what could not be verified |
 
-**Escalate one tier when any of these holds:**
+**Escalate one shape when any of these holds:**
 
 - Two attempts failed and you cannot explain why.
 - The next step is irreversible.
 - The scope crossed a system boundary since you last consulted.
 - Your confidence has stopped tracking your evidence.
 
-**Front-load.** One L consultation at plan time is cheaper than five M
+**Front-load.** One architecture consultation at plan time is cheaper than five plan
 consultations during execution. Spend early, at the point of maximum leverage.
 
 ---
@@ -142,7 +142,7 @@ briefing described above; use the block as your completeness check before
 sending. Fable must never need to explore.
 
 ```
-TIER: S | M | L        EFFORT: low | medium | high | xhigh | max
+SHAPE: verdict | plan | architecture        EFFORT: low | medium | high | xhigh | max
 DOMAIN: coding | business | research
 GOAL: <target state in one sentence, and the decision this answer feeds>
 QUESTIONS:
@@ -186,7 +186,7 @@ reformat, then work with what you have.
    verify before starting, which failure mode from the Manual's section 8 that
    step invites, and the observation that means stop and come back. The plan is
    written for you to execute at your best, not just to be correct on paper.
-7. **L tier only, kill criteria:** the observation that means abandon this plan.
+7. **Architecture shape only, kill criteria:** the observation that means abandon this plan.
 
 **Consuming the answer:**
 
@@ -210,12 +210,12 @@ reformat, then work with what you have.
   consultation on all of them. Five separate S calls that were really one M
   question is the most common way to overpay.
 - **Cadence for large work:** at most three consultations. One after
-  exploration, for plan design (L). One before the irreversible step, for risk
-  review (S or M). One after implementation, for adversarial review of the
-  result (M). Everything between those points is your own work.
-- **Keep a ledger.** For each consultation record the question, the tier, the
-  first line of the answer, and what it changed in your actions. If a tier's
-  answers never change what you do, you are over-buying that tier. Stop.
+  exploration, for plan design (architecture). One before the irreversible step, for risk
+  review (verdict or plan). One after implementation, for adversarial review of the
+  result (plan). Everything between those points is your own work.
+- **Keep a ledger.** For each consultation record the question, the shape, the
+  first line of the answer, and what it changed in your actions. If a shape's
+  answers never change what you do, you are over-buying that shape. Stop.
 
 ---