@zalom/plastic 1.0.2 → 1.1.0

package/PLASTIC-reference.md

@@ -115,19 +115,19 @@ Detailed conventions live inside the skills that use them, not in this file.
 
 | Topic | Skill | References in skill |
 |-------|-------|-------------------|
-| Creating intents, lifecycle | `plastic-creating-intent` | lifecycle, wikilinks |
-| Brainstorming, spec writing | `plastic-brainstorming` | — |
-| Planning, actions | `plastic-writing-plans` | — |
-| Execution, delivery | `plastic-executing-plan` | — |
+| Creating intents, lifecycle | `plastic-intent-creating` | lifecycle, wikilinks |
+| Brainstorming, spec writing | `plastic-intent-brainstorming` | — |
+| Planning, actions | `plastic-intent-planning` | — |
+| Execution, delivery | `plastic-intent-executing` | — |
 | Autonomous delivery | `plastic-auto` | agent architecture |
-| Save/restore state | `plastic-savepoint`, `plastic-continuing` | context management |
-| Knowledge graph, linking | `plastic-linking-intents` | zettelkasten, wikilinks |
-| Projects, hubs | `plastic-creating-project` | hubs, project stores |
-| Provision a project store | `plastic-add-project-store` | project stores |
-| Index maintenance | `plastic-managing-index` | — |
+| Save/restore state | `plastic-intent-savepoint`, `plastic-intent-continuing` | context management |
+| Knowledge graph, linking | `plastic-intent-linking` | zettelkasten, wikilinks |
+| Projects, hubs | `plastic-project-creating` | hubs, project stores |
+| Provision a project store | `plastic-store-provisioning` | project stores |
+| Index maintenance | `plastic-store-indexing` | — |
 | Releases, deprecations | `plastic-releasing` | deprecation process |
 | Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
-| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
-| Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
+| Authoring skills, agents, hooks | `plastic-skill-creating` | progressive disclosure, agentskills.io spec |
+| Evaluating skills, evals | `plastic-skill-evaluating` | eval methodology, convention checks |
 | Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |
 

package/PLASTIC.md

@@ -93,10 +93,10 @@ tags: [plastic, architecture]
 
 | Stage | Section | Deliverable | Detail |
 |-------|---------|-------------|--------|
-| **What** | `## Intent` | `{ID}--{slug}.md` | `plastic-creating-intent` |
-| **Why** | `## Context` + Decisions | `spec.md` | `plastic-brainstorming` |
-| **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-writing-plans` |
-| **Exec** | Execution | `outcome.md` | `plastic-executing-plan` |
+| **What** | `## Intent` | `{ID}--{slug}.md` | `plastic-intent-creating` |
+| **Why** | `## Context` + Decisions | `spec.md` | `plastic-intent-brainstorming` |
+| **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-intent-planning` |
+| **Exec** | Execution | `outcome.md` | `plastic-intent-executing` |
 
 `## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
 An insight is a discovery worth keeping for later reads: novel, or old but newly relevant,
@@ -237,7 +237,7 @@ Beyond the lifecycle agents, Plastic ships thin skills for day-to-day operation:
   for its three scopes (`--core` for the boot integrity check, `--store` per store on dashboard
   load, and the full no-flag walk after an update).
 - **Lifecycle skills** (`plastic-install`, `plastic-update`, `plastic-uninstall`,
-  `plastic-versions`, intent 55) are thin wrappers over a single pinned
+  `plastic-rollback`, intent 55) are thin wrappers over a single pinned
   `npx -y @zalom/plastic@<channel> <verb>` call: initialize or repair an install, advance a
   channel, remove Plastic, and step the local versions ledger.
 
@@ -327,7 +327,7 @@ A Zettelkasten structure note, not a table of contents. Clusters by meaning.
 
 Sections: `## Active`, `## Future`, `## Clusters`, `## Abandoned`, `## Completed`.
 
