@skitterbyte/skitterspec-linear 10.4.0 → 10.5.0

package/assets/core/SETUP.md

@@ -237,7 +237,19 @@ the repo.
 
 ## 8. Smoke test (verify your setup)
 
-With a linked spec, confirm push end-to-end:
+**Start here — one command answers "did it work?":**
+
+```
+skitterspec spec-sync doctor              # every layer, offline
+skitterspec spec-sync doctor --check-remote   # …and prove the key reaches Linear
+```
+
+It reports the scaffold, per-spec isolation, the tracker config and the API key
+in one table, and every row that needs attention names the command that fixes
+it. It exits non-zero only when something is **broken** (configured but wrong) —
+a `missing` row is an opt-in you have not taken, which is fine.
+
+Then, with a linked spec, confirm push end-to-end:
 
 1. `/spec-status` → shows what would push (`pending — N to create, M to update`).
 2. `/spec-push` → creates the spec issue and its phase sub-issues and sets the

package/assets/core/linear.config.md

@@ -29,7 +29,8 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   // IDs are read by the MCP adapter; leave blank until you connect the `linear`
   // MCP server.
   "linear": {
-    "teamKey": "",        // human-facing key, e.g. "ENG" (optional)
+    "teamKey": "",        // human-facing key, e.g. "ENG" — the RECORDED key;
+                          // see "Renaming a team" below (optional)
     "teamId": "",         // Linear team UUID (the issue's team)
     "projectId": ""       // DEFAULT for the project picker (see below)
   },
@@ -483,3 +484,28 @@ Linear-native triage and are never touched. No base merge, no conflicts, no
   last-pushed snapshot is content hashes of the last push, so `/spec-push` knows
   what changed without reading Linear back; each worktree carries its own, so it
   must travel with the branch.
+
+## Renaming a team
+
+Renaming a Linear team rewrites the key in every issue identifier (`ENG-7` →
+`PLT-7`). The repo stamps identifiers in three places — spec frontmatter, the
+`linear-base` snapshot filenames, and the `subIssues` keys inside them — and
+nothing moves them, so afterwards `/spec-push` fails with
+`no Linear issue found for ENG-7`.
+
+```
+skitterspec spec-sync retarget          # what would change
+skitterspec spec-sync retarget --yes    # apply it
+```
+
+`teamId` survives a rename, so the command asks Linear for that team's *current*
+key and compares it with `teamKey` — which is why `teamKey` is worth setting even
+though nothing else reads it. With `teamKey` empty it falls back to the prefix
+observed in the stamps, and refuses if those disagree rather than guessing.
+
+Before reporting a plan as safe it resolves one remapped identifier and compares
+its **title** to the spec's: a team rename preserves issue numbers, and this is
+what proves it did. `--yes` refuses on a dirty tree so the rewrite lands as one
+revertable change, and it rewrites machine-read fields only — identifiers in
+spec prose are the historical record and are left alone. It pushes nothing; the
+next ordinary `/spec-push` reconciles content once its issues resolve again.

package/assets/rules/negative-checks.md

@@ -0,0 +1,69 @@
+# Checks That Accuse
+
+A check **accuses** when being wrong costs something: it deletes, it exits
+non-zero, or it tells the user their code is broken. Those checks earn the four
+rules below. An ordinary conditional does not — this is about the ones that act
+on what they conclude.
+
+Almost every accusation begins as an **absence**: a name not in a list, a
+directory not on disk, a version not in a response. An absence is evidence only
+once you have established that the lookup could have seen the thing. Three
+times in one day, in unrelated code, we established nothing and acted anyway:
+
+| Absence observed | Concluded | What had blinded the lookup |
+|------------------|-----------|-----------------------------|
+| ref not in the issue list | "it does not exist" | the query excluded archived issues, and capped at 250 |
+| version not in the registry's list | "the publish failed" | the registry is eventually consistent |
+| lifecycle folder not on disk | "half-installed" | git does not store an empty directory |
+
+The bills: 146 healthy refs accused, a valid release tag deleted, a non-zero
+exit on a healthy repo. Each blind spot was knowable in advance.
+
+## 1. Prefer a positive signal to an absence
+
+Assert something that must be **present**, not something that must not be
+missing. A positive signal fails loudly when you are wrong about it; an absence
+fails silently whenever the lookup was narrower than you assumed.
+
+The scaffold check above stopped asking "is the lifecycle folder there?" — a
+folder git drops as soon as it empties — and started asking whether the config
+folder the installer always writes into is there. Same intent, and the new
+question has an answer.
+
+Where no positive signal exists, widen the lookup until absence means
+something (include the archived rows, ask the API for the one id rather than
+scanning a page) — or do not conclude.
+
+## 2. Name the blind spot beside the check
+
+A comment naming what could make this lookup lie is what makes the next reader
+check it. Not what the code does — what would fool it:
+
+```js
+// A LIFECYCLE FOLDER IS NOT CHECKED, deliberately. git does not track empty
+// directories, so it disappears whenever the bucket empties and returns the
+// moment something lands in it.
+```
+
+Write it when you write the check, while you still know why it is safe.
+
+## 3. Pair every accusation with a stays-silent test
+
+For each accusing check, a test that feeds it a **healthy but unusual** input
+and asserts it says nothing: the empty bucket, the archived record, the
+just-published version, the file the user edited on purpose. The positive test
+proves the check can fire; only this one proves it does not fire at everyone
+else. All three incidents would have been caught by it, and prose alone had
+already failed to prevent them.
+
+## 4. Bias the unknown case toward inaction
+
+Three states, not two: yes, no, and *cannot tell*. Route the third to the
+harmless branch — skip, warn, keep, retry — never to the destructive one.
+
+The install manifest classifies a file whose hash it does not recognise as
+`customized` rather than stale, so a resync **keeps** it (`managedState`,
+`packages/common/src/init.js`). An unrecognised hash could mean a user's edit or
+a lost manifest; only one of those readings is safe to act on, so it takes that
+one. Being wrong there costs a redundant file on disk. The opposite default
+costs the user their work.

