@zalom/plastic 2.0.0-alpha.26 → 2.0.0-alpha.28

package/scripts/release-check

@@ -13,7 +13,7 @@
 # suite.
 #
 # Usage:
-#   release-check --tag <tag> --npm-version <version>
+#   release-check (--tag <tag> | --branch <branch>) --npm-version <version>
 #                  [--github-output <path>] [--root <dir>]
 #
 # Exit codes: 0 (clean), 1 (violations; reported on stderr, one per line,
@@ -24,10 +24,10 @@ require "json"
 require_relative "lib/release_guard"
 
 NPM_FLOOR = [11, 5, 1].freeze
-KNOWN_FLAGS = %w[--tag --npm-version --github-output --root].freeze
+KNOWN_FLAGS = %w[--tag --branch --npm-version --github-output --root].freeze
 
 def usage
-  warn "usage: release-check --tag <tag> --npm-version <version> [--github-output <path>] [--root <dir>]"
+  warn "usage: release-check (--tag <tag> | --branch <branch>) --npm-version <version> [--github-output <path>] [--root <dir>]"
   exit 2
 end
 
@@ -54,7 +54,7 @@ rescue Errno::ENOENT, JSON::ParserError
 end
 
 opts = parse_args(ARGV)
-usage unless opts["--tag"] && opts["--npm-version"]
+usage unless (opts["--tag"] || opts["--branch"]) && opts["--npm-version"]
 
 root = opts["--root"] ? File.expand_path(opts["--root"]) : File.expand_path("..", __dir__)
 package_json_path = File.join(root, "package.json")
@@ -66,16 +66,20 @@ violations = []
 canonical_version = read_version(package_json_path)
 violations << "could not read a version from #{package_json_path}" if canonical_version.nil?
 
-tag = opts["--tag"].sub(%r{\Arefs/tags/}, "")
+branch = opts["--branch"]
 dist_tag = nil
 
 if canonical_version
   expected_tag = "v#{canonical_version}"
+  tag = opts.fetch("--tag", expected_tag).sub(%r{\Arefs/tags/}, "")
   if tag != expected_tag
     violations << "tag #{tag} does not match package.json version #{canonical_version} (expected #{expected_tag})"
   end
 
   dist_tag = ReleaseGuard.dist_tag(canonical_version)
