@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/skills/linking-intents/SKILL.md

@@ -6,34 +6,70 @@ description: Use when creating connections between intents, the user says "link"
 # Linking Intents
 
 ## When to Use
-- During intent creation (automatic — ask about related intents)
+- During intent creation (automatic: ask about related intents)
 - User says "link", "connect", "relates to"
 - Agent discovers a relationship between intents during work
 
-## Connection Types (Ranked by Strength)
+## Discovery and ranking are separate
 
-### 1. Direct Links (Strongest)
-Explicit wikilinks in the `## Links` section. Bidirectional — add to both intents.
+Two distinct steps, do not conflate them:
 
-```markdown
-## Links
-- [[1a]] — research this plan is based on
-```
+1. **Discovery** (finding candidate related intents) may use any tool: grep, find, ripgrep,
+   or QMD/Serena when present (QMD-first per the project rule). Discovery casts a wide net.
+2. **Ranking** the candidates is a CONTEXT-INFLUENCE judgement: read each candidate's `## Intent`
+   and `## Context` and ask whether that context actually informed this intent. Ranking is NOT a
+   structural metric (no shared-file or shared-symbol grading: on intent 90, matching whole files
+   flagged 35 intents because ~20 touch `bridge.rb`). It is NOT a similarity score either (QMD
+   relevance measures topic proximity, not influence). A script cannot make this call; an agent
+   does.
+
+## The three tiers (by context influence)
+
+- **sources:** the foundational context that shaped this intent's CREATION (a split, an idea born
+  during development, a merge). Earns an edge. Decided by origin, never inferred.
+- **chain:** the context that materially helps DELIVER this intent. HIGH bar: only the genuinely
+  delivery-moving intents, not everything in the same area. Earns an edge, reflected in `## Links`.
+  Worked example (intent 90): 79 created it so 79 is a source; 80 deferred the exact fix 90 makes,
+  so its context directly helps delivery and 80 is chain; 49/66/73 are same-area background, so
+  they get a shared tag and no link.
+- **tags:** loose theme grouping for search. NOT a link.
+
+**Timing.** The influence judgement happens at What/Why (and during upkeep), guided by this rule.
+It does not wait for code to exist; it is reasoning over the candidate's context, not over a diff.
+
+**Record the call.** For every edge an agent adds, store a rating (high / medium / low) plus a
+one-line reason as a dated line under the intent file's `## Insights` section (per 96 D3, link
+rationale lives in the intent file, not a side file). It stays out of frontmatter (graph only) and
+out of the projected `## Links` label, so the audit trail never breaks the projection identity.
+
+## `## Links` is derived (never author it by hand)
+
+`## Links` is a DERIVED view of `sources` then `chain`, not a place to write links. Never
+hand-write a `## Links` line, and never auto-delete one. To add a link, add the frontmatter
+edge (below), then let the projection regenerate the section (`scripts/project-links`).
+
+Run `scripts/link-suggest <id>` to gather candidate intents WITH each one's Intent and Context (the
+evidence you judge influence on) and to flag drift (a `## Links` line with no frontmatter edge
+behind it). To record a confirmed edge plus its rating and reason, run it with
+`--record <id> --edge <sources|chain> --rating <high|medium|low> --reason "..." --confirm`. It never
+grades influence itself, never writes an edge without `--confirm`, and never deletes.
+
+## Connection Types (the frontmatter edges)
 
-### 2. Sources (Backward)
+### 1. Sources (Backward)
 The `sources` array in frontmatter. The direct ascendant(s) this intent was created from / emerged from the lifecycle of (formation, not topic similarity), backward links to the work it was built out of:
 ```yaml
 sources: ["1a", "1a2"]
 ```
 
-### 3. Chain (Forward)
+### 2. Chain (Forward)
 The `chain` array in frontmatter. What this intent spawned AND related-but-not-spawned successors it leads to, forward links to children, follow-on, and related work:
 ```yaml
 chain: ["1b1", "1b2"]
 ```
 
