reffy-cli 1.8.0 → 1.9.1

package/README.md

@@ -25,7 +25,6 @@ Command summary:
 
 - `reffy init`: runs the canonical first-run setup flow, creates the `.reffy/` and `.reffy/reffyspec/` structure, writes managed instructions, reindexes artifacts, and on first-run text output prints a copy/paste instruction for your agent harness.
 - `reffy bootstrap`: compatibility alias for `reffy init`.
-- `reffy migrate`: migrates a legacy `.references/` workspace into `.reffy/`.
 - `reffy doctor`: diagnoses required Reffy setup and workspace health.
 - `reffy reindex`: reconciles `.reffy/manifest.json` with `.reffy/artifacts` by adding missing files and removing stale entries.
 - `reffy validate`: validates `.reffy/manifest.json` against manifest v1 contract.
@@ -136,7 +135,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 +369,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.
@@ -434,7 +440,6 @@ function usage() {
         "Commands:",
         "  init       Run the canonical first-run setup flow and refresh managed instructions.",
         "  bootstrap  Compatibility alias for init.",
-        "  migrate    Migrate a legacy .references workspace to the canonical .reffy layout.",
         "  doctor     Diagnose required Reffy setup and optional tool availability.",
         "  reindex    Scan .reffy/artifacts and add missing files to manifest.",
         "  validate   Validate .reffy/manifest.json against manifest v1 contract.",
@@ -1894,40 +1899,6 @@ async function main() {
         const repoRoot = parseRepoArg(rest);
         return await runSetupCommand("bootstrap", output, repoRoot);
     }
-    if (command === "migrate") {
-        const repoRoot = parseRepoArg(rest);
-        const workspace = await prepareCanonicalWorkspace(repoRoot);
-        const planning = await prepareCanonicalPlanningLayout(repoRoot);
-        const agents = await initAgents(repoRoot);
-        const skills = await scaffoldManagedSkills(repoRoot);
-        const payload = {
-            status: "ok",
-            command: "migrate",
-            workspace_mode: workspace.state.mode,
-            migrated_workspace: workspace.migrated,
-            created_workspace: workspace.created,
-            planning_mode: planning.state.mode,
-            migrated_planning_layout: planning.migrated,
-            created_planning_layout: planning.created,
-            refs_dir: workspace.state.canonicalDir,
-            ...agents,
-            skills,
-        };
-        if (output === "json") {
-            printResult(output, payload);
-        }
-        else {
-            console.log(workspace.message ?? `Workspace ready at ${workspace.state.canonicalDir}`);
-            if (planning.message) {
-                console.log(planning.message);
-            }
-            console.log(`Updated ${agents.root_agents_path}`);
-            console.log(`Updated ${agents.reffy_agents_path}`);
-            console.log(`Updated ${agents.reffyspec_agents_path}`);
-            console.log(`Skills: ${String(skills.written_skills.length)} managed (${skills.preserved_unmanaged.length} unmanaged preserved)`);
-        }
-        return 0;
-    }
     if (command === "reindex") {
         const repoRoot = parseRepoArg(rest);
         const store = new ReferencesStore(repoRoot);

package/dist/doctor.js

@@ -86,7 +86,7 @@ export async function runDoctor(repoRoot) {
         level: "optional",
         ok: workspace.mode !== "legacy",
         message: workspace.mode === "legacy"
-            ? "legacy .references workspace detected; run `reffy migrate` to adopt .reffy/"
+            ? "legacy .references workspace detected; run `reffy init` to adopt .reffy/"
             : ".reffy/ is the active workspace",
     });
     const commandDrift = await findCommandDrift(repoRoot);

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

@@ -214,7 +214,6 @@ export async function validateSkills(repoRoot, name) {
 export const KNOWN_COMMANDS = [
     "reffy init",
     "reffy bootstrap",
-    "reffy migrate",
     "reffy doctor",
     "reffy reindex",
     "reffy validate",
@@ -341,6 +340,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",
@@ -398,7 +427,7 @@ Use this first when a Reffy command misbehaves in an unfamiliar repo.
 2. Run \`reffy validate\` to confirm the manifest contract.
 3. Resolve each failure by class:
    - Missing \`.reffy/\` or \`AGENTS.md\`: run \`reffy init\`.
-   - Legacy \`.references/\` workspace: run \`reffy migrate\`.
+   - Legacy \`.references/\` workspace: run \`reffy init\`.
    - Invalid manifest: fix the reported entry, then re-run \`reffy validate\`.
    - Skill command drift: update the stale skill's \`commands\` list.
 

package/package.json

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