@skitterbyte/skitterspec-linear 10.4.0 → 10.5.2

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)
   },
@@ -402,6 +403,22 @@ issue exists, where it lives is Linear's business: move it between projects and
 A spec that **adopted** an existing issue (see below) skips the picker entirely —
 it was filed somewhere deliberately.
 
+`skitterspec spec-sync doctor` reports what this setting is doing:
+
+| `linear.projectId` | Row | Meaning |
+|--------------------|-----|---------|
+| unset | `missing` | specs file to the team, and the picker asks each push — a supported choice, and it never fails the run |
+| set | `ok` | the id is there; add `--check-remote` to resolve it against Linear |
+| set, resolves in the team | `ok` | the project exists and this team is one of its teams |
+| set, resolves elsewhere | `broken` | specs would file out of the team — exits non-zero |
+| set, resolves to nothing | `broken` | a deleted or mistyped id |
+
+`doctor --mcp <file>` additionally compares this id — and the team and workspace —
+against what the Linear **MCP server** reports, so the two transports cannot
+quietly point at different places. A mismatch is `broken` and names both sides; it
+is never resolved by rewriting this file, because which side is wrong is yours to
+say.
+
 ### Known limits — one team per repo, no initiatives
 
 Two things this config deliberately cannot express today. Both are limits, not
@@ -483,3 +500,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

@@ -47,6 +47,11 @@ anything. The interview offers real lists; it never prompts for a raw id.
 | `list_projects` | the projects, per candidate team — names + ids, minus archived/completed |
 | `list_issue_statuses` | the team's **issue workflow-state names**, exactly as spelled |
 | `list_issue_labels` | the label names available for intake routing |
+| `get_workspace` | **which workspace this MCP server is connected to** — id + name |
+
+`get_workspace` is not part of the interview: nothing is asked about it. It is
+recorded so step 8 can prove the MCP server and the API key are pointed at the
+same Linear, which nothing else establishes.
 
 Projects, labels and statuses are all **team-scoped** — fetch them for the team
 once step 3 has settled it, not for the whole workspace up front.
@@ -159,22 +164,55 @@ 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.** First write down what the MCP server
+says, from the reads you already made in step 2 — no extra round trip unless a
+project was chosen and you have not read it yet (`get_project`):
 
-- `/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.
+```json
+{ "workspace": {"id": "…", "name": "…"},
+  "team":      {"id": "…", "key": "SKS"},
+  "project":   {"id": "…", "name": "…"} }
+```
 
-Then **check the API key, but never ask for it.** Run:
+Every key is optional, and **omit what you could not fetch** rather than guessing
+— an absent field is reported as unchecked, while a wrong one is reported as a
+mismatch. Then run:
 
 ```
-skitterspec spec-sync credentials status
+skitterspec spec-sync doctor --mcp <factsfile>
 ```
 
-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**:
+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. An empty `project` row is exactly that: specs file to the team and
+the picker asks each push.
+
+**A `broken` `mcp` row is the one to stop on.** It means the MCP server and the
+config (or the API key) name different workspaces, teams or projects — so where a
+spec lands depends on which transport ran. Relay both sides as the row prints
+them and **stop**: do not rewrite the config to make them agree. Which one is
+correct is the user's to say — the API key may be the wrong one just as easily as
+the config, and picking a winner silently sends their specs somewhere they did
+not choose. Ask which is right, then re-run this skill (or reconnect the MCP
+server) to match it.
+
+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.
+
+**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.2",
   "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
@@ -246,6 +246,36 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
       const data = await call(`query($id: String!) { team(id: $id) { id key name } }`, { id: teamId })
       return (data && data.team) || null
     },
+    // The WORKSPACE this key belongs to. The one fact that says whether the API
+    // transport and the MCP transport are pointed at the same Linear at all —
+    // every other id could match by coincidence across two workspaces, but an
+    // organization id is the workspace.
+    //
+    // API-only, like `readTeam`.
+    async readOrganization() {
+      const data = await call('query { organization { id name urlKey } }')
+      return (data && data.organization) || null
+    },
+    // One project by id, with the teams it belongs to — enough to answer both
+    // halves of the `project` doctor row: does this id resolve at all, and is it
+    // a project of the team this repo files into?
+    //
+    // `teams`, not `team`: a Linear project can span several teams, so belonging
+    // is a membership test. Treating it as a single field would report a healthy
+    // shared project as foreign.
+    //
+    // API-only, like `readTeam` — the adapter may add ops, it may only never be
+    // missing one (see the operation-contract test).
+    async readProject(projectId) {
+      const data = await call(
+        `query($id: String!) { project(id: $id) { id name teams { nodes { id key } } } }`,
+        { id: projectId },
+      )
+      const project = (data && data.project) || null
+      if (!project) return null
+      const teams = (project.teams && project.teams.nodes) || []
+      return { id: project.id, name: project.name, teams }
+    },
     // The workspace's issue workflow states, in the shape `--workspace-states`
     // already accepts, so the existing state check is reused rather than forked.
     async listIssueStates(teamId) {