@skitterbyte/skitterspec-linear 10.3.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)
   },
@@ -189,6 +190,59 @@ instead:
 
 ```bash
 export LINEAR_API_KEY=lin_api_…      # from Linear → Settings → Security & access
+
+Or store it once, for every repo on the machine, instead of exporting it in each:
+
+```
+skitterspec spec-sync credentials set        # prompts; input is hidden
+skitterspec spec-sync credentials status     # readiness only, never the value
+skitterspec spec-sync credentials unset      # remove this team's key
+```
+
+That writes `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else
+`~/.config/…`) at mode `600`, keyed by team id. Resolution order is **environment
+variable first, then the store**, so CI is unaffected. A store readable by other
+users is refused with the `chmod` to run rather than used.
+
+`set` reads the key from a hidden prompt, or from a pipe with `--stdin`. There is
+deliberately **no `--key <value>` flag**: a secret in the command line is visible
+in shell history and to `ps`. For the same reason, run `set` yourself — never
+paste a key into an assistant conversation, where it would enter the transcript.
+`status` exists so an assistant can confirm readiness without ever seeing the
+key.
+
+### Delegating to a password manager
+
+Rather than storing the key at all, record a **command** that prints it. A
+command is not a secret, so unlike `--key` it is safe as an argument:
+
+```
+# 1Password CLI
+skitterspec spec-sync credentials set --command 'op read op://Private/linear/token'
+
+# pass
+skitterspec spec-sync credentials set --command 'pass show linear/api-key'
+
+# macOS Keychain (add once: security add-generic-password -s skitterspec -a linear -w)
+skitterspec spec-sync credentials set --command 'security find-generic-password -w -s skitterspec -a linear'
+```
+
+The command runs on each resolution; its stdout, trimmed, is the key. A non-zero
+exit or empty output means "no key", which simply falls back to MCP — with the
+reason shown by `credentials status`, so a broken command is never silently
+inert. It has 60 seconds to complete, enough for a biometric or master-password
+prompt. Recording a command replaces any stored key for that team, so the
+command actually runs.
+
+A command with a key written into it (`--command 'echo lin_api_…'`) is
+**refused**: commands are displayed by `status` and stored in clear, so that is
+strictly worse than storing the key. Use `credentials set` for a key.
+
+> **`keyCommand` is honoured only from the user-level store — never from
+> `specs/.core/linear.config.json`.** That file is committed and travels with the
+> repo, so a command named there would run on the machine of anyone who cloned it
+> and ran `spec-sync`. If one is found there it is ignored, and `credentials
+> status` says so.
 ```
 
 ```json
@@ -430,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,14 +159,45 @@ 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.
 
