reffy-cli 1.8.0 → 1.9.0

package/README.md

@@ -136,7 +136,7 @@ managed: true
 - `commands` declares the CLI commands the skill wraps, which `reffy doctor` cross-checks against the installed CLI.
 - `managed: true` marks skills Reffy owns. `reffy init` scaffolds and refreshes managed skills in place and never touches unmanaged ones.
 
-`reffy init` ships six managed skills covering the core workflows: `create-artifact`, `create-change`, `archive-change`, `inspect-specs`, `sync-remote`, and `diagnose`. Author your own with `reffy skill create <name>`.
+`reffy init` ships seven managed skills covering the core workflows: `create-artifact`, `create-change`, `archive-change`, `supersede-change`, `inspect-specs`, `sync-remote`, and `diagnose`. Author your own with `reffy skill create <name>`.
 
 ```bash
 reffy skill list                       # name + description + managed flag
@@ -370,6 +370,15 @@ Useful side commands during the arc:
 
 Pivots, deprecations, and wind-downs are not a separate concept in ReffySpec — they are ordinary changes whose delta is mostly REMOVED or MODIFIED requirements instead of ADDED ones. Because every change's `specs/<capability>/spec.md` is already a delta against the canonical spec, a course correction reuses the same machinery as a feature addition: scaffold a change, author a delta that removes or rewrites the relevant requirements, pair it with code-removal tasks, and archive it when shipped. The history of pivots stays legible as a series of deltas under `changes/archive/`, rather than getting buried in code commits.
 
+There is no pivot command and no per-requirement "deprecated" flag: signaling a change of direction just requires another change. The archive is append-only — you never edit or delete an archived change to reverse it; you land a new change on top, and canonical `specs/` always reflects current truth. When a change reverses or replaces a prior one, name the prior change-id(s) in an optional `## Supersedes` section of `proposal.md`:
+
+```md
+## Supersedes
+- add-old-direction
+```
+
+This is a navigational pointer that keeps the lineage explicit; the spec delta remains the authoritative record of what actually changed. `reffy plan create` scaffolds the `## Supersedes` section (defaulting to `None`) so the convention is there when you need it.
+
 ### Reference implementation in this repo
 
 - `AGENTS.md`: contains both managed instruction blocks and encodes sequencing.

package/dist/cli.js

@@ -195,6 +195,12 @@ These instructions are for AI assistants working in this project.
 - Delta specs must use \`## ADDED|MODIFIED|REMOVED|RENAMED Requirements\`.
 - Each requirement must include at least one \`#### Scenario:\`.
 
+## Representing Pivots
+
+- A pivot, deprecation, or wind-down is not a special object — it is an ordinary change whose delta is mostly \`REMOVED\`/\`MODIFIED\` requirements.
+- Never edit or delete an archived change to reverse direction; land a new change on top. The archive is an append-only ledger and canonical \`specs/\` always reflects current truth.
+- When a change reverses or replaces the direction of a prior one, name the prior change-id(s) in a \`## Supersedes\` section of \`proposal.md\`. This is a navigational pointer; the spec delta remains the authoritative record of what changed.
+
 ## Reffy Relationship
 
 - Reffy owns the runtime and artifact workflow.

package/dist/plan.js

@@ -156,6 +156,10 @@ ${changeBullets}
 
 ${buildImpactText(capabilityId, signals)}
 
+## Supersedes
+_Optional. If this change reverses or replaces the direction of a prior change (a pivot, deprecation, or wind-down), name the prior change-id(s) here, e.g. \`- add-old-direction\`. Leave as "None" otherwise. The spec delta remains the authoritative record of what changed; this is a navigational pointer._
+None
+
 ## Reffy References
 ${references}
 `;

package/dist/skills.js

@@ -341,6 +341,36 @@ Use this once a change is implemented and verified and you want to fold its spec
 
 ## Failure modes
 - If archive reports unmerged or conflicting requirements, inspect the delta against the canonical spec before retrying.`,
+    },
+    {
+        name: "supersede-change",
+        description: "Represent a pivot, deprecation, or reversal as a new change that supersedes a prior one.",
+        triggers: [
+            "pivot",
+            "change direction",
+            "deprecate",
+            "wind down",
+            "reverse the decision",
+            "supersede",
+            "replace the approach",
+            "abandon",
+        ],
+        commands: ["reffy plan list", "reffy plan create", "reffy plan validate", "reffy plan archive"],
+        body: `## When to use this skill
+Use this when a request changes direction rather than adding to it: a pivot, deprecation, wind-down, or reversal of a prior decision. A pivot is not a special object — it is an ordinary change that supersedes another. Never edit or delete an archived change to reverse it; land a new change on top. Canonical \`specs/\` always reflects current truth and the archive stays append-only.
+
+## Steps
+1. Run \`reffy plan list\` to identify the prior change-id(s) whose direction this reverses or replaces.
+2. Run \`reffy plan create --change-id <kebab-id> --title "<title>"\` for the new change.
+3. Author the spec delta with \`REMOVED\`/\`MODIFIED\` requirements (not \`ADDED\`) that retire or rewrite the superseded behavior. The delta is the authoritative record of what changed.
+4. In \`proposal.md\`, fill the \`## Supersedes\` section with the prior change-id(s) — a navigational pointer that keeps the lineage explicit.
+5. Pair the change with code-removal / migration tasks in \`tasks.md\`.
+6. Run \`reffy plan validate <change-id>\`, then \`reffy plan archive <change-id>\` once shipped.
+
+## Failure modes
+- If you find yourself wanting to edit an archived change, stop: model the reversal as a new superseding change instead.
+- Leaving \`## Supersedes\` as "None" on a genuine pivot loses the lineage; name the prior change-id.
+- A pivot whose delta only \`ADDED\`s requirements is probably not actually retiring the old direction — check the canonical spec for what should be \`REMOVED\`/\`MODIFIED\`.`,
     },
     {
         name: "inspect-specs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Planning system for AI assisted development.",
   "keywords": [
     "reffy",