-For index maintenance, use `plastic-managing-index`.
+For index maintenance, use `plastic-store-indexing`.
 
 One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>](<dir>) <tags>`.
 The title is the title, not a summary: aim for about 80 characters, no multi-sentence
@@ -350,7 +350,7 @@ ALL work flows through intents.
 3. On completion, capture observations in `## Insights`.
 4. When done, write `outcome.md` + `## Outcome` summary. Update INDEX.md.
 5. Researches are intents. No separate folder.
-6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete. `--intent` text is escaped for double quotes and backslashes before it lands in frontmatter, so free-form text is safe to pass as-is, and a reciprocal `chain:` append preserves the target intent's existing flow- or block-style entries.
+6. Intents are created only via `plastic-intent-creating`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete. `--intent` text is escaped for double quotes and backslashes before it lands in frontmatter, so free-form text is safe to pass as-is, and a reciprocal `chain:` append preserves the target intent's existing flow- or block-style entries.
 
 ## House Style (self-check)
 
@@ -370,6 +370,36 @@ cache) over re-reading them from disk, which only widens context. QMD is for OTH
 intents, not for re-reading what you just wrote. Pairs with `/clear` plus savepoint-resume
 hygiene after each intent. Advisory self-check, not hard-verifiable.
 
+## Tabular-First Reporting (intent 160)
+
+**Default.** Tabular layout is the default shape for three surfaces: What-stage discovery
+deposits, all research reports, and all agent reporting or presentation surfaces.
+
+**Calibration.** Tables are REQUIRED for any listing or discussion of intents, and for
+explaining complex data, comparisons, or multi-factor reasoning. This is NOT a blanket
+tables-everywhere rule: simple data stays prose, and tables must not be overused.
+
+**Bullets-limit.** Use bullets only when a table genuinely does not fit the content, and
+never more than 3-5 items.
+
+**Why tables.**
+
+| # | Reason |
+|---|--------|
+| 1 | Parallel structure makes comparison a row-vs-row scan, not a re-read. |
+| 2 | Coverage is provable: N items means N rows, an empty cell exposes a gap while a missing bullet hides it. |
+| 3 | Schema stated once in the headers, no repeated labels, higher density. |
+| 4 | A column reads vertically to show every value at once. |
+| 5 | Cells force terseness where bullets sprawl and nest. |
+| 6 | A ruling or decision column turns the report into the decision worksheet. |
+| 7 | Rows stay machine-readable for downstream tooling. |
+| 8 | Uniform granularity: every item answers the same questions. |
+| 9 | Line-scoped git diffs. |
+
+**Exception.** The EM-to-CTO human briefing (`skills/auto/references/human-report-contract.md`)
+keeps its deliberate prose shape (fixed State/Risk/Call, single item, nothing to tabulate) and
+is exempt from this rule.
+
 ## Retrieval Gate
 
 Advisory. Hard gates guard writes, locks, and structure, never reads or searches. Read,

package/README.md

@@ -99,6 +99,53 @@ Plastic delivers all work through successive stages ->
 | How   | What is the plan?                               | Plan and checklist | plan.md, checklist.md, actions/ACTION_1.md ... ACTION_N.md |
 | Exec  | What was actually delivered?                    | Outcome            | outcome.md                                     |
 