+**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
+```
+
+**Do not ask the user to paste an API key into this conversation, and do not
+offer to store one for them.** A key pasted into a chat enters the transcript,
+is sent to the model, and may be logged — moving where a key is stored is
+pointless if it travels through the conversation to get there. Your job is to
+confirm the setup is ready and name the command; the value is theirs alone. The
+key is optional: without one, pushes go over MCP.
+
 Mention what setup did **not** configure, so the defaults aren't mistaken for
-decisions: phase mapping (`mapping.phases` — sub-issue per phase by default),
-field ownership, and the API key (`LINEAR_API_KEY`, which makes pushes take the
-fast path and never lives in the config). Point at `linear.config.md` for those.
+decisions: phase mapping (`mapping.phases` — sub-issue per phase by default) and
+field ownership. Point at `linear.config.md` for those.

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

@@ -0,0 +1,167 @@
+---
+name: spec-sync
+description: Run the repo-wide spec-sync operations against Linear — what's linked, the workspace's states and projects, read-back verification, manual stamping, and bulk `apply --all <bucket>`. Run it bare for the repo-wide overview. Wraps the `spec-sync` CLI, which is a local devDependency and never on PATH, so this skill always states the full invocation. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Linear", "which states does the workspace have", or "mirror the whole backlog".
+---
+
+# /spec-sync — the repo-wide Linear sync operations
+
+`/spec-push` and `/spec-status` cover **one spec**. This skill covers everything
+**repo-wide**, and is the answer to a bare "run spec-sync" — which is not itself
+a command.
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync and stop.
+
+## The invocation — always state it
+
+`spec-sync` is a subcommand of a binary that is a **local devDependency**, so it
+is never on `PATH`. Typing `spec-sync` gives `command not found`, which reads as
+a broken install rather than a wrong invocation. Always run it — and always show
+the user you ran it — in full:
+
+```
+pnpm exec skitterspec-linear spec-sync <subcommand> [args]
+```
+
+In a project that installs the Linear superset the binary is
+`skitterspec-linear` (it also answers to `skitterspec`). Never print a bare
+`spec-sync …` as if the user could type it.
+
+## 1. Route the ask
+
+| The user asks | Run |
+|---------------|-----|
+| bare `/spec-sync`, "what's linked?", "how much is mirrored?" | `linked` |
+| "what states / projects does the workspace have?" | `states`, `projects` |
+| "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?" | `retarget` |
+| push one spec, or "what would push?" | **defer** — see below |
+
+**With no argument, run `linked`.** It is the repo-wide overview, it is
+read-only, and it is what a bare "run spec-sync" means.
+
+**When the ask is genuinely ambiguous between a read and a write — ask.**
+"Sync the backlog" could mean `linked` (show me) or `apply --all backlog`
+(write dozens of issues). Never resolve that guess in favour of the write.
+
+## 2. Defer, don't duplicate
+
+Two front doors to one write path is worse than none:
+
+- **Push one spec** → `/spec-push`. It owns the transport choice, the
+  workspace-state gate, the plan, the apply, the stamping and the snapshot.
+- **Per-spec drift** ("is this spec in sync?", "what would push?") →
+  `/spec-status`.
+
+Say which skill you're handing to and stop; don't reimplement either.
+
+## 3. The read-only subcommands
+
+```
+pnpm exec skitterspec-linear spec-sync linked [--json]
+pnpm exec skitterspec-linear spec-sync states [--via api|mcp] [--json]
+pnpm exec skitterspec-linear spec-sync projects [--via api|mcp] [--json]
+```
+
+- **`linked`** is offline: which specs carry a `linear_identifier`, their bucket,
+  and an `N/M linked` total. Relay it, and when specs in `in-progress` have no
+  issue, say so — those are the ones a push would mint.
+- **`states` / `projects`** reach the workspace. `states` also reports the
+  **transport** (`api` when a key is set, else `mcp`), which is the honest way to
+  answer "how is this talking to Linear?".
+
+## 4. `verify` — check what the tracker actually stored
+
+```
+pnpm exec skitterspec-linear spec-sync verify <spec> --stored <file>
+```
+
+`--stored` is **what Linear currently holds**, read back over MCP:
+
+```json
+{ "issue": "…", "subIssues": { "01-engine": "…" } }
+```
+
+**It is not a `linear-base/*.base.json` snapshot.** That file holds content
+*hashes* keyed by identifier; comparing one against a description reports
+enormous losses on a perfectly intact mirror. The engine refuses a snapshot
+outright — if you see that refusal, you passed the wrong file, not found a bug.
+
+Warns, never fails. The repo is the source of truth; a mangled mirror is fixed
+by pushing again.
+
+## 5. `stamp` — the manual escape hatch
+
+```
+pnpm exec skitterspec-linear spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]
+```
+
+Writes the ids into the spec's frontmatter without touching Linear. For adopting
+an issue created by hand, or repairing a stamp — not the normal path, which is
+`/spec-push`. A wrong id here makes the next push see an **unlinked** spec and
+mint a duplicate, so read the values back to the user before writing.
+
+## 6. `apply --all <bucket>` — bulk, and the one with real blast radius
+
+```
+pnpm exec skitterspec-linear spec-sync apply --all <bucket> [--via api|mcp] [--json]
+```
+
+**Confirm before running, and state creates and updates separately.** They are
+not the same risk:
+
+- an **update** refreshes a mirror that already exists;
+- a **create** mints new issues and sub-issues in someone's shared tracker.
+
+A repo adopting Linear reports "N to create" for every unlinked spec, so an
+unconsidered `--all` can mint dozens of sub-issues. Get the counts first — run
+`linked` to see what is unlinked, or `spec-sync push <spec>` per spec for exact
+numbers — then show the user something like:
+
+```
+apply --all backlog would:
+  create  12 issue(s) + 34 sub-issue(s)   ← new objects in Linear
+  update   3 issue(s) +  5 sub-issue(s)   ← refresh existing mirrors
+```
+
+Only run it on an explicit yes. It is resumable: every id is stamped the moment
+its object exists, so an interrupted run continues rather than duplicating.
+
+`--all` refuses over MCP by design — bulk goes through the API path.
+
+## 7. `retarget` — after a Linear team is renamed
+
+```
+pnpm exec skitterspec-linear spec-sync retarget [--yes]
+```
+
+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
+
+Relay the engine's output. Name the subcommand you ran, in full, so the user can
+re-run it themselves. For anything that wrote, say what changed in Linear and
+that the repo is unchanged — it is the source of truth either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.3.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
@@ -562,11 +567,21 @@ function printReport(dir, mode, { diff = false } = {}) {
   // ships none. Discovering it from what was actually installed keeps this file
   // tracker-free — it never has to know which tracker (if any) is in the box.
   const setupSkill = SKILLS.find((s) => /^spec-.+-setup$/.test(s))
-  const trackerNote = setupSkill
-    ? `Tracker sync is opt-in: run /${setupSkill} to configure it` +
-      ' (it discovers your workspace and writes the config), or see' +
-      ' specs/.core/SETUP.md.\n'
-    : ''
+  const provider = setupSkill ? /^spec-(.+)-setup$/.exec(setupSkill)[1] : null
+  // …and the same derivation gives the provider's config filename, so this can
+  // report tracker sync the way it reports isolation above — from what is
+  // actually on disk. It used to say "opt-in: run /…-setup" even on a repo that
+  // had already configured it, telling you to set up what was already set up.
+  const trackerOn =
+    provider && fs.existsSync(path.join(dir, 'specs', '.core', `${provider}.config.json`))
+  const trackerNote = !setupSkill
+    ? ''
+    : trackerOn
+      ? `Tracker sync is ON: ${provider} — the repo stays the source of truth;` +
+        ' /spec-push mirrors a spec up and /spec-status reports drift.\n'
+      : `Tracker sync is opt-in: run /${setupSkill} to configure it` +
+        ' (it discovers your workspace and writes the config), or see' +
+        ' specs/.core/SETUP.md.\n'
   process.stdout.write(
     '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
       ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +

package/src/vendor/linear/api.js

@@ -29,27 +29,69 @@ const ENDPOINT = 'https://api.linear.app/graphql'
 const MAX_RETRIES = 5
 const MAX_BACKOFF_MS = 60_000
 
+const { storePath, readStore, resolveTeamKey } = require('./credentials.js')
+
 /**
- * Resolve the personal API key from the environment.
+ * Resolve the personal API key, environment first.
+ *
+ * Order — first hit wins:
+ *   1. `process.env[auth.keyEnv]`  (default LINEAR_API_KEY) — CI and every
+ *      existing setup, so this path is unchanged.
+ *   2. the user-level credentials store, keyed by `linear.teamId`.
  *
- * Returns `{ ok: true, key, envVar }`, or `{ ok: false, envVar, error }` when
- * unset — a value the caller branches on rather than an exception, because "no
- * key" is a normal state that means "use MCP", not a failure.
+ * Returns `{ ok: true, key, envVar, source }` where `source` is `'env'` or
+ * `'store'`, or `{ ok: false, envVar, error }` when nothing is set — a value the
+ * caller branches on rather than an exception, because "no key" is a normal
+ * state that means "use MCP", not a failure. A store that exists but is
+ * unreadable or world-readable is reported in `error`; it never silently
+ * degrades to "no key", or the leak would be invisible.
  *
  * The key is never part of the returned error, and callers must keep it out of
  * logs, plans, snapshots and stamped frontmatter.
  */
