@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.2

package/skills/evaluating-skills/references/eval-methodology.md

@@ -0,0 +1,154 @@
+# Evaluation Methodology
+
+Load when choosing a grader type, interpreting pass rate results, or deciding
+whether to graduate or retire evals.
+
+Sources: agentskills.io, Anthropic eval engineering, Tessl eval framework,
+Philipp Schmid skill testing guide.
+
+## Three-Tier Grader Taxonomy
+
+Layer graders like a Swiss cheese model — no single tier catches everything.
+Use the simplest grader that covers the assertion. Combine tiers for coverage.
+
+### Code-Based Graders
+
+Best for structural and mechanical checks:
+- File existence and correct path
+- JSON/YAML validity
+- Line count, character count, token budget
+- Regex pattern matching (frontmatter fields, required sections)
+- Exit codes from bundled scripts
+
+Use as the default tier. Fast, deterministic, reproducible.
+
+### LLM-as-Judge Graders
+
+Best for subjective quality and semantic checks:
+- "Does this description convey when to use the skill?"
+- "Are the gotchas concrete corrections, not general advice?"
+- "Does the output address the user's actual intent?"
+
+Calibration protocol:
+1. Write a natural-language rubric (not binary pass/fail)
+2. Run the judge on 10-15 cases where you already know the correct grade
+3. Compare judge grades to your grades — adjust rubric until >80% agreement
+4. Spot-check with human grading periodically (every 5th eval run)
+
+Rubric template:
+- PASS: [specific criteria with examples]
+- PARTIAL: [what partial credit looks like]
+- FAIL: [specific failure modes]
+
+### Human Graders
+
+Best for edge cases and final calibration:
+- Novel failure modes the other tiers miss
+- Calibration set for LLM judges
+- Final sign-off on graduating evals to regression
+
+Use sparingly — human grading doesn't scale. Reserve for calibration
+and cases where code + LLM judges disagree.
+
+## pass@k vs pass^k
+
+Two metrics that diverge dramatically. Always track both.
+
+### pass@k — Capability
+
+"Did it succeed at least once in k trials?"
+
+Formula: pass@k = 1 - (1 - p)^k where p = single-trial pass rate
+
+Measures: Can the skill/agent do this at all?
+
+Example at p=0.7, k=10: pass@k = 97.2%
+
+Use when: evaluating whether a skill enables a new capability,
+initial development, deciding whether to invest more iteration.
+
+### pass^k — Reliability
+
+"Did it succeed every time in k trials?"
+
+Formula: pass^k = p^k
+
+Measures: Will it always do this correctly?
+
+Example at p=0.7, k=10: pass^k = 2.8%
+
+Use when: evaluating production readiness, regression testing,
+deciding whether a skill is reliable enough to ship.
+
+### Interpreting the Gap
+
+| pass@k | pass^k | Interpretation |
+|--------|--------|----------------|
+| High | High | Reliable — ready for production |
+| High | Low | Capable but flaky — needs iteration on consistency |
+| Low | Low | Not yet capable — needs fundamental skill improvement |
+| Low | High | Impossible (pass^k <= pass@k always) |
+
+Run k=3 minimum for meaningful results. k=5 for production decisions.
+
+## Capability-to-Regression Graduation
+
+Track pass rates across iterations. When a capability eval consistently
+hits ~100% (pass@k=1.0 for 3+ consecutive runs):
+
+1. Graduate the eval from "capability" to "regression"
+2. Regression evals run on every skill change — they protect against backsliding
+3. If a regression eval starts failing, the recent change broke something
+4. Investigate the failing regression before iterating further
+
+Graduation is one-way. Once an eval is regression, it stays regression
+unless the underlying requirement changes.
+
+## Skill Retirement Detection
+
+Monitor the with/without skill delta over time:
+
+1. Run paired evals (with-skill vs without-skill) periodically
+2. Compute the delta in pass rates
+3. If delta shrinks to near-zero across 3+ consecutive runs:
+   - The model has likely internalized the skill's knowledge
+   - The skill may be ready for retirement
+4. Before retiring: run one final full eval suite to confirm
+5. Archive the skill (don't delete — may need to restore if model changes)
+
+Common cause of false retirement signals: model update changed capabilities.
+Re-test after model updates.
+
+## Tessl Three-Layer Eval Taxonomy
+
+Three layers of increasing realism. Each catches failures the others miss.
+
+### Layer 1: Skill Review (Structural Lint)
+
+Does the skill itself follow best practices?
+- SKILL.md structure (frontmatter, sections, length)
+- Description quality (imperative, user-intent, trigger keywords)
+- Reference organization (conditional triggers, one level deep)
+- Convention compliance (for Plastic skills, see convention-checks.md)
+
+Fast, cheap, runs without executing the skill.
+
+### Layer 2: Task Evals (Synthetic)
+
+Does the skill improve agent output on synthetic tasks?
+- Paired with/without comparison
+- Controlled prompts with known-good expected outputs
+- Measures the delta the skill adds
+
+This is the core eval loop (Steps 2-5 in the SKILL.md procedure).
+
+### Layer 3: Repo Evals (Real Codebase)
+
+Does the skill work correctly in a real project context?
+- Install the skill in a real repository
+- Run real tasks (not synthetic prompts)
+- Measure whether the agent uses the skill correctly in situ
+
+Most expensive, most realistic. Catches skills that pass synthetic tests
+but fail under real project complexity. Use for high-stakes skills
+or before shipping to users.

package/skills/executing-plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:executing-plan
+name: plastic-executing-plan
 description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (dispatches fresh subagent per task with two-stage review). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
 ---
 
@@ -70,11 +70,12 @@ After all tasks complete, dispatch a final reviewer for the entire implementatio
 ### Step 4: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory
+1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form
 2. Write `## Outcome` summary in the intent file (1-2 sentences)
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -95,11 +96,12 @@ For each task:
 ### Step 3: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory
+1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form
 2. Write `## Outcome` summary in the intent file (1-2 sentences)
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/install/SKILL.md

@@ -1,22 +1,64 @@
 ---
-name: plastic:install
-description: Use when initializing Plastic globally (~/.plastic/) or locally in a project. Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
+name: plastic-install
+description: Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. Accepts channel flags (--alpha, --beta, --latest) to select release channel. Default is --latest (stable). Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
 ---
 
 # Install Plastic
 
+> **Recommended path:** for a first install, run `npx @zalom/plastic@latest install --claude`
+> in your shell (or `bunx @zalom/plastic@latest --claude` if you use Bun). This skill
+> exists to **re-install or repair** an existing setup from inside the agent, and to
+> drive interactive global configuration. Whenever this skill performs an install or
+> re-install, it **runs `/plastic-doctor` afterward** and reports the result.
+
+## Re-install / repair
+
+If Plastic is already installed but something is broken (skills missing, hooks not
+firing, leftover legacy plugin), re-run the installer — it is idempotent, prunes
+files that no longer ship, and removes any legacy plugin/marketplace layout:
+
+```bash
+npx @zalom/plastic@latest install --reinstall --claude   # or @beta / @alpha to match your channel
+```
+
+Then **run `/plastic-doctor`** and report what it found.
+
+## Channel Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--latest` | Install from stable channel (default) |
+| `--beta` | Install from beta channel |
+| `--alpha` | Install from alpha channel |
+
+When invoked from within Claude Code (re-install or channel switch), the skill
+runs the appropriate npx command:
+
+```bash
+# Stable (default)
+npx @zalom/plastic install --claude
+
+# Beta
+npx @zalom/plastic@beta install --claude
+
+# Alpha
+npx @zalom/plastic@alpha install --claude
+```
+
+The installed version and channel are recorded in `~/.plastic/VERSION`.
+
 ## Modes
 
 ### Global Install (default, recommended)
 
-Run `/plastic:install` with no arguments.
+Run `/plastic-install` with no arguments.
 
 #### Procedure
 
 **Step 1: Check for existing installation**
 
 Check if `~/.plastic/INDEX.md` exists.
-- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic:update` to sync core files."
+- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic-update` to sync core files."
 - If no: proceed with fresh install.
 
 **Step 2: Create ~/.plastic/ as a git repo**
@@ -106,13 +148,32 @@ Update `config.yml` with any additional roots.
 
 Auto-commit the config change.
 
-**Step 4: Announce**
+**Step 4: Verify with doctor**
+
+Run `/plastic-doctor` and report the result. Resolve any fixable findings before
+announcing success.
+
+**Step 5: Register stores with QMD (optional)**
+
+QMD is an optional search layer. If it is installed, register the Plastic stores so
+they are searchable:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync detect && ruby ~/.plastic/scripts/qmd-sync register --all
+```
+
+`qmd-sync` no-ops cleanly when QMD is absent, so this is safe to run unconditionally.
+It registers `plastic-global` and every project store from `projects.yml`, then indexes
+them. Report what was registered, or that QMD was not detected and the step was skipped.
+
+**Step 6: Announce**
 
-> "Plastic installed globally at ~/.plastic/. Create your first intent with `/plastic:creating-intent`."
+> "Plastic installed globally at ~/.plastic/. Health check: [doctor summary].
+> Create your first intent with `/plastic-creating-intent`."
 
 ### Local Install (testing/legacy)
 
-Run `/plastic:install --local`.
+Run `/plastic-install --local`.
 
 #### Procedure
 
@@ -131,4 +192,4 @@ Run `/plastic:install --local`.
 
 **Step 4:** Commit in project: `git add .plastic/ && git commit -m "chore: initialize Plastic local store"`
 
-**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider `/plastic:install` for global mode."
+**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider `/plastic-install` for global mode."

package/skills/intent-curator/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:intent-curator
+name: plastic-intent-curator
 description: |
   Use when completing or reviewing intents, reorganizing the index,
   or when the intent store needs maintenance. Examples:
@@ -15,7 +15,7 @@ description: |
 
 # Intent Curator
 
-Dispatches to the `plastic:intent-curator` agent for intent store maintenance.
+Dispatches to the `plastic-intent-curator` agent for intent store maintenance.
 
 ## When to Use
 - Completing or reviewing intents
@@ -25,7 +25,7 @@ Dispatches to the `plastic:intent-curator` agent for intent store maintenance.
 
 ## Workflow
 
-Invoke the `plastic:intent-curator` agent via the Agent tool with `subagent_type: "plastic:intent-curator"`. Pass the user's request as the prompt, including:
+Invoke the `plastic-intent-curator` agent via the Agent tool with `subagent_type: "plastic-intent-curator"`. Pass the user's request as the prompt, including:
 
 1. **What to do** — complete intent, reorganize, triage stale, etc.
 2. **Which store** — global (`~/.plastic/`) or project (`.plastic/store/`)

package/skills/linking-intents/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:linking-intents
+name: plastic-linking-intents
 description: Use when creating connections between intents, the user says "link" or "connect", or when discovering that two intents are related. Manages sources, chain, and cross-reference links.
 ---
 
@@ -21,13 +21,13 @@ Explicit wikilinks in the `## Links` section. Bidirectional — add to both inte
 ```
 
 ### 2. Sources (Backward)
-The `sources` array in frontmatter. What influenced this intent — backward links to parent/prior work:
+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)
-The `chain` array in frontmatter. What this intent spawned — forward links to children/follow-on work:
+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"]
 ```
@@ -55,18 +55,27 @@ done
 
 ### 2. Choose Connection Type
 Ask the user which type of connection:
-- **source** — "this was influenced by that" (add to `sources[]`, update `chain[]` on the target)
-- **cross-reference** — "these are related" (add wikilink in `## Links` of both intents)
+- **source**: "this was CREATED FROM that" (D1). The reciprocal update is one-directional (I1): add the ascendant id to this intent's `sources[]` AND add this intent's id to the ascendant's `chain[]`. A merely-related (not-created-from) connection is NOT a source: record it on the predecessor's `chain[]` only, plus a `## Links` wikilink, with NO `sources` (the related-but-not-spawned rule).
+- **cross-reference**: "these are related" (add wikilink in `## Links` of both intents)
 
 ### 3. Apply Connection
 
-**For sources:**
-Update frontmatter arrays on both intents:
+**For sources (a true created-from edge only):**
+Update frontmatter arrays on both intents (I1, two-sided):
 - Add the parent's ID to the child's `sources` array
 - Add the child's ID to the parent's `chain` array
 
+For the merely-related case, only the predecessor's `chain` (and both sides' `## Links`)
+get the link, never `sources`. `chain` is NOT strictly the reverse of `sources` (I2):
+relational `chain` entries are valid and must never be "corrected" by adding a reciprocal
+`sources`.
+
 **For cross-references:**
 Add a wikilink in the `## Links` section of **both** intents (bidirectional).
 
 ### 4. Update INDEX.md Clusters
 If both intents share a topic, ensure they're in the same cluster.