+## How to use Plastic
+
+Plastic organizes all work as intents. Each intent is one directory, and it carries the same
+small set of files at every stage.
+
+**The intent directory**
+
+| File | What it holds |
+| ---- | -------------- |
+| `{id}--slug.md` | The intent itself: intent line, context, decisions |
+| `spec.md` | The Why, consolidated into one contract for the plan |
+| `plan.md`, `checklist.md`, `actions/` | The How: the plan and its execution registry |
+| `outcome.md` | The Exec record: what actually shipped |
+
+See [`docs/architecture.md`](docs/architecture.md) for the full store layout, and
+[reading a delivered intent](docs/guides/reading-a-delivered-intent.md) for how to read a
+finished one fast.
+
+**From idea to delivery, one line per stage**
+
+| Stage | What happens |
+| ----- | ------------- |
+| What | Describe the idea in plain words; Plastic scaffolds the intent |
+| Why | Explore it, one ruling at a time, then consolidate into `spec.md` |
+| How | Turn `spec.md` into `plan.md` and `checklist.md` |
+| Exec | Build the change, verify it, tick the checklist |
+| Done | `outcome.md` records what shipped; the index moves the intent to Completed |
+
+Walk this once in
+[your first intent in 10 minutes](docs/guides/your-first-intent-in-10-minutes.md), or run
+`plastic-tutorial` for an interactive, hands-on walkthrough of three different ways to work.
+
+**Commands, by family**
+
+| Family | Commands |
+| ------ | -------- |
+| Mode | `plastic-tutorial`, `plastic-auto` |
+| Intent | `plastic-intent-creating`, `plastic-intent-starting`, `plastic-intent-brainstorming`, `plastic-intent-grilling`, `plastic-intent-speccing`, `plastic-intent-planning`, `plastic-intent-executing`, `plastic-intent-ending`, `plastic-intent-continuing`, `plastic-intent-researching` |
+| Project and delivery | `plastic-project-creating`, `plastic-roadmap`, `plastic-releasing` |
+| Skill | `plastic-skill-creating`, `plastic-skill-evaluating` |
+| Product | `plastic-install`, `plastic-update`, `plastic-uninstall`, `plastic-rollback`, `plastic-doctor`, `plastic-humanizer` |
+
+See [`docs/guides/index.md`](docs/guides/index.md) for task-oriented walkthroughs.
+
+The agent helps most at Why and How: turning a rough idea into rulings, and rulings into a
+plan a machine can build from exactly. Read
+[pick your mode](docs/guides/pick-your-mode.md) to decide how much of that to hand over.
 
 ## Compatibility and ownership
 

package/agents/plastic-enforcer.md

@@ -56,7 +56,7 @@ ceremony, never these guarantees.
 1. Arm the gate, then dispatch the brainstorming specialist; gate its `## Context` + `### Decisions`
 2. Dispatch the spec-specialist; gate `spec.md`. Then the planner; gate `plan.md` + `checklist.md`
 3. Dispatch the executor; require a green suite. Sequential, one team per intent, on one branch when files are shared
-4. Dispatch and review by default through Plastic's native engine, `plastic-executing-plan` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
+4. Dispatch and review by default through Plastic's native engine, `plastic-intent-executing` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
 5. At the final gate, dispatch an independent reviewer subagent, then complete the intent
 
 ## Human-facing stage reporting
@@ -72,5 +72,5 @@ The orchestrator consumes that internal report to write the human briefing; the
 
 - Enforce gates manually; do not rely on hooks, because the session id may be unset in headless or background runs
 - You never delegate gate ownership; the orchestrator is always the gate-keeper
-- Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-executing-plan` by default, and through the superpowers skills only when they are available or the user prefers them
-- Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-executing-plan` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle
+- Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-intent-executing` by default, and through the superpowers skills only when they are available or the user prefers them
+- Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-intent-executing` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle

package/agents/plastic-intent-curator.md

@@ -10,11 +10,11 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 
 ## Your Responsibilities
 
-1. **Intent lifecycle management** — move intents between Active/Future/Completed/Abandoned in INDEX.md, fill in `## Outcome` sections (including the abandonment rationale when an intent is abandoned)
-2. **INDEX.md maintenance** — keep Active/Future/Clusters/Completed/Abandoned sections accurate and well-organized
-3. **Link discovery** — suggest connections between intents that share topics but aren't linked
-4. **Cluster management** — create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
-5. **Orphan detection** — flag intents with no links and no cluster membership
+1. **Intent lifecycle management** - move intents between Active/Future/Completed/Abandoned in INDEX.md, fill in `## Outcome` sections (including the abandonment rationale when an intent is abandoned)
+2. **INDEX.md maintenance** - keep Active/Future/Clusters/Completed/Abandoned sections accurate and well-organized
+3. **Link discovery** - suggest connections between intents that share topics but aren't linked
+4. **Cluster management** - create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
+5. **Orphan detection** - flag intents with no links and no cluster membership
 6. **Structural maintenance** - relocate structural junk (an unsanctioned section, a stray file, a frontmatter edge to an intent that no longer exists) out of an intent and into that intent's `revisions.md`, without altering what the intent delivered
 
 ## How You Work