package/assets/skills/spec-linear-setup/SKILL.md

@@ -159,22 +159,33 @@ paraphrase it into "done".
 
 ## 8. Report and hand off
 
-Confirm the file written and what it says, then name the next step:
+**Finish by checking, not by describing.** Run:
+
+```
+skitterspec spec-sync doctor
+```
+
+and relay its table. That is the difference between a summary of what setup
+*meant* to do and a check of what is actually true — including the layers this
+skill never touched (the scaffold, isolation) and the one it deliberately does
+not set (the key). Every row that needs attention names its own fix, so there is
+nothing to paraphrase.
+
+It exits non-zero only when a layer is **broken** — configured but wrong. A
+`missing` row is an opt-in nobody took, which is fine; report it, don't treat it
+as a failure.
+
+Then name the next step:
 
 - `/spec` — write a spec; with Linear configured it offers the project picker,
   creates the linked issue and stamps the id.
 - `/spec-status` — read-only drift report, the safe way to prove the link works.
 - `/spec-push` — send a spec up.
 
-Then **check the API key, but never ask for it.** Run:
-
-```
-skitterspec spec-sync credentials status
-```
-
-It reports whether a key is set and where from, and never prints the value. If
-it says `key: not set`, tell the user to run this **themselves, in their own
-terminal**:
+**Never ask for the API key.** `doctor`'s `key` row already reports whether one
+is set and where from, masked — `spec-sync credentials status` says the same in
+more detail if you need it. If the key is missing, tell the user to run this
+**themselves, in their own terminal**:
 
 ```
 skitterspec spec-sync credentials set

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

@@ -46,6 +46,24 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
 - With `--workspace-states`, fails loudly if a configured state name isn't in the
   workspace (Linear would silently no-op it).
 
+## 3b. A key mismatch is a different problem
+
+If the spec's `linear_identifier` carries a **different team key** than
+`linear.teamKey` in `specs/.core/linear.config.json` — or the issue read in step
+2 came back under another key — the team was renamed and the repo's stamps are
+stale. That is not push drift and `/spec-push` cannot fix it: it will fail with
+`no Linear issue found for <old>-<n>`.
+
+Point the user at the CLI and stop:
+
+```
+pnpm exec skitterspec-linear spec-sync retarget
+```
+
+Read-only until `--yes`. Do not attempt the rewrite by hand — the identifiers
+live in frontmatter, snapshot filenames and the keys inside those snapshots, and
+a hand edit misses some (it has, twice).
+
 ## 4. Report
 
 Relay the engine's output verbatim. Suggest `/spec-push` if a push is pending.

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

@@ -36,7 +36,7 @@ In a project that installs the Linear superset the binary is
 | "did the mirror survive the push?" | `verify <spec> --stored <file>` |
 | "link this spec to KEY-1 by hand" | `stamp <spec> --issue KEY-1` |
 | "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
-| "is the team key stale?", "did Linear get renamed?" | `doctor` |
+| "is the team key stale?", "did Linear get renamed?" | `retarget` |
 | push one spec, or "what would push?" | **defer** — see below |
 
 **With no argument, run `linked`.** It is the repo-wide overview, it is
@@ -131,44 +131,34 @@ its object exists, so an interrupted run continues rather than duplicating.
 
 `--all` refuses over MCP by design — bulk goes through the API path.
 
-## 7. `doctor` — identifier drift after a team rename
+## 7. `retarget` — after a Linear team is renamed
 
 ```
