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

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"]
 ```
@@ -41,6 +41,12 @@ tags: [plastic, project-reddit-kb]
 ## Workflow
 
 ### 1. Identify Intents to Connect
+
+QMD-first (when available): before scanning the store with grep/Read, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related
+intents to propose as sources/chain, then open the authoritative intent file for any hit you act
+on. The command is a no-op when QMD is absent, so fall back to the directory scan below.
+
 Show existing intents by scanning the store's directory for intent files:
 ```bash
 for dir in $STORE_ROOT/store/*/; do
@@ -55,18 +61,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/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-linking-intents",
+  "notes": "Intent 66a. Spec for the QMD-first discovery step (surface candidate/related intents to propose as sources/chain before grep/Read). Runner is intent 76; this case is a spec, not executed.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: link this intent to the related upload-pipeline work.",
+      "expected_output": "Before scanning the store directory with grep/Read to identify related intents, runs `ruby ~/.plastic/scripts/qmd-sync search \"upload pipeline\"` to surface candidate or related intents to propose as sources/chain, then opens the authoritative intent file for any hit it links. No-op fallback to the directory scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before the directory scan; authoritative file opened for any hit before proposing sources/chain",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,45 @@
+# 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.
+
+`## Links` mirrors the frontmatter graph exactly. Each entry is
+`- [[id--slug|<target's full intent: text>]]` (cross-store: `- [[store:id--slug|...]]`),
+a clickable `id--slug` target with the target's full `intent:` text as the label.
+Ordering is mandatory: all `sources` first (top), then all `chain`, frontmatter order
+preserved within each group. Sources never appear at the end. No source/chain tags, no
+sub-grouping. An intent with empty `sources` and `chain` carries the empty-state comment.
+
+## 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.
 ---
 
@@ -43,6 +43,12 @@ All completed intents with dates. Links preserved, never deleted.
 
 ## Workflow
 
+QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or
+cluster it) rather than rebuild every section, before scanning the store with grep/Read run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate or related intents, then
+open the authoritative intent file for any hit you act on. The command is a no-op when QMD is
+absent, so fall back to the directory scan below.
+
 ### Rebuild Sections
 Scan the active store's `store/` directory for intent files and rebuild each section:
 
@@ -64,3 +70,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/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-managing-index",
+  "notes": "Intent 66a. Spec for the QMD-first step when locating a specific intent to reclassify/flag/cluster before grep/Read. Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: move the intent about the statusline into the Completed section.",
+      "expected_output": "When locating one specific intent rather than rebuilding every section, before scanning the store with grep/Read runs `ruby ~/.plastic/scripts/qmd-sync search \"statusline\"` to surface the candidate intent, then opens the authoritative intent file for the hit it reclassifies. No-op fallback to the directory scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before the directory scan when locating a specific intent; authoritative file opened for the hit",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

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

@@ -8,8 +8,13 @@
 
 ## 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
+1. **Direct links** (strongest): wikilinks in the `## Links` section, the projection of the
+   frontmatter graph. Each entry is `- [[id--slug|<target's full intent: text>]]` (cross-store:
+   `- [[store:id--slug|...]]`), a clickable `id--slug` target labeled with the target's full
+   `intent:` text. Ordering is mandatory: all `sources` first (top), then all `chain`,
+   frontmatter order preserved within each group. Sources never appear at the end. No
+   source/chain tags, no sub-grouping.
+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

package/skills/releasing/references/deprecations.md

@@ -0,0 +1,60 @@
+# Deprecation Process
+
+When removing a feature, changing a convention, or making a breaking change:
+
+1. Add entry to `deprecations.yml` in the Plastic source root
+2. Set severity: `info` (awareness), `warning` (action needed), `critical` (urgent)
+3. Provide clear migration steps
+4. Set `removal` version at least 2 minor versions ahead
+5. SessionStart hook displays active deprecations automatically
+6. Remove the feature AND the deprecation entry together
+
+## Pre-1.0 removal policy
+
+The numbered process above is the steady-state rule: a deprecation rides until its `removal`
+version, which step 4 sets at least two minors ahead. While Plastic is still pre-1.0 (any
+version below `1.0.0`), one exception applies:
+
+- **Pre-1.0 exception.** Before `1.0.0`, a *satisfied* deprecation (the migration it
+  announced is complete on installed machines) may be removed immediately, rather than waiting
+  for its declared `removal` major. Delete the entry from `deprecations.yml` (leaving
+  `deprecations: []` if it was the last one) the moment the migration is done.
+
+This exception only holds below `1.0.0`. From `1.0.0` onward, the steady-state grace rule
+(step 4, removal at least two minors ahead) governs again, unchanged. The exception narrows
+*when* a satisfied entry may be pulled early during the pre-release line; it does not loosen
+the grace window for the released-product contract.
+
+## Severity Levels
+
+| Severity | When to use | Dismissable? |
+|----------|-------------|--------------|
+| `info` | Upcoming change | Yes |
+| `warning` | Action needed | Yes (re-shown at removal) |
+| `critical` | Urgent/security | Never |
+
+## deprecations.yml Schema
+
+```yaml
+deprecations:
+  - id: unique-slug
+    severity: info | warning | critical
+    summary: "One-line description"
+    migration_steps:
+      - "Step 1"
+      - "Step 2"
+    introduced: "0.9.0"
+    removal: "1.0.0"
+    link: "optional URL"
+```
+
+## Dismissal
+
+Users dismiss by adding the id to `deprecations_dismissed` in `config.yml`:
+
+```yaml
+deprecations_dismissed:
+  - some-deprecated-feature
+```
+
+Critical deprecations and final-version warnings ignore dismissal.

package/skills/research/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:research
+name: plastic-research
 description: "Research a topic for the active intent. Agent decides shallow vs deep based on scope. Produces reports in the intent's resources/ directory."
 ---
 
@@ -14,9 +14,17 @@ Investigate a topic related to the active intent. Choose the right depth, produc
 Before proceeding, resolve the active intent:
 
 1. **Detect store:** Read `~/.plastic/projects.yml`, match CWD against registered project paths. If match → project store at `~/.plastic/projects/{slug}/store/`. If no match → global store at `~/.plastic/store/`.
-2. **Find active intent:** Read `INDEX.md` from the detected store. Look under `## Active`. If exactly one → use it. If multiple → ask which. If none → refuse: "No active intent. Create one first with /plastic:creating-intent"
+2. **Find active intent:** Read `INDEX.md` from the detected store. Look under `## Active`. If exactly one → use it. If multiple → ask which. If none → refuse: "No active intent. Create one first with /plastic-creating-intent"
 3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
 
+## Check Prior Work First
+
+QMD-first (when available): before scanning the store with grep/Read or searching the web, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related intents
+and existing research, then open the authoritative intent file for any hit you act on. Reusing a
+prior report beats re-deriving it. The command is a no-op when QMD is absent, so fall back to the
+existing INDEX.md / file scan.
+
 ## Depth Decision
 
 Before starting research, assess the question against these criteria:

package/skills/research/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-research",
+  "notes": "Intent 66a. Spec for the QMD-first step before researching (reuse prior intents/reports before grep/Read or web search). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user asks the agent to research installer patterns for the active intent.",
+      "expected_output": "Before scanning the store with grep/Read or searching the web, runs `ruby ~/.plastic/scripts/qmd-sync search \"installer patterns\"` to surface candidate, prior, or related intents and existing research, then opens the authoritative intent file for any hit it reuses. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read and web search; authoritative file opened for any prior report reused",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/savepoint/SKILL.md

@@ -1,57 +1,66 @@
 ---
-name: plastic:savepoint
-description: Use when context is being compacted (PreCompact hook), user says "save" or "savepoint", or before ending a session. Saves the active intent's state so work can resume after /clear.
+name: plastic-savepoint
+description: Use when verifying or repairing an intent's savepoint ledger, when the user says "save" or "savepoint", or when a PreCompact hook fires. The ledger is written automatically by the gate hook at each lifecycle boundary; this skill only reads, verifies, and rebuilds it.
 ---
 
 # Savepoint
 
-## When to Use
-- PreCompact hook fires (automatic)
-- User says "save", "savepoint", or "save progress"
-- Before ending a long session
-- Before switching to a different intent
+`savepoint.md` is a deterministic, append-only ledger of an intent's cycle steps, one line
+per lifecycle milestone, newest at the bottom:
 
-## Workflow
+```
+2026-06-16T14:02Z  What  34--cycle-step-savepoints.md
+2026-06-16T14:20Z  Why   spec.md created
+2026-06-16T15:10Z  How   plan.md created
+2026-06-16T15:11Z  How   checklist.md created
+2026-06-16T16:40Z  Exec  outcome.md created
+```
 
-### 1. Find Active Intent(s)
-Read `~/.plastic/INDEX.md` (or the project INDEX.md) and extract all intents listed under `## Active`.
+It is **sugar on top of the conventions**, not a source of truth. The gate hook
+(`hook-gate-check`) writes each line automatically when a stage file is created, so there is
+nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
+a resuming agent read the cycle's succession from one glance (last line = where we are).
 
-### 2. For Each Active Intent
-Read the intent directory at `~/.plastic/store/ID--slug/`:
+## When to Use
+- A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
+- Resuming an intent: read the ledger to learn the cycle's succession quickly.
+- The ledger looks stale, empty, or missing: rebuild it from the filesystem.
 
-**a. Update checklist.md** (if exists):
-- Check off completed items
-- Add any new items discovered during the session
+## What this skill does NOT do
+- It does not write prose, "in progress", "next step", or "blockers". The old 50%-context
+  prose savepoint is retired. The semantic trace lives in `## Insights` (append-only,
+  newest at the bottom); the byte history lives in git.
 
-**b. Create/update savepoint.md:**
-```markdown
-# Savepoint
+## Workflow
 
-## Last Updated
-{{DATE}} — Session #{{N}}
+### 1. Find Active Intent(s)
+Read the active store's `INDEX.md` and extract intents under `## Active`.
 
-## In Progress
-- (what was being worked on when savepoint triggered)
-- Next: (immediate next step)
+### 2. For Each Active Intent — verify the ledger
+- Read `savepoint.md`. Confirm it exists and is non-empty.
+- Confirm the **last line's stage** matches the stage derived from files-on-disk
+  (`Bridge.derive_stage`). If they disagree, or the file is missing/empty, the ledger has
+  drifted.
 
-## Blockers
-(any blockers or open questions)
+### 3. Rebuild on drift
+Reconstruct from the filesystem rather than hand-editing:
 
-## Key Discoveries This Session
-- (important things learned)
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e \
+  'Bridge.rebuild_savepoint("<intent_dir>")'
 ```
 
-**c. Update `{ID}--{slug}.md`:**
-- Add observations to `## Insights` section
-
-### 3. Update INDEX.md
-Verify the `## Active` section is accurate.
+This rewrites `savepoint.md` from the milestone files present (timestamps from mtimes),
+in stage order. Safe to run anytime: the ledger is derived.
 
-### 4. Commit
+### 4. Commit (store only)
+If a rebuild changed the ledger, commit it in the store repo:
 ```bash
-git add .plastic/
-git commit -m "chore: savepoint — [active intent name]"
+cd <store-root> && git add . && git commit -m "chore: rebuild savepoint ledger — [intent]"
 ```
+Never push `~/.plastic/`.
+
+## References
 
-### 5. Notify User
-Tell the user: "Context is getting large. I've saved progress to intent [ID] — [name]. Please run `/clear` and say `continue` to resume."
+- Read `references/context-management.md` for the full save/continue protocol and how the
+  resume flow consumes the ledger.