-### 4. Tags (Weakest)
-Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership.
+### 3. Tags (for discovery, not links)
+Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership. A shared tag is a loose theme grouping: it earns NO edge.
 ```yaml
 tags: [plastic, project-reddit-kb]
 ```

package/skills/lock/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: lock
+description: Inspect, repair, release, or reclaim an intent's delivery lock. Use when a lock-gate deny names /plastic-lock, when resuming interrupted work after a crash, reboot, or /tmp wipe, when a lock reads held or stale, or when the user says "fix the lock", "who holds the lock", or "reclaim the lock".
+---
+
+# Plastic Lock
+
+Command-only wrapper around `~/.plastic/scripts/plastic-lock`. The durable
+delivery lock is a `delivery.lock` file in the intent directory: ownership is
+session-keyed, liveness is a lease (the owner's hooks refresh the file mtime;
+stale means the heartbeat is older than the TTL). The /tmp bridge is only a
+cache; the lock file wins every disagreement.
+
+## Verbs
+
+Run from the project (the intent resolves from this session's bridge), or pass
+`--intent-dir` explicitly:
+
+| Verb | What it does | When |
+|---|---|---|
+| `status` | Report the lock file, bridge cache, freshness, agreement | Always safe; run first |
+| `fix` | Idempotent repair: rebuild lock + bridge from disk truth for THIS session. Never touches a fresh foreign lock | Interrupted work, corrupted state, /tmp wiped, legacy pid locks |
+| `release` | Owner clears the lock | Ending or abandoning a boarding |
+| `reclaim` | Explicit takeover of a STALE lock; appends an audit line to savepoint.md | The owner is gone and the lease expired |
+| `delegate` | Owner registers a subagent session under the lock (`--delegate <session-id>`) | Auto-mode orchestration |
+
+```
+ruby ~/.plastic/scripts/plastic-lock status
+ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock reclaim --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock delegate --delegate <subagent-session-id>
+```
+
+## Rules
+
+- `fix` exits non-zero when another session holds a FRESH lock: back off, do
+  not retry in a loop. `status` shows the owner.
+- `reclaim` refuses a fresh lock. There is no silent reclaim anywhere; every
+  takeover is audited in the intent's savepoint.md.
+- Acquiring a lock for new work is NOT this skill's job: board through
+  `/plastic-intent-starting`, which calls the same repair internally.

package/skills/managing-index/SKILL.md

@@ -41,6 +41,12 @@ Topic-based groupings. Manually curated. Create a new cluster when 3+ intents sh
 ### Completed
 All completed intents with dates. Links preserved, never deleted.
 
+When you move an intent INTO Completed or Abandoned, run the closing acts of the transfer in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
+
+1. 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).
+2. Stamp the terminal savepoint bookend (intent 81), so the ledger's last line records the disposition: `ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'` (use `"abandoned"` for an abandoned intent). Idempotent.
+3. Refresh the QMD index for that store LAST, after the terminal move and savepoint (no-op when QMD is absent), in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
+
 ## Workflow
 
 QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or

package/skills/releasing/SKILL.md

@@ -20,6 +20,7 @@ Project configuration drives the workflow - no hardcoded assumptions.
 - [ ] Run post-push actions (GitHub release, npm publish, etc.)
 - [ ] Verify release sync (npm dist-tag, GitHub "Latest", git tag all show the new version)
 - [ ] Complete active intent
+- [ ] Clean up the intent's worktrees (merge-then-remove)
 
 ## Workflow
 
@@ -84,6 +85,12 @@ git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 
 Always `--no-ff` to preserve branch history in the merge commit.
 
+**Worktree-isolated intents (intent 73c3).** A worktree-delivered intent's code lives on
+`plastic/{id}--{slug}`, merged together with cleanup in step 9, not on a hand-made feature
+branch. Do not delete the worktree before its branch is merged, or the work is lost. For
+the full rationale and the already-merged-by-hand no-op case, read
+`references/promotion-and-tagging.md`.
+
 ### 4. Bump Version
 
 Determine which files to update from project.yml:
@@ -94,8 +101,20 @@ Determine which files to update from project.yml:
 
 Update the version string in each file, then commit:
 
+**Cut the CHANGELOG entry.** Before committing, edit `CHANGELOG.md` at the repo root so
+the changelog change rides this same version-bump commit and reaches the tag. Write one
+line in the existing shape:
+
+`` `<version>` - shipped <date>; collected <intent-id> (<one-line summary>) ``
+
+Prepend it as the first bullet under `## Released` (newest-first). If this version was
+sitting under `## Unreleased`, move it out of that section and into `## Released`. Keep
+the line intent-centric narrative (which intents the cut collected and why), NOT commit
+detail: step 5's tag-message changelog and step 7's `gh release create --generate-notes`
+already own the commit-level detail, so do not duplicate it here.
+
 ```bash
-git add <version-files>
+git add <version-files> CHANGELOG.md
 git commit -m "chore: bump version to X.Y.Z - [one-line summary]"
 ```
 
