@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.2

package/scripts/update.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# 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]
+#
+# Forward-only version transitions, sourced from npm dist-tags:
+#   - no flag                = next version on the CURRENT channel (derived from VERSION)
+#   - --beta/--latest/--alpha = switch channel. Toward stability (alpha->beta->latest) is
+#                               frictionless; toward bleeding edge requires confirmation.
+# "Already up to date" is a clean no-op. Performs the switch by delegating the file-sync to
+# `install --reinstall --ledger-action update` for the chosen version via npx.
+
+require_relative "lib/installer_core"
+require_relative "doctor"
+
+class Update < InstallerCore
+  PKG = "@zalom/plastic"
+
+  def cli(argv = ARGV)
+    if argv.include?("--help") || argv.include?("-h")
+      show_help
+      return 0
+    end
+
+    iv = installed_version
+    unless iv
+      warn "Plastic is not installed. Run: npx #{PKG} install --claude"
+      return 1
+    end
+
+    requested = requested_channel(argv)
+    tags = fetch_dist_tags
+    unless tags
+      warn "Could not query npm dist-tags. Are you online?"
+      return 1
+    end
+
+    res = compute_target(installed_version: iv, dist_tags: tags, requested_channel: requested)
+
+    case res[:status]
+    when :up_to_date
+      puts "\u{2705} Plastic v#{iv} is already up to date on the #{channel_for(iv)} channel."
+      return 0
+    when :unknown_channel
+      warn "No published version on the #{requested} channel."
+      return 1
+    when :ok
+      if res[:kind] == :cross_bleeding && !confirm_bleeding(iv, res[:target])
+        puts "Aborted."
+        return 1
+      end
+      puts "\u{2b06}\u{fe0f}  Updating Plastic #{iv} \u{2192} #{res[:target]}"
+      exit_code = perform_switch(res[:target], agent_args(argv))
+      run_post_update_doctor if exit_code == 0
+      exit_code
+    end
+  end
+
+  # Run the full doctor after a successful update and print a human-readable
+  # summary. Informational only: does not raise and does not affect the update's
+  # exit code. Accepts injected `doctor` and `out` for hermetic unit tests.
+  def run_post_update_doctor(doctor: nil, out: $stdout)
+    doctor ||= Doctor.new
+    out.puts "\nRunning full doctor after update..."
+    result = doctor.run_checks("claude")
+    s = result[:summary]
+    out.puts "  Doctor status: #{result[:status]} " \
+             "(pass: #{s[:pass]}, warn: #{s[:warn]}, fail: #{s[:fail]}, total: #{s[:total]})"
+    out.puts "  Run /plastic-doctor for details." unless result[:status] == "pass"
+    result
+  rescue StandardError => e
+    # Non-blocking: a crash here (e.g. malformed file in the real store) must not
+    # undo or fail an update that already succeeded. Report and move on.
+    out.puts "  doctor could not run: #{e.message} — run /plastic-doctor"
+    nil
+  end
+
+  # Pure decision logic (hermetically testable). Returns a status hash.
+  def compute_target(installed_version:, dist_tags:, requested_channel: nil)
+    installed_ch = channel_for(installed_version)
+    target_ch = requested_channel || installed_ch
+    cand = dist_tags[target_ch]
+    return { status: :unknown_channel } unless cand
+
+    if target_ch == installed_ch
+      return { status: :up_to_date } unless semver_gt?(cand, installed_version)
+      { status: :ok, target: cand, kind: :in_channel }
+    else
+      bleeding = stability_rank(target_ch) < stability_rank(installed_ch)
+      { status: :ok, target: cand, kind: bleeding ? :cross_bleeding : :cross_stable }
+    end
+  end
+
+  def installed_version
+    path = File.join(plastic_home, "VERSION")
+    File.exist?(path) ? File.read(path).strip : nil
+  end
+
+  private
+
+  def requested_channel(argv)
+    return "alpha" if argv.include?("--alpha")
+    return "beta" if argv.include?("--beta")
+    return "latest" if argv.include?("--latest")
+    nil
+  end
+
+  # Agent flags to pass through to the delegated install (default --claude).
+  def agent_args(argv)
+    flags = agents.map { |a| a[:flag] }.select { |f| argv.include?(f) }
+    flags << "--all" if argv.include?("--all")
+    flags.empty? ? ["--claude"] : flags
+  end
+
+  def fetch_dist_tags
+    raw = `npm view #{PKG} dist-tags --json 2>/dev/null`
+    return nil if raw.nil? || raw.strip.empty?
+    JSON.parse(raw)
+  rescue JSON::ParserError, StandardError
+    nil
+  end
+
+  def confirm_bleeding(current, target)
+    return false unless $stdin.tty?
+    print "Switch from #{current} to the less-stable #{target}? [y/N]: "
+    ($stdin.gets&.strip || "").downcase.start_with?("y")
+  end
+
+  # Thin npx-exec glue (not unit-tested; the decision above is). Delegates the file-sync to
+  # the target version's install verb, recording the ledger action as `update`.
+  def perform_switch(target, agent_flags)
+    cmd = ["npx", "#{PKG}@#{target}", "install", "--reinstall", "--ledger-action", "update", *agent_flags]
+    puts "  $ #{cmd.join(" ")}"
+    system(*cmd) ? 0 : 1
+  end
+
+  def show_help
+    puts <<~HELP
+
+      plastic update — upgrade Plastic to a newer version
+
+      Usage:
+        npx @zalom/plastic update [options]
+
+      Channel options (default: stay on the current channel):
+        --latest      Switch to / advance the stable channel
+        --beta        Switch to / advance the beta channel
+        --alpha       Switch to / advance the alpha channel (bleeding edge — confirmed)
+
+      Agent options (default: --claude):
+        --claude --codex --hermes --all
+
+      Behaviour:
+        No flag advances to the next version on your current channel. Switching toward a
+        more stable channel is frictionless; switching toward bleeding edge is confirmed.
+        Use `versions` to roll back to a previously-installed version.
+
+    HELP
+  end
+end
+
+exit(Update.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__)).cli(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/validate-intent

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# validate-intent — deterministic CLI over IntentValidator (intent 60).
+#
+# Checks whether a single intent directory is born complete: required frontmatter
+# fields present, and `sources`/`chain` well-formed arrays of id strings. The
+# creating-intent skill self-verifies a freshly written intent with this CLI
+# before announcing or committing; any agent or human can run it on one dir.
+#
+# Usage:
+#   validate-intent <intent_dir> [--home <path>]
+#
+# Exit codes: 0 (born complete), 1 (incomplete; report on stderr), 2 (usage).
+# --home <path> overrides the Plastic home (default: ~/.plastic).
+
+require_relative "lib/intent_validator"
+
+def plastic_home(args)
+  if (i = args.index("--home")) && args[i + 1]
+    File.expand_path(args[i + 1])
+  else
+    File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+  end
+end
+
+home = plastic_home(ARGV)
+
+# First positional arg, skipping any flag and the value that follows --home.
+home_value_index = (i = ARGV.index("--home")) ? i + 1 : nil
+intent_dir = ARGV.each_index.find do |idx|
+  arg = ARGV[idx]
+  !arg.start_with?("--") && idx != home_value_index
+end
+intent_dir = intent_dir && ARGV[intent_dir]
+
+if intent_dir.nil?
+  warn "usage: validate-intent <intent_dir> [--home <path>]"
+  exit 2
+end
+
+dir = File.expand_path(intent_dir)
+result = IntentValidator.validate(dir, plastic_home: home)
+
+if result[:ok]
+  puts "OK: #{dir}"
+  exit 0
+end
+
+warn "INCOMPLETE: #{dir}"
+result[:missing].each { |field| warn "missing: #{field}" }
+result[:errors].each { |error| warn error }
+exit 1

package/scripts/versions.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Plastic — `versions` verb. Runs via `npx @zalom/plastic versions` (bin/plastic.js) or directly.
+# Usage: ruby scripts/versions.rb [--downgrade [--version <v>] | --upgrade] [--help]
+#
+# Local time-machine over the append-only versions.json ledger. Navigates ONLY versions you
+# have actually run (the ledger), never npm's full list — fetching brand-new versions is
+# `update`'s job. Lets you roll back to a known-good build after a bad release.
+#   - no flag                  print the ledger table (and offer to continue a rollback)
+#   - --downgrade              step back one version in your history
+#   - --downgrade --version V  jump to a specific previously-run version
+#   - --upgrade                step forward one version (after a rollback)
+
+require_relative "lib/installer_core"
+
+class Versions < InstallerCore
+  PKG = "@zalom/plastic"
+
+  def cli(argv = ARGV)
+    if argv.include?("--help") || argv.include?("-h")
+      show_help
+      return 0
+    end
+
+    ledger = ledger_read
+    if ledger.empty?
+      puts "No version history yet (versions.json is empty). Install or update first."
+      return 0
+    end
+
+    timeline = version_timeline(ledger)
+    current = installed_version || timeline.last
+
+    if argv.include?("--downgrade")
+      explicit = flag_value(argv, "--version")
+      target = explicit || step_target(timeline, current, :back)
+      return no_target("No earlier version in your history.") unless target
+      unless timeline.include?(target)
+        warn "#{target} is not in your version history. Choose one of: #{timeline.join(", ")}"
+        return 1
+      end
+      return switch_to(target, current)
+    elsif argv.include?("--upgrade")
+      target = step_target(timeline, current, :forward)
+      return no_target("No later version in your history. Use `update` for new releases.") unless target
+      return switch_to(target, current)
+    end
+
+    # No flag: show the table, and detect an in-progress rollback.
+    print_table(ledger, current)
+    if ledger.last && ledger.last["action"] == "downgrade"
+      prev = step_target(timeline, current, :back)
+      if prev && $stdin.tty?
+        print "\nYou recently rolled back. Go back further to #{prev}? [y/N]: "
+        return switch_to(prev, current) if ($stdin.gets&.strip || "").downcase.start_with?("y")
+      end
+    end
+    0
+  end
+
+  # Unique versions in first-seen (chronological) order — the user's personal timeline.
+  def version_timeline(ledger)
+    ledger.map { |e| e["version"] }.compact.uniq
+  end
+
+  # Neighbour of `current` in the timeline. direction :back (older) or :forward (newer).
+  def step_target(timeline, current, direction)
+    i = timeline.index(current)
+    return nil if i.nil?
+    j = direction == :back ? i - 1 : i + 1
+    return nil if j < 0 || j >= timeline.length
+    timeline[j]
+  end
+
+  # Direction-derived ledger action for moving current -> target.
+  def action_for(target, current)
+    cmp = semver_compare(target, current)
+    cmp == -1 ? "downgrade" : "update"
+  end
+
+  def installed_version
+    path = File.join(plastic_home, "VERSION")
+    File.exist?(path) ? File.read(path).strip : nil
+  end
+
+  private
+
+  def flag_value(argv, name)
+    i = argv.index(name)
+    return nil unless i && argv[i + 1]
+    argv[i + 1]
+  end
+
+  def no_target(msg)
+    puts msg
+    0
+  end
+
+  def switch_to(target, current)
+    action = action_for(target, current)
+    puts "#{action == "downgrade" ? "\u{23ea}" : "\u{23e9}"}  #{current} \u{2192} #{target} (#{action})"
+    cmd = ["npx", "#{PKG}@#{target}", "install", "--reinstall", "--ledger-action", action, "--claude"]
+    puts "  $ #{cmd.join(" ")}"
+    system(*cmd) ? 0 : 1
+  end
+
+  def print_table(ledger, current)
+    puts "\nPlastic version history (versions.json — append-only):\n\n"
+    puts "    %-22s %-10s %s" % ["version", "action", "at"]
+    ledger.each do |e|
+      marker = e["version"] == current ? "\u{2192} " : "  "
+      puts "  #{marker}%-22s %-10s %s" % [e["version"], e["action"], e["at"]]
+    end
+    puts "\n  \u{2192} = currently installed (v#{current})\n\n"
+  end
+
+  def show_help
+    puts <<~HELP
+
+      plastic versions — manage and roll back your local Plastic versions
+
+      Usage:
+        npx @zalom/plastic versions [options]
+
+      Options:
+        (none)                  Show the version-history table
+        --downgrade             Roll back one version in your history
+        --downgrade --version V Roll back to a specific previously-run version
+        --upgrade               Step forward one version in your history
+        -h, --help              Show this help
+
+      Navigates only versions you have already run (the append-only ledger). To move to a
+      brand-new release, use `update`.
+
+    HELP
+  end
+end
+
+exit(Versions.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__)).cli(ARGV)) if $PROGRAM_NAME == __FILE__