+
+## References
+
+- Read `references/zettelkasten.md` for the three Zettelkasten structures (Folgezettel, directed graph, tags), ID encoding rules, and dual-mode (Obsidian + programmatic) design

package/skills/linking-intents/references/zettelkasten.md

@@ -0,0 +1,38 @@
+# Zettelkasten Structure
+
+Plastic implements three Zettelkasten structures:
+
+| Structure | Implementation | Purpose |
+|---|---|---|
+| Folgezettel (linked list) | `sources` + `chain` in frontmatter | Sequential provenance |
+| Directed graph (web of notes) | `## Links` with wikilinks | Obsidian navigation |
+| Tag-based taxonomy | `tags` in frontmatter | Topic grouping |
+
+INDEX.md is a structure note (hub), not a table of contents.
+
+## Folgezettel IDs
+
+IDs encode lineage using Luhmann's alternating convention:
+- Root intents: sequential numbers (`1`, `2`, `3`...)
+- Branches alternate letters and numbers: `1` → `1a` → `1a1` → `1a1a` → ...
+- Multiple branches from the same parent increment: `1a`, `1b`, `1c`
+- IDs are assigned at creation time and never change
+
+## Knowledge Graph
+
+`sources` and `chain` form the directed knowledge graph:
+- `sources` = the direct ascendant(s) this intent was created from / emerged from the
+  lifecycle of (formation, not topic similarity); a DAG (acyclic), strong must-load context.
+- `chain` = forward continuations AND related-but-not-spawned successors it leads to; a
+  directed graph that may cycle, lighter contributory context.
+- Reciprocity is one-directional: every `sources` edge has a reciprocal `chain` entry (I1),
+  but `chain` may carry relational entries with no reciprocal `sources` (I2), so the graph is
+  NOT strictly double-linked.
+
+## Dual-Mode
+
+This store works in two modes without modification:
+- **Obsidian** (human, offline) — browse, link, write markdown
+- **Programmatic** (any agent) — read/write via filesystem operations
+
+No special tooling required for either mode.

