@skitterbyte/skitterspec-linear 7.0.2 → 8.0.1

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

@@ -1,14 +1,14 @@
 ---
 name: spec-push
-description: Push a spec's local content up to its linked Linear project (repo → Linear), three-way aware and ownership-respecting. Never pushes pull-owned fields or local-only sections; aborts if Linear moved since the last sync unless --force (which backs up the remote side first). Runs `skitterspec spec-sync push` then applies the blessed writes over MCP. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "sync my spec up to Linear", or "update the Linear project from this spec".
+description: Push a spec up to its linked Linear project (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (project description/status, milestones, issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear project from this spec".
 ---
 
-# /spec-push — send spec content up to Linear
+# /spec-push — send a spec up to Linear (one-way)
 
-Repo → Linear. Sends the fields the repo owns/co-authors (description, phases,
-tasks per config) up to the linked project. It **never** writes `pull`-owned
-fields (status/priority/labels) or `localOnlySections`, and it **aborts** if
-Linear moved since the last sync (pull first) unless you `--force`.
+Repo → Linear. The repo is the **source of truth**; Linear is a **generated
+mirror**. This skill computes what changed since the last push and applies it —
+it never reads Linear content back or merges. A person editing the mirror in
+Linear will see it overwritten on the next push.
 
 **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
 tell the user how to enable Linear sync and stop.
@@ -17,58 +17,64 @@ tell the user how to enable Linear sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Fetch the Linear project
+## 2. Get the plan from the engine
 
-- Read `linear_project_id` from `00-overview.md` frontmatter; if missing, stop
-  (link via `/spec` first).
-- Discover the Linear MCP tools at runtime (project read **and** update). If
-  Linear isn't connected — or the update tool is missing — relay the fix and stop,
-  **writing nothing**.
-- Call the read tool and write the project JSON to a temp file.
+```
+skitterspec spec-sync push <spec> --json
+```
 
-## 3. Run the engine (the guard)
+The engine prints a JSON **plan** (no network, no remote read):
 
+```json
+{
+  "project": { "description": "…", "status": "in-progress", "priority": 2, "labels": ["…"] },
+  "milestones": { "create": [{ "ref": "01-outbox", "name": "…", "goal": "…" }], "update": [{ "id": "…", "name": "…", "goal": "…" }] },
+  "issues": { "create": [{ "ref": "<task text>", "title": "…", "description": "…", "done": false, "milestoneRef": "01-outbox" }], "update": [{ "id": "SKI-1", "title": "…", "description": "…", "done": true }] }
+}
 ```
-skitterspec spec-sync push <spec> --remote <tempfile> --out <mergedfile> [--force]
-```
 
-- **Refused** (`remote-moved` / `concurrent-write` / conflict) — relay the message
-  and **stop**. Do not write to Linear. Suggest `/spec-pull` first.
-- **OK** — the engine has confirmed it's safe, rewritten the base, and stamped
-  `last_synced_at`. Its summary lists the `written` fields (and any `skipped`
-  because they're not pushable).
-- **`--force`** — only when the user explicitly asks. Local wins after the engine
-  backs up the remote side under `sync.backupDir`. Relay the backup path.
+An empty plan (no project, no create/update) means the mirror is up to date —
+say so and stop.
+
+## 3. Discover the Linear MCP tools
 
-## 4. Apply the blessed writes to Linear
+Discover project + milestone + issue **create/update** tools at runtime. If
+Linear isn't connected or a needed tool is missing, relay the fix and stop,
+**writing nothing**.
 
-Only when step 3 returned OK: for each `written` field, call the Linear update
-tool with that field's local value (e.g. `description` → the project description).
-The engine has already vetted the change and moved the base — so if a Linear
-write fails, re-run `/spec-pull` to reconcile rather than retrying blindly.
+**Validate the project states first.** Fetch the workspace's project-status
+names and run `skitterspec spec-sync status <spec> --workspace-states <file>`; if
+it errors (a configured `states` name isn't in the workspace), stop and fix the
+config — Linear silently ignores an unknown project status.
 
-**Milestones (`milestonesPush` in the result).** When milestones are keyed, the
-engine can't write them itself — apply the plan over MCP:
+## 4. Apply the plan (order matters)
 
-- `update`: for each `{ id, name, goal }`, call the milestone-save tool with that
-  `id` (name → milestone name, goal → its description).
-- `create`: for each `{ name, goal }`, call the milestone-save tool with no id to
-  create it under the project, then **stamp the returned milestone id** into the
-  matching phase file's frontmatter (`linear_milestone_id`) so it links on the
-  next sync. Match the phase file by its title.
+1. **Milestones create** → create each in Linear; for each, stamp the returned id
+   into its phase file: the `ref` is the phase-file basename.
+2. **Issues create** → create each (link to its milestone by `milestoneRef`,
+   resolving a `create` ref to the id just minted); stamp the returned identifier
+   back onto the matching task line (`ref` is the task's text).
+3. **Milestones/issues update** → save by `id`.
+4. **Project** → set description + status (map `status` — the local bucket — to
+   the Linear project-status name via `config.states`). Priority, labels, cycles
+   and comments are Linear-native triage — do **not** push them; they're the PM's.
 
-Progress is Linear-derived — never push it.
+Map the local status bucket to Linear's project status through `config.states`
+(e.g. `complete → Completed`).
 
-**Issues (`issuesPush` in the result).** When tasks are keyed:
+## 5. Record the snapshot
+
+After everything applied and the ids are stamped into the files:
+
+```
+skitterspec spec-sync record <spec>
+```
 
-- `update`: for each `{ id, text, done }`, call the issue-save tool with that `id`
-  (text → title; `done` → a completed state, else a non-completed state — leave an
-  already-non-completed issue's exact state untouched).
-- `create`: for each `{ text, done }`, create an issue under the project (attach it
-  to the milestone of the phase the task lives in when known), then **stamp the new
-  issue identifier inline** on that task line (`… (SKI-123)`), matching by text.
+This writes the last-pushed snapshot from the now-stamped files, so the next
+`/spec-push` produces an empty plan. Commit the stamped spec + snapshot into the
+branch so the mirror-link rides in the PR.
 
-## 5. Report
+## 6. Report
 
-Relay the git-like summary (written / skipped / backup / base) plus which Linear
-fields you updated.
+Summarise what was created/updated in Linear and confirm the snapshot was
+recorded. There is no pull — Linear is a generated mirror.

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

@@ -1,46 +1,51 @@
 ---
 name: spec-status
-description: Show a spec's sync status against its linked Linear project — a read-only, git-status-style per-field divergence (local-only / remote-only / conflict / in-sync). Fetches the Linear project over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what's diverged from Linear", or "show spec sync status".
+description: Show a spec's one-way sync status against Linear — a read-only drift report. Reports whether the spec changed since the last push (there's something to push) and, optionally, whether Linear's workflow-state differs from the spec's. Fetches the Linear project over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
 ---
 
-# /spec-status — show a spec's divergence from Linear
+# /spec-status — one-way sync drift report
 
-Read-only. Prints, per field, whether the spec and its linked Linear project have
-diverged since the last sync — the `git status` of the hybrid sync. Writes
-nothing to either side.
+Read-only. Reports two things and writes nothing:
 
-This skill is **opt-in**: it only runs when `specs/.core/linear.config.json`
-exists. If it's absent, tell the user to copy `linear.config.json.example` →
-`linear.config.json` to enable Linear sync, and stop.
+1. **Pending push** — has the spec changed since the last push (are there
+   milestones/issues/description to create or update)?
+2. **State drift** — does Linear's project workflow-state differ from the spec's
+   status? (The repo wins on the next push; this is just a heads-up, e.g. a card
+   moved in Linear.)
+
+The repo is the source of truth; Linear is a generated mirror, so there is no
+per-field "conflict" — only "what would the next push send" and "did the mirror
+drift".
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync and stop.
 
 ## 1. Identify the target spec
 
-Use the spec named as an argument, else the spec **currently in context**. If
-neither is clear, ask which spec.
+Use the argument, else the spec in context; ask if unclear.
+
+## 2. Fetch the Linear project (optional, for drift)
 
-## 2. Fetch the Linear project (read-only)
+If the spec has a `linear_project_id`, discover the Linear MCP read tool and write
+the project JSON to a temp file — this lets the report compare workflow-state. If
+Linear isn't connected, skip the drift line (still report pending-push).
 
-- Read the spec's `linear_project_id` from `00-overview.md` frontmatter. If it's
-  missing, the spec isn't linked yet — say so and stop (link it via `/spec`).
-- Discover the connected Linear MCP tools at runtime (the project-read tool). If
-  Linear isn't connected, relay "connect the `linear` MCP server" and stop — do
-  nothing else.
-- Call the project-read tool for that id and write the returned JSON to a temp
-  file (e.g. under the OS temp dir).
+Optionally fetch the workspace project-status names to a file to validate the
+configured `states` at the same time.
 
 ## 3. Run the engine
 
 ```
-skitterspec spec-sync status <spec> --remote <tempfile>
+skitterspec spec-sync status <spec> [--remote <projectfile>] [--workspace-states <statesfile>]
 ```
 
-The engine does the three-way compare (local vs Linear vs the committed base) and
-prints each diverged field with its classification and sync direction. Without
-`--remote` it falls back to a local-vs-base comparison (still read-only).
+- Reports `push: pending — N to create, M to update` or `up to date`.
+- With `--remote`, adds a `drift:` line comparing Linear's workflow-state to the
+  spec's status.
+- With `--workspace-states`, fails loudly if a configured state name isn't in the
+  workspace (Linear would silently no-op it).
 
 ## 4. Report
 
-Relay the engine's summary verbatim, then offer the natural next step:
-`/spec-pull` for remote-only changes, `/spec-push` for local-only, and — for a
-`conflict` — resolve locally or use `--force` (which backs up the losing side).
-Never write anything from this skill.
+Relay the engine's output verbatim. Suggest `/spec-push` if a push is pending.
+Never write to either side.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "7.0.2",
-  "description": "Spec-driven development for Claude Code, with Linear hybrid-sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus git-like /spec-status · /spec-pull · /spec-push and the spec-sync CLI. Install this OR the base, not both.",
+  "version": "8.0.1",
+  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",
     "claude-code",

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')