@@ -207,6 +226,27 @@ A release IS a delivery. The active intent that drove this work must be complete
 
 **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:
+
+```bash
+ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
+  'b = Bridge.discover_bridge(session: ENV["CLAUDE_CODE_SESSION_ID"], cwd: Dir.pwd); Worktree.finish(b, merge: true) if b'
+```
+
+(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.)
+
+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
+merge-vs-remove policy lands on merge, and the fail-open/idempotent guarantees of `finish`,
+read `references/promotion-and-tagging.md`.
+
 ## Conventions
 
 - **Annotated tags only** - `git tag -a`, never lightweight tags
@@ -219,34 +259,9 @@ A release IS a delivery. The active intent that drove this work must be complete
 - **Verify sync** - after pushing, confirm npm dist-tag, GitHub "Latest", and the git tag all show the new version
 - **Branch cleanup** - delete merged feature branches: `git branch -d <branch>`
 
-## Promotion
-
-To promote a release across channels, use `--promote`:
-
-```bash
-plastic-releasing --promote beta    # promotes current alpha → beta
-plastic-releasing --promote stable  # promotes current beta → stable
-```
-
-**Promotion rules:**
-- Linear only: alpha → beta → stable. Cannot skip channels.
-- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
-  to `-beta.1`, publishes with `--tag beta`.
-- `--promote stable`: reads version from `package.json`, strips pre-release suffix
-  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
-- Version files are bumped and committed as in a normal release.
-- An annotated tag is created for the promoted version.
-
-## Retroactive Tagging
-
-For repos without prior tags, tag historical releases:
-
-```bash
-git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
-```
-
-Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).
-
 ## References
 
+- When promoting a pre-release across channels (`--promote beta`/`--promote stable`) or
+  tagging a historical release retroactively, read `references/promotion-and-tagging.md`
+  for the exact commands and rules first
 - Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

package/skills/releasing/references/promotion-and-tagging.md