package/skills/managing-index/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:managing-index
+name: plastic-managing-index
 description: Use after creating, completing, or abandoning intents, when the user says "index" or "organize", or when INDEX.md needs maintenance. Curates the INDEX.md structure note.
 ---
 
@@ -64,3 +64,7 @@ When 3+ intents share tags but aren't in a cluster, suggest a new cluster headin
 Intents with no links (empty `sources`, empty `chain`, no `## Links` entries, not in any cluster) should be flagged for curation.
 
 REQUIRED BACKGROUND: linking-intents (for understanding connection types and Zettelkasten theory)
+
+## References
+
+- Read `references/zettelkasten-linking.md` for the three structural layers (Folgezettel, directed graph, tags) and how they map to INDEX.md organization

package/skills/managing-index/references/zettelkasten-linking.md

@@ -9,7 +9,7 @@
 ## Three Connection Types (Ranked)
 
 1. **Direct links** (strongest) — wikilinks in `## Links` section
-2. **Sources/Chain** (knowledge graph) — `sources` array (backward), `chain` array (forward) in frontmatter
+2. **Sources/Chain** (knowledge graph): `sources` = direct ascendants this was created from (formation, acyclic, must-load); `chain` = forward continuations and related successors (may cycle, lighter context). See `docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
 3. **Tags** (weakest) — shared tags, `project-<name>` for project membership
 
 ## When to Create a Cluster

package/skills/releasing/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: plastic:releasing
+name: plastic-releasing
 description: Use when merging a feature branch to main and tagging a release, bumping the version, or when the user says "release", "tag", or "ship it"
 ---
 
 # Releasing
 
 Merge, bump, tag, push. Annotated tags with changelogs. Semantic versioning.
-Project configuration drives the workflow — no hardcoded assumptions.
+Project configuration drives the workflow - no hardcoded assumptions.
 
 ## Checklist
 
@@ -18,6 +18,7 @@ Project configuration drives the workflow — no hardcoded assumptions.
 - [ ] Create annotated tag
 - [ ] Push to remote with tags
 - [ ] 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
 
 ## Workflow
@@ -26,9 +27,9 @@ Project configuration drives the workflow — no hardcoded assumptions.
 
 Before anything else, determine which project we are releasing and load its config.
 
-1. Read `~/.plastic/projects.yml` — find the project whose `path` matches the current working directory.
+1. Read `~/.plastic/projects.yml` - find the project whose `path` matches the current working directory.
 2. Extract the project slug (the key under `projects:`).
-3. Read `~/.plastic/projects/{slug}/project.yml` — this contains the `release:` section.
+3. Read `~/.plastic/projects/{slug}/project.yml` - this contains the `release:` section.
 
 Expected `release:` keys in project.yml:
 
@@ -37,8 +38,9 @@ release:
   verify: "bin/rails test"              # command to run before release
   version_file: package.json            # single file containing the version
   version_files:                        # multiple files (overrides version_file)
-    - package.json
-    - .claude-plugin/plugin.json
+    - package.json                      # list EVERY file carrying the version;
+    - .claude-plugin/plugin.json        # they must all be bumped together or they drift
+    - .claude-plugin/marketplace.json
   tag_format: "v{{version}}"            # tag naming pattern ({{version}} is replaced)
   on_green:                             # actions to run after push succeeds
     - github_release
@@ -47,7 +49,7 @@ release:
   on_red: stop                          # what to do if verification fails
 ```
 