+  if branch && ReleaseGuard::CHANNELS[branch] != dist_tag
+    violations << "branch #{branch} publishes #{ReleaseGuard::CHANNELS[branch] || "nothing"}, and version #{canonical_version} is #{dist_tag}"
+  end
   stable = dist_tag == "latest"
 
   result = ReleaseGuard.check(
@@ -107,6 +111,7 @@ if violations.empty?
     File.open(opts["--github-output"], "a") do |f|
       f.puts "version=#{canonical_version}"
       f.puts "dist_tag=#{dist_tag}"
+      f.puts "tag=#{tag}"
     end
   end
   puts "OK: tag #{tag}, version #{canonical_version}, dist-tag #{dist_tag}"

package/scripts/report-screen

@@ -63,7 +63,7 @@ end
 def resolve_repo(intent_dir, explicit_repo, script_dir, include_self: true)
   candidates = []
   candidates << File.expand_path(explicit_repo) if explicit_repo
-  if (m = intent_dir.match(%r{\A(.*)/projects/([^/]+)/store/[^/]+\z}))
+  if (m = intent_dir.match(%r{\A(.*)/(?:projects|stores)/([^/]+)/store/[^/]+\z}))
     home, slug = m[1], m[2]
     projects_yml = File.join(home, "projects.yml")
     if File.exist?(projects_yml)

package/scripts/session-commit

@@ -18,6 +18,7 @@
 #   0 - always, except a usage error
 #   2 - usage error (missing --cwd or --summary); nothing is written
 
+require_relative "lib/store_layout"
 require "fileutils"
 require_relative "lib/session_git"
 require_relative "lib/session_ledger"
@@ -78,7 +79,7 @@ def main(argv)
   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")
+  store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(plastic_home)
   cwd = expand(opts[:cwd])
 
   day = opts[:day] || SessionLedger.day_id

package/scripts/spawn-preamble

@@ -44,7 +44,7 @@ WORKTREE_FALLBACK_INSTRUCTION =
   "directory, cd directly to the code worktree path above before editing project code."
 
 # Verbatim completion-report contract (intent 74). Kept as one constant so the
-# contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
+# contract doc (docs/help/agent-report-contract.md), the role prompts,
 # and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
 # report wording: the work output is lifecycle artifacts, the final message is a
 # structured report about them. Both are required and they do not contradict.
@@ -64,7 +64,7 @@ REPORT_CONTRACT =
   "depends on the discovering session's file-write access. Keep the report " \
   "prose-stripped: the envelope and payload only, no greeting, no preamble, " \
   "no end-recap, no restating of the task; reasoning stays in the thinking channel. " \
-  "See skills/auto/references/agent-report-contract.md for the per-role format."
+  "See docs/help/agent-report-contract.md for the per-role format."
 
 def parse_args(argv)
   role = nil

package/scripts/update.rb

@@ -231,12 +231,33 @@ class Update < InstallerCore
     ($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)
+  # Thin npx-exec glue (the decision above is unit-tested). Delegates the file-sync to
+  # the target version's install verb, recording the ledger action as `update`. On
+  # success, commits the re-synced core files and clears the update-check cache
+  # (former update skill, lines 124-125).
+  def perform_switch(target, agent_flags, switch_runner: ->(cmd) { system(*cmd) })
     cmd = ["npx", "#{PKG}@#{target}", "install", "--reinstall", "--ledger-action", "update", *agent_flags]
     puts "  $ #{cmd.join(" ")}"
-    system(*cmd) ? 0 : 1
+    return 1 unless switch_runner.call(cmd)
+
+    commit_core_files(target)
+    clear_update_check_cache
+    0
+  end
+
+  # Intent 372 (former update skill, lines 124-125): `~/.plastic` is its own git
+  # repository (install.rb's git_init_if_absent), so a successful update commits the
+  # core files it just re-synced. Empty commits are allowed: a same-version repair
+  # re-syncs nothing new, and that is still worth a ledger-adjacent commit.
+  def commit_core_files(target, runner: ->(cmd) { system(*cmd) })
+    runner.call(["git", "-C", plastic_home, "add", "PLASTIC.md", "scripts", "AGENTS.md", "VERSION",
+      "versions.json", "deprecations.yml", "config_asks.yml"])
+    runner.call(["git", "-C", plastic_home, "commit", "-m", "chore: update Plastic to #{target}",
+      "--allow-empty"])
+  end
+
+  def clear_update_check_cache
+    FileUtils.rm_f(File.join(plastic_home, ".cache", "update-check.json"))
   end
 
   def show_help

package/scripts/write-handoff

@@ -16,6 +16,7 @@
 #
 # Exit codes: 0 done; 2 usage error.
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
 
@@ -48,7 +49,7 @@ usage_abort("--trigger is required (#{Handoff::TRIGGERS.join(', ')})") unless op
 usage_abort("--trigger must be one of #{Handoff::TRIGGERS.join(', ')}") unless Handoff::TRIGGERS.include?(opts[:trigger])
 
 plastic_home = expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
-store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
+store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(plastic_home)
 templates = opts[:templates] ? expand(opts[:templates]) : File.expand_path("../templates", __dir__)
 usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
 

package/templates/agents.md

@@ -42,7 +42,7 @@ Active/Future/Completed placement is managed in INDEX.md, not in frontmatter.
 
 ## Creating Tactical Intents
 
-Create through the `plastic-intent-creating` skill, which scaffolds with one call:
+Create through the `plastic intent new` command, which scaffolds with one call:
 `ruby ~/.plastic/scripts/new-intent --store .plastic/store --intent "<one-line>" --slug <slug> [--sources <governing-id>]`.
 It allocates the Folgezettel ID, creates `.plastic/store/ID--slug/ID--slug.md` born
 complete, and wires the links. Never hand-author the files: `new-intent` validates the
@@ -54,11 +54,11 @@ Plastic has its own lifecycle skills. When a Plastic skill exists for the curren
 
 | Phase | Skill | Produces |
 |-------|-------|----------|
-| What | `plastic-intent-creating` | Intent file |
-| Why | `plastic-intent-speccing` | Rulings as insights, `resources/*.md`, `spec.md` |
-| How | `plastic-intent-speccing` | `actions/`, `plan.md`, `checklist.md` |
-| Exec | `plastic-intent-executing` | Code + `outcome.md` |
-| End | `plastic-intent-ending` | Lifecycle transition |
+| What | `plastic intent new` | Intent file |
+| Why | `plastic intent spec` | Rulings as insights, `resources/*.md`, `spec.md` |
+| How | `plastic intent spec` | `actions/`, `plan.md`, `checklist.md` |
+| Exec | `plastic intent step` | Code + `outcome.md` |
+| End | `plastic intent end` | Lifecycle transition |
 
 **Artifact convention:** ALL lifecycle artifacts go to the active intent directory (`store/{id}--{slug}/`). Never write specs to `docs/superpowers/specs/` or plans to `docs/superpowers/plans/`.
 

package/templates/config.yml

@@ -34,18 +34,25 @@ architect:
 #       plastic-enforcer: opus
 #     codex:
 #       plastic-executor: gpt-5.6-terra
+#   efforts:
+#     claude:
+#       plastic-executor: medium
+#     codex:
+#       plastic-executor: medium
+# Every shipped agent defaults to medium reasoning effort on both harnesses.
+# An agents.efforts.<harness>.<agent> entry is an explicit per-agent override.
 
-# The advisor (intent 185): two consultation agents, plastic-advisor (the real
-# advisor, expensive, model fable by default) and plastic-faux-advisor (the
-# cheaper imitation, model opus by default, carrying the same reasoning
-# discipline inline). advisor.enabled defaults to enabled; missing or
+# The advisors: Primary Advisor and Secondary Advisor. Both use Fable on Claude
+# Code and gpt-6-astra on Codex. Primary uses medium effort; Secondary uses high.
+# advisor.enabled defaults to enabled; missing or
 # unreadable counts as enabled (fail-open). The claude.default value is an
 # AGENT NAME, never a model name, so it can point at
 # a locally registered agent instead. Set at install time via --no-advisor /
 # --advisor, or uncomment here directly. Each agent's actual model is a plain
-# agents.models.claude.<name> override, same mechanism as any other agent.
+# agents.models.claude.<name> override, same mechanism as any other agent. Codex
+# generates both advisors with their role-specific effort.
 # advisor:
 #   enabled: false               # skip installing both advisor agents and the
 #                                 # agent-advisor skill entirely
 #   claude:
-#     default: plastic-advisor         # which agent the advisor skill routes to
+#     default: plastic-primary-advisor # which agent the advisor skill routes to

package/templates/node-research.md

@@ -3,9 +3,11 @@ node: r1
 kind: research
 files: []
 budget: 60000
+# Optional. When present, use one relative Markdown path under resources/.
+# report: resources/report--topic.md
 ---
 # r1 - <what to find out>
 
 ## Deposit
-<Where the finding lands: a resources/ file, an artifact URL, or a ruling
-recorded in the intent's ## Decisions.>
+<Where the finding lands: declare report: above for a resources/ Markdown file,
+or name an artifact URL or a ruling recorded in the intent's ## Decisions.>

package/templates/render.css

@@ -0,0 +1,10 @@
+body { max-width: 46rem; margin: 2rem auto; padding: 0 1rem; font: 16px/1.6 system-ui, sans-serif; color: #1f2933; background: #f4f5f7; }
+h1, h2, h3 { line-height: 1.25; }
+table { border-collapse: collapse; display: block; overflow-x: auto; }
+th, td { border: 1px solid #9aa5b1; padding: 0.3rem 0.6rem; text-align: left; }
+pre { background: #e4e7eb; padding: 0.8rem; overflow-x: auto; }
+code { font-family: ui-monospace, monospace; }
+@media (prefers-color-scheme: dark) {
+  body { color: #e4e7eb; background: #1f2933; }
+  pre { background: #323f4b; }
+}

package/bin/plastic.js

@@ -1,70 +0,0 @@
-#!/usr/bin/env node
-
-// Thin shim — npx entry point that dispatches a subcommand to the matching Ruby verb script.
-// All logic lives in scripts/<verb>.rb. JS is only the distribution + dispatch mechanism.
-//
-//   npx @zalom/plastic install   [flags]
-//   npx @zalom/plastic update    [flags]
-//   npx @zalom/plastic uninstall [flags]
-//   npx @zalom/plastic rollback  [flags]
-//
-// Back-compat: a bare `--uninstall` (no subcommand) routes to uninstall with a deprecation
-// warning; no subcommand at all defaults to install (legacy behaviour, one release).
-
-import { execFileSync } from 'node:child_process'
-import { resolve } from 'node:path'
-import { existsSync } from 'node:fs'
-
-const VERBS = ['install', 'update', 'uninstall', 'rollback']
-const packageRoot = new URL('..', import.meta.url).pathname
-const argv = process.argv.slice(2)
-
-let verb
-let rest
-
-if (VERBS.includes(argv[0])) {
-  verb = argv[0]
-  rest = argv.slice(1)
-} else if (argv.includes('--uninstall')) {
-  // Deprecated: `--uninstall` as a flag instead of the `uninstall` subcommand.
-  console.error('! plastic: `--uninstall` is deprecated — use `npx @zalom/plastic uninstall`. (works for now)')
-  verb = 'uninstall'
-  rest = argv.filter((a) => a !== '--uninstall')
-} else {
-  // No subcommand: legacy default to install (one release of grace).
-  verb = 'install'
-  rest = argv
-}
-
-const script = resolve(packageRoot, 'scripts', `${verb}.rb`)
-
-if (!existsSync(script)) {
-  console.error(`Error: scripts/${verb}.rb not found in package.`)
-  process.exit(1)
-}
-
-try {
-  execFileSync('ruby', [script, ...rest], {
-    stdio: 'inherit',
-    // Clear RUBYOPT last, after the spread, so a global setting (for example --yjit)
-    // cannot reach a ruby that does not know the flag. A machine with an old ruby
-    // must get preflight's real message, not a crash.
-    env: { ...process.env, PLASTIC_PACKAGE_ROOT: packageRoot, RUBYOPT: '' },
-  })
-} catch (err) {
-  if (err.status) process.exit(err.status)
-  // We only get here when ruby could not be executed at all. A ruby that runs but is
-  // too old exits with a status, handled on the line above, and prints its own real
-  // message from scripts/lib/preflight.rb naming the version actually found.
-  if (err.code === 'ENOENT') {
-    console.error('Plastic needs Ruby 3.0.0 or newer to run its scripts (ruby was not found on PATH).')
-    console.error('Install a pinned Ruby with mise:')
-    console.error('  curl https://mise.run | sh        # only if mise is not installed yet')
-    console.error('  mise use --global ruby@3.3')
-    console.error('Then re-run the Plastic installer.')
-  } else {
-    console.error(`Plastic could not run ruby: ${err.message}`)
-    console.error('Check that `ruby -v` works in this shell, then re-run the Plastic installer.')
-  }
-  process.exit(1)
-}

package/skills/agent-advisor/SKILL.md

@@ -1,92 +0,0 @@
----
-name: plastic-agent-advisor
-description: >-
-  Consult the advisor for expensive reasoning: one-way doors, plans, adversarial
-  review of a plan or conclusion before an irreversible step, a deadlock after two
-  failed attempts, or ranking several plausible options. Use when the user asks for
-  a second opinion, a hard design decision, an architecture review, help breaking a
-  deadlock, or says "ask the advisor". Also sets which advisor is the default when
-  asked ("make Fable my advisor", "switch my advisor", "use the real advisor").
-user-invocable: true
----
-
-# Agent Advisor
-
-Plastic ships two consultation agents, never dispatched by the auto pipeline, summoned
-only when you decide the reasoning is worth buying:
-
-- **`plastic-advisor`** ("the real advisor"): the frontier model itself, expensive,
-  billed through usage credits. Spawn it for a few rounds on the hardest problem, then
-  close the session.
-- **`plastic-faux-advisor`** ("the imitation advisor"): an ordinary model carrying the
-  same reasoning discipline inline in its own body, so it reasons the same disciplined
-  way at a fraction of the cost. The cheaper default.
-
-## When to consult (and when not to)
-
-Buy a consultation for: decisions with one-way doors (architecture, migration order,
-public contracts); turning a goal plus evidence into a step plan with checks;
-adversarial review of your plan or conclusion before an irreversible step; a deadlock
-after two failed attempts where you cannot say why; ranking several plausible options
-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 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.
-
-## Routing: which advisor answers
-
-1. Read the harness-scoped config: `advisor.claude.default`, the only advisor routing key
-   the installer writes. If unset, use `plastic-advisor`, the shipped default.
-2. If the user names which advisor they want ("ask the real one", "use Fable", "ask the
-   cheap one"), honor that directly and dispatch `plastic-advisor` (the real advisor) or
-   `plastic-faux-advisor` (the cheaper imitation) accordingly, overriding step 1 for this
-   consultation only.
-3. If `advisor.enabled` reads `false`, neither advisor agent nor this skill is
-   installed; this step should not be reachable, but if it is, tell the user the
-   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 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,
-   not authority; the plan is the advisor's, the outcome is yours.
-
-Read the resolved config value with:
-
-```bash
-ruby ~/.plastic/scripts/read-config advisor.claude.default --project <repo>
-```
-
-(Omit `--project` outside a registered project; falls back to the global value.)
-
-## Setting the default advisor
-
-When asked to change the default ("make Fable my advisor", "switch my advisor", "use
-the cheaper one by default"), present the two options in plain language and write the
-choice:
-
-- **Faux Fable** (`plastic-faux-advisor`, recommended): an ordinary model carrying the
-  frontier reasoning instructions. Much cheaper, available on any plan, reasons in the
-  same disciplined way.
-- **Fable 5** (`plastic-advisor`): the frontier model itself. The strongest reasoning
-  available, billed through usage credits, so summon it for a few rounds and close it.
-
-These are the same two options the installer offers at install and update time. Write
-the choice to `advisor.claude.default` in the global `~/.plastic/config.yml` (or the
-project's `.plastic_store/config.yml` when the user scopes the change to one project):
-read the file as YAML, set `advisor.claude.default` to the agent name (`plastic-advisor`
-or `plastic-faux-advisor`, never a model name or nickname), and write it back. Confirm
-the new default back to the user in one line.
-
-## References
-
-- `references/advisor-protocol.md`: the full shipped Advisor Protocol (what to buy,
-  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.