-function resolveApiKey(config, env = process.env) {
+function resolveApiKey(config, env = process.env, deps = {}) {
   const envVar = (config && config.auth && config.auth.keyEnv) || DEFAULT_KEY_ENV
-  const key = env[envVar]
-  if (typeof key !== 'string' || !key.trim()) {
+  const fromEnv = env[envVar]
+  if (typeof fromEnv === 'string' && fromEnv.trim()) {
+    return { ok: true, key: fromEnv.trim(), envVar, source: 'env' }
+  }
+
+  // The store is keyed by team, so with no teamId there is nothing to look up —
+  // skip the read entirely. That also keeps callers with no Linear config (and
+  // every unit test using the defaults) off the real filesystem.
+  const teamId = config && config.linear && config.linear.teamId
+  if (!teamId) {
     return {
       ok: false,
       envVar,
       error: `no Linear API key — set ${envVar}, or apply the plan over MCP with --via mcp`,
     }
   }
-  return { ok: true, key: key.trim(), envVar }
+
+  const file = (deps.storePath || storePath)(env)
+  const result = (deps.readStore || readStore)(file)
+  let commandReason = ''
+  if (result.ok) {
+    const found = (deps.resolveTeamKey || resolveTeamKey)(result.store, teamId, deps)
+    if (found.key) {
+      return { ok: true, key: found.key, envVar, source: found.source, command: found.command, path: file }
+    }
+    // A keyCommand that exists but did not produce a key is a real problem —
+    // surfacing it is the difference between "fix your command" and silence.
+    if (found.reason) commandReason = `\n  ${found.reason}`
+  }
+
+  // A store that is present but unusable is a distinct, reportable problem —
+  // don't let a permissions refusal read as "you never set a key".
+  const detail = (result.ok || result.code === 'absent' ? '' : `\n  ${result.reason}`) + commandReason
+  return {
+    ok: false,
+    envVar,
+    path: file,
+    error:
+      `no Linear API key — set ${envVar}, run \`skitterspec spec-sync credentials set\` ` +
+      `to store one in ${file}, or apply the plan over MCP with --via mcp${detail}`,
+  }
 }
 
 // Fields we read back on every write. `identifier` and `url` are what the skill
@@ -192,6 +234,18 @@ 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 `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
+    // teamId is stable across a rename; the key is not.
+    //
+    // API-only, like `listIssueStates` — see the operation-contract test: the
+    // API adapter may add ops, it may only never be missing one.
+    async readTeam(teamId) {
+      const data = await call(`query($id: String!) { team(id: $id) { id key name } }`, { id: teamId })
+      return (data && data.team) || null
+    },
     // 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) {