-**Fallback:** If no project.yml exists or it has no `release:` section, fall back to asking the user for each step — verify command, version files, tag format, and post-push actions.
+**Fallback:** If no project.yml exists or it has no `release:` section, fall back to asking the user for each step - verify command, version files, tag format, and post-push actions.
 
 ### 1. Verify Tests Pass
 
@@ -77,7 +79,7 @@ Pre-1.0: minor bumps for features, patch for fixes. No major until stable.
 
 ```bash
 git checkout main
-git merge <branch-name> --no-ff -m "feat: merge intent [ID] — [description]"
+git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 ```
 
 Always `--no-ff` to preserve branch history in the merge commit.
@@ -94,7 +96,7 @@ Update the version string in each file, then commit:
 
 ```bash
 git add <version-files>
-git commit -m "chore: bump version to X.Y.Z — [one-line summary]"
+git commit -m "chore: bump version to X.Y.Z - [one-line summary]"
 ```
 
 ### 5. Create Annotated Tag
@@ -113,7 +115,7 @@ git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges | grep -E
 Create the tag with a multi-line message:
 
 ```bash
-git tag -a <tag-name> -m "<tag-name> — [release name]
+git tag -a <tag-name> -m "<tag-name> - [release name]
 
 - [changelog bullet points from feat/fix/refactor commits]"
 ```