package/skills/_active-intent-gate.md

@@ -13,7 +13,7 @@ Before proceeding, resolve the active intent:
    - Look under `## Active` for intent entries
    - If exactly one active intent → use it
    - If multiple active intents → ask user which one
-   - If no active intent → refuse: "No active intent. Create one first with /plastic:creating-intent"
+   - If no active intent → refuse: "No active intent. Create one first with /plastic-creating-intent"
 
 3. **Resolve paths:**
    - Intent directory: `{store}/store/{id}--{slug}/`

package/skills/add-project-store/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: plastic-add-project-store
+description: >-
+  Add an intent store to a project that is already registered in projects.yml
+  but has no store on disk. Use when a project is registered but has no store,
+  when you need to provision a store, or when doctor reports a missing project
+  store (project_store_dir). Thin wrapper around provision-project-store plus an
+  optional qmd register step.
+---
+
+# Add a Project Store
+
+Provision the intent store for a project that is already registered in
+`projects.yml` but whose `~/.plastic/projects/{slug}/store/` is missing. This is
+the standalone path; `plastic-creating-project` provisions the store for brand
+new projects.
+
+The provisioner is the single source of truth for store creation. It is pure
+filesystem and idempotent, so re-running is always safe. The project must already
+be registered (this skill does not edit `projects.yml`).
+
+## 1. Resolve the slug
+
+The slug is the project's key under `projects` in `~/.plastic/projects.yml`. If
+the user names a project, map it to its slug. If the slug is missing from
+`projects.yml`, stop: the provisioner requires the project to already be
+registered. If ambiguous, list the registered slugs and ask which one.
+
+## 2. Run the provisioner
+
+```bash
+ruby ~/.plastic/scripts/provision-project-store <slug>
+```
+
+This creates `~/.plastic/projects/<slug>/store/` with `.gitkeep`, writes
+`INDEX.md` and `project.yml` only if they are missing, and never clobbers
+existing files. An unregistered slug exits non-zero with a clear error and
+creates nothing.
+
+## 3. Register with QMD (separate, optional step)
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store
+```
+
+This is the only qmd mutation; the provisioner itself performs none. It no-ops
+when qmd is absent, so it is safe to run unconditionally.
+
+## Scope
+
+- Provisioning and qmd registration are two distinct steps. Do not fold qmd into
+  the provisioner.
+- No `projects.yml` edits, no project-tree edits, no tactical-mirror or
+  founding-intent seeding.

package/skills/auto/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:auto
+name: plastic-auto
 description: >-
   Autonomous intent delivery — agent takes over How and Exec. Use when user says
   "auto", "take it from here", "deliver this", or when brainstorming-grill-me concludes
@@ -12,14 +12,68 @@ Announce: "Taking over intent [ID] — [name] for autonomous delivery."
 
 ## Precondition
 
-An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found. Create one first with /plastic:creating-intent."
+An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found. Create one first with /plastic-creating-intent."
 
 If multiple active intents exist, ask the user which one to deliver (this is the only question auto asks).
 
+**Picking work when no intent is specified.** If the user says "auto" without naming an
+intent and none is active, consult the dashboard's machine-readable queue to choose the
+next dispatchable intent:
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb all --json
+```
+
+Work `dispatchable_queue` in `rank` order (these are `defer`/`research` dispositions —
+safe to deliver autonomously). Leave `human_only` and `next_big_thing` for the user — those
+are `drive`/`triage` items the human should lead. See the `plastic-dashboard` skill.
+
+## Arm the Lifecycle Gate (do this FIRST)
+
+Immediately after selecting the intent — before any other work — arm auto mode. This
+writes the session bridge that makes the code-edit gate live, so project code cannot be
+edited before the plan exists (the gate applies to YOU, the orchestrator):
+
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e \
+  'Bridge.arm_auto(ENV["CLAUDE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+```
+
+Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
+`<dir>` (the `ID--slug` directory), and `<name>`. If `CLAUDE_SESSION_ID` is unset, `arm_auto`
+falls back to a deterministic derived bridge key (a hash of the store and intent id), so the
+gate still engages; arming prints a one-line notice to stderr in that case.
+
+**Hard rule for the rest of this run:** do NOT edit project code (anything outside the
+intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
+Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.md) → Exec.
+
 ## Flags
 
 - `--skip-permissions` — bypass hard stops on destructive actions on existing projects. Full trust mode. Default: off.
 
