@skitterbyte/skitterspec-linear 10.5.0 → 10.5.2

package/assets/core/linear.config.md

@@ -403,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

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,10 +164,22 @@ paraphrase it into "done".
 
 ## 8. Report and hand off
 
-**Finish by checking, not by describing.** Run:
+**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`):
+
+```json
+{ "workspace": {"id": "…", "name": "…"},
+  "team":      {"id": "…", "key": "SKS"},
+  "project":   {"id": "…", "name": "…"} }
+```
+
+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 doctor
+skitterspec spec-sync doctor --mcp <factsfile>
 ```
 
 and relay its table. That is the difference between a summary of what setup
@@ -173,7 +190,17 @@ 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.
+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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.5.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/vendor/linear/api.js

@@ -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) {

package/src/vendor/linear/cli-sync.js

@@ -604,6 +604,14 @@ function verifyLines(snapshotDir, config, stored, identifier) {
  */
 async function specSyncDoctor(dir, flags, out) {
   const state = gatherState(dir, flags)
+  if (flags.mcp) {
+    const read = readMcpFacts(flags.mcp)
+    if (read.error) {
+      out.write(`spec-sync doctor: cannot read --mcp ${flags.mcp}: ${read.error}\n`)
+      return 1
+    }
+    state.mcp = read.facts
+  }
   if (flags.remoteCheck) state.remote = await checkRemote(state, flags)
 
   const report = runChecks(state)
@@ -675,7 +683,74 @@ async function checkRemote(state, flags) {
       fix: '/spec-linear-setup',
     }
   }
-  return { checked: true, ok: true, teamKey: team.key, recordedKey: state.tracker.teamKey }
+  // The team resolved, so the key works. Only now is it worth spending further
+  // calls — on the workspace this key belongs to (so the MCP row has an API side
+  // to compare against, and only when there is an MCP side to compare with), and
+  // on the project, when one is configured.
+  let organization = null
+  if (state.mcp && state.mcp.workspace && typeof adapter.readOrganization === 'function') {
+    try {
+      organization = await adapter.readOrganization()
+    } catch {
+      // Unexamined, exactly like the project below: the team read already proved
+      // the key works, so a failure here is not evidence about the config.
+      organization = null
+    }
+  }
+
+
+  let project = null
+  // `readProject` is API-only. An adapter without it cannot answer the question,
+  // and a `TypeError` caught below would be dressed up as Linear refusing the
+  // request — accusing the user's config of a gap that is ours. Unexamined.
+  if (state.project && state.project.configured && typeof adapter.readProject === 'function') {
+    try {
+      const found = await adapter.readProject(state.project.configured)
+      project = found
+        ? {
+            resolved: true,
+            name: found.name,
+            // Membership, not equality: a Linear project can span teams.
+            belongsToTeam: (found.teams || []).some((t) => t && t.id === state.tracker.teamId),
+          }
+        : { resolved: false }
+    } catch (error) {
+      // Same rule as the team read: NEVER ANSWERED is not ANSWERED NO. A
+      // transport failure leaves the project unexamined rather than accused.
+      const failure = classifyRemoteFailure(error)
+      project = failure.reached === false ? null : { resolved: false, reason: failure.reason }
+    }
+  }
+
+  return { checked: true, ok: true, teamKey: team.key, teamId: team.id, organization, recordedKey: state.tracker.teamKey, project }
+}
+
+/**
+ * The MCP server's view of where this repo files, as the calling skill read it.
+ *
+ * The engine never speaks MCP — the same split `--workspace-states` and
+ * `verify --stored` use — so a skill fetches `get_workspace` / `get_team` /
+ * `get_project` and writes them here:
+ *
+ *   { "workspace": {"id","name"}, "team": {"id","key"}, "project": {"id","name"} }
+ *
+ * Every field is optional. A field the skill could not fetch is ABSENT, and
+ * absent means unchecked — never mismatched. That distinction is the whole
+ * safety of the row: it is a comparison, so it can only speak about the pairs it
+ * actually has both halves of.
+ */
+function readMcpFacts(file) {
+  let parsed
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+  } catch (error) {
+    return { error: error.message }
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { error: 'expected an object with workspace / team / project keys' }
+  }
+  const pick = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null)
+  return { facts: { workspace: pick(parsed.workspace), team: pick(parsed.team), project: pick(parsed.project) } }
 }
 
 // Map a thrown API error onto our own short reason. Matched on the shapes
