@skitterbyte/skitterspec-linear 10.5.2 → 10.6.0

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-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.2",
+  "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/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,
@@ -860,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.
  *
@@ -2025,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':
@@ -2047,6 +2224,8 @@ 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] [--mcp <file>] [--json]\n' +
         '       skitterspec spec-sync init-config --team-id <id> [--team-key K] [--project-id id]\n' +

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 }