@zalom/plastic 1.0.3 → 1.1.0

package/skills/intent-speccing/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: plastic-intent-speccing
+description: >
+  Consolidate the enriched Why (`## Context`, `### Decisions`, `## Insights`) into `spec.md`
+  through a deterministic, judgment-free numbered sequence. Use when the user types the command
+  to turn the brainstorm into a spec, asks to "write the spec", "spec this intent", "consolidate
+  into spec.md", or the active intent is at Why with enough Decisions on record to close it out.
+  Also fires on an indirect request that never names spec.md, such as "turn what we just
+  discussed into the contract the planner builds from." Distinct from `plastic-intent-brainstorming`
+  (the exploration that produces the enriched Why, upstream of this skill) and
+  `plastic-intent-planning` (turns an existing spec.md into plan.md for How, downstream of this
+  skill).
+user-invocable: true
+---
+
+# Intent Speccing
+
+Consolidate the enriched Why into `spec.md` through eight fixed steps, one action per step. The
+next action is never a judgment call: when a section cannot be filled from what is on record,
+step 5 is to stop and ask, never invent.
+
+## Precondition
+
+Run only when the active intent is at Why (its `## Intent` and enriched `## Context` plus
+`### Decisions` exist, `spec.md` does not yet exist or is being redone) and the user has asked to
+consolidate that Why into the spec. If no intent is active, or the active intent is not at Why,
+report that and stop; do not guess which intent is meant.
+
+## The 8-step sequence
+
+| Step | Action |
+|---|---|
+| 1 | Confirm the precondition above. |
+| 2 | Read inputs in fixed order and build a ruling ledger: (a) `## Context` and `### Decisions`; (b) `## Insights` newest-last, so a later ruling supersedes an earlier conflicting one; (c) `resources/discovery--<slug>.md`; (d) any other `resources/*.md`. |
+| 3 | Decide the tier: adopt the brainstorming `Tier:` recommendation from Decisions or Insights; otherwise apply the PLASTIC.md tiers rubric (S = single mechanism or file cluster, M = one subsystem, L = cross-cutting or novel design). |
+| 4 | Fill the template section by section, all 8 sections in template order. Read `references/per-section-fill-rules.md` now, filling the template is the trigger. Write the tier as the literal top line above `# Spec:`. Encode every ruling into its matching section, later supersedes earlier on conflict. A collapsed single-line S/M section is complete and valid; do not pad it. |
+| 5 | Gap rule: if any section cannot be filled from the ledger built in step 2, STOP and ask the user for the missing ruling. Never invent scope to fill a gap. |
+| 6 | State the gate position (below) so the user knows what happens next. |
+| 7 | Self-verify against the checklist. Read `references/self-verify-checklist.md` now, verifying before presenting is the trigger. Fix any failing check, then re-verify from the top. |
+| 8 | Present `spec.md` for the user-review gate, then hand off to `plastic-intent-planning` for How. |
+
+## Gate position (step 6)
+
+The Why stage's deliverable is `spec.md`; the gate is satisfied the moment a complete, real
+`spec.md` exists (this is the gates-by-name framing: gate-check enforces spec.md before plan.md,
+not the Transition Gates table row). Writing `plan.md` is what opens the code gate for Exec, and
+writing `plan.md` is not this skill's job, that is `plastic-intent-planning`. State this to the user
+at step 6 so the handoff at step 8 is expected, not a surprise.
+
+## Tier stamp (step 3, convention only)
+
+Write `Tier: S|M|L` as the literal first line of the file, above the `# Spec:` heading. This line
+is convention-only: the orchestrator and the planner read it, no gate and no doctor check
+validates it.
+
+## Completion report
+
+State, in this order: which file was written (`spec.md`, new or rewritten), the stamped `Tier:`
+value, the count of Acceptance Criteria produced (the surface the planner will cover), which
+`## Insights` rulings superseded an earlier Decision (if any) and where each landed, and the
+handoff target (`plastic-intent-planning`). If step 5 stopped for a missing ruling, report that
+instead: which section, what is missing, and the question put to the user.
+
+## References
+
+| Trigger | Read |
+|---|---|
+| Filling the template (step 4) | `references/per-section-fill-rules.md` |
+| Self-verifying before presenting (step 7) | `references/self-verify-checklist.md` |

