@skitterbyte/skitterspec 14.0.3 → 15.0.1

package/README.md

@@ -29,7 +29,7 @@ Ticketing sync is a **separate superset you install instead of this one**:
 | Install | You get |
 |---------|---------|
 | `@skitterbyte/skitterspec` | The base filesystem workflow. No tracker. |
-| `@skitterbyte/skitterspec-linear` | Everything here **plus** Linear hybrid-sync (`/spec-status` · `/spec-pull` · `/spec-push`, the `spec-sync` CLI). |
+| `@skitterbyte/skitterspec-linear` | Everything here **plus** one-way Linear sync (`/spec-status` · `/spec-push`, the `spec-sync` CLI) — repo canonical, Linear a generated mirror. |
 
 Install exactly one — the superset is a strict superset of this package.
 

package/assets/rules/spec-planning.md

@@ -68,13 +68,15 @@ Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engin
 tracker-free: it knows nothing about any specific ticketing system. A
 ticketing provider is installed as its own distribution that plugs into two named
 **seams** in the shared skills (`/spec` Phase E, `/spec-go` step 3b) and fulfils a
-skill-name + CLI contract — it ships `/spec-status` (read-only per-field
-divergence), `/spec-pull` (tracker→repo), and `/spec-push` (repo→tracker), backed
-by a `spec-sync` CLI, three-way merged against a committed base sidecar. When a
-provider is present, `/spec` also links the spec to the tracker and `/spec-go`
-pulls first. With no provider installed the seams are empty and every skill
-behaves as a plain filesystem workflow. See the provider package's own docs for
-its config and field reference.
+skill-name + CLI contract. Sync is **one-way**: the repo is the source of truth
+and the tracker is a **generated mirror**. It ships `/spec-push` (repo→tracker;
+computes a create/update plan against a committed last-pushed snapshot and applies
+it) and `/spec-status` (read-only drift report — what would push, and whether the
+tracker's workflow-state drifted), backed by a `spec-sync` CLI. There is no
+content pull — the tracker is never read back or merged. When a provider is
+present, `/spec` also links the spec to the tracker. With no provider installed
+the seams are empty and every skill behaves as a plain filesystem workflow. See
+the provider package's own docs for its config and field reference.
 
 ## Project conventions (fill this in)
 

package/assets/skills/spec/SKILL.md

@@ -217,11 +217,11 @@ finish as above.
 ## Phase E — link to a ticketing provider (only if one is installed)
 
 **Only when a ticketing provider is installed and configured** (it ships the
-`/spec-push` · `/spec-pull` · `/spec-status` skills and a provider config under
+`/spec-push` · `/spec-status` skills and a provider config under
 `specs/.core/`). If none is present, skip this phase entirely — the spec stays
 local-only and `/spec` behaves exactly as above. When a provider is present, link
 the spec to the tracker after writing it, so status and discussion live there
-while the repo stays the co-authoring surface — follow the provider's link steps
+while the repo stays the source of truth — follow the provider's link steps
 below (nothing to do here without one).
 
 

package/assets/skills/spec-go/SKILL.md

@@ -129,12 +129,11 @@ Before writing any code for this phase, get the workspace clean:
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
 
-## 3b. Pull from the tracker first (only if a provider is installed)
+## 3b. Sync with the tracker (only if a provider is installed)
 
-**Only when a ticketing provider with a `/spec-pull` skill is installed** and the
-spec is linked to the tracker. Otherwise skip this step — no provider means zero
-change to the flow below. Follow the provider's pull steps below (nothing to do
-here without one).
+**Only when a ticketing provider is installed** and the spec is linked to the
+tracker. Otherwise skip this step — no provider means zero change to the flow
+below. Follow the provider's steps below (nothing to do here without one).
 
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "14.0.3",
+  "version": "15.0.1",
   "description": "Spec-driven development for Claude Code — a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

package/src/init.js

@@ -259,6 +259,30 @@ function removeRetiredFiles(dir) {
   }
 }
 
+// Prune a file the manifest records as managed but the current package no longer
+// ships — a retired skill (e.g. `spec-pull` after the one-way switch), rule, or
+// template. Without this, upgrading leaves a live, model-visible skill on disk
+// whose instructions invoke a command that no longer exists. Delete it only when
+// PRISTINE (still matches the hash we last wrote) so a user edit is never lost; a
+// customized retired file is kept with a warning. An emptied skill folder is
+// removed. Takes the pre-flush manifest (which still holds the retired entries).
+function pruneRetiredManaged(dir, manifest) {
+  const managedRel = new Set(managedTargets(dir).map((t) => t.relPath))
+  for (const relPath of Object.keys(manifest.files || {})) {
+    if (managedRel.has(relPath)) continue // still shipped by this version
+    const abs = path.join(dir, relPath)
+    if (!fs.existsSync(abs)) continue // already gone
+    if (managedState(dir, relPath, manifest) === 'customized') {
+      report.warnings.push(`retired but kept (you edited it): ${relPath} — delete manually if unused`)
+      continue
+    }
+    fs.unlinkSync(abs)
+    report.removed.push(rel(dir, abs))
+    const folder = path.dirname(abs)
+    if (fs.existsSync(folder) && !fs.readdirSync(folder).length) fs.rmdirSync(folder)
+  }
+}
+
 // Scaffold the opt-in isolation templates into specs/.core/ (the example config
 // + its field docs). Copied, not activated: the feature stays off until the
 // consumer copies env.config.json.example → env.config.json.
@@ -409,6 +433,7 @@ function resync(dir, { force = false, claudeMd = true } = {}) {
   for (const t of managedTargets(dir)) resyncManagedFile(dir, t, manifest, force)
   installFolders(dir)
   removeRetiredFiles(dir)
+  pruneRetiredManaged(dir, manifest)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
   printReport(dir, 'resync')