@skitterbyte/skitterspec-linear 10.7.0 → 10.8.0

package/assets/commands/spec-live.md

@@ -1,6 +1,6 @@
 ---
-description: Put one spec live on the already-running dev server (take | release | abort | status)
-argument-hint: "[take <spec> | release | abort | status]"
+description: Put one spec live on the already-running dev server — `<spec>` takes it, a bare `take` takes the spec you are on, `main` hands the instance back
+argument-hint: "[<spec> | main | take | release | abort | status]"
 allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
 disable-model-invocation: true
 ---

package/assets/core/linear.config.json.example

@@ -24,7 +24,8 @@
     "overviewFile": "00-overview.md"
   },
   "release": {
-    "stages": []
+    "stages": [],
+    "ignorePaths": ["specs/"]
   },
   "branch": {
     "pattern": "{type}/{slug}"

package/assets/core/linear.config.md

@@ -88,8 +88,12 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   // The project's OWN deployment ladder — where a ticket goes AFTER its spec is
   // complete. Empty (the default) means no ladder is declared and every
   // stage-aware path is unused. See "The deployment ladder" below.
+  //
+  // `ignorePaths` is what `released`/`stage` treat as BOOKKEEPING rather than
+  // shipped work — see "Bookkeeping commits" below. `[]` opts out.
   "release": {
-    "stages": []
+    "stages": [],
+    "ignorePaths": ["specs/"]
   },
 
   // Git branch name derived for a linked spec. Tokens: {type}, {slug},
@@ -168,6 +172,44 @@ Run `skitterspec spec-sync states` to see the whole configured vocabulary — th
 bucket map and the ladder — against what the workspace actually has.
 
 
+## Bookkeeping commits (`release.ignorePaths`)
+
+`spec-sync released` and `spec-sync stage` answer "what did this release
+contain?" from the `Refs:` trailers in the range. Left alone, that over-answers:
+a spec's `chore(spec): complete <name>` commit carries the **same ref** as the
+code it describes, but lands **after** the tag that shipped that code — so the
+ticket turns up in two consecutive release ranges, once for its code and once
+for its paperwork. Downstream, a deployment ladder then drags an issue that had
+already reached the top back down a rung.
+
+`release.ignorePaths` names the repo-relative prefixes that are paperwork:
+
+```jsonc
+"release": {
+  "ignorePaths": ["specs/"]
+}
+```
+
+- **Paths, not subjects.** `chore(spec):` is a convention a mislabelled commit
+  escapes; what a commit changed is a fact. A commit touching an ignored path
+  **and** a source file still counts — it shipped code.
+- **Prefixes, not globs.** `specs` and `specs/` both mean the directory, and a
+  prefix matches only on a path boundary, so `specs/` never swallows
+  `specs-archive/`. Name a single file to ignore just that file.
+- **Only a commit whose paths are ALL ignored is dropped**, and only when git
+  actually listed paths for it. A merge commit (for which git lists none) counts,
+  as does every commit if the path read fails — a lookup that saw nothing knows
+  nothing, and dropping a ticket nobody notices is worse than the double-count
+  this is fixing.
+- **Every drop is disclosed.** The report says `N commit(s) ignored as
+  bookkeeping`, and `--json` carries `ignored` / `ignoredCommits`.
+- **`[]` is the opt-out**; a blank entry is a hard error, since `""` is a prefix
+  of every path and would silently empty the release.
+
+Default: `["specs/"]`. A project that keeps its paperwork elsewhere names its own
+directories instead.
+
+
 ## Spec → Issue, phases → sub-issues
 
 Push maps the spec's structure to Linear's, keyed by id so it updates rather than

package/assets/rules/spec-planning.md

@@ -55,7 +55,8 @@ your canonical `localhost` ports so you can test it at the normal URL
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|down|prune|dev|connect|integrate|hotfix>` is the CLI engine. Teardown drops
+<up|down|prune|dev|connect|integrate|hotfix|live|status|resolve>` is the CLI
+engine (omit the spec name and it uses the worktree you are standing in). Teardown drops
 the finished spec's own test-DB volume; `spec-env prune` additionally reaps
 **orphaned** volumes left by declined/aborted teardowns, so `/spec-complete` and
 `/spec-cancel` also sweep orphans (confirm-first). A **hotfix** is the one

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

@@ -312,6 +312,38 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all

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

@@ -323,6 +323,38 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;

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

@@ -156,6 +156,14 @@ 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.
 
+**Bookkeeping commits are excluded.** A spec's `chore(spec): complete <name>`
+commit carries the same ref as the code it describes but lands *after* the tag
+that shipped it, so counting it would put the ticket in two consecutive releases.
+A commit whose changed paths are **all** under `release.ignorePaths` (default
+`specs/`) contributes nothing; one that touches an ignored path *and* a source
+file still counts. Relay the **ignored count** whenever it is non-zero — that is
+the report saying which commits it set aside.
+
 ## 8. `retarget` — after a Linear team is renamed
 
 ```

package/package.json

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

@@ -1151,25 +1151,53 @@ const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.l
 // receipt is advisory metadata. `status` is read-only; `take` performs the switch
 // (release/abort land in a later phase).
 async function specEnvLive(dir, config, positional) {
-  const action = positional[0] || 'status'
+  const { action, specArg } = liveGrammar(dir, config, positional)
   switch (action) {
     case 'status':
-      specEnvLiveStatus(dir, config, positional[1])
+      specEnvLiveStatus(dir, config, specArg)
       break
     case 'take':
-      await specEnvLiveTake(dir, config, positional[1])
+      await specEnvLiveTake(dir, config, specArg)
       break
     case 'release':
-      await specEnvLiveRelease(dir, config, positional[1])
+      await specEnvLiveRelease(dir, config, specArg)
       break
     case 'abort':
       await specEnvLiveAbort(dir, config)
       break
     default:
-      process.stdout.write('Usage: skitterspec spec-env live <take|release|abort|status> [spec]\n')
+      process.stdout.write(
+        'Usage: skitterspec spec-env live <spec>|<base branch>|<take|release|abort|status> [spec]\n',
+      )
   }
 }
 
+const LIVE_VERBS = new Set(['status', 'take', 'release', 'abort'])
+
+// The two front doors every doc names — `/spec-live <spec>` and `/spec-live main`
+// — translated to verbs. They live here rather than in the command because
+// `.claude/commands/spec-live.md` relays `$ARGUMENTS` untranslated (it is a
+// pre-executed script, with no model turn to rewrite them); the skill this
+// replaced did the translation itself, which is how these forms came to be
+// documented but unimplemented. `connect` needs no equivalent — its argument was
+// always spec-shaped (`specArg || 'main'`).
+//
+// VERB PRECEDENCE IS DELIBERATE, and so is the order below: the four verbs and
+// the base branch are matched BEFORE the spec-name fallback, so a spec folder
+// that happens to be called `status` cannot silently branch-switch the primary
+// checkout. Such a spec is still reachable — as `live take status`. The literal
+// `main` is honoured even where the base branch is named something else,
+// matching `connect main`, so the muscle memory works in either repo.
+function liveGrammar(dir, config, positional) {
+  const [first, second] = positional
+  if (!first) return { action: 'status', specArg: undefined }
+  if (LIVE_VERBS.has(first)) return { action: first, specArg: second }
+  if (first === 'main' || first === resolveBaseBranch(config, gitReader(dir))) {
+    return { action: 'release', specArg: undefined }
+  }
+  return { action: 'take', specArg: first }
+}
+
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
@@ -1466,7 +1494,9 @@ async function specEnv(rest) {
           '  [spec] is optional for up/down/dev/integrate/hotfix/resolve and live take:\n' +
           '  omit it and the sole provisioned spec is used (several -> it lists them).\n' +
           '  NOTE connect and live status keep their own meaning for a missing spec:\n' +
-          '  connect disconnects (= main), live status reports on the whole repo.\n',
+          '  connect disconnects (= main), live status reports on the whole repo.\n' +
+          '  connect and live also take a bare spec name: `live <spec>` takes the\n' +
+          '  instance, `live main` (or your base branch) hands it back.\n',
       )
   }
 }

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

@@ -61,6 +61,7 @@ const {
   CONFIG_FILE,
   LIFECYCLE_BUCKETS,
   releaseStages,
+  releaseIgnorePaths,
   stageFor,
 } = require('./config.js')
 const { resolveApiKey, makeApiAdapter, stateIdFor, fetchWorkspaceStates } = require('./api.js')
@@ -942,6 +943,38 @@ function unreachableBase(git, range) {
   return git(['merge-base', '--is-ancestor', base, head]) === null ? base : null
 }
 
+/**
+ * The paths each commit in the range changed, as sha → string[], or null when
+ * git could not be asked at all.
+ *
+ * A SECOND `git log` rather than `--name-only` on the first one: that format is
+ * NUL-delimited so a body cannot split a record, and appending a file list to
+ * the same stream would put one commit's files inside the next commit's record.
+ * `-z` also stops git C-quoting a non-ASCII filename (`"specs/\303\251.md"`),
+ * which a prefix match would then miss.
+ *
+ * Returning null on failure is deliberate: the caller leaves every commit's
+ * paths unknown, nothing is filtered, and the report is exactly what it was
+ * before the filter existed. A read that failed must not be able to empty a
+ * release.
+ */
+function readChangedPaths(git, range) {
+  const raw = git(['log', '-z', '--format=%x1e%H', '--name-only', range])
+  if (raw === null) return null
+  const bySha = new Map()
+  for (const chunk of raw.split('\x1e')) {
+    if (!chunk.trim()) continue
+    const [sha, ...names] = chunk.split('\x00')
+    const id = String(sha || '').trim()
+    if (!id) continue
+    bySha.set(
+      id,
+      names.map((n) => n.replace(/^\n+/, '').trim()).filter(Boolean),
+    )
+  }
+  return bySha
+}
+
 /**
  * Resolve a commit range and read it, shared by `released` (which reports on it)
  * and `stage` (which acts on it). Both must agree on what a release contains,
@@ -1007,6 +1040,14 @@ function readCommitRange(dir, rangeArg, verb) {
       return { sha, subject, body: rest.join('\x00') }
     })
 
+  // What each commit CHANGED, so bookkeeping can be told from shipped work. A
+  // commit git listed no files for keeps `paths: null` — unknown, never
+  // "changed nothing" — see `onlyIgnoredPaths`.
+  const pathsBySha = readChangedPaths(git, range)
+  for (const commit of commits) {
+    commit.paths = (pathsBySha && pathsBySha.get(commit.sha)) || null
+  }
+
   return { range, commits }
 }
 
@@ -1018,7 +1059,7 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
   }
   const { range, commits } = read
 
-  const report = ticketsInRange(commits)
+  const report = ticketsInRange(commits, { ignorePaths: releaseIgnorePaths(config) })
 
   // 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.
@@ -1061,6 +1102,12 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
   // MISSED trailer looks identical, so silence here would read as "everything is
   // accounted for".
   lines.push(`  ${report.unreferenced} commit(s) carry no ref`)
+  // A filter that removes commits without saying so reads as "there was nothing
+  // there". Named only when it actually fired — on a project with no paperwork
+  // in the range there is nothing to disclose.
+  if (report.ignored) {
+    lines.push(`  ${report.ignored} commit(s) ignored as bookkeeping (release.ignorePaths)`)
+  }
   out.write(lines.join('\n') + '\n')
   return 0
 }
@@ -1110,7 +1157,7 @@ async function specSyncStage(dir, config, stageKey, rangeArg, flags, out) {
   }
   const { range, commits } = read
 
-  const report = ticketsInRange(commits)
+  const report = ticketsInRange(commits, { ignorePaths: releaseIgnorePaths(config) })
   const teamKey = (config.linear && config.linear.teamKey) || ''
   const parts = partitionStageMoves({
     tickets: report.tickets,
@@ -1211,6 +1258,7 @@ async function specSyncStage(dir, config, stageKey, rangeArg, flags, out) {
             unreadable: unreadable.map((t) => t.ref),
           },
           unreferencedCommits: report.unreferenced,
+          ignoredCommits: report.ignored,
           totalCommits: report.total,
         },
         null,
@@ -1248,6 +1296,9 @@ async function specSyncStage(dir, config, stageKey, rangeArg, flags, out) {
   // legitimately carries no ref and a MISSED trailer looks identical, so silence
   // would read as "every commit is accounted for".
   lines.push(`  ${report.unreferenced} commit(s) carry no ref, of ${report.total}`)
+  if (report.ignored) {
+    lines.push(`  ${report.ignored} commit(s) ignored as bookkeeping (release.ignorePaths)`)
+  }
   if (!applying) lines.push('  dry run — pass --apply to move them')
   out.write(lines.join('\n') + '\n')
   return failed.length ? 1 : 0

package/src/vendor/linear/config.js

@@ -92,6 +92,23 @@ const DEFAULT_KEY_ENV = 'LINEAR_API_KEY'
 // LIFECYCLE_BUCKETS.
 const DEFAULT_RELEASE_STAGES = Object.freeze([])
 
+// Repo-relative path prefixes whose commits are BOOKKEEPING, not shipped work.
+//
+// A spec's `chore(spec): complete <name>` commit carries the same `Refs:`
+// trailer as the code it describes, but lands AFTER the tag that shipped that
+// code — so without this the ticket appears in two consecutive release ranges:
+// once for its code, once for its paperwork. Measured on one consumer, 14 of the
+// 22 ref-carrying commits in 300 were spec bookkeeping, so this is the dominant
+// case rather than an edge one.
+//
+// PATHS, not commit subjects. `chore(spec):` is a convention a mislabelled
+// commit escapes; what a commit changed is a fact. A commit touching an ignored
+// path AND a source file still counts — it shipped code.
+//
+// An explicit `[]` is the opt-out, and a project that keeps its paperwork
+// elsewhere names its own directories here.
+const DEFAULT_RELEASE_IGNORE_PATHS = Object.freeze(['specs/'])
+
 const DEFAULT_CONFIG = Object.freeze({
   // `projectId` is the project picker's DEFAULT, not a mandate: `/spec` and the
   // first `/spec-push` offer the team's projects and pre-select this one; empty
@@ -128,7 +145,9 @@ const DEFAULT_CONFIG = Object.freeze({
   // See DEFAULT_RELEASE_STAGES above. `stages` is ordered: the order is recorded
   // for reporting and doctor's ladder check, and deliberately NOT enforced — a
   // rollback from test and a hotfix going straight to prod are both legitimate.
-  release: Object.freeze({ stages: DEFAULT_RELEASE_STAGES }),
+  // `ignorePaths` (see DEFAULT_RELEASE_IGNORE_PATHS) is what `released`/`stage`
+  // treat as bookkeeping rather than shipped work.
+  release: Object.freeze({ stages: DEFAULT_RELEASE_STAGES, ignorePaths: DEFAULT_RELEASE_IGNORE_PATHS }),
   branch: Object.freeze({ pattern: '{type}/{slug}' }),
   // `keyEnv` names the env var holding the personal API key. It is a NAME, not a
   // key: putting the secret itself here would commit it.
@@ -180,7 +199,10 @@ function defaults() {
     mapping: { ...DEFAULT_CONFIG.mapping },
     states: { ...DEFAULT_CONFIG.states },
     snapshot: { ...DEFAULT_CONFIG.snapshot },
-    release: { stages: DEFAULT_CONFIG.release.stages.map((s) => ({ ...s })) },
+    release: {
+      stages: DEFAULT_CONFIG.release.stages.map((s) => ({ ...s })),
+      ignorePaths: [...DEFAULT_CONFIG.release.ignorePaths],
+    },
     branch: { ...DEFAULT_CONFIG.branch },
     auth: { ...DEFAULT_CONFIG.auth },
     apply: { ...DEFAULT_CONFIG.apply },
@@ -317,6 +339,35 @@ function mergeReleaseStages(base, parsed) {
   base.stages = stages
 }
 
+// Merge (and validate) release.ignorePaths — the path prefixes whose commits are
+// bookkeeping. Loud on anything but an array of non-empty strings, like
+// release.stages above: a bad value that quietly fell back to the default would
+// let a project believe it had opted out and go on double-counting tickets.
+//
+// A BLANK entry is rejected rather than dropped. `""` is a prefix of every path,
+// so a stray empty string would silently ignore every commit in the range and
+// report a release as containing nothing — the loudest possible wrong answer,
+// arriving as silence.
+function mergeReleaseIgnorePaths(base, parsed) {
+  const value = parsed.ignorePaths
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `Invalid ${CONFIG_FILE}: release.ignorePaths = ${JSON.stringify(value)} ` +
+        '(expected an array of repo-relative path prefixes)',
+    )
+  }
+  value.forEach((entry, i) => {
+    if (typeof entry !== 'string' || !entry.trim()) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: release.ignorePaths[${i}] = ${JSON.stringify(entry)} ` +
+          '(expected a non-empty repo-relative path prefix, e.g. "specs/")',
+      )
+    }
+  })
+  base.ignorePaths = stringList(value)
+}
+
 // Merge (and validate) sync.keyedFields. Each value is the item's id property
 // name (a non-empty string); a field listed here is compared per item.
 function mergeKeyedFields(base, parsed) {
@@ -382,6 +433,7 @@ function mergeConfig(base, parsed) {
 
   if (isObject(parsed.release)) {
     mergeReleaseStages(base.release, parsed.release)
+    mergeReleaseIgnorePaths(base.release, parsed.release)
   }
 
   if (isObject(parsed.branch)) {
@@ -462,9 +514,23 @@ function stageFor(config, key) {
   return releaseStages(config).find((s) => s.key === key) || null
 }
 
+/**
+ * The path prefixes whose commits are bookkeeping, always an array.
+ *
+ * A config object that predates the field gets the DEFAULT — the list
+ * `loadLinearConfig` would have produced — rather than an empty one, so an older
+ * object cannot quietly turn the filter off. An explicit `[]` survives
+ * `Array.isArray` and is honoured as the opt-out.
+ */
+function releaseIgnorePaths(config) {
+  const paths = config && config.release && config.release.ignorePaths
+  return Array.isArray(paths) ? paths : [...DEFAULT_RELEASE_IGNORE_PATHS]
+}
+
 module.exports = {
   loadLinearConfig,
   releaseStages,
+  releaseIgnorePaths,
   stageFor,
   mergeConfig,
   defaults,
@@ -476,4 +542,5 @@ module.exports = {
   LIFECYCLE_BUCKETS,
   TRANSPORTS,
   DEFAULT_KEY_ENV,
+  DEFAULT_RELEASE_IGNORE_PATHS,
 }

package/src/vendor/linear/released.js

@@ -51,18 +51,77 @@ function refsInBody(body) {
   return found
 }
 
+/**
+ * Whether a commit's changed paths are ENTIRELY bookkeeping.
+ *
+ * The problem it solves: a spec's `chore(spec): complete <name>` commit carries
+ * the same `Refs:` trailer as the code it describes, but lands after the tag
+ * that shipped that code — so the ticket turns up in two consecutive release
+ * ranges, once for its code and once for its paperwork.
+ *
+ * Deliberately a POSITIVE signal: it says yes only when it actually saw paths
+ * and every one of them sits under an ignored prefix. It never reasons from an
+ * absence.
+ *
+ * WHAT WOULD FOOL THE OTHER PHRASING ("no unignored path was found"): git lists
+ * no files at all for a MERGE commit (without `-m`) — verified, not assumed —
+ * nor for a genuinely empty one, and a `git log` that failed outright yields no
+ * paths for anything. Under that phrasing every one of those becomes a release
+ * silently losing its tickets. Under this one they mean "nothing was seen, so
+ * nothing is known", which keeps the pre-filter behaviour: an over-claimed
+ * ticket is noticed when someone looks for it, whereas a ticket that quietly
+ * belongs to no release never is.
+ *
+ * Matching is path-prefix, not glob: `specs` and `specs/` both mean the
+ * directory, and a prefix only matches on a path SEGMENT boundary, so `specs/`
+ * never swallows `specs-archive/`.
+ *
+ * @param {string[]|null|undefined} paths repo-relative paths the commit changed
+ * @param {string[]} ignorePaths repo-relative prefixes that are bookkeeping
+ */
+function onlyIgnoredPaths(paths, ignorePaths) {
+  if (!Array.isArray(paths) || !paths.length) return false
+  const prefixes = (Array.isArray(ignorePaths) ? ignorePaths : [])
+    .filter((p) => typeof p === 'string' && p.trim())
+    .map((p) => p.trim().replace(/^\.\//, '').replace(/\/+$/, ''))
+    .filter(Boolean)
+  if (!prefixes.length) return false
+  return paths.every((raw) => {
+    const file = String(raw == null ? '' : raw)
+      .trim()
+      .replace(/^\.\//, '')
+    // An unreadable entry is an unknown, not an ignored one — it makes the whole
+    // commit count, per the bias above.
+    if (!file) return false
+    return prefixes.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))
+  })
+}
+
 /**
  * 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}}
+ * @param {Array<{sha?:string, subject?:string, body?:string, paths?:string[]}>} commits
+ * @param {{ignorePaths?:string[]}} [options] `ignorePaths` marks bookkeeping —
+ *   see `onlyIgnoredPaths`. Omitted (or empty) means nothing is ignored, so the
+ *   report is what it was before the filter existed.
+ * @returns {{tickets: Array<{ref:string, commits:number}>, unreferenced:number, ignored: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.
+ *   is listed once, where it first appears, not eight times. `ignored` is
+ *   reported rather than merely subtracted — a filter that removes commits in
+ *   silence reads as "there was nothing there".
  */
-function ticketsInRange(commits) {
+function ticketsInRange(commits, options = {}) {
+  const ignorePaths = (options && options.ignorePaths) || []
   const seen = new Map()
   let unreferenced = 0
+  let ignored = 0
   for (const commit of commits || []) {
+    if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
+      // Not counted as unreferenced either: that number exists to surface a
+      // MISSED trailer, and a paperwork commit is not a gap someone should hunt.
+      ignored++
+      continue
+    }
     const refs = [...new Set(refsInBody(commit && commit.body))]
     if (!refs.length) {
       unreferenced++
@@ -73,6 +132,7 @@ function ticketsInRange(commits) {
   return {
     tickets: [...seen.entries()].map(([ref, count]) => ({ ref, commits: count })),
     unreferenced,
+    ignored,
     total: (commits || []).length,
   }
 }
@@ -161,4 +221,4 @@ function stageOrderWarning(stages, fromState, toKey, lifecycleStates = []) {
   return null
 }
 
-module.exports = { ticketsInRange, refsInBody, partitionStageMoves, stageOrderWarning }
+module.exports = { ticketsInRange, refsInBody, onlyIgnoredPaths, partitionStageMoves, stageOrderWarning }