@@ -24,17 +24,16 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
 3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
-5. On a terminal-state transition (Completed OR Abandoned), run the closing acts in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
+5. On a terminal-state transition (Completed OR Abandoned), do these things:
    a. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
-   b. Stamp the terminal savepoint bookend (intent 81) recording the disposition. Idempotent.
-   c. Refresh the QMD index for that store LAST, after the terminal move, outcome.md, and savepoint, so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
+   b. Call `plastic-intent-ending` for the terminal-transition close (INDEX move, savepoint `Done` bookend, store commit, disarm, and the QMD reindex last): `ruby ~/.plastic/scripts/end-intent --store <store> --id <id> --disposition delivered|abandoned`, then follow that skill's own disarm and reindex steps. Never restate the INDEX/savepoint/reindex one-liners here.
 6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
 7. Report what you changed
 
 ## Constraints
 
 - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
-- You never create new intents — that's the creating-intent skill's job
-- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
+- You never create new intents - that's the intent-creating skill's job
+- You never modify `## Insights`, `## Context`, or `## Outcome` content sections - those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
 - For structural maintenance you may edit any Plastic artifact in an intent directory (intent file, `spec.md`, `plan.md`, `checklist.md`, `outcome.md`, frontmatter, or a stray file) and may create or append `revisions.md`. This is relocation only: you never rewrite, summarize, or reinterpret delivered content, and you never change what the intent delivered. A change to delivered meaning is a new intent, not a revision.
 - For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes

package/agents/plastic-intent-discovery.md

@@ -24,6 +24,7 @@ for the Why stage to consume.
    the intent file, spec.md, or any lifecycle deliverable: the lock-owner-only
    write rule stays intact, and the Why-stage `plastic-brainstorming` agent is
    the one that reads your deposit and enriches `## Context`.
