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

package/bin/plastic

@@ -0,0 +1,6 @@
+#!/usr/bin/env -S ruby --disable-gems
+# frozen_string_literal: true
+
+require_relative "../scripts/lib/cli"
+
+exit Plastic::CLI.call(ARGV)

package/bin/plastic-skill-census

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Plastic skill usage census (intent 324). Counts typed /plastic-* commands
+# from the prompt history against agent-invoked Skill calls, loads, and
+# attribution from the transcript tree, so D19 (which Plastic verbs stay
+# visible as slash commands) is decided on measured use.
+#
+# Maintainer tool: it reads the paths given to it and is never installed
+# into ~/.plastic. This file never resolves the running process's home
+# directory or its home environment variable: `bin/` ships in the npm
+# tarball, so a default rooted there would make a published executable
+# read any installer's transcripts. `--history` and `--transcripts` are
+# required, with no default.
+#
+# Usage: bin/plastic-skill-census --history PATH --transcripts DIR
+#          [--skills-dir DIR] [--format md|json] [--out PATH]
+#          [--cutoff YYYY-MM-DD]
+#
+#   --history PATH     ~/.claude/history.jsonl, or a fixture (required)
+#   --transcripts DIR   ~/.claude/projects, or a fixture tree (required)
+#   --skills-dir DIR    a skill roster directory (default: this repo's skills/)
+#   --format md|json    report format (default: md)
+#   --out PATH          write the report here instead of stdout
+#   --cutoff YYYY-MM-DD  exclude records on or after this date (default: 2026-09-02)
+#
+# Exit codes: 0 a report was produced, 1 a named path does not exist,
+# 2 bad usage or a missing required flag.
+
+require_relative "lib/skill_census"
+
+USAGE = <<~TEXT
+  usage: plastic-skill-census --history PATH --transcripts DIR [--skills-dir DIR] [--format md|json] [--out PATH] [--cutoff YYYY-MM-DD]
+
+    --history PATH      ~/.claude/history.jsonl, or a fixture (required)
+    --transcripts DIR    ~/.claude/projects, or a fixture tree (required)
+    --skills-dir DIR     a skill roster directory (default: this repo's skills/)
+    --format md|json     report format (default: md)
+    --out PATH           write the report here instead of stdout
+    --cutoff YYYY-MM-DD   exclude records on or after this date (default: #{SkillCensus::DEFAULT_CUTOFF})
+    --help                this message
+
+  Exits 0 on a report, 1 when a named path is missing, 2 on bad usage.
+TEXT
+
+def fail_usage(message)
+  warn "plastic-skill-census: #{message}"
+  warn USAGE
+  exit 2
+end
+
+history = nil
+transcripts = nil
+skills_dir = File.expand_path("../skills", __dir__)
+format = "md"
+out_path = nil
+cutoff = SkillCensus::DEFAULT_CUTOFF
+
+argv = ARGV.dup
+until argv.empty?
+  case (flag = argv.shift)
+  when "--help", "-h"
+    puts USAGE
+    exit 0
+  when "--history"
+    history = argv.shift
+    fail_usage("--history needs a path") if history.to_s.empty?
+  when "--transcripts"
+    transcripts = argv.shift
+    fail_usage("--transcripts needs a path") if transcripts.to_s.empty?
+  when "--skills-dir"
+    skills_dir = argv.shift
+    fail_usage("--skills-dir needs a path") if skills_dir.to_s.empty?
+  when "--format"
+    format = argv.shift
+    fail_usage("--format must be md or json") unless %w[md json].include?(format)
+  when "--out"
+    out_path = argv.shift
+    fail_usage("--out needs a path") if out_path.to_s.empty?
+  when "--cutoff"
+    cutoff = argv.shift
+    fail_usage("--cutoff needs a YYYY-MM-DD date") if cutoff.to_s.empty?
+  else
+    fail_usage("unknown argument #{flag}")
+  end
+end
+
+fail_usage("--history is required") if history.nil?
+fail_usage("--transcripts is required") if transcripts.nil?
+
+begin
+  roster = SkillCensus::Roster.load(skills_dir)
+  history_scan = SkillCensus::HistoryScanner.new(history, cutoff: cutoff).scan
+  transcript_scan = SkillCensus::TranscriptScanner.new(transcripts, cutoff: cutoff).scan
+  built = SkillCensus::Tally.new(history_scan, transcript_scan, roster).build
+
+  report = if format == "json"
+             SkillCensus::Report.json(built, history_path: history, transcripts_path: transcripts, cutoff: cutoff)
+           else
+             SkillCensus::Report.markdown(built, history_path: history, transcripts_path: transcripts, cutoff: cutoff)
+           end
+rescue RuntimeError => error
+  warn "plastic-skill-census: #{error.message}"
+  exit 1
+end
+
+if out_path
+  File.write(out_path, report)
+else
+  puts report
+end
+
+exit 0

package/bin/verify-change

@@ -0,0 +1,345 @@
+#!/usr/bin/env ruby
+require "fileutils"
+require "open3"
+require "tmpdir"
+
+class VerifyChange
+  USAGE = <<~TEXT
+    Usage: bin/verify-change [BASE] [--test FILE]...
+
+    Checks only the code changed since the merge base of BASE and HEAD
+    (BASE defaults to origin/main, then main, then master):
+
+      1. lint on the changed Ruby files, in the project's style guide
+      2. the tests for the changed files, plus every --test FILE, with coverage on
+      3. patch coverage of the changed lines (simplecov patch)
+      4. mutation testing of the changed lines (mutineer, operators from .mutineer.yml)
+      5. CRAP scores of the changed methods (bin/crap)
+
+    Runs RSpec specs in a project with spec/ and .rspec, spec/spec_helper.rb,
+    or spec/rails_helper.rb, or with rspec, rspec-core, or rspec-rails under
+    DEPENDENCIES in Gemfile.lock, and Minitest tests otherwise. Warns when
+    both test/ and spec/ exist. Pass --test for the integration or system
+    tests of a feature the change touches.
+
+    A lint failure is reported but does not stop the other checks. Lint is
+    skipped, not failed, with no style guide, two style guides, no changed
+    Ruby files, or the linter gem missing from Gemfile.lock.
+
+    Every child runs under a throwaway HOME and PLASTIC_TMP, so a test or a
+    mutant that spawns an installer cannot reach the real home directory.
+
+    Exit codes: 0 verified, 1 a check failed, 2 usage or git error.
+  TEXT
+
+  PATCH_COVERAGE_MINIMUM = 100
+  MUTATION_THRESHOLD = 75
+  CRAP_THRESHOLD = 30
+  TESTS_STEP = "Tests with coverage"
+  LINT_STEP = "Lint"
+  DEFAULT_BASES = %w[origin/main main master].freeze
+  ALL_OPERATORS = %w[arithmetic comparison boolean_connector boolean_literal statement_removal return_nil
+                      literal_mutation condition_negation string_literal regex collection_method].freeze
+  SOURCE_PATH = %r{\A(app|lib|tools|scripts|bin/lib)/.+\.rb\z}
+  RSPEC_DEPENDENCY = /^  rspec(-core|-rails)?(\s|!|$)/
+
+  Suite = Data.define(:name, :folder, :test_path, :locations, :suffix)
+  MINITEST = Suite.new(name: "Minitest", folder: "test/", test_path: %r{\Atest/.+_test\.rb\z}, suffix: "_test.rb",
+                       locations: { %r{\Aapp/} => ["test/"], %r{\Alib/} => ["test/", "test/lib/"], %r{\Atools/} => ["test/tools/"],
+                                    %r{\Ascripts/lib/} => ["test/", "test/lib/"], %r{\Abin/lib/} => ["test/"], %r{\Ascripts/} => ["test/"] })
+  RSPEC = Suite.new(name: "RSpec", folder: "spec/", test_path: %r{\Aspec/.+_spec\.rb\z}, suffix: "_spec.rb",
+                    locations: { %r{\Aapp/} => ["spec/"], %r{\Alib/} => ["spec/", "spec/lib/"], %r{\Atools/} => ["spec/tools/"] })
+
+  Step = Struct.new(:title, :env, :command)
+  LintDecision = Struct.new(:step, :skip_reason)
+  Plan = Struct.new(:sources, :tests, :untested, :lint_files, :lint_decision, :steps)
+
+  def self.test_candidates(source, suite = MINITEST)
+    suite.locations.flat_map do |prefix, targets|
+      source.match?(prefix) ? targets.map { |target| source.sub(prefix, target).sub(/\.rb\z/, suite.suffix) } : []
+    end
+  end
+
+  def initialize(argv, root: Dir.pwd, out: $stdout, err: $stderr, git: nil, run: nil, sandbox: nil)
+    @argv = argv.dup
+    @root = root
+    @out = out
+    @err = err
+    @git = git || ->(*args) { Open3.capture2e("git", "-C", root, *args) }
+    @run = run || ->(env, command) { system(env, *command, chdir: root) }
+    @sandbox = sandbox
+    @owned_sandbox = sandbox.nil?
+  end
+
+  # A throwaway home for every child this script spawns. A gate step runs the
+  # project's own tests, and a test (or a mutant that defeats an injected
+  # runner) can spawn an installer, which resolves ~/.plastic and ~/.claude
+  # from HOME. Pointing HOME at a fresh directory is what keeps the real home
+  # out of reach; PLASTIC_TMP does the same for the session bridge files.
+  def sandbox
+    @sandbox ||= { "HOME" => Dir.mktmpdir("verify-change-home"),
+                   "PLASTIC_TMP" => Dir.mktmpdir("verify-change-tmp") }
+  end
+
+  def call
+    return usage(0) if @argv.include?("--help") || @argv.include?("-h")
+
+    requested_base, extra_tests = parse_arguments
+    return usage(2) unless requested_base
+
+    base = merge_base(requested_base)
+    return 2 unless base
+
+    report_untracked
+    chosen = suite
+    report_both_suites(chosen)
+    plan = plan(changed: changed_files(base), extra_tests: extra_tests, base: base, rails: rails?, suite: chosen)
+    execute(plan, requested_base)
+  ensure
+    discard_sandbox
+  end
+
+  def discard_sandbox
+    return unless @owned_sandbox && @sandbox
+
+    @sandbox.each_value { |dir| FileUtils.remove_entry(dir, true) }
+    @sandbox = nil
+  end
+
+  def plan(changed:, extra_tests:, base:, rails:, suite: MINITEST)
+    sources = changed.grep(SOURCE_PATH).select { |path| exist?(path) }
+    lint_files = changed.select { |path| File.extname(path) == ".rb" && exist?(path) }
+    mapped = sources.to_h { |source| [source, self.class.test_candidates(source, suite).select { |path| exist?(path) }] }
+    changed_tests = changed.grep(suite.test_path)
+    tests = (changed_tests + mapped.values.flatten + extra_tests).uniq.select { |path| exist?(path) }
+    covered_elsewhere = !extra_tests.empty? || changed_tests.any?
+    untested = covered_elsewhere ? [] : mapped.select { |_source, found| found.empty? }.keys
+    Plan.new(sources, tests, untested, lint_files, lint_decision(lint_files), steps(sources, tests, base, rails, suite))
+  end
+
+  private
+
+  def parse_arguments
+    base = nil
+    extra_tests = []
+    arguments = @argv.dup
+    until arguments.empty?
+      argument = arguments.shift
+      if argument == "--test"
+        file = arguments.shift
+        return [nil, []] unless file
+
+        extra_tests << file
+      elsif argument.start_with?("-") || base
+        return [nil, []]
+      else
+        base = argument
+      end
+    end
+    [base || default_base, extra_tests]
+  end
+
+  def default_base
+    DEFAULT_BASES.find { |ref| @git.call("rev-parse", "--verify", "--quiet", ref).last.success? } || DEFAULT_BASES.last
+  end
+
+  def merge_base(ref)
+    output, status = @git.call("merge-base", ref, "HEAD")
+    return output.strip if status.success?
+
+    @err.puts "Cannot find the merge base of #{ref} and HEAD: #{output.strip}"
+    nil
+  end
+
+  def changed_files(base)
+    @git.call("diff", "--name-only", base, "--", "*.rb").first.split("\n")
+  end
+
+  def report_untracked
+    untracked = @git.call("ls-files", "--others", "--exclude-standard", "--", "*.rb").first.split("\n")
+    return if untracked.empty?
+
+    @err.puts "Not checked, because git does not track them yet (run git add first): #{untracked.join(", ")}"
+  end
+
+  def report_both_suites(chosen)
+    return unless File.directory?(File.join(@root, "test")) && File.directory?(File.join(@root, "spec"))
+
+    skipped = chosen == RSPEC ? MINITEST : RSPEC
+    @err.puts "Both test/ and spec/ exist. Checking with #{chosen.name} only, so changed files under #{skipped.folder} do not run."
+  end
+
+  def steps(sources, tests, base, rails, suite)
+    steps = []
+    steps << step(TESTS_STEP, { "COVERAGE" => "1" }, test_command(tests, rails, suite)) unless tests.empty?
+    return steps if sources.empty?
+
+    steps << step("Patch coverage", {}, %W[bundle exec simplecov patch --base #{base} --minimum #{PATCH_COVERAGE_MINIMUM}])
+    steps << step("Mutation testing", {}, mutation_command(sources, tests, base, rails, suite))
+    steps << step("CRAP scores", {}, %W[bundle exec bin/crap --threshold #{CRAP_THRESHOLD} --since #{base}] + sources)
+  end
+
+  def step(title, env, command)
+    Step.new(title, sandbox.merge(env), command)
+  end
+
+  def test_command(tests, rails, suite)
+    return %w[bundle exec rspec] + tests if suite == RSPEC
+    return %w[bin/rails test] + tests if rails
+
+    %w[bundle exec ruby -Ilib -Itools -Itest -e] + [%(require "test_helper"; ARGV.each { |file| require File.expand_path(file) })] + tests
+  end
+
+  def lint_decision(lint_files)
+    return LintDecision.new(nil, "no changed Ruby files to lint") if lint_files.empty?
+    return LintDecision.new(nil, "two style guides found: .standard.yml and .rubocop.yml") if ambiguous_style_guide?
+
+    if rubocop_file?
+      return lint_gem_available?(:rubocop) ? LintDecision.new(lint_step(:rubocop, lint_files), nil) : LintDecision.new(nil, "the rubocop gem is not in Gemfile.lock")
+    end
+
+    if standard_file? || dependencies_section.match?(/^  standard(\s|!|$)/)
+      return lint_gem_available?(:standard) ? LintDecision.new(lint_step(:standard, lint_files), nil) : LintDecision.new(nil, "the standard gem is not in Gemfile.lock")
+    end
+
+    LintDecision.new(nil, "no style guide found")
+  end
+
+  # Local adaptation (intent 363): RuboCop reads .rubocop_with_todo.yml here, which
+  # is .rubocop.yml plus the generated todo. The todo holds this repository's 16,116
+  # pre-existing offences, so a lint run reports what the change did and nothing
+  # else. .rubocop.yml, the todo-free config, is what the repository is measured
+  # against as the todo shrinks.
+  def lint_step(guide, lint_files)
+    command = guide == :standard ? %w[bundle exec standardrb --force-exclusion] : rubocop_command
+    step(LINT_STEP, {}, command + lint_files)
+  end
+
+  def rubocop_command
+    base = %w[bundle exec rubocop --force-exclusion]
+    exist?(".rubocop_with_todo.yml") ? base + %w[--config .rubocop_with_todo.yml] : base
+  end
+
+  def lint_gem_available?(command_gem)
+    return true if command_gem == :rubocop && (dependencies_section.match?(/^  rubocop(\s|!|$)/) ||
+                    dependencies_section.match?(/^  standard(\s|!|$)/) || dependencies_section.match?(/^  rubocop-rails-omakase(\s|!|$)/))
+    return true if command_gem == :standard && dependencies_section.match?(/^  standard(\s|!|$)/)
+
+    false
+  end
+
+  def ambiguous_style_guide?
+    standard_file? && rubocop_file? && !rubocop_config_uses_standard?
+  end
+
+  def rubocop_config_uses_standard?
+    config = rubocop_config
+    return false if config.empty?
+
+    config.match?(/inherit_gem:\s*\{?\s*standard:/m) ||
+      config.match?(/^(plugins|require):\s*\n(?:[ \t]*-[ \t]*\S+[ \t]*\n)*?[ \t]*-[ \t]*standard[ \t]*$/m) ||
+      config.match?(/^(plugins|require):\s*\[[^\]]*\bstandard\b[^\]]*\]/m)
+  end
+
+  def rubocop_config
+    exist?(".rubocop.yml") ? File.read(File.join(@root, ".rubocop.yml")) : ""
+  end
+
+  def standard_file?
+    exist?(".standard.yml")
+  end
+
+  def rubocop_file?
+    exist?(".rubocop.yml")
+  end
+
+  def dependencies_section
+    return @dependencies_section if defined?(@dependencies_section)
+
+    lockfile = exist?("Gemfile.lock") ? File.read(File.join(@root, "Gemfile.lock")) : nil
+    unless lockfile
+      return @dependencies_section = ""
+    end
+
+    lines = lockfile.lines
+    start = lines.index { |line| line.strip == "DEPENDENCIES" }
+    unless start
+      return @dependencies_section = ""
+    end
+
+    section = []
+    lines[(start + 1)..].each do |line|
+      break if line.strip.empty?
+
+      section << line
+    end
+    @dependencies_section = section.join
+  end
+
+  def mutation_command(sources, tests, base, rails, suite)
+    %w[bundle exec mutineer run] + sources + tests.flat_map { |test| ["--test", test] } +
+      %W[--since #{base} --threshold #{MUTATION_THRESHOLD}] + (suite == RSPEC ? %w[--framework rspec] : []) +
+      (rails ? %w[--rails] : %w[--strategy redefine]) +
+      (exist?(".mutineer.yml") ? [] : ["--operators", ALL_OPERATORS.join(",")])
+  end
+
+  def execute(plan, requested_base)
+    if plan.sources.empty? && plan.tests.empty? && plan.lint_files.empty?
+      @out.puts "No changed Ruby files since #{requested_base}."
+      return 0
+    end
+    unless plan.untested.empty?
+      @err.puts "No test file found for: #{plan.untested.join(", ")}. Write one, or pass --test FILE for the tests that cover it."
+      return 1
+    end
+    unless exist?(".mutineer.yml") || plan.sources.empty?
+      @err.puts "Missing .mutineer.yml: passing all 11 operators on the command line instead."
+    end
+
+    @out.puts "Base:    #{requested_base}"
+    @out.puts "Sources: #{plan.sources.empty? ? "none" : plan.sources.join(", ")}"
+    @out.puts "Tests:   #{plan.tests.join(", ")}"
+    @out.puts "Home:    #{sandbox["HOME"]}"
+    FileUtils.rm_rf(File.join(@root, "coverage"))
+    failed = []
+    if plan.lint_decision.step
+      @out.puts "\n== #{LINT_STEP}"
+      failed << plan.lint_decision.step unless @run.call(plan.lint_decision.step.env, plan.lint_decision.step.command)
+    elsif plan.lint_decision.skip_reason
+      @out.puts "\nLint skipped: #{plan.lint_decision.skip_reason}"
+    end
+    plan.steps.each do |step|
+      @out.puts "\n== #{step.title}"
+      next if @run.call(step.env, step.command)
+
+      failed << step
+      next unless step.title == TESTS_STEP
+
+      @out.puts "\nThe tests are red, so the other checks did not run: a failing test kills every mutant."
+      break
+    end
+    @out.puts failed.empty? ? "\nChange verified" : "\nFailed: #{failed.map(&:title).join(", ")}"
+    failed.empty? ? 0 : 1
+  end
+
+  def rails?
+    exist?("config/application.rb")
+  end
+
+  def suite
+    listed = dependencies_section.match?(RSPEC_DEPENDENCY)
+    spec = File.directory?(File.join(@root, "spec")) && (exist?(".rspec") || exist?("spec/spec_helper.rb") || exist?("spec/rails_helper.rb"))
+    spec || listed ? RSPEC : MINITEST
+  end
+
+  def exist?(path)
+    File.exist?(File.join(@root, path))
+  end
+
+  def usage(code)
+    (code.zero? ? @out : @err).puts USAGE
+    code
+  end
+end
+
+exit VerifyChange.new(ARGV).call if $PROGRAM_NAME == __FILE__

package/deprecations.yml

@@ -1,6 +1,6 @@
 # Plastic deprecation notices
 # Each entry is shown to the user during SessionStart.
-# See the plastic-releasing skill for the full convention.
+# See CONTRIBUTING.md's "Cut a release" section for the full convention.
 #
 # Schema:
 #   id: unique-slug (used for dismissal tracking)

package/{skills/agent-advisor/references → docs/help}/advisor-protocol.md

@@ -2,16 +2,13 @@
 
 *Companion to the Operating Manual. How to use Fable as your advisor and planner.*
 
-*Adapted for Plastic (intent 185): this is the shipped reference copy the
-`plastic-agent-advisor` skill teaches from. Two named agents carry it,
+*Adapted for Plastic (intent 185): this is the shipped reference copy, reached with
+`plastic help advisor-protocol`. Two named agents carry it,
 `plastic-primary-advisor` (Primary Advisor) and `plastic-secondary-advisor`
 (Secondary Advisor, the explicit escalation); the
 answer shape below shapes 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 `plastic-primary-advisor`) to route your
-consultation automatically; name a
-specific advisor in your request to override it. A frontier model rewards a
+dispatch, never which file to pick. There is no automatic routing between them: the user or
+the main session dispatches one deliberately, by naming it. A frontier model rewards a
 single, well-formed one-shot brief more than a back-and-forth, so front-load
 everything section 3 below asks for before you send. The rest of this
 document is the owner's protocol, unchanged.*

package/{skills/auto/references → docs/help}/agent-architecture.md

@@ -28,9 +28,9 @@ in 2.0, intent 304; the lead writes the Why and How record itself):
   reviewed before code; dispatches the executor; applies the risk rule; closes.
 - **plastic-executor** (Exec): commits the matrix's tests red, writes the code, checks off
   `checklist.md`, appends `## Insights`, and drives the suite green.
-- **the plan reviewer**: a fresh agent on `plastic-intent-executing`'s
-  `plan-reviewer-prompt.md`, an optional dispatch before any code exists.
-- **the post-execution reviewer**: a fresh agent on `code-quality-reviewer-prompt.md`,
+- **the plan reviewer**: a fresh agent on the auto skill's
+  `references/plan-reviewer-prompt.md`, an optional dispatch before any code exists.
+- **the post-execution reviewer**: a fresh agent on `references/code-quality-reviewer-prompt.md`,
   dispatched only when the auto skill's risk rule fires; never the maker.
 
 One agent boot (the executor) is the minimum delivery; the plan reviewer is a second,
@@ -118,14 +118,14 @@ written path, and the lead verifies state from the files (`plastic-lock status`,
 ### Delegation
 
 The roles are thin handoff contracts, not a spawning engine. Dispatch runs through Plastic's
-own engine, `plastic-intent-executing`: one executor for the consolidated action, the two
+own engine, `plastic intent step`: one executor for the consolidated action, the two
 reviewer prompts as fresh agents. The team model defines who hands what to whom and where the
 reviews sit; the engine does the actual spawning.
 
 ### Fallback by Case
 
 If the harness supports agent dispatch, auto mode dispatches through
-`plastic-intent-executing`. If the harness has no agent dispatch at all (Codex CLI today), the
+`plastic intent step`. If the harness has no agent dispatch at all (Codex CLI today), the
 lead walks the five steps itself: it still writes the matrix and the tests first, and reviews
 its own plan against the matrix before code, saying so in `## Insights`.
 
@@ -147,8 +147,8 @@ tests first, one suite run per intent.
 ## Autonomous Delivery
 
 Human owns What and Why for human-initiated intents. The team assists (research, exploration)
-but the human drives until handoff. When Why is complete, or the human triggers `plastic-auto`,
-the auto team takes over How and Exec autonomously.
+but the human drives until handoff. When Why is complete, or the human runs
+`plastic auto take ID`, the auto team takes over How and Exec autonomously.
 
 - **Safe-by-default:** the executor always prefers non-destructive routes (rename vs delete,
   additive migrations, backups before changes). Destructive actions on existing projects

package/{skills/conventions/references → docs/help}/completion-and-done.md

@@ -39,4 +39,4 @@ INDEX but the lock is still present or stale). Finishing the tail is FINISHING a
 a done intent is never moved back to `## Active`.
 
 One report per audience: a delivery produces `outcome.md` plus one EM-to-CTO owner report, and
-no other step restates either (see `skills/auto/references/human-report-contract.md`).
+no other step restates either (see `plastic help human-report-contract`).

package/{skills/auto/references → docs/help}/human-report-contract.md

@@ -29,27 +29,25 @@ written by eye:
 
 ## Binding table (intent 331f)
 
-Every skill that shows state names its own report verb, one row per skill and trigger. Each
-bound skill's file carries the SAME rule next to its verb: print the screen as the first
+Every command or lead role that shows state names its own report verb, one row per binding
+and trigger. Each one carries the SAME rule next to its verb: print the screen as the first
 characters of the reply, nothing before it, no fence, or the hook cannot paint it.
 
-| Skill | Trigger | Verb |
+| Command or lead | Trigger | Verb |
 |---|---|---|
-| `plastic-intent-continuing` | project route (continue, load project) | `dashboard.rb ... --screen` |
-| `plastic-intent-continuing` | a named intent | `report-screen state` |
-| `plastic-intent-continuing` | "where are we" (a status ask) | `report-screen session` |
-| `plastic-intent-continuing` | "why so long" | `report-screen delay` |
-| `plastic-intent-continuing` | a roadmap route | `report-screen roadmap ... state` |
-| `plastic-auto` | the How boundary, before the executor | `report-screen plan` |
-| `plastic-auto` | each of the five triggers | `report-screen state` |
-| `plastic-auto` | close | `report-screen delivered` |
-| `plastic-intent-ending` | the close | `report-screen delivered` |
-| `plastic-intent-speccing` | the action files are written | `report-screen plan` |
-| `plastic-roadmap` | create | `report-screen roadmap ... plan` |
-| `plastic-roadmap` | read | `report-screen roadmap ... state` |
-| `plastic-roadmap` | close | `report-screen roadmap ... delivered` |
-| `plastic-dashboard` | any invocation | `dashboard.rb ... --screen` |
-| `plastic-intent-executing` | after the red commit, and after the suite | `report-screen state` |
+| `plastic continue` | project route (continue, load project) | `dashboard.rb ... --screen` |
+| `plastic continue` | a named intent | `report-screen state` |
+| `plastic continue` | "where are we" (a status ask) | `report-screen session` |
+| `plastic continue` | "why so long" | `report-screen delay` |
+| `plastic continue` | a roadmap route | `report-screen roadmap ... state` |
+| the auto team's lead | the How boundary, before the executor | `report-screen plan` |
+| the auto team's lead | each of the five triggers | `report-screen state` |
+| the auto team's lead | close | `report-screen delivered` |
+| `plastic intent end` | the close | `report-screen delivered` |
+| `plastic intent spec` | the action files are written | `report-screen plan` |
+| `plastic roadmap show` | any invocation | `report-screen roadmap ... state` |
+| `plastic status` | any invocation | in-process (`Scope#stores`) |
+| `plastic intent step` | after the red commit, and after the suite | `report-screen state` |
 
 ## A roadmap's own three reports (intent 331c)
 
@@ -104,7 +102,7 @@ A delivery still ends with `outcome.md` plus one `delivered` screen.
 
 A delivery produces exactly two artifacts: `outcome.md` (generated by `scripts/end-intent`
 from `graph.md`, `nodes/`, and the ledger when the intent has one, intent 339; hand-authored
-by `plastic-intent-ending` otherwise) and one `delivered` screen at the End stage. No stage or skill restates a delivery already
+by `plastic intent end` otherwise) and one `delivered` screen at the End stage. No stage or skill restates a delivery already
 written to `outcome.md`; point at it instead. Skills do not open with a banner that names the
 skill or restates the intent id and name the owner just typed. Announce only what the reader
 cannot already know: an error, a result, a choice with its reason, or a handoff.

package/{skills/conventions/references → docs/help}/roadmaps.md

@@ -6,8 +6,8 @@ This chapter holds the full roadmap file format and its relationship to INDEX.md
 
 Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
 is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
-release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
-close, and consume one.
+release (completion-side, tracked in `CHANGELOG.md`). Create one by hand from the template, then
+use `plastic roadmap show`, `next`, `log`, and `check` to read, drive, and audit it.
 
 File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
 inside `store/` (store holds intent directories, not project artifacts). For a project that is its