@skitterbyte/skitterspec-linear 10.7.0 → 11.0.0

package/src/env/provision.js

@@ -158,4 +158,61 @@ function planUp(spec, alloc, config) {
   }
 }
 
-module.exports = { planUp, seedCommandFor, worktreeCd }
+/**
+ * Plan `spec-env up` in CHECKOUT mode — the branch is built in the primary
+ * checkout and there is no worktree at all.
+ *
+ * Pure: every git fact it needs arrives in `ctx`, and it writes nothing.
+ *
+ * ctx: { current, base, onBase, clean, branchExists }
+ *
+ * What it refuses, and why each is a refusal rather than a warning:
+ *  - a dirty tree, because `git switch -c` CARRIES uncommitted changes onto the
+ *    new branch. That is silent and it is the operator's work, so it is theirs
+ *    to place, not ours.
+ *  - standing on another branch, because switching away from it is a decision
+ *    about someone else's unfinished spec. Being on THIS spec's branch is not a
+ *    refusal — it is the re-run, and the answer is "already attached".
+ *
+ * There is no bootstrap and no opener: the primary checkout already has its
+ * dependencies, and no new session is being opened.
+ */
+function planCheckoutUp(spec, ctx, config) {
+  const base = ctx.base || (config && config.baseBranch) || 'main'
+  const result = {
+    mode: 'checkout',
+    blocked: false,
+    reason: null,
+    attached: false,
+    branch: spec.branch,
+    checkoutPath: ctx.checkoutPath || null,
+    commands: [],
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // Order matters: report "already attached" before anything else, so a re-run
+  // on the spec's own branch is never refused for a dirty tree it legitimately
+  // has — you are mid-phase, with the phase's own edits in progress.
+  if (ctx.current && ctx.current === spec.branch) {
+    return { ...result, attached: true }
+  }
+  if (!ctx.clean) {
+    return block(
+      'the primary checkout has uncommitted changes — commit or stash them first ' +
+        '(switching would carry them onto the new branch)',
+    )
+  }
+  if (!ctx.onBase) {
+    return block(
+      `the primary checkout is on ${ctx.current || '(detached)'}, not ${base} — ` +
+        'finish or park that branch first; checkout mode holds one spec at a time',
+    )
+  }
+
+  result.commands.push(
+    ctx.branchExists ? `git switch ${spec.branch}` : `git switch -c ${spec.branch}`,
+  )
+  return result
+}
+
+module.exports = { planUp, planCheckoutUp, seedCommandFor, worktreeCd }

package/src/env/teardown.js

@@ -105,7 +105,7 @@ function planDown(spec, config, flags, ctx) {
   // different question from ours: it also declines a branch that is ahead of its
   // upstream ref, reporting `not yet merged to refs/remotes/origin/<branch>,
   // even though it is merged to HEAD`. That fires on the ordinary spec flow —
-  // `/spec-go` pushes the branch when it provisions, and the phase commits after
+  // `/spec-start` pushes the branch when it provisions, and the phase commits after
   // it are landed locally rather than pushed — so teardown meets a branch whose
   // every commit is on `main` and `-d` refuses it. `merged` (HEAD is an ancestor
   // of base) already establishes what we actually care about, and establishes it
@@ -122,7 +122,7 @@ function planDown(spec, config, flags, ctx) {
 
   // --- delete the branch on the remote (planned, never run here) ---
   //
-  // `/spec-go` pushes the branch at provision time, so a completed spec otherwise
+  // `/spec-start` pushes the branch at provision time, so a completed spec otherwise
   // leaves a merged branch on the remote forever. Cleaning that up is the goal;
   // doing it safely is the constraint.
   //
@@ -185,4 +185,42 @@ function blocked(reason) {
   }
 }
 
-module.exports = { planDown }
+/**
+ * Pure teardown planner for CHECKOUT mode.
+ *
+ * There is no worktree to remove, no slot and no volumes — the only thing a
+ * finished spec leaves behind is its branch, and the checkout standing on it.
+ *
+ * Order is load-bearing: git refuses to delete the branch you are on, so the
+ * switch to base must come first. It is also what returns the checkout to a
+ * state the next `spec-env up` will accept.
+ *
+ * The same "are these commits recoverable?" question decides `-d` vs `-D`, and
+ * it is asked exactly as worktree-mode teardown asks it — a landed branch is
+ * safe to force-delete because its commits are on base (or under a tag); an
+ * unlanded one is not, and is refused rather than quietly dropped.
+ *
+ * ctx: { dirty, landed, onBranch, base, checkoutPath }
+ */
+function planDownCheckout(spec, config, flags, ctx) {
+  const { dirty, landed, onBranch, base, checkoutPath } = ctx || {}
+  const force = Boolean(flags && flags.force)
+  const result = { mode: 'checkout', blocked: false, reason: null, commands: [], branch: spec.branch }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  if (!force) {
+    if (config.guards.refuseTeardownIfDirty && dirty) {
+      return block('the checkout has uncommitted changes')
+    }
+    if (!landed) {
+      return block(`${spec.branch} is not merged into ${base} — landing it first is what makes the delete safe`)
+    }
+  }
+
+  const commands = []
+  if (onBranch !== false) commands.push(`git -C ${checkoutPath} switch ${base}`)
+  commands.push(`git -C ${checkoutPath} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
+  return { ...result, commands }
+}
+
+module.exports = { planDown, planDownCheckout }

package/src/init.js

@@ -423,18 +423,24 @@ function installCore(dir, opts) {
 }
 
 // Activate opt-in per-spec isolation: write specs/.core/env.config.json from the
-// example asset so /spec-go provisions a worktree for every in-progress spec.
+// example asset so /spec-start provisions a worktree for every in-progress spec.
 // Only called when the operator opts in, and never on `update` (adopting isolation
 // is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
 // never clobbers an existing env.config.json without --force.
-function installIsolation(dir, { enabled }, opts) {
+function installIsolation(dir, { enabled, workspaceMode }, opts) {
   if (!enabled) return
-  copyAsset(
-    dir,
-    path.join('core', 'env.config.json.example'),
-    path.join(dir, 'specs', '.core', 'env.config.json'),
-    opts,
-  )
+  const target = path.join(dir, 'specs', '.core', 'env.config.json')
+  copyAsset(dir, path.join('core', 'env.config.json.example'), target, opts)
+
+  // Only 'checkout' is written; 'worktree' is already what the template says and
+  // what the loader defaults to, so the common path leaves the file untouched.
+  // Guarded by existsSync because copyAsset legitimately declines to overwrite a
+  // config the operator already customized — rewriting it here would undo that.
+  if (workspaceMode === 'checkout' && fs.existsSync(target)) {
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8'))
+    parsed.mode = 'checkout'
+    fs.writeFileSync(target, `${JSON.stringify(parsed, null, 2)}\n`)
+  }
   trustWorktreeRoot(dir)
 }
 
@@ -673,7 +679,7 @@ function printReport(dir, mode, { diff = false } = {}) {
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
   const isolationNote = isolationOn
     ? 'Per-spec isolation is ON: every in-progress spec gets its own git worktree' +
-      ' at /spec-go (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
+      ' at /spec-start (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
   // A provider superset ships its own `spec-<provider>-setup` skill; the base
@@ -696,7 +702,7 @@ function printReport(dir, mode, { diff = false } = {}) {
         ' (it discovers your workspace and writes the config), or see' +
         ' specs/.core/SETUP.md.\n'
   process.stdout.write(
-    '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
+    '\nDone. Skills resolve as /spec, /spec-start, /spec-next, /spec-complete,' +
       ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
@@ -705,7 +711,10 @@ function printReport(dir, mode, { diff = false } = {}) {
   )
 }
 
-async function init({ dir, force, claudeMd, mode, isolation }) {
+// `mode` here is the INSTALL mode ('init' | 'update'), long-standing and
+// unrelated to the config's own `mode` key — which arrives as `workspaceMode`
+// precisely so the two cannot be confused at a call site.
+async function init({ dir, force, claudeMd, mode, isolation, workspaceMode }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   resetReport()
 
@@ -716,7 +725,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   removeRetiredFiles(dir)
   installCore(dir, { force })
   // Adopting isolation writes the live env.config.json — init only, never update.
-  if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
+  if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
   // Record what we wrote (and migrate a pre-manifest repo) so a later resync can

package/src/prompts.js

@@ -7,7 +7,8 @@
  * test suite never imports the interactive UI.
  *
  * `isolationSeed` pre-fills the per-spec isolation question. Returns
- * `{ isolation }`.
+ * `{ isolation, mode }` — `mode` is only asked when isolation is enabled, and
+ * is `'worktree'` otherwise (the value the config defaults to anyway).
  */
 
 async function promptSetup({ isolationSeed = false } = {}) {
@@ -23,15 +24,42 @@ async function promptSetup({ isolationSeed = false } = {}) {
     {
       type: 'confirm',
       name: 'isolation',
-      message: 'Enable per-spec isolation — a git worktree per spec?',
+      message: 'Enable per-spec isolation — build each spec on its own branch?',
       initial: isolationSeed,
     },
+    {
+      // Only reachable when isolation was accepted: `prev` is the previous
+      // answer, and returning null skips the question entirely.
+      type: (prev) => (prev ? 'select' : null),
+      name: 'mode',
+      message: 'Where should a spec be built?',
+      hint: '- this is the trade, not a preference',
+      initial: 0,
+      choices: [
+        {
+          title: 'Its own worktree (default)',
+          value: 'worktree',
+          description: 'several specs at once, main left free — one terminal session per spec',
+        },
+        {
+          title: 'The checkout you are in',
+          value: 'checkout',
+          description: 'one spec at a time, no second session — your terminal follows the work',
+        },
+      ],
+    },
   ]
 
   const ans = await prompts(questions, { onCancel })
   if (cancelled) throw new Error('Setup cancelled')
 
-  return { isolation: Boolean(ans.isolation) }
+  // Anything other than an explicit 'checkout' resolves to the default, so a
+  // skipped or cancelled-into-default answer can never select the mode that
+  // puts a spec's work in the primary checkout.
+  return {
+    isolation: Boolean(ans.isolation),
+    mode: ans.mode === 'checkout' ? 'checkout' : 'worktree',
+  }
 }
 
 /**

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')
@@ -251,7 +252,7 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
 function deferredLines(n) {
   return [
     `  ${n} phase(s) deferred — mapping.phases is "deferred" and this spec has not started`,
-    '     they are created on the push that follows /spec-go',
+    '     they are created on the push that follows /spec-start',
   ]
 }
 
@@ -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
@@ -1276,7 +1327,7 @@ async function specSyncStage(dir, config, stageKey, rangeArg, flags, out) {
  * beats no ref for looking correct). An explicit override cannot be blinded, and
  * needs no answer for mixed staging.
  *
- * The branch→spec direction is the INVERSE of what `/spec-go` provisions with,
+ * The branch→spec direction is the INVERSE of what `/spec-start` 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.

package/src/vendor/linear/config.js

@@ -2,7 +2,7 @@
 
 /**
  * Config loader for the one-way Linear sync feature (`/spec-status`, `/spec-push`
- * and the Linear-aware paths of `/spec` and `/spec-go`).
+ * and the Linear-aware paths of `/spec` and `/spec-next`).
  *
  * Reads `specs/.core/linear.config.json` from the project root and normalises it
  * over frozen defaults. The feature is strictly opt-in: when the file is absent
@@ -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 }