+   Shape the deposit tabular-first per `PLASTIC.md` (## Tabular-First Reporting, intent 160).
 
 ## Constraints
 - Read-only with respect to the intent: your single output is

package/agents/plastic-spec-specialist.md

@@ -12,18 +12,21 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Your Responsibilities
 
-1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec
-2. **Follow the template** — produce `spec.md` with Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria
-3. **Stamp the tier** — write a `Tier: S|M|L` line as the TOP line of spec.md, above the `#
+1. **Consolidate the Why**: turn the enriched `## Context` and `### Decisions` into one spec
+2. **Follow the template**: produce `spec.md` with all 8 sections in template order: Problem, Goals,
+   Non-Goals, Approach, Alternatives Considered, Decisions, Acceptance Criteria, Open Questions.
+   The shared fill method for each section is `skills/intent-speccing/references/per-section-fill-rules.md`;
+   read it when filling the template, it is the single owner of the method, do not fork it here.
+3. **Stamp the tier**: write a `Tier: S|M|L` line as the TOP line of spec.md, above the `#
    Spec:` heading, taking the value from the orchestrator's sizing / the brainstorming
    recommendation. This line is convention-only: read by the orchestrator, never validated by
    any gate or by doctor. It is an extra top line, not a template field, so no template changes.
-4. **Accept collapsed sections at S/M** — a spec.md whose Problem, Goals, Non-Goals, Approach,
+4. **Accept collapsed sections at S/M**: a spec.md whose Problem, Goals, Non-Goals, Approach,
    Decisions, or Acceptance Criteria sections are a single line each is still a complete
    spec.md under the same-structure invariant; do not pad it. The gates check file existence
    and realness, not artifact depth, so a collapsed-but-real spec passes.
-5. **Make it the contract** — the spec is what the planner and executor build against
-6. **Hand off** — leave a complete `spec.md` ready for the planner
+5. **Make it the contract**: the spec is what the planner and executor build against
+6. **Hand off**: leave a complete `spec.md` ready for the planner
 
 ## How You Work
 

package/bin/plastic.js

@@ -6,7 +6,7 @@
 //   npx @zalom/plastic install   [flags]
 //   npx @zalom/plastic update    [flags]
 //   npx @zalom/plastic uninstall [flags]
-//   npx @zalom/plastic versions  [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).
@@ -15,7 +15,7 @@ import { execFileSync } from 'node:child_process'
 import { resolve } from 'node:path'
 import { existsSync } from 'node:fs'
 
-const VERBS = ['install', 'update', 'uninstall', 'versions']
+const VERBS = ['install', 'update', 'uninstall', 'rollback']
 const packageRoot = new URL('..', import.meta.url).pathname
 const argv = process.argv.slice(2)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/dashboard.rb

@@ -33,7 +33,7 @@ def today
 end
 
 # A generic "about a month" threshold, not tuned to any one store's item count.
-# Deliberately independent from plastic-continuing's separate stale_threshold_days
+# Deliberately independent from plastic-intent-continuing's separate stale_threshold_days
 # config: that one is a proactive boot-time triage nudge, this is a board annotation.
 # Unifying the two is a follow-up, not this intent.
 STALE_DAYS = 30
@@ -466,7 +466,7 @@ def render_continue(records)
   out.concat(matrix(open, scope_tag: true))
   out << ""
   out << LEGEND
-  out << "run     plastic-dashboard project <slug>  ·  plastic-auto  (works the dispatchable queue)"
+  out << "ask    for the <slug> project board  ·  plastic-auto  (works the dispatchable queue)"
   out.join("\n") + "\n"
 end
 

package/scripts/doctor.rb

@@ -476,7 +476,7 @@ class Doctor
         message: "#{bad_sections.size} intent file(s) have non-sanctioned ## sections",
         details: bad_sections.map { |b| "#{b[:dir]}: #{b[:issues].join(", ")}" },
         fixable: true,
-        fix_hint: "Dispatch plastic-intent-curator to relocate each unsanctioned section into the " \
+        fix_hint: "Dispatch plastic-store-curating to relocate each unsanctioned section into the " \
                   "intent's revisions.md via move-and-record (a missing required section is restored " \
                   "or reprojected instead); see PLASTIC.md > Structural maintenance and revisions.md"
       )
@@ -660,7 +660,7 @@ class Doctor
                  "(outcome.md or the savepoint Done echo is missing; advisory on immutable history)",
         details: gaps, fixable: true,
         fix_hint: "For live terminals, author a real outcome.md with the `disposition:` header via the " \
-                  "completion/abandon path (plastic-auto or plastic-intent-curator) and stamp the terminal " \
+                  "completion/abandon path (plastic-auto or plastic-store-curating) and stamp the terminal " \
                   "savepoint. Legacy terminal intents are immutable, so pre-convention gaps stay advisory."
       )
     end
@@ -676,9 +676,9 @@ class Doctor
         message: "#{stalled.size} stalled completion#{stalled.size == 1 ? "" : "s"} " \
                  "(terminal in INDEX but the End tail did not finish)",
         details: stalled, fixable: true,
-        fix_hint: "Finish the End tail via stale-lock reclaim: `plastic-lock reclaim`, then complete the " \
-                  "tail (Worktree.release -> Lock.release -> purge -> QMD reindex last). This FINISHES a " \
-                  "completion; it is NOT a reactivation of a done intent."
+        fix_hint: "Finish the End tail via stale-lock reclaim: run /plastic-doctor reclaim the lock, " \
+                  "then complete the tail (Worktree.release -> Lock.release -> purge -> QMD reindex " \
+                  "last). This FINISHES a completion; it is NOT a reactivation of a done intent."
       )
     end
 
