@skitterbyte/skitterspec-linear 10.5.0 → 10.6.0

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/rules/commit-trailers.md

@@ -0,0 +1,52 @@
+# Commit Trailers
+
+Extends `commit-messages.md` — the format, length limits and `Release-Note:`
+grammar there all still apply. This file adds one trailer, and it is only
+installed when a ticketing provider is.
+
+## `Refs:` — the ticket this commit belongs to
+
+A commit made on a spec's branch carries the Linear issue it belongs to, as the
+**last** trailer in the message:
+
+```
+fix(sync): verify no longer flags every update
+
+- Key the apply read-back by ref, resolving id via the projection
+
+Release-Note: Pushing a spec whose phases already exist in Linear no
+longer reports every one of them as a possible stale reference.
+
+Refs: SKS-29
+```
+
+Get the value from the engine rather than reading it off a spec by hand:
+
+```
+pnpm exec skitterspec-linear spec-sync ref
+```
+
+## Rules
+
+- **Omit the trailer entirely when there is no ref.** `spec-sync ref` exits
+  non-zero and prints nothing on a commit that has no ticket — on `main`, or on
+  a spec kept deliberately local. Never invent one, and never write
+  `Refs: none`: the release report counts unreferenced commits, and a fabricated
+  ref is worse than an honest gap.
+- **One ref per commit.** A commit belongs to one spec — the spec whose branch
+  it is on. If work genuinely spans two tickets, that is two commits.
+- **Never use Linear's magic words** — `Fixes`, `Closes`, `Resolves`. Those
+  close the issue the moment the commit reaches the default branch, which is
+  wrong here: a ticket moves when its work is **released**, not when it merges.
+  `Refs:` is deliberately inert to Linear's automation.
+- **Blank line before it**, like `Release-Note:` — it is a git trailer, not body
+  text.
+- Put it **after** `Release-Note:` when both are present, so the human-facing
+  note reads first.
+
+## Why it exists
+
+The repo lands specs with `merge --ff-only`, so history is linear and branch
+names never reach it. The commit message is the only artefact that survives into
+the range a release scans, which is what lets
+`spec-sync released <range>` report the tickets a release contains.

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

@@ -311,6 +311,30 @@ test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
 `00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
 Say so explicitly — don't fake green.
 
+**Then refresh the mirror (only if a provider is installed).** The Fix tasks are
+ticked, so the repo is now the truth about this fix — and this skill can take a
+bug all the way to green without `/spec-go` ever running. Without a provider this
+is a no-op.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this phase's progress, and progress is what the mirror
+exists to show. Deferring it to `/spec-complete` is what makes every phase
+sub-issue jump from Backlog straight to Done, with nothing visible in between.
+
+- **Never mint.** An unlinked spec is skipped, not created.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The phase is done in the repo regardless;
+  the mirror is disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and these skills do not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
 ## 6. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test

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

@@ -139,11 +139,17 @@ Before writing any code for this phase, get the workspace clean:
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
 
-## 3b. Sync with the tracker (only if a provider is installed)
+## 4. Implement the phase
+
+Identify the **first unfinished phase** from the `00-overview.md` phase index,
+then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
+started: set the phase-file heading to `🔄` and its `> **Status:**` to
+`In progress`, and flip the matching row in the overview phase index to `🔄`.
 
-**Only when a ticketing provider is installed** and the spec is linked to the
-tracker. Otherwise skip this step — no provider means zero change to the flow
-below. Follow the provider's steps below (nothing to do here without one).
+**Then sync with the tracker (only if a provider is installed).** The phase has
+just changed state, so refresh the mirror before the build starts — that is what
+makes the phase show as in progress *while* it is being built rather than only
+once it is over. Without a provider this is a no-op and nothing below changes.
 
 **Only when `specs/.core/linear.config.json` exists** and the spec carries a
 `linear_identifier`. Otherwise skip this step — no config means zero change.
@@ -152,26 +158,27 @@ below. Follow the provider's steps below (nothing to do here without one).
   to bring down before building — the repo is already the source of truth. (A
   workflow-state a teammate moved in Linear is advisory only; `/spec-status`
   surfaces it. It is overwritten on the next push.)
-- **Refresh the mirror.** Run `/spec-push` to send the now in-progress spec up.
-  Whether that is optional depends on `mapping.phases`:
-  - `"subissue"` (the default) — **optional**. The phase sub-issues already
-    exist; this push only moves their states. Refresh now or later.
-  - `"deferred"` — **do it now, without asking.** Under deferral a spec sitting
-    in the backlog is mirrored as the issue alone, and this push is what mints
-    its phase sub-issues. Skip it and a started spec stays mirrored as a
-    phase-less issue until someone happens to run `/spec-push` by hand. Run it
-    straight after the step-2 commit, so the sub-issues land with the same
-    branch push that fires the tracker's automation.
+- **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
+  moved to `in-progress` and its phase to `🔄` — both real state changes, and the
+  tracker is a generated mirror of them. This holds under **both**
+  `mapping.phases` modes, for different reasons:
+  - `"subissue"` (the default) — the phase sub-issues already exist, and this
+    push is what moves the current one into its in-progress state. Skip it and
+    every sub-issue sits in Backlog until the spec completes.
+  - `"deferred"` — the sub-issues do not exist yet, and this push is what mints
+    them. Skip it and a started spec stays mirrored as a phase-less issue.
+- **Never mint the spec issue.** An unlinked spec is skipped, not created —
+  `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **carry on with the build**. The repo is correct regardless; the mirror is
+  disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and `/spec-go` does not commit. The next `/commit`
+  sweeps it up with the phase's own work.
 - Linear's GitHub branch/PR automation may drive status transitions off the
   branch/PR you pushed in step 2; that's expected and the repo still wins on the
   next `/spec-push`.
 