package/skills/intent-speccing/evals/evals.json

@@ -0,0 +1,126 @@
+{
+  "skill_name": "plastic-intent-speccing",
+  "notes": "Intent 163. Scopes: description triggering (1-4) and behavior (5-8: all-8-sections output, mandatory superseding-ruling case, STOP-and-ask gap rule, tabular alternatives with no em-dash). No dedicated Ruby test file backs this skill yet (natural-language guided command), so all assertions are result: expect-pass pending a real observed run, per the intent-starting evals.json convention.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "triggering",
+      "set": "train",
+      "prompt": "The active intent is at Why with Context and Decisions recorded. Consolidate the enriched Why into spec.md.",
+      "expected_output": "Activates plastic-intent-speccing (the user-typed Why-to-How consolidation command).",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "router CHOICE == plastic-intent-speccing",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "scope": "triggering",
+      "set": "train",
+      "prompt": "Turn what we just discussed into the contract the planner builds from.",
+      "expected_output": "Activates plastic-intent-speccing; an indirect trigger that names neither the skill nor spec.md.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "router CHOICE == plastic-intent-speccing",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "Brainstorm this intent.",
+      "expected_output": "Does NOT activate plastic-intent-speccing; activates plastic-intent-brainstorming (exploration that produces the enriched Why, upstream of speccing).",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "router CHOICE != plastic-intent-speccing",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "Write the plan.",
+      "expected_output": "Does NOT activate plastic-intent-speccing; activates plastic-intent-planning (turns an existing spec.md into plan.md for How, downstream of speccing).",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "router CHOICE != plastic-intent-speccing",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Intent Y is at Why: Context describes the problem and goal, and 5 Decisions are recorded resolving scope, approach, and one rejected alternative. Consolidate into spec.md.",
+      "expected_output": "Produces spec.md with Tier: S|M|L as the literal top line above the Spec heading; all 8 template sections present once, in template order (Problem, Goals, Non-Goals, Approach, Alternatives Considered, Decisions, Acceptance Criteria, Open Questions); no template placeholder text remains; every recorded Decision is encoded into its matching section.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "Tier line is literally the first line of the file; all 8 sections appear once each, in template order; no placeholder text; every Decision traces to a section",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 6,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Intent Z has Decisions recording D4: ship the setting as a CLI flag. A later Insights entry, timestamped after D4, reads: superseding ruling, ship as a config-file setting instead of a CLI flag, per user correction. Consolidate into spec.md.",
+      "expected_output": "The produced spec Approach and Decisions sections encode the LATER ruling (config-file setting); the superseded earlier Decision (CLI flag) does not stand as the shipped design in any section. The Decisions section notes that the later Insight supersedes D4.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "Approach and Decisions state the config-file setting, not the CLI flag; no section still asserts the CLI-flag path as the shipped design",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 7,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Intent W is at Why. Context says the team wants error handling that is more resilient, but no Decision or Insight states which specific mechanism (retry, circuit breaker, or fallback) was chosen. Consolidate into spec.md.",
+      "expected_output": "Stops at step 5 (the gap rule) instead of inventing an Approach; asks the user which error-handling mechanism was decided, naming the missing ruling and the section it blocks.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "no invented Approach or Decisions content fills the gap; the agent asks for the missing ruling instead of guessing a default mechanism",
+          "result": "expect-pass"
+        }
+      ]
+    },
+    {
+      "id": 8,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Intent V has Decisions recording 3 rejected alternatives, each with a one-line reason it lost. Consolidate into spec.md.",
+      "expected_output": "Alternatives Considered renders as a table (Alternative, Not chosen because), not the bullet-dash form shown in the template; the produced spec file contains no em-dashes or en-dashes anywhere in the file.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "Alternatives Considered is a two-column table with one row per rejected alternative; a full-file dash-glyph scan of the produced spec file finds none",
+          "result": "expect-pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/intent-speccing/references/per-section-fill-rules.md

@@ -0,0 +1,92 @@
+# Per-Section Fill Rules
+
+The single shared method for turning the enriched Why into `spec.md`. Both
+`plastic-intent-speccing` (guided) and the `plastic-spec-specialist` agent (auto) point here;
+neither restates these rules. One fill rule per template section, in template order.
+
+Read the ruling ledger first (built in step 2 of the SKILL.md sequence): `## Context` plus
+`### Decisions`, then `## Insights` newest-last (a later ruling supersedes an earlier
+conflicting one), then `resources/discovery--<slug>.md`, then any other `resources/*.md`.
+Every rule below names which part of that ledger feeds the section.
+
+## 1. Problem
+
+Source: the intent's `## Intent` line plus the problem narrative in `## Context`.
+
+State the problem as a problem, not a solution: what is broken, missing, or costly today, for
+whom. Do not describe the fix here, that belongs in Approach. If `## Insights` records a later
+reframe of the problem (a scope correction, a retargeted root cause), the later framing wins.
+
+## 2. Goals
+
+Source: explicit goal statements in `## Context`, plus any `### Decisions` entry that commits to
+delivering a specific outcome.
+
+One bullet per goal, each a concrete, observable outcome the delivery must reach. Encode every
+Decision that commits to an outcome as its own bullet, do not compress two Decisions into one
+vague goal. A single-line collapsed Goals section (S/M tier) is complete if it names every
+outcome; do not pad it with restated Problem text.
+
+## 3. Non-Goals
+
+Source: `### Decisions` entries that name something explicitly out of scope, and `## Insights`
+rulings that narrowed scope after the initial brainstorm.
+
+One bullet per excluded item, each naming what is out and, briefly, why (a sibling intent owns
+it, a scope-reframe ruling cut it, it is a future intent). If a later Insight narrows scope
+further than an earlier Decision, the Insight's narrower boundary is the one recorded.
+
+## 4. Approach
+
+Source: every `### Decisions` entry that describes HOW, resolved into one coherent narrative.
+
+Write prose, not a decision list. Synthesize the chosen path so it reads as one design: what
+gets built, in what shape, and how the pieces fit. Every Decision that shapes the approach must
+be traceable to a sentence here, but do not restate each Decision by its Dn label, that
+enumeration belongs in the Decisions section. Use a table only where the Approach itself compares
+options inline (rare; usually that comparison belongs in Alternatives Considered instead).
+
+## 5. Alternatives Considered
+
+Source: `### Decisions` entries and `## Insights` rulings that name a rejected path and the
+reason it lost.
+
+Render as a table, not the template's bullet-dash form, so the reason column stays uniform and
+free of dash-glyph punctuation:
+
+| Alternative | Not chosen because |
+|---|---|
+| <rejected path> | <the ruling's stated reason, paraphrased> |
+
+One row per rejected alternative. If two Decisions reject variants of the same alternative, merge
+them into one row rather than duplicating it. Never use an em-dash or en-dash in the reason
+column; write "because" or a colon instead.
+
+## 6. Decisions
+
+Source: `### Decisions` verbatim, in the order recorded, one entry per Decision.
+
+One bullet per decision, each keeping its `Dn` label and its ruling in paraphrase or verbatim.
+Do not drop a decision because it seems minor: every Decision must appear here even if its effect
+on the shipped Approach or Goals is small. When `## Insights` records a later ruling that
+supersedes an earlier Decision, add or amend the bullet to state the later ruling and note which
+earlier Decision it supersedes.
+
+## 7. Acceptance Criteria
+
+Source: any criteria named directly in `### Decisions` or `## Insights`, plus one inferred
+criterion per Goal that has no explicit criterion on record.
+
+One checkbox bullet per criterion, each concretely checkable: a fact a reviewer can confirm true
+or false by inspection, a command, or a file, never a vague quality judgment. Every Goal must map
+to at least one criterion. A criterion that cannot be checked without more interpretation is not
+done, rewrite it or ask (the gap rule, SKILL.md step 5).
+
+## 8. Open Questions
+
+Source: any question raised during Why that has no matching Decision or Insight resolving it.
+
+List each unresolved question as its own bullet. If every question raised during Why has a
+resolving Decision or Insight, write `None` and, directly under it, one line per resolved
+question naming which Decision or Insight resolved it (so a reader can audit the resolution
+instead of taking "None" on faith).

package/skills/intent-speccing/references/self-verify-checklist.md

@@ -0,0 +1,38 @@
+# Self-Verify Checklist
+
+Run this before presenting spec.md (SKILL.md step 7). Ten checks: the four points of
+brainstorming's proven Spec Self-Review, merged with the six binding output checks this skill
+adds. Fix any failing check, then re-verify from the top; do not present a spec that fails one of
+these.
+
+## Brainstorming's four Spec Self-Review points
+
+1. **Placeholder scan.** Any "TBD", "TODO", incomplete section, or vague requirement left in the
+   draft? Fix it before moving on.
+2. **Internal consistency.** Do any two sections contradict each other? Does the Approach
+   actually match what Goals and Acceptance Criteria describe?
+3. **Scope check.** Is this spec focused enough for a single implementation plan, or does the
+   Problem actually describe more than one independent piece of work that needs decomposing
+   first?
+4. **Ambiguity check.** Could any requirement be read two different ways? If so, pick one
+   reading and rewrite the line so only that reading survives.
+
+## The six binding output checks
+
+5. **No template placeholder text remains.** No literal `<intent name>`, `<alternative>`, `...`,
+   sample bracket text, or other template filler from `templates/spec.md` survives anywhere in
+   the artifact.
+6. **Tier stamp is the top line.** `Tier: S|M|L` is the literal first line of the file, above the
+   `# Spec:` heading, not folded into a section body.
+7. **All 8 sections present, in template order.** Problem, Goals, Non-Goals, Approach,
+   Alternatives Considered, Decisions, Acceptance Criteria, Open Questions, each present once, in
+   that order, none merged into another.
+8. **Every `## Insights` ruling is traceable to a spec line.** Walk the Insights log entry by
+   entry: each one lands in some section of the spec. Where two rulings conflict, the later one
+   (further down the log) is the one that landed, and the earlier one does not silently persist
+   in a different section.
+9. **Acceptance criteria are concretely checkable.** Each Acceptance Criteria bullet reads as a
+   fact a reviewer can confirm true or false by inspection, a command, or a named file, not a
+   quality judgment a reviewer would have to interpret.
+10. **No em-dashes or en-dashes anywhere in the artifact.** Scan the full file; replace any dash
+    glyph with a comma, period, parenthesis, or colon.

package/skills/intent-starting/SKILL.md

@@ -57,7 +57,7 @@ enforces it: without a held lock, mutating writes to this active intent's dir ar
 4. **Dispatch What-stage discovery (under the lock).** Right after arming, when the intent
    was just activated in step 1 (on a resume that already has
    `resources/discovery--<slug>.md`, skip: discovery runs once per intent, at activation
-   only), dispatch the `plastic-intent-discovery` agent (see the `plastic-intent-discovery`
+   only), dispatch the `plastic-intent-discovery` agent (see the `plastic-intent-discovering`
    skill), now that this session owns the lock, deposit authorized as the owner session. Resolve its
    model explicitly and pass it at dispatch time (belt-and-braces): `read-config
    agents.models.plastic-intent-discovery --project <repo>`. The agent runs QMD discovery
@@ -88,7 +88,7 @@ that message, never delete a lock file by hand.
 Read `savepoint.md` and classify from the **last line** alone, then verify ONLY that line's
 artifact is real (sentinel-aware via `Bridge.stage_file_present?`). On drift (the last line
 disagrees with files on disk), rebuild the ledger from disk and note the correction. Do not
-inline the rebuild; the `plastic-savepoint` skill owns it:
+inline the rebuild; the `plastic-intent-savepoint` skill owns it:
 ```bash
 ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
 ```

package/skills/intent-starting/evals/evals.json

@@ -40,7 +40,7 @@
       "scope": "triggering",
       "set": "validation",
       "prompt": "continue",
-      "expected_output": "Does NOT activate plastic-intent-starting; bare 'continue' is plastic-continuing (no specific intent named).",
+      "expected_output": "Does NOT activate plastic-intent-starting; bare 'continue' is plastic-intent-continuing (no specific intent named).",
       "files": [],
       "assertions": [
         { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
@@ -51,7 +51,7 @@
       "scope": "triggering",
       "set": "validation",
       "prompt": "create a new intent for the uploader retry policy",
-      "expected_output": "Does NOT activate plastic-intent-starting; activates plastic-creating-intent.",
+      "expected_output": "Does NOT activate plastic-intent-starting; activates plastic-intent-creating.",
       "files": [],
       "assertions": [
         { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }

package/skills/{creating-project → project-creating}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic-creating-project
+name: plastic-project-creating
 description: >-
   Create a new project from an implementation intent. Sets up project directory,
   git init, AGENTS.md with founding intent decisions, plastic-install --local,
@@ -79,7 +79,7 @@ writes `INDEX.md` and `project.yml` only if missing. It is idempotent, so it is
 safe even when the tactical mirror in step 5 already created the store directory.
 Do not create the store with an inline `mkdir`; the provisioner is the only place
 a store is made. For a project that is already registered but store-less, use the
-`plastic-add-project-store` skill instead.
+`plastic-store-provisioning` skill instead.
 
 ### 8. Mark Global Intent(s) Completed
 

package/skills/releasing/SKILL.md

@@ -214,26 +214,30 @@ gh release edit <tag-name> --latest
 
 ### 8. Complete Active Intent
 
-A release IS a delivery. The active intent that drove this work must be completed as part of the release process. This is NOT optional.
+A release IS a delivery. The active intent that drove this work must be completed as part of the release process. This is NOT optional. The mechanical close (outcome/INDEX/savepoint/commit) is `plastic-intent-ending`'s job, not this skill's: run its backing script rather than restating that prose here.
 
-1. Read `~/.plastic/INDEX.md` → find active intent(s) related to this release
+1. Read `~/.plastic/INDEX.md` (or the project's INDEX.md) - find active intent(s) related to this release.
 2. For each active intent being delivered:
-   a. Write `outcome.md` with detailed results
-   b. Write `## Outcome` summary in the intent file (reference the release tag)
-   c. Update `## Insights` with final observations
-   d. Move from `## Active` to `## Completed` in INDEX.md (with today's date)
-   e. Update clusters to show `_(completed)_`
-3. Auto-commit: `cd ~/.plastic && git add . && git commit -m "feat: complete intent <ID> - delivered in <tag-name>"`
+   a. Write a real `outcome.md` (never leave the scaffold placeholder), `disposition: delivered`, referencing the release tag.
+   b. Update `## Insights` with final observations.
+   c. Run the mechanical close (steps 1-4 of `plastic-intent-ending`): this stamps the intent file's `## Outcome` summary, moves the INDEX.md line to `## Completed` (dated today, with a rich entry description via `--index-note`), appends the savepoint `Done` bookend, and commits the store, all in one call:
+      ```bash
+      ruby ~/.plastic/scripts/end-intent --store <store_path> --id <ID> --disposition delivered \
+        --outcome-summary "delivered in <tag-name>: <one-line summary>" \
+        --index-note "<tag-name>, <mode/tier>; <what shipped>; <suite result>"
+      ```
+   d. Update clusters to show `_(completed)_` (the store-curating skill's job on its next pass).
 
 **If no active intent exists for this release**, that itself is a problem - work happened outside the intent system. Log it and move on, but flag it.
 
 ### 9. Clean Up the Intent's Worktrees (merge-then-remove)
 
-A release is the merge-then-remove path for the intent's worktrees (intent 73c3): the
-intent's code branch is merged back into the default branch BEFORE the worktree is removed.
-Drive it through `Worktree.finish` with `merge: true`, which merges the code branch, then
-removes both worktrees (code + paired store), prunes both repos, and clears the worktree block
-from the bridge:
+This is the release branch of `plastic-intent-ending`'s Step 5 disarm (`merge: true`), not a
+separate concern: a release is the merge-then-remove path for the intent's worktrees (intent
+73c3), so the intent's code branch is merged back into the default branch BEFORE the worktree
+is removed. Drive it through `Worktree.finish` with `merge: true`, which merges the code
+branch, then removes both worktrees (code + paired store), prunes both repos, and clears the
+worktree block from the bridge:
 
 ```bash
 ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
@@ -241,7 +245,7 @@ ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
 ```
 
 (Uses `discover_bridge`, not a bare session-keyed `Bridge.read`, because a session can own more
-than one live bridge now — intent 131 — and `discover_bridge` resolves the right one for this cwd.)
+than one live bridge now (intent 131) and `discover_bridge` resolves the right one for this cwd.)
 
 Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
 prune` in the affected repo if you hit a stale reference. For why this is the one place the

package/skills/{versions → rollback}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: plastic-versions
+name: plastic-rollback
 description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
 user-invocable: true
 ---
 
-# Plastic Versions: local version time-machine
+# Plastic Rollback: local version time-machine
 
 ## When to Use
 - "show plastic versions", "version history", "what versions have I run"
@@ -14,12 +14,18 @@ user-invocable: true
 For upgrading to a **new** release, use `plastic-update`. This skill only navigates
 versions you have **already installed**, the ones recorded in the ledger.
 
+## Read-only by default
+
+A flagless run only prints the version history table. It never switches, never prompts,
+and never offers to keep going further back. Switching a version always needs an
+explicit target, named with `--version`.
+
 ## Channel rule
 
-`versions` restores whichever build you pick from the ledger, it does not take a channel
+`rollback` restores whichever build you name from the ledger, it does not take a channel
 flag for the target. The pinned `<channel>` below is only the npx invocation itself:
 derive it from `~/.plastic/VERSION` the same way as the other lifecycle skills,
-`-alpha` -> `@alpha`, `-beta` -> `@beta`, otherwise `@latest`.
+`-alpha` to `@alpha`, `-beta` to `@beta`, otherwise `@latest`.
 
 ## The ledger
 
@@ -37,45 +43,49 @@ troubleshooting record.
 
 ## Procedure
 
-### Show history
+### Show history (read-only, no switch)
 
 ```bash
-npx -y @zalom/plastic@<channel> versions
+npx -y @zalom/plastic@<channel> rollback
 ```
 
-Prints the table with the currently-installed version marked. If the most recent action was
-a `downgrade`, it asks whether to keep rolling back.
+Prints the table with the currently-installed version marked. Never switches, never
+prompts, no matter what the last recorded action was.
 
-### Roll back
+### Switch to a specific version
 
 ```bash
-npx -y @zalom/plastic@<channel> versions --downgrade                    # one step back
-npx -y @zalom/plastic@<channel> versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+npx -y @zalom/plastic@<channel> rollback --version 1.0.0-alpha.15
 ```
 
-Rollback targets are restricted to versions in the ledger (only builds you have actually
-run, so you only ever return to something known-good for you). The chosen version is
-re-fetched from npm and re-synced; your intent store, config, and the ledger are untouched.
+The only way to actually switch. The target must be a version you have actually run (the
+ledger); the direction (upgrade or downgrade) is derived automatically by comparing the
+target to the installed version.
 
-### Step forward (after a rollback)
+`--downgrade --version V` and `--upgrade --version V` are accepted as explicit-target
+synonyms of `--version V`, the direction flag is descriptive only:
 
 ```bash
-npx -y @zalom/plastic@<channel> versions --upgrade                      # one step forward in your history
+npx -y @zalom/plastic@<channel> rollback --downgrade --version 1.0.0-alpha.15
+npx -y @zalom/plastic@<channel> rollback --upgrade --version 1.0.0-alpha.18
 ```
 
+A bare `--downgrade` or `--upgrade` with no `--version` is an error: it prints a message
+asking for an explicit target and performs no switch.
+
 ### After any change
 
 Run `plastic-doctor` to confirm health, then emit the reporting block and suggest
 `/clear` so the session picks up the swapped conventions:
 
 ```
-Plastic versions (<channel>)
-Command:  npx -y @zalom/plastic@<channel> versions <flags>
+Plastic rollback (<channel>)
+Command:  npx -y @zalom/plastic@<channel> rollback <flags>
 Version:  <before> -> <after>
 Doctor:   <summary or "all clear">
 ```
 
 ## Notes
 - The ledger is **never** edited or pruned, it is the audit trail.
-- Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
-  the user rather than forcing the rollback.
+- Switching cannot un-migrate a store-format change; if a warning appears, surface it to
+  the user rather than forcing the switch.

package/skills/{creating-skills → skill-creating}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic-creating-skills
+name: plastic-skill-creating
 description: >
   Author or revise a Plastic skill, a subagent or Agent role file, or a
   lifecycle hook with progressive disclosure. Use when creating or editing a
@@ -63,4 +63,4 @@ routes each authoring task to the reference that holds the depth.
 - To start a new skill, agent, or hook from a born-slim file, run
   `scripts/scaffold.rb`.
 - To design, run, and grade evals in depth (paired runs, assertions after
-  observing, pass rates), use the `plastic-evaluating-skills` skill.
+  observing, pass rates), use the `plastic-skill-evaluating` skill.

package/skills/{creating-skills → skill-creating}/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "plastic-creating-skills",
+  "skill_name": "plastic-skill-creating",
   "evals": [
     {
       "id": 1,
@@ -45,19 +45,19 @@
     {
       "id": 5,
       "prompt": "Run the evals on my skill and check the pass rate",
-      "expected_output": "The skill should NOT trigger. Running evals and reading pass rates is the job of plastic-evaluating-skills, not authoring. Near-miss negative: shares the words 'skill' and 'evals' but the operation is grading an existing skill, not creating or revising one.",
+      "expected_output": "The skill should NOT trigger. Running evals and reading pass rates is the job of plastic-skill-evaluating, not authoring. Near-miss negative: shares the words 'skill' and 'evals' but the operation is grading an existing skill, not creating or revising one.",
       "files": [],
       "assertions": [
-        "The skill does not activate (running and grading evals is plastic-evaluating-skills, not authoring)."
+        "The skill does not activate (running and grading evals is plastic-skill-evaluating, not authoring)."
       ]
     },
     {
       "id": 6,
       "prompt": "Create a new intent for the dashboard work",
-      "expected_output": "The skill should NOT trigger. Creating an intent is plastic-creating-intent. Near-miss negative: shares the verb 'create' but the object is an intent, not a skill, agent, or hook.",
+      "expected_output": "The skill should NOT trigger. Creating an intent is plastic-intent-creating. Near-miss negative: shares the verb 'create' but the object is an intent, not a skill, agent, or hook.",
       "files": [],
       "assertions": [
-        "The skill does not activate (creating an intent is plastic-creating-intent)."
+        "The skill does not activate (creating an intent is plastic-intent-creating)."
       ]
     },
     {

package/skills/{creating-skills → skill-creating}/references/progressive-disclosure.md

@@ -125,8 +125,8 @@ agent reads as a dependency it loads on its own terms. [C8]
 | Form | Effect |
 |------|--------|
 | `REQUIRED BACKGROUND: superpowers:test-driven-development` | Good. Names the dependency; the agent loads it when relevant. |
-| `For eval depth, use plastic-evaluating-skills.` | Good. Names the skill, leaves loading to the agent. |
-| `@skills/evaluating-skills/SKILL.md` | Bad. `@`-path syntax force-loads the file immediately, defeating disclosure. |
+| `For eval depth, use plastic-skill-evaluating.` | Good. Names the skill, leaves loading to the agent. |
+| `@skills/skill-evaluating/SKILL.md` | Bad. `@`-path syntax force-loads the file immediately, defeating disclosure. |
 
 The `@`-path form pulls the target into context the moment the line is read, so it spends
 the budget the level split was built to protect. Name the skill and let the trigger

package/skills/{evaluating-skills → skill-evaluating}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic-evaluating-skills
+name: plastic-skill-evaluating
 description: >
   Evaluate Plastic skills for correctness, convention compliance, and
   progressive disclosure. Use when testing whether a skill produces good

package/skills/{evaluating-skills → skill-evaluating}/evals/evals.json

@@ -1,16 +1,16 @@
 {
-  "skill_name": "evaluating-skills",
+  "skill_name": "skill-evaluating",
   "evals": [
     {
       "id": 1,
-      "prompt": "I want to evaluate whether my creating-intent skill follows Plastic conventions",
+      "prompt": "I want to evaluate whether my intent-creating skill follows Plastic conventions",
       "expected_output": "The skill should activate and guide the user through convention compliance evaluation: choose eval scope, design test cases using convention-checks reference, run paired evals, write assertions after observing.",
       "files": [],
       "assertions": []
     },
     {
       "id": 2,
-      "prompt": "Run evals on the brainstorming skill to see if the description triggers correctly",
+      "prompt": "Run evals on the intent-brainstorming skill to see if the description triggers correctly",
       "expected_output": "The skill should activate and guide through description triggering evaluation: design ~20 queries with should-trigger and near-miss negatives, 60/40 train/validation split, compute trigger rates.",
       "files": [],
       "assertions": []