@@ -882,7 +882,7 @@ class Doctor
     checks << graph_finding_check(
       "graph_i4_danglers", i4,
       "Every sources/chain id resolves to a real intent (I4)",
-      "Dispatch plastic-intent-curator to record the dangling sources/chain edge as a " \
+      "Dispatch plastic-store-curating to record the dangling sources/chain edge as a " \
       "broken-source/broken-chain move-and-record entry in the intent's revisions.md (see " \
       "PLASTIC.md > Structural maintenance and revisions.md), or restore the missing intent"
     )
@@ -1052,6 +1052,11 @@ class Doctor
     # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)
     checks << flat_skills_check(agent_dir, "--claude")
 
+    # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
+    # e.g. an old-name copy after a rename; intent 158a AC15)
+    stray_check = stray_skills_check(agent_dir, "--claude", File.join(agent_dir, "plastic", "manifest.json"))
+    checks << stray_check if stray_check
+
     # agents_exist — auto-mode role files (plastic-*.md) synced into <dir>/agents
     checks << flat_agents_check(agent_dir, "--claude")
 
@@ -1078,6 +1083,43 @@ class Doctor
     end
   end
 
+  # Backstop for a rename or removal (intent 158a, AC15): an installed plastic-*
+  # skill directory under agent_dir/skills that has NO corresponding entry in the
+  # current install manifest is a stray (e.g. a leftover old-name copy the
+  # install/update prune should have removed, or one it never saw because the
+  # manifest predates it). Complements flat_skills_check (which only confirms at
+  # least one skill exists). Defers to the manifest check when the manifest itself
+  # is missing or malformed, so the two checks never double-report the same gap.
+  def stray_skills_check(agent_dir, installer_flag, manifest_path)
+    skills_root = File.join(agent_dir, "skills")
+    manifest = read_json_safe(manifest_path)
+    files = manifest.is_a?(Hash) ? manifest["files"] : nil
+    return nil unless files.is_a?(Hash)
+
+    installed = Dir.glob(File.join(skills_root, "plastic-*", "SKILL.md"))
+                    .map { |f| File.basename(File.dirname(f)) }
+    tracked = files.keys
+                   .select { |p| p.start_with?("#{skills_root}/") }
+                   .map { |p| p.sub("#{skills_root}/", "").split("/").first }
+                   .uniq
+
+    strays = (installed - tracked).sort
+
+    if strays.empty?
+      check(
+        category: "agent_registration", name: "stray_skills", status: "pass",
+        message: "No stray plastic-* skill directories in #{tilde(skills_root)}"
+      )
+    else
+      check(
+        category: "agent_registration", name: "stray_skills", status: "warn",
+        message: "#{strays.size} installed skill dir(s) not in the current manifest (stray, e.g. a leftover old-name copy)",
+        details: strays,
+        fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest #{installer_flag}"
+      )
+    end
+  end
+
   # Auto-mode role agents install as <dir>/agents/plastic-*.md. Pass if at least
   # one such role file is present (the installer syncs agents/ on every install).
   def flat_agents_check(agent_dir, installer_flag)
@@ -1104,6 +1146,12 @@ class Doctor
 
     # For codex/hermes: just check skills exist (no settings.json hooks)
     checks << flat_skills_check(agent_dir, "--#{agent_key}")
+
+    # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
+    # e.g. an old-name copy after a rename; intent 158a AC15)
+    stray_check = stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic-manifest.json"))
+    checks << stray_check if stray_check
+
     checks << flat_agents_check(agent_dir, "--#{agent_key}")
 
     checks
@@ -1405,7 +1453,7 @@ class Doctor
       checks << check(
         category: "project_stores", name: "project_yml_exists", status: "warn",
         message: "project.yml missing for project '#{slug}'",
-        fixable: true, fix_hint: "Create project.yml from template — see plastic-creating-project"
+        fixable: true, fix_hint: "Create project.yml from template — see plastic-project-creating"
       )
     end