-## 4. Implement the phase
-
-Identify the **first unfinished phase** from the `00-overview.md` phase index,
-then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
-started: set the phase-file heading to `🔄` and its `> **Status:**` to
-`In progress`, and flip the matching row in the overview phase index to `🔄`.
 Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
 
 - Work task by task through the phase file. Make focused edits that match
@@ -194,6 +201,29 @@ Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.m
 - If new work surfaced, add it as tasks to the appropriate phase file (or add a
   new phase file + index row) rather than doing it silently.
 
+**Then refresh the mirror (only if a provider is installed).** The phase is done
+in the repo now; leaving the tracker to catch up at `/spec-complete` is what makes
+a mirror lag a whole spec behind. Without a provider this is a no-op.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this phase's progress, and progress is what the mirror
+exists to show. Deferring it to `/spec-complete` is what makes every phase
+sub-issue jump from Backlog straight to Done, with nothing visible in between.
+
+- **Never mint.** An unlinked spec is skipped, not created.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The phase is done in the repo regardless;
+  the mirror is disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and these skills do not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
 ## 6. Report
 
 Summarise what was implemented, the test result (quote failures if any), and

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

@@ -318,6 +318,30 @@ message.
 - Commit the fix to the `hotfix/<slug>` branch (this commit is what gets tagged
   and cherry-picked). Tick the Fix tasks; add a Changelog line.
 
+**Then refresh the mirror (only if a provider is installed).** The Fix tasks are
+ticked, so the repo is now the truth about this fix — and this skill can take a
+bug all the way to green without `/spec-go` ever running. Without a provider this
+is a no-op.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this phase's progress, and progress is what the mirror
+exists to show. Deferring it to `/spec-complete` is what makes every phase
+sub-issue jump from Backlog straight to Done, with nothing visible in between.
+
+- **Never mint.** An unlinked spec is skipped, not created.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The phase is done in the repo regardless;
+  the mirror is disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and these skills do not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
 ## 7. Report
 
 Summarise: the base tag, root cause, the failing→passing test, the fix, and the

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/assets/skills/spec-sync/SKILL.md

@@ -37,6 +37,8 @@ In a project that installs the Linear superset the binary is
 | "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` |
+| "what ticket am I on?", writing a commit | `ref` |
+| "what shipped in this release?" | `released` |
 | push one spec, or "what would push?" | **defer** — see below |
 
 **With no argument, run `linked`.** It is the repo-wide overview, it is