+## Team Spin-Up
+
+Auto mode spins up exactly ONE enforcer-led team per intent. The plastic-enforcer IS this orchestrator (you), not a separately dispatched agent, which avoids the who-gates-the-gater regress.
+
+Roster (one role per cycle stage):
+
+- **plastic-brainstorming** (Why exploration): enriches `## Context` + `### Decisions`
+- **plastic-spec-specialist** (`spec.md`)
+- **plastic-planner** (`plan.md` + `actions/` + `checklist.md`)
+- **plastic-executor** (code + checklist + `## Insights`)
+- **plastic-enforcer** (orchestrates + gates; that is YOU)
+
+Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. The How and Exec phases below default to Plastic's native dispatch (`plastic-executing-plan`) and delegate to the superpowers skills only when they are available or the user asks; do not restate the phase mechanics here.
+
+Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
+
+Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
+
+Headless manual gate: when running headless or in the background, enforce gates manually and do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset (this ties to the arm-gate fallback above).
+
+Solo fallback: if the harness has no subagent dispatch, fall back to a single agent walking the full What, Why, How, Exec cycle yourself. This preserves current behavior.
+
 ## Stage-Aware Entry
 
 Read the active intent's directory. Determine current lifecycle stage from filesystem state:
@@ -67,7 +121,7 @@ If the plan calls for creating a new project (the intent is an implementation in
 1. Determine project path from `~/.plastic/config.yml` `project_roots` or from intent context
 2. **Confirm path with user** — this is the ONE human interaction during auto delivery:
    > "Creating project `<slug>` at `<path>`. Confirm path, or provide alternative."
-3. Invoke `plastic:creating-project` skill
+3. Invoke `plastic-creating-project` skill
 4. The global intent is now Completed (creating-project handles this)
 5. The tactical mirror in the project store becomes the active intent
 6. Continue execution from the project directory using the tactical intent
@@ -75,7 +129,7 @@ If the plan calls for creating a new project (the intent is an implementation in
 ## Exec Phase
 
 1. If `superpowers:subagent-driven-development` or `superpowers:executing-plans` is available, delegate execution to it
-2. Otherwise invoke `plastic:executing-plan`
+2. Otherwise invoke `plastic-executing-plan`
 3. Execute actions from checklist sequentially
 4. Check off items in `checklist.md` as completed
 5. Append observations to `## Insights` with `(autonomous)` marker
@@ -124,13 +178,25 @@ During initial project creation, all decisions are non-destructive by definition
         - `fix_and_retry` — attempt to fix the failure, re-run verify (max 2 retries)
         - `stop` — write `savepoint.md` with current state, notify user: "Verify failed — savepoint written.", **STOP**
         - `manual` — notify user: "Verify failed: [summary]. Resolve manually."
-   5. If `release.on_green` has items, invoke `plastic:releasing` to handle them (tag, changelog, publish, etc.). Do NOT duplicate release logic — delegate entirely.
+   5. If `release.on_green` has items, invoke `plastic-releasing` to handle them (tag, changelog, publish, etc.). Do NOT duplicate release logic — delegate entirely.
 5. Review `## Insights` for observations that should spawn future intents. If any:
-   - Create them (using `plastic:creating-intent` conventions)
+   - Create them (using `plastic-creating-intent` conventions)
    - Update `chain` in the current intent's frontmatter
 6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+8. Refresh the QMD search index for this store (optional, no-op when QMD is absent):
+   ```bash
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>
+   ```
+   Delivery is the lifecycle event that keeps the search index fresh. `<store-root>` is the
+   store that holds this intent (the global store or the project store).
+9. Disarm the lifecycle gate (auto delivery is finished):
+   ```bash
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
+   ```
+   Disarming also purges stale bridge files from the temp directory automatically (it keeps the
+   current bridge and any live run), so no manual `/tmp` cleanup is needed.
+10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling
 
@@ -139,3 +205,7 @@ If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail
 2. Write `savepoint.md` with current state
 3. Notify user: "Blocked on intent [ID] — [name]: [description]. Savepoint written."
 4. **STOP.** Do not attempt workarounds that could leave the project in a broken state.
+
+## References
+
+- Read `references/agent-architecture.md` for the full team model (the 5-role enforcer-led team, per-stage handoffs, gate ownership, headless note, solo fallback) and the orchestrator hierarchy (Main Orchestrator, Project Orchestrators, coordination loop) when spinning up the team or understanding autonomous delivery scope