@@ -0,0 +1,60 @@
+# Promotion, Retroactive Tagging, and Worktree Merge Rationale
+
+Occasional variant paths off the main release workflow: promoting a pre-release
+across channels, tagging historical releases retroactively, and the deep rationale
+for why the intent's worktree is merged before removal.
+
+## Table of Contents
+
+- [Worktree merge-then-remove rationale](#worktree-merge-then-remove-rationale)
+- [Promotion](#promotion)
+- [Retroactive Tagging](#retroactive-tagging)
+
+## Worktree merge-then-remove rationale
+
+**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
+worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
+feature branch. The merge-then-remove of that worktree is handled together with cleanup in
+Workflow step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
+worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
+date") and proceeds straight to removal. Do not delete the worktree before its branch is
+merged, or the work is lost.
+
+A release is the merge-then-remove path for the intent's worktrees. This is the one place
+the merge-vs-remove policy lands on "merge": the intent's code branch (`plastic/{id}--{slug}`)
+is merged back into the repo's default branch BEFORE the worktree is removed, so the
+integrated work is never lost. (The disarm path in `plastic-auto`, by contrast, is a plain
+remove because no release is merging the branch.)
+
+`Worktree.finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the
+worktree is still removed rather than stranded), and a second call with the block already
+cleared is a no-op.
+
+## Promotion
+
+To promote a release across channels, use `--promote`:
+
+```bash
+plastic-releasing --promote beta    # promotes current alpha → beta
+plastic-releasing --promote stable  # promotes current beta → stable
+```
+
+**Promotion rules:**
+- Linear only: alpha → beta → stable. Cannot skip channels.
+- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
+  to `-beta.1`, publishes with `--tag beta`.
+- `--promote stable`: reads version from `package.json`, strips pre-release suffix
+  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
+- Version files are bumped and committed as in a normal release.
+- An annotated tag is created for the promoted version.
+
+## Retroactive Tagging
+
+For repos without prior tags, tag historical releases:
+
+```bash
+git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
+```
+
+Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).

package/skills/roadmap/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: plastic-roadmap
+description: Use when the user wants to plan a delivery batch, order waves of intents, ship a batch of tickets in one go, track a named collection of intents toward a goal, or asks for a "roadmap". Creates and maintains a roadmap file, a delivery-side collection of intents (the counterpart to a release), separate from INDEX.md status tracking.
+---
+
+# Roadmap
+
+A roadmap is a named, ordered, delivery-side collection of intents: the delivery-side counterpart
+to a release (completion-side, `CHANGELOG.md`). It lives at `roadmaps/{slug}.md`, a sibling of
+`INDEX.md` wherever `INDEX.md` lives: the global tier's `~/.plastic/roadmaps/` (beside
+`~/.plastic/INDEX.md`), or a project's root, `~/.plastic/projects/{slug}/roadmaps/` (beside that
+project's `INDEX.md` and `project.yml`). It never sits inside `store/`, which holds intent
+directories, not project artifacts.
+
+A roadmap file has four parts: a title/meta header, `## Goal` (prose), `## Waves` (ordered; entries
+inside a wave are parallel-safe, waves run sequentially), and an append-only dated `## Log`. Each
+wave entry mirrors that intent's status in `INDEX.md` (`queued`/`delivering`/`delivered`/
+`abandoned`/`blocked`).
+
+**`INDEX.md` is the single writer of intent status; on any conflict INDEX wins and the roadmap
+entry is corrected to match.**
+
+The skill operates on the file directly via Read/Edit; no helper script.
+
+## Verbs
+
+| Verb | When | Mechanics |
+|------|------|-----------|
+| Create | user wants to start a new roadmap / plan a delivery batch | `references/operations.md#create` |
+| Add / reorder entries | user wants to add intents to a wave or resequence waves | `references/operations.md#add--reorder-entries` |
+| Sync status mirror | an entry's status may be stale against INDEX | `references/operations.md#sync-status-mirror` |
+| Append log line | a roadmap event just happened (created, wave done, closed) | `references/operations.md#append-a-log-line` |
+| Read / consume | a human or a coordinator needs the roadmap's current state | `references/operations.md#read--consume` |
+| Close / archive | the roadmap's `## Goal` is reached | `references/operations.md#close--archive` |
+
+See `references/file-format.md` for the exact entry-line shape, status vocabulary, checkbox/log
+format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
+verb above.
+
+## Notes
+
+- File location and the four-section shape are identical across tiers; do not invent a different
+  layout per project. The general rule: `roadmaps/` is a sibling of `INDEX.md`, wherever `INDEX.md`
+  lives.
+- `## Goal` is a checkable prose condition read by a human or agent, not an executable checker.
+- Wave entries render as checkboxes (`- [x] ... — delivered` / `- [ ] ... — <status>`); a human
+  reading cold should see shipped/running/next within a minute. `## Log` lines are one-sentence,
+  EM-to-CTO-voice, dated, and link each entry-intent's `outcome.md` (lossless-by-reference).
+- Additive: this skill introduces no gate, lock, or hook, and does not change `INDEX.md`'s section
+  list or the intent frontmatter schema.
+- Closing a roadmap moves it to `roadmaps/archived/{slug}.md` so `roadmaps/` lists only live ones.

package/skills/roadmap/references/file-format.md

@@ -0,0 +1,91 @@
+# Roadmap File Format
+
+## Location
+
+`roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives. For the global tier
+that is `~/.plastic/roadmaps/{slug}.md` (beside `~/.plastic/INDEX.md`); for any project it is
+that project's root, `~/.plastic/projects/{slug}/roadmaps/{slug}.md` (beside that project's
+`INDEX.md` and `project.yml`). `roadmaps/` never sits inside `store/`: `store/` holds intent
+directories, not project artifacts. Create the `roadmaps/` directory the first time a tier gets a
+roadmap.
+
+`roadmaps/` lists only live (open or in-flight) roadmaps. Once a roadmap's `## Goal` is reached,
+its file moves to `roadmaps/archived/{slug}.md` (see Close/archive in `operations.md`); the
+`archived/` subdirectory is scaffolded once, alongside `roadmaps/`, with a `.gitkeep`.
+
+## The four sections (in order)
+
+1. **Title/meta header** — `# Roadmap: <name>` plus a one-line meta sentence naming what the
+   roadmap delivers and which tier (project or global) it lives in.
+2. **`## Goal`** — a checkable prose condition: one or a few sentences a human or coordinator reads
+   to decide the roadmap is done. Not an executable checker, not a list of tasks.
+3. **`## Waves`** — ordered waves (`### Wave 1`, `### Wave 2`, ...). Entries inside a wave are
+   parallel-safe (can be dispatched together); waves run top to bottom, sequentially (wave 2 does
+   not start until wave 1's entries are no longer `queued`/`delivering`).
+4. **`## Log`** — append-only, dated, one line per event. Newest entry at the bottom. Never edit or
+   remove an existing log line.
+
+## Entry line shape
+
+One line per intent, inside its wave, as a Markdown checkbox:
+
+```
+- [x] <intent-id> <title> — delivered
+- [ ] <intent-id> <title> — <status>
+```
+
+`<intent-id>` and `<title>` match the intent's `INDEX.md` entry (terse, not a summary). The
+checkbox is checked (`[x]`) once `<status>` is `delivered`, unchecked (`[ ]`) for every other
+status. The checkbox is a rendering of the mirrored status token, not a second piece of state: a
+human scanning the file sees at a glance what shipped (checked) and what has not (unchecked),
+while the trailing token still carries the precise state (`queued`/`delivering`/`blocked`/
+`abandoned`) when unchecked.
+
+## Status vocabulary
+
+`queued` | `delivering` | `delivered` | `abandoned` | `blocked`
+
+Status is a **mirror** of `INDEX.md`. `INDEX.md` is the single writer of intent status; on any
+conflict INDEX wins and the roadmap entry (both its token and its checkbox) is corrected to match
+it. The roadmap never sets a status that INDEX does not already reflect.
+
+## Log line shape
+
+One line per event, starting `YYYY-MM-DD HH:MM UTC` (human-readable, sortable, zone-explicit so
+same-day parallel deliveries can still be ordered), in plain-language EM-to-CTO voice: what shipped
+and why it matters to a non-expert reader, no jargon or internal codenames, ending with a link to
+that entry-intent's `outcome.md`:
+
+```
+- <YYYY-MM-DD HH:MM UTC> <one plain-language sentence: what shipped, its impact> — see store/<id>--<slug>/outcome.md
+```
+
+The log line never restates `outcome.md` detail; it points at it (lossless-by-reference). This
+complements, and does not replace, `INDEX.md`'s `## Completed` section or `CHANGELOG.md`.
+
+## Worked example
+
+```
+# Roadmap: Stable 1.0
+
+Delivery-side collection of intents that close out the pre-1.0 hardening pass, plastic project store.
+
+## Goal
+All intents below are delivered, the suite is green, and a 1.0.0 release is cut.
+
+## Waves
+Entries in a wave are parallel-safe; waves run top to bottom. The checkbox tracks delivered/not;
+the token after the em-dash carries the precise mirrored status (queued | delivering | delivered |
+abandoned | blocked); INDEX wins on any conflict.
+
+### Wave 1
+- [x] 121 Fix bash gate redirect parsing — delivered
+- [ ] 130 Proportional cycle tiers — delivering
+
+### Wave 2
+- [x] 124 Roadmap feature — delivered
+
+## Log
+- 2026-07-06 14:32 UTC Shipped the bash-gate redirect fix so quoted arrows and heredoc trailers
+  stop blocking legitimate commits — see store/121--fix-bash-gate-redirect-parsing/outcome.md.
+```

package/skills/roadmap/references/operations.md

@@ -0,0 +1,78 @@
+# Roadmap Operations
+
+All six verbs operate on the Markdown file directly (Read/Edit). No helper script exists or is
+needed; the file is small and the edits are mechanical.
+
+**Human-comprehension goal.** Every operation below should leave the file such that a cold reader
+(no INDEX.md, no intent directories open) can answer "what's shipped, what's running, what's
+next" in under a minute, just from this one file.
+
+## Create
+
+1. Pick a `slug` (kebab-case, descriptive) and a `title`.
+2. Resolve the tier root: the directory that holds `INDEX.md` (a project's root, beside
+   `project.yml`, or `~/.plastic/` for the global tier). `roadmaps/` is always a sibling of
+   `INDEX.md`, never inside `store/`. Create `roadmaps/` there if it does not exist yet.
+3. Copy `templates/roadmap.md` to `roadmaps/{slug}.md`.
+4. Fill the header (`# Roadmap: <title>` + the one-line meta) and write a real `## Goal` prose
+   condition.
+5. Add at least one `## Waves` wave with real entries (see Add / reorder below), each entry's
+   status mirroring that intent's current `INDEX.md` status.
+6. Append the first `## Log` line, a short `YYYY-MM-DD HH:MM UTC`-prefixed plain-language note
+   that the roadmap was created.
+
+## Add / reorder entries
+
+- **Add**: append an entry line (`- <intent-id> <title> — <status>`) to the target wave. Pick the
+  intent's title and status straight from `INDEX.md`.
+- **New wave**: add a new `### Wave N` heading after the last wave; entries in it are gated behind
+  every earlier wave's entries leaving `queued`/`delivering`.
+- **Reorder**: move an entry line to a different wave, or move a `### Wave` heading (with its
+  entries) earlier or later. Reordering never changes an entry's status; it only changes when the
+  entry is eligible to run.
+- After any add/reorder, append a `## Log` line describing the change (e.g.
+  `- <YYYY-MM-DD HH:MM UTC> added 132 to wave 2`).
+
+## Sync status mirror
+
+1. Read the intent's real status from `INDEX.md` (`## Active`, `## Future`, `## Completed`, or
+   `## Abandoned`).
+2. Compare to the roadmap entry's `<status>` token.
+3. If they differ, **INDEX wins**: rewrite the roadmap entry's status token to match INDEX, and
+   flip its checkbox in the same edit (`[x]` when the new status is `delivered`, `[ ]` otherwise).
+   Never edit INDEX.md from the roadmap skill; the roadmap is a mirror, not a second writer.
+4. Append a `## Log` line recording the change. When the new status is `delivered`, write the
+   one-line EM-to-CTO entry described in `file-format.md` (date, what shipped and its impact in
+   plain language, then a link to that intent's `outcome.md`). For other transitions, write a
+   short dated plain-language line (no codenames, no jargon).
+
+## Append a log line
+
+- One line per event, starting `YYYY-MM-DD HH:MM UTC`, appended at the bottom of `## Log`. Never
+  edit or delete an existing line (append-only).
+- Every line is plain language a non-expert can read, never a codename or a raw `field -> value`.
+  A delivery event follows the EM-to-CTO one-line shape with an `outcome.md` link (see
+  `file-format.md`); bookkeeping events (created, an intent added to a wave, a wave completed, a
+  roadmap closed) are short dated plain-language lines.
+
+## Read / consume
+
+- A human reading the file gets the current picture directly: `## Goal` for the target, `## Waves`
+  for what is queued/delivering/delivered per wave (checkboxes give the shipped/not-shipped view at
+  a glance), `## Log` for a one-line, plain-language history with a link into each intent's
+  `outcome.md` for detail.
+- A future coordinator (for example, an auto-mode dispatcher) reads `## Waves` top to bottom:
+  a wave is eligible to dispatch once every entry in the previous wave is no longer
+  `queued`/`delivering`; within an eligible wave, entries still `queued` are parallel-dispatchable.
+  Always re-sync against `INDEX.md` before dispatch decisions, since INDEX is the source of truth.
+
+## Close / archive
+
+1. Confirm the roadmap's `## Goal` prose condition is met (every entry `delivered` or explicitly
+   `abandoned` with a recorded reason, plus whatever else the goal states).
+2. Create `roadmaps/archived/` beside `roadmaps/` (both siblings of `INDEX.md`) if it does not
+   exist yet.
+3. Move the file: `roadmaps/{slug}.md` -> `roadmaps/archived/{slug}.md`. `roadmaps/` itself then
+   lists only live (open or in-flight) roadmaps.
+4. Append the final `## Log` line before or as part of the move:
+   `- <YYYY-MM-DD HH:MM UTC> roadmap closed`.

package/skills/uninstall/SKILL.md

@@ -9,15 +9,21 @@ The installer tracks every file it writes in a manifest, so uninstall is exact a
 leaves no orphans. Prefer running it through the CLI; this skill wraps the same
 underlying uninstaller and adds reporting + verification.
 
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed,
+default to `@beta`. The user can always override with `--alpha` / `--beta` / `--latest`.
+
 ## Procedure
 
 ### Step 1: Run the uninstaller
 
 ```bash
-npx @zalom/plastic@latest uninstall --claude
+npx -y @zalom/plastic@<channel> uninstall --claude
 ```
 
-(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx` works too.)
+(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx -y @zalom/plastic@<channel> uninstall --claude` works too.)
 
 This removes, for the targeted agent:
 - all `~/.claude/skills/plastic-*/` skills
@@ -29,8 +35,8 @@ This removes, for the targeted agent:
 
 ### Step 2: Report removed vs left
 
-Relay the uninstaller's output to the user — what was **removed** and what was
-**left in place**:
+Relay the uninstaller's output to the user: what was **removed** and what was
+**left in place**.
 - **Left:** `~/.plastic/` (intent store, history, projects) and any non-Plastic
   settings.json entries.
 
@@ -39,21 +45,33 @@ Relay the uninstaller's output to the user — what was **removed** and what was
 Tell the user to confirm:
 
 ```bash
-ls ~/.claude/skills | grep '^plastic-'    # → no output
-ls ~/.claude/hooks  | grep '^plastic-'    # → no output
-grep -n plastic ~/.claude/settings.json   # → no plastic hook/plugin refs
+ls ~/.claude/skills | grep '^plastic-'    # -> no output
+ls ~/.claude/hooks  | grep '^plastic-'    # -> no output
+grep -n plastic ~/.claude/settings.json   # -> no plastic hook/plugin refs
+```
+
+### Step 4: Report + offer the data decision
+
+Emit the reporting block, using the Step 3 checks for the verification line:
+
+```
+Plastic uninstall (<channel>)
+Command:  npx -y @zalom/plastic@<channel> uninstall --claude <flags>
+Version:  removed
+Verification: <Step 3 results, or "clean">
 ```
 
-### Step 4: Offer the data decision
+Then:
 
 ```
 Plastic is uninstalled from [agent].
 Your intent store at ~/.plastic/ is untouched.
 
 Delete it too?
-  a) Keep everything (recommended) — re-install anytime with npx
-  b) Delete everything now — removes ~/.plastic/ entirely (irreversible)
+  a) Keep everything (recommended): re-install anytime with npx
+  b) Delete everything now: removes ~/.plastic/ entirely (irreversible)
 ```
 
-- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with `npx @zalom/plastic@latest install --claude`."
+- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with
+  `npx -y @zalom/plastic@beta install --claude` (or your channel)."
 - **Delete:** run `rm -rf ~/.plastic/` and confirm.