@@ -131,7 +133,29 @@ 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
+## 7. `ref` and `released` — tickets in commits
+
+```
+pnpm exec skitterspec-linear spec-sync ref [--json]
+pnpm exec skitterspec-linear spec-sync released [<range>] [--json]
+```
+
+`ref` prints the ticket for the branch you are on, so a commit can carry
+`Refs: <KEY-N>` — see `.claude/rules/commit-trailers.md`. **Off a spec branch, or
+on a spec that is not linked, it prints nothing and exits non-zero.** That is the
+correct answer, not an error to work around: do not invent a ref, and never write
+`Refs: none`.
+
+`released` reports the tickets in a commit range — by default since the most
+recent tag, and it always prints the range it chose so a wrong default is
+visible. It is **read-only**: it does not move anything in Linear. A release can
+be cut and never deployed, so transitioning tickets stays a deliberate act.
+
+Relay the **unreferenced count** even when it is zero. A chore commit
+legitimately carries no ticket and a *missed* trailer looks identical, so
+omitting the number reads as "everything is accounted for" when it may not be.
+
+## 8. `retarget` — after a Linear team is renamed
 
 ```
 pnpm exec skitterspec-linear spec-sync retarget [--yes]
@@ -160,7 +184,7 @@ rewrites those fields. Read-only until `--yes`.
 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
+## 9. 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

package/package.json

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

@@ -23,7 +23,10 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
-const { BUCKETS, findSpecFolder } = require('../../env/resolve.js')
+const { BUCKETS, findSpecFolder, branchFor, splitPrefix, currentBranch } = require('../../env/resolve.js')
+const { loadEnvConfig } = require('../../env/config.js')
+const { ticketsInRange } = require('./released.js')
+const { execFileSync } = require('node:child_process')
 const {
   normalizeLocal,
   readSnapshot,
@@ -604,6 +607,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 +686,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 +786,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 +817,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
@@ -781,6 +863,176 @@ function countSkills(dir) {
   }
 }
 
+/**
+ * `spec-sync released [<range>] [--json]` — the tickets a release contains.
+ *
+ * Read-only, and deliberately so: it reports what shipped, it does not move
+ * anything. A release can be cut and never deployed, and workflow state is
+ * pushed from a spec's lifecycle bucket — "released" is not one, so moving
+ * tickets here would be a new kind of write with no dry run.
+ *
+ * The default range is the most recent tag reachable from HEAD, resolved with
+ * `git describe` rather than by knowing a tag scheme. This repo tags
+ * `name@version`, but a consumer may tag `v1.2.3` — and the scheme lives in
+ * `scripts/`, which is not shipped. The chosen range is always printed, so a
+ * wrong guess is visible rather than silent.
+ */
+async function specSyncReleased(dir, config, rangeArg, flags, out) {
+  const git = (argv) => {
+    try {
+      return execFileSync('git', ['-C', dir, ...argv], { stdio: ['ignore', 'pipe', 'ignore'] }).toString()
+    } catch {
+      return null
+    }
+  }
+
+  let range = rangeArg
+  if (!range) {
+    const tag = (git(['describe', '--tags', '--abbrev=0']) || '').trim()
+    if (!tag) {
+      out.write(
+        'spec-sync released: no range given and no tag to default from.\n' +
+          '  Pass one explicitly, e.g. spec-sync released v1.2.0..HEAD\n',
+      )
+      return 1
+    }
+    range = `${tag}..HEAD`
+  }
+
+  // NUL-delimited so a subject or body containing the separator cannot split a
+  // record; RS between commits for the same reason.
+  const raw = git(['log', '--format=%H%x00%s%x00%b%x1e', range])
+  if (raw === null) {
+    out.write(`spec-sync released: git could not resolve the range "${range}".\n`)
+    return 1
+  }
+
+  const commits = raw
+    .split('\x1e')
+    .map((r) => r.replace(/^\n/, ''))
+    .filter((r) => r.trim())
+    .map((record) => {
+      const [sha, subject, ...rest] = record.split('\x00')
+      return { sha, subject, body: rest.join('\x00') }
+    })
+
+  const report = ticketsInRange(commits)
+
+  // Titles are an ENRICHMENT: the scan itself is offline. No key, the MCP
+  // transport, or a read failure degrades to bare refs — never a failure.
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+  let titles = null
+  let titleNote = ''
+  if (report.tickets.length && transport === 'api') {
+    const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+    titles = {}
+    for (const t of report.tickets) {
+      try {
+        const issue = await adapter.readIssue(t.ref)
+        if (issue && issue.title) titles[t.ref] = issue.title
+      } catch {
+        titleNote = '  (titles unavailable — Linear could not be read)'
+        titles = null
+        break
+      }
+    }
+  } else if (report.tickets.length) {
+    titleNote = `  (titles unavailable — transport = ${transport})`
+  }
+
+  if (flags.json) {
+    out.write(JSON.stringify({ range, ...report, titles }, null, 2) + '\n')
+    return 0
+  }
+
+  const lines = [`spec-sync released: ${range}`, '']
+  if (!report.tickets.length) lines.push('  no ticket references found')
+  for (const t of report.tickets) {
+    const title = titles && titles[t.ref] ? `  ${titles[t.ref]}` : ''
+    lines.push(`  ${t.ref}${title}`)
+  }
+  if (titleNote) lines.push(titleNote)
+  lines.push('')
+  lines.push(`  ${report.tickets.length} ticket(s) in ${report.total} commit(s)`)
+  // Said even when zero: a chore commit legitimately carries no ticket and a
+  // MISSED trailer looks identical, so silence here would read as "everything is
+  // accounted for".
+  lines.push(`  ${report.unreferenced} commit(s) carry no ref`)
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
+/**
+ * `spec-sync ref [--json]` — the ticket this branch's work belongs to.
+ *
+ * Exists so neither a person nor a model has to go spelunking for the id when
+ * writing a commit: `Refs: $(spec-sync ref)`. With a fast-forward-only history
+ * the commit message is the ONLY place a ticket survives into the range a
+ * release scans — branch names never reach it.
+ *
+ * The branch→spec direction is the INVERSE of what `/spec-go` provisions with,
+ * so it is computed by running `branchFor` over each spec and matching, rather
+ * than by re-deriving the pattern here. A second implementation of the naming
+ * rule would drift from the one that created the branch.
+ *
+ * **Every no-ref case prints nothing on stdout** and exits non-zero. A commit on
+ * `main`, or on a spec kept deliberately local, has no ticket — and a command
+ * that wrote an error message to stdout would see a shell splice it straight
+ * into the commit body via `$(…)`.
+ */
+function specSyncRef(dir, config, flags, out, err) {
+  const say = (msg) => err.write(`spec-sync ref: ${msg}\n`)
+
+  const git = (argv) => {
+    try {
+      return execFileSync('git', ['-C', dir, ...argv], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
+    } catch {
+      return null
+    }
+  }
+  const branch = currentBranch(git)
+  if (!branch) {
+    say('not on a git branch (detached HEAD, or not a git repository)')
+    return 1
+  }
+
+  const env = loadEnvConfig(dir).config
+  let match = null
+  for (const bucket of BUCKETS) {
+    let entries
+    try {
+      entries = fs.readdirSync(path.join(dir, 'specs', bucket), { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const specPath = path.join(dir, 'specs', bucket, entry.name)
+      const { type, slug } = splitPrefix(entry.name)
+      if (branchFor({ type, slug, path: specPath }, env) === branch) {
+        match = { folder: entry.name, bucket, path: specPath }
+        break
+      }
+    }
+    if (match) break
+  }
+
+  if (!match) {
+    say(`branch "${branch}" is not a spec branch — no ticket to reference`)
+    return 1
+  }
+
+  const identifier = linkedIdentifier(path.join(match.path, (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'))
+  if (!identifier) {
+    say(`${match.folder} is not linked to Linear — /spec-push to mirror it`)
+    return 1
+  }
+
+  out.write(flags.json ? JSON.stringify({ ref: identifier, spec: match.folder, branch }, null, 2) + '\n' : `${identifier}\n`)
+  return 0
+}
+
 /**
  * `spec-sync retarget [--yes]` — repoint a mirror after a team-key rename.
  *
@@ -1706,7 +1958,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 +2042,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 +2083,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 +2159,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
@@ -1915,6 +2198,10 @@ async function specSync(rest, io = {}) {
       return (await specSyncProjects(dir, config, flags, out)) || 0
     case 'states':
       return (await specSyncStates(dir, config, flags, out)) || 0
+    case 'released':
+      return (await specSyncReleased(dir, config, positional[0], flags, out)) || 0
+    case 'ref':
+      return specSyncRef(dir, config, flags, out, err) || 0
     case 'retarget':
       return (await specSyncRetarget(dir, config, flags, out)) || 0
     case 'apply':
@@ -1937,8 +2224,10 @@ async function specSync(rest, io = {}) {
         '       skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync verify <spec> --stored <file>\n' +
         '       skitterspec spec-sync linked [--json]\n' +
+        '       skitterspec spec-sync ref [--json]\n' +
+        '       skitterspec spec-sync released [<range>] [--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 +2235,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 }

package/src/vendor/linear/released.js

@@ -0,0 +1,80 @@
+'use strict'
+
+/**
+ * Which tickets a release contains.
+ *
+ * The repo lands specs with `merge --ff-only`, so history is linear and branch
+ * names never reach it. A commit's `Refs:` trailer is therefore the only place
+ * the ticket survives into the range a release scans — see the
+ * `commit-trailers` rule.
+ *
+ * The parsing half is pure and takes commits as data, so the rules below are
+ * testable without git. Reading the range, and enriching refs with issue titles,
+ * belong to the caller.
+ */
+
+// An issue identifier: uppercase team key, dash, number.
+const IDENTIFIER_RE = /\b[A-Z][A-Z0-9]*-\d+\b/g
+// A `Refs:` trailer line. Anchored, so it is a line of its own — never prose
+// that happens to mention the word.
+const TRAILER_RE = /^Refs:[ \t]*(.+?)[ \t]*$/
+
+/**
+ * The refs a single commit body claims.
+ *
+ * Deliberately blind to three things that LOOK like trailers and are not:
+ *
+ *   - a line inside a ``` fence — a commit explaining the convention quotes it;
+ *   - a quoted line (`> Refs: …`) — same reason, in review replies;
+ *   - an indented line (4+ spaces) — markdown code, e.g. a sample message.
+ *
+ * Counting any of those would make a release claim work it does not contain,
+ * which is worse than missing a ticket: the missing one is noticed when someone
+ * looks for it, the invented one never is.
+ */
+function refsInBody(body) {
+  const found = []
+  let fenced = false
+  for (const raw of String(body || '').split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    if (/^\s*>/.test(line)) continue
+    if (/^ {4,}|\t/.test(line)) continue
+    const m = TRAILER_RE.exec(line.trim() === line ? line : line.trimStart())
+    if (!m) continue
+    for (const id of m[1].match(IDENTIFIER_RE) || []) found.push(id)
+  }
+  return found
+}
+
+/**
+ * Fold commits into the report a release needs.
+ *
+ * @param {Array<{sha?:string, subject?:string, body?:string}>} commits
+ * @returns {{tickets: Array<{ref:string, commits:number}>, unreferenced:number, total:number}}
+ *   `tickets` is deduped in FIRST-SEEN order: a ticket touched by eight commits
+ *   is listed once, where it first appears, not eight times.
+ */
+function ticketsInRange(commits) {
+  const seen = new Map()
+  let unreferenced = 0
+  for (const commit of commits || []) {
+    const refs = [...new Set(refsInBody(commit && commit.body))]
+    if (!refs.length) {
+      unreferenced++
+      continue
+    }
+    for (const ref of refs) seen.set(ref, (seen.get(ref) || 0) + 1)
+  }
+  return {
+    tickets: [...seen.entries()].map(([ref, count]) => ({ ref, commits: count })),
+    unreferenced,
+    total: (commits || []).length,
+  }
+}
+
+module.exports = { ticketsInRange, refsInBody }