@@ -708,7 +783,7 @@ function classifyRemoteFailure(error) {
 // Read the project's real state for `runChecks`. Never throws: every probe that
 // can fail reports the failure as data.
 function gatherState(dir, flags) {
-  const state = { scaffold: {}, isolation: {}, tracker: {}, key: {}, remote: { checked: false } }
+  const state = { scaffold: {}, isolation: {}, tracker: {}, key: {}, project: {}, remote: { checked: false } }
 
   const specs = path.join(dir, 'specs')
   state.scaffold.specsDir = fs.existsSync(specs)
@@ -739,6 +814,10 @@ function gatherState(dir, flags) {
       state.tracker.parsed = true
       state.tracker.teamId = (config.linear && config.linear.teamId) || ''
       state.tracker.teamKey = (config.linear && config.linear.teamKey) || ''
+      // Offline this is all that can be known: whether a string is there. That a
+      // well-formed id names a LIVE project is only answerable with
+      // --check-remote, which is why the row says what it checked.
+      state.project.configured = (config.linear && config.linear.projectId) || ''
     } catch (error) {
       state.tracker.parsed = false
       state.tracker.error = error.message
@@ -1706,7 +1785,19 @@ async function credentialsSet(file, teamId, label, flags, out) {
 
   let key
   if (flags.stdin) {
-    key = (await readAllStdin(flags.input || process.stdin)).trim()
+    const piped = flags.input || process.stdin
+    // A TTY on stdin is positive evidence that nothing was piped: `--stdin` then
+    // waits for an EOF a terminal never sends, printing nothing while it does.
+    // Refuse and name the two working forms rather than blocking forever.
+    if (piped.isTTY) {
+      out.write(
+        'spec-sync credentials: --stdin expects a pipe, but stdin is a terminal.\n' +
+          '  Run it without --stdin to be prompted (input is hidden), or pipe the key:\n' +
+          '    <command that prints the key> | skitterspec spec-sync credentials set --stdin\n',
+      )
+      return 1
+    }
+    key = (await readAllStdin(piped)).trim()
     if (!key) {
       out.write('spec-sync credentials: nothing on stdin — no key stored.\n')
       return 1
@@ -1778,19 +1869,33 @@ function readAllStdin(input) {
 }
 
 // Prompt on a TTY with the input hidden. `_writeToOutput` is readline's own echo
-// hook — silencing it is what keeps the key off the screen (and out of a
+// hook — filtering it is what keeps the key off the screen (and out of a
 // screen-shared terminal or a recorded session).
+//
+// READLINE OWNS THE PROMPT, deliberately. Writing it ourselves and then starting
+// the interface loses it: readline clears from the cursor to the end of the
+// screen (`ESC[0J`) before its first redraw, so the prompt was wiped the instant
+// it appeared and the user was left staring at a blank line while the process
+// waited for a key — indistinguishable from a hang.
+//
+// The hook is assigned BEFORE `question`, so the very first redraw goes through
+// it. readline hands it `prompt + what has been typed`; re-writing only the
+// prompt is what keeps the key hidden while the prompt survives every redraw.
 function promptHidden(question, input, out) {
   const readline = require('node:readline')
   return new Promise((resolve) => {
-    const rl = readline.createInterface({ input, output: process.stdout, terminal: true })
-    out.write(question)
-    rl.question('', (answer) => {
+    // `out`, never `process.stdout`: they are the same stream in production, and
+    // hardcoding one half meant readline cleared a screen the prompt had not
+    // been written to under test — the split that hid this bug from the suite.
+    const rl = readline.createInterface({ input, output: out, terminal: true })
+    rl._writeToOutput = (s) => {
+      if (s.includes(question)) out.write(question)
+    }
+    rl.question(question, (answer) => {
       out.write('\n')
       rl.close()
       resolve(answer)
     })
-    rl._writeToOutput = () => {}
   })
 }
 
@@ -1805,12 +1910,13 @@ async function specSync(rest, io = {}) {
   // after the loop.
   const unknownFlags = []
   const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null, plan: null, via: null, project: null, all: null,
-    force: false, yes: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
+    mcp: null, force: false, yes: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
     else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
     else if (args[i] === '--stored') flags.stored = path.resolve(args[++i])
+    else if (args[i] === '--mcp') flags.mcp = path.resolve(args[++i])
     else if (args[i] === '--plan') flags.plan = path.resolve(args[++i])
     else if (args[i] === '--via') flags.via = args[++i]
     else if (args[i] === '--all') flags.all = args[++i]
@@ -1880,6 +1986,10 @@ async function specSync(rest, io = {}) {
   flags.env = io.env || process.env
   if (io.adapter) flags.adapter = io.adapter
   if (io.fetch) flags.fetch = io.fetch
+  // The stdin seam. `credentials set` branches on whether stdin is a TTY, and
+  // with no way to inject one the suite could only ever exercise the non-TTY
+  // half — which is how a prompt that erased itself reached a release.
+  if (io.input) flags.input = io.input
 
   // Dispatched ahead of the load on purpose: this is the command you run when
   // there is no config, and `--force` must be able to replace one that is
@@ -1938,7 +2048,7 @@ async function specSync(rest, io = {}) {
         '       skitterspec spec-sync verify <spec> --stored <file>\n' +
         '       skitterspec spec-sync linked [--json]\n' +
         '       skitterspec spec-sync retarget [--yes]\n' +
-        '       skitterspec spec-sync doctor [--check-remote] [--json]\n' +
+        '       skitterspec spec-sync doctor [--check-remote] [--mcp <file>] [--json]\n' +
         '       skitterspec spec-sync init-config --team-id <id> [--team-key K] [--project-id id]\n' +
         '                    [--intake-label L] [--bug-labels a,b] [--hotfix-labels a,b]\n' +
         '                    [--state <bucket>=<name> …] [--states <file>] [--force] [--json]\n')
@@ -1946,4 +2056,4 @@ async function specSync(rest, io = {}) {
   }
 }
 
-module.exports = { specSync, listSpecs }
+module.exports = { specSync, listSpecs, promptHidden }

package/src/vendor/linear/doctor.js

@@ -54,8 +54,10 @@ function runChecks(state = {}) {
     scaffoldCheck(state.scaffold),
     isolationCheck(state.isolation),
     trackerCheck(state.tracker),
+    projectCheck(state.project, state.tracker, state.remote),
     keyCheck(state.key, state.tracker),
     remoteCheck(state.remote),
+    mcpCheck(state.mcp, state.tracker, state.project, state.remote),
   ]
   // `missing` is a declined opt-in, so it must not fail the run. Only a
   // configured-but-wrong layer does.
@@ -123,6 +125,53 @@ function trackerCheck(s = {}) {
 // caller resolves all three before this sees it. `s.error` carries WHY when one
 // of them failed; passing it through is what keeps a broken keyCommand from
 // being reported as a key the user never set.
+// Where specs get filed. `projectId` is the picker's DEFAULT, not a mandate
+// (`config.js`), so an unset one is a declined opt-in and NEVER fails the run —
+// filing to the team and choosing a project each push is a supported way to work.
+//
+// BLIND SPOT: offline this can only see that a string is present. A well-formed
+// id naming a deleted project, or one belonging to another team, reads `ok`
+// until `--check-remote` resolves it — so the detail says which of the two was
+// actually established rather than implying the stronger one.
+function projectCheck(s = {}, tracker = {}, remote = {}) {
+  if (!tracker.present) return row('project', 'project', 'skipped', 'no tracker configured')
+  if (!s.configured) {
+    return row(
+      'project',
+      'project',
+      'missing',
+      'no linear.projectId — specs file to the team, and the picker asks each push',
+      '/spec-linear-setup',
+    )
+  }
+
+  const found = remote && remote.project
+  // Configured but unexamined — either --check-remote was not passed, or it was
+  // and Linear never answered. Both are "we did not look", not "it is wrong".
+  if (!found) {
+    return row('project', 'project', 'ok', `${s.configured} — configured, not checked against Linear`)
+  }
+  if (!found.resolved) {
+    return row(
+      'project',
+      'project',
+      'broken',
+      found.reason || `linear.projectId ${s.configured} does not resolve in this workspace`,
+      '/spec-linear-setup',
+    )
+  }
+  if (!found.belongsToTeam) {
+    return row(
+      'project',
+      'project',
+      'broken',
+      `"${found.name}" is not a project of team ${tracker.teamKey || tracker.teamId} — specs would file out of the team`,
+      '/spec-linear-setup',
+    )
+  }
+  return row('project', 'project', 'ok', `"${found.name}" (${s.configured}) in team ${tracker.teamKey || tracker.teamId}`)
+}
+
 function keyCheck(s = {}, tracker = {}) {
   // Without a tracker there is nothing for a key to authenticate, so asking for
   // one would be noise.
@@ -176,4 +225,65 @@ function remoteCheck(s = {}) {
   return row('remote', 'remote', 'ok', `team ${s.teamKey} resolves, key accepted`)
 }
 
+/**
+ * Do the two transports point at the same place?
+ *
+ * A repo reaches Linear over the API or over MCP, chosen per invocation, and
+ * they are configured independently: the API key belongs to whatever workspace
+ * issued it, the MCP server to whatever workspace it was connected to. Nothing
+ * made them agree, so the destination could depend on which transport ran.
+ *
+ * `s` is what a skill read over MCP (see `readMcpFacts`). Three sources are
+ * compared — the repo's config, the API key's workspace, and the MCP server's —
+ * and a disagreement is `broken` because writes would land in the wrong place.
+ *
+ * IDS, NEVER NAMES: a renamed workspace, team or project keeps its id, and
+ * `retarget` exists precisely because a team KEY is not identity.
+ *
+ * BLIND SPOT: the file is a snapshot the skill took, so `ok` means the sources
+ * agreed WHEN IT WAS FETCHED. And a field the skill could not fetch is absent —
+ * absence is unchecked, so it never produces `broken`. The row can only speak
+ * about pairs it holds both halves of, which is why it names them.
+ */
+function mcpCheck(s, tracker = {}, project = {}, remote = {}) {
+  if (!s) {
+    return row('mcp', 'mcp', 'skipped', 'pass --mcp <file> to check the MCP server points at the same place')
+  }
+
+  const apiOrg = remote && remote.organization
+  const pairs = [
+    ['workspace', s.workspace && s.workspace.id, apiOrg && apiOrg.id, s.workspace && s.workspace.name, apiOrg && apiOrg.name, "the API key's workspace"],
+    ['team', s.team && s.team.id, tracker.teamId, s.team && s.team.key, tracker.teamKey, 'the config'],
+    ['project', s.project && s.project.id, project && project.configured, s.project && s.project.name, null, 'the config'],
+  ]
+
+  const checked = []
+  for (const [what, mcpId, otherId, mcpName, otherName, whose] of pairs) {
+    // Both halves, or nothing to compare. An absent id is a question nobody
+    // asked, not an answer of "no".
+    if (!mcpId || !otherId) continue
+    checked.push(what)
+    if (mcpId !== otherId) {
+      return row(
+        'mcp',
+        'mcp',
+        'broken',
+        `${what} mismatch — the MCP server says ${describe(mcpName, mcpId)}, ${whose} says ` +
+          `${describe(otherName, otherId)}; writes land wherever the transport does`,
+        '/spec-linear-setup',
+      )
+    }
+  }
+
+  if (!checked.length) {
+    return row('mcp', 'mcp', 'skipped', 'the --mcp file names nothing that can be compared yet')
+  }
+  const where = (s.workspace && s.workspace.name) || (s.team && s.team.key) || 'the same place'
+  return row('mcp', 'mcp', 'ok', `${where} — ${checked.join(', ')} agree across both transports`)
+}
+
+// `Name (id)` when a name is known, the bare id otherwise — the id is what was
+// compared, so it is always shown.
+const describe = (name, id) => (name ? `"${name}" (${id})` : String(id))
+
 module.exports = { runChecks, STATES }