-pnpm exec skitterspec-linear spec-sync doctor [--json]
+pnpm exec skitterspec-linear spec-sync retarget [--yes]
 ```
 
-Renaming a Linear team changes every issue's identifier prefix and **nothing in
-the repo moves**: the stamps, the config `teamKey`, and the snapshot filenames
-and their sub-issue keys all keep the old prefix. `doctor` reports that. It is
-read-only and needs the **API transport** — it reads one issue per drifted ref,
-which over MCP would be a model round-trip each.
-
-It reports three things, deliberately separately:
-
-- **drift** — what `--write` would repair: stamps, snapshot filenames and keys,
-  the config key.
-- **mentions** — stale refs in spec *prose* (`(REU-61)` beside a task). Reported,
-  **never rewritten** — say so, so nobody reads a repair as total.
-- **missing** — refs that resolve to no issue under the new key. A different
-  problem; repair leaves them alone.
-
-A `missing` count that looks alarmingly high is worth a second look before you
-relay it as fact — the first hand-run of this check reported 146 of 198 refs as
-non-existent when every one was healthy and merely archived.
-
-**`--write` repairs it — confirm first, and state the counts.** It rewrites the
-config key, the frontmatter stamps, the snapshot filenames and the identifier
-keys inside them, all together. It refuses on a dirty git tree, because the
-repair is one large diff and has to be reviewable (and `git checkout -- .`-able)
-on its own — so commit or stash before offering it.
-
-It exits non-zero when it left anything behind: a ref that resolves to no issue
-is **not** rewritten, because repair fixes what is provably repairable rather
-than inventing a target. Relay that as an unfinished repair, not a success.
-
-After a repair, `spec-sync status` should still read `up to date` — the snapshot
-hashes are content-derived, so only their keys move. If it does not, say so
-rather than pushing over it.
+Renaming a Linear team rewrites the key in every issue identifier, and **nothing
+in the repo moves**: the frontmatter stamps, the config `teamKey`, and the
+snapshot filenames and their sub-issue keys all keep the old prefix, so
+`/spec-push` starts failing with `no Linear issue found for SKI-7`.
+
+`retarget` detects the rename (the team id survives it; the key does not) and
+rewrites those fields. Read-only until `--yes`.
+
+- It **never takes the new key as an argument** — a typo would rewrite every
+  stamp to a key that does not exist.
+- It **spot-checks one identifier by title** before reporting the plan as safe.
+  Existence is not identity: `SKS-7` existing does not make it the issue that was
+  `SKI-7`. A mismatch refuses, and writes nothing.
+- It rewrites **machine-read fields only**. Identifiers in spec prose are the
+  historical record and are left alone — so do not report a retarget as having
+  made the repo free of the old key.
+- `--yes` refuses on a dirty tree, so the rewrite lands as one revertable change.
+  It pushes nothing: only the repo's stamps move, and the next ordinary
+  `/spec-push` reconciles content now that its issues resolve again.
+
+Over MCP the team key is unreadable (`get_team` does not return it), so it says
+so and asks you to confirm the key rather than guessing.
 
 ## 8. Report
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.4.0",
+  "version": "10.5.0",
   "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",

package/src/init.js

@@ -406,6 +406,11 @@ function installClaudeMd(dir, { mode }) {
 
 // True when the repo looks already set up: any managed file present, any spec
 // lifecycle folder, or the CLAUDE.md spec marker (Decision 1 — detect eagerly).
+// Is skitterspec already installed here? Matched on what we ACTUALLY install —
+// our managed files, our lifecycle folders, our CLAUDE.md marker — never on
+// `.claude/` merely existing: someone else's skills are not evidence of ours,
+// and reading them as ours would treat every Claude Code project as a
+// half-finished install.
 function isExistingSetup(dir) {
   if (managedTargets(dir).some((t) => fs.existsSync(t.abs))) return true
   if (SPEC_FOLDERS.some((f) => fs.existsSync(path.join(dir, 'specs', f)))) return true

package/src/vendor/linear/api.js

@@ -234,7 +234,7 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
       if (data && data.team) return (data.team.projects && data.team.projects.nodes) || []
       return (data && data.projects && data.projects.nodes) || []
     },
-    // The team's CURRENT key, which is what `doctor` compares stamped
+    // The team's CURRENT key, which is what `retarget` compares stamped
     // identifiers against. Read from Linear rather than `config.linear.teamKey`
     // on purpose: the config key is itself one of the things that goes stale
     // when a team is renamed, so trusting it would make drift invisible. The