@@ -133,23 +135,37 @@ Read `release.on_green` from project.yml. This is a list of actions to run after
 Create a GitHub release from the tag:
 
 ```bash
-gh release create <tag-name> --title "<tag-name> — [release name]" --generate-notes --notes-start-tag <previous-tag>
+gh release create <tag-name> --title "<tag-name> - [release name]" --latest --generate-notes --notes-start-tag <previous-tag>
 ```
 
+`--latest` is REQUIRED. Pre-release (alpha/beta) tags are NOT auto-promoted to the "Latest"
+badge by GitHub, so without it the Releases page keeps showing an older version as Latest while
+the newest tag sits below it (a real sync drift we hit on the alpha line). Pass `--latest` on
+every release so the newest one always carries the badge. Do NOT pass `--prerelease` unless you
+specifically want the release hidden from Latest.
+
 For the first release (no previous tag), write notes manually with `--notes "..."` instead.
 
 #### `npm_publish`
 
-Publish the package to npm:
+Publish the package to npm with the appropriate dist-tag:
 
 ```bash
-# For pre-release versions (0.x.y, or version contains -alpha/-beta/-rc):
+# Alpha pre-release (version contains -alpha):
 npm publish --access public --tag alpha
 
-# For stable versions (>= 1.0.0, no pre-release suffix):
+# Beta pre-release (version contains -beta):
+npm publish --access public --tag beta
+
+# Stable release (no pre-release suffix, >= 1.0.0):
 npm publish --access public
 ```
 
+The dist-tag is derived from the version string in `package.json`:
+- Contains `-alpha` → `--tag alpha`
+- Contains `-beta` → `--tag beta`
+- No pre-release suffix → no `--tag` flag (publishes to `latest`)
+
 #### Other values
 
 If `on_green` contains an action not listed above, log it:
@@ -160,6 +176,22 @@ If `on_green` contains an action not listed above, log it:
 
 If `on_green` is empty or absent: skip post-push actions entirely.
 
+#### Verify sync (always, after the post-push actions)
+
+A release is not done until all three surfaces show the SAME newest version. Confirm:
+
+```bash
+npm view <package> dist-tags                      # channel tag (alpha/beta/latest) -> new version
+gh release list --limit 1                         # newest release is the new tag AND marked "Latest"
+git ls-remote --tags origin | grep <tag-name>     # the tag reached the remote
+```
+
+If the GitHub "Latest" badge is on an older tag (the common drift), fix it without re-releasing:
+
+```bash
+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.
@@ -171,25 +203,50 @@ A release IS a delivery. The active intent that drove this work must be complete
    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>"`
+3. Auto-commit: `cd ~/.plastic && git add . && git commit -m "feat: complete intent <ID> - delivered in <tag-name>"`
 
-**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.
+**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.
 
 ## Conventions
 
-- **Annotated tags only** — `git tag -a`, never lightweight tags
-- **Tag format** — driven by `release.tag_format` in project.yml (default: `vX.Y.Z`)
-- **Tag message** — first line: `<tag> — [short name]`, then blank line, then bullet changelog
-- **Commit prefixes** — `feat:`, `fix:`, `refactor:`, `chore:`, `docs:` (conventional commits)
-- **Version files** — driven by project.yml; all listed files must always match
-- **Branch cleanup** — delete merged feature branches: `git branch -d <branch>`
+- **Annotated tags only** - `git tag -a`, never lightweight tags
+- **Tag format** - driven by `release.tag_format` in project.yml (default: `vX.Y.Z`)
+- **Tag message** - first line: `<tag> - [short name]`, then blank line, then bullet changelog
+- **Commit prefixes** - `feat:`, `fix:`, `refactor:`, `chore:`, `docs:` (conventional commits)
+- **Hyphens, never em-dashes** - in tag names, release titles, and commit messages, use a hyphen (`-`). Never an em-dash.
+- **Latest badge** - always `gh release create --latest`; the newest release must carry GitHub's "Latest" badge.
+- **Version files** - driven by project.yml; list and bump EVERY file carrying the version (they drift otherwise)
+- **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]"
+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
+
+- Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations