@skitterbyte/skitterspec-linear 10.6.0 → 10.8.0

package/src/vendor/linear/config.js

@@ -20,6 +20,7 @@
  *     intake:   { label, bugLabels, hotfixLabels },
  *     mapping:  { specFolder, phases, tasks },
  *     states:   { backlog, "in-progress", complete, cancelled },
+ *     release:  { stages: [{ key, state }] },
  *     snapshot: { overviewFile },
  *     branch:   { pattern },
  *     sync: {
@@ -78,6 +79,36 @@ const TRANSPORTS = Object.freeze(['api', 'mcp'])
 // nothing secret is ever written to the repo.
 const DEFAULT_KEY_ENV = 'LINEAR_API_KEY'
 
+// The project's OWN deployment ladder: where a ticket goes AFTER its spec is
+// complete — deployed to test, approved for demo, live in prod. Deliberately an
+// open, ORDERED list in the project's vocabulary rather than a fixed set: one
+// team's `On Test`/`Ready for Demo` is another's `staging`, and most projects
+// have none at all. Empty (the default) means the project declared no ladder,
+// and every stage-aware path is simply unused.
+//
+// It is NOT keyed by lifecycle bucket, unlike `states` and `mapping.phases`.
+// A deployment stage is a fact about an ENVIRONMENT, and no folder under
+// `specs/` can ever derive one — which is why it must not join
+// 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
@@ -111,6 +142,12 @@ const DEFAULT_CONFIG = Object.freeze({
     cancelled: 'Canceled',
   }),
   snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
+  // 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.
+  // `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.
@@ -162,6 +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 })),
+      ignorePaths: [...DEFAULT_CONFIG.release.ignorePaths],
+    },
     branch: { ...DEFAULT_CONFIG.branch },
     auth: { ...DEFAULT_CONFIG.auth },
     apply: { ...DEFAULT_CONFIG.apply },
@@ -249,6 +290,84 @@ function mergePhaseMapping(base, parsed) {
   }
 }
 
+// Merge (and validate) `release.stages` — the project's deployment ladder.
+//
+// Loud on a malformed entry, like fieldOwnership and mapping.phases above: this
+// list names Linear states, and Linear SILENTLY IGNORES an unknown state. A
+// half-typed ladder would push clean and move nothing, which is exactly the
+// failure `validateStates` exists to stop — so a bad shape fails here, at load,
+// rather than at the first deploy nobody is watching.
+//
+// An ABSENT `release` block is not an error: it is the opt-out, and the whole
+// feature is unused without it.
+function mergeReleaseStages(base, parsed) {
+  const value = parsed.stages
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `Invalid ${CONFIG_FILE}: release.stages = ${JSON.stringify(value)} ` +
+        '(expected an array of { key, state })',
+    )
+  }
+  const stages = []
+  const seen = new Set()
+  value.forEach((entry, i) => {
+    if (!isObject(entry)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
+          '(expected { key, state })',
+      )
+    }
+    for (const field of ['key', 'state']) {
+      if (typeof entry[field] !== 'string' || !entry[field].trim()) {
+        throw new Error(
+          `Invalid ${CONFIG_FILE}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
+            '(expected a non-empty string)',
+        )
+      }
+    }
+    const key = entry.key.trim()
+    if (seen.has(key)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
+          '(a stage key is how CI names the rung, so it must be unique)',
+      )
+    }
+    seen.add(key)
+    stages.push({ key, state: entry.state.trim() })
+  })
+  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) {
@@ -312,6 +431,11 @@ function mergeConfig(base, parsed) {
     assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
   }
 
+  if (isObject(parsed.release)) {
+    mergeReleaseStages(base.release, parsed.release)
+    mergeReleaseIgnorePaths(base.release, parsed.release)
+  }
+
   if (isObject(parsed.branch)) {
     assign(base.branch, parsed.branch, 'pattern', 'string')
   }
@@ -350,7 +474,8 @@ function mergeConfig(base, parsed) {
  * Returns `{ config, present }`:
  *   - missing file → `{ config: defaults, present: false }` (opt-out; never throws)
  *   - present      → `{ config: merged,   present: true }`
- * Malformed JSON or a bad `fieldOwnership` enum → throws a clear Error.
+ * Malformed JSON, a bad `fieldOwnership` enum, or a malformed `release.stages`
+ * entry → throws a clear Error.
  */
 function loadLinearConfig(dir = process.cwd()) {
   const base = defaults()
@@ -374,8 +499,39 @@ function loadLinearConfig(dir = process.cwd()) {
   return { config: mergeConfig(base, parsed), present: true }
 }
 
+/**
+ * The project's declared deployment ladder, always an array (empty = none
+ * declared). Callers read this rather than reaching into the config, so an
+ * older config object without a `release` block cannot throw.
+ */
+function releaseStages(config) {
+  const stages = config && config.release && config.release.stages
+  return Array.isArray(stages) ? stages : []
+}
+
+/** The ladder rung with this key, or null. */
+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,
   DEFAULT_CONFIG,
@@ -386,4 +542,5 @@ module.exports = {
   LIFECYCLE_BUCKETS,
   TRANSPORTS,
   DEFAULT_KEY_ENV,
+  DEFAULT_RELEASE_IGNORE_PATHS,
 }

package/src/vendor/linear/doctor.js

@@ -29,7 +29,11 @@
  * by construction rather than by convention.
  */
 
-const STATES = ['ok', 'missing', 'broken', 'skipped']
+// `warn` sits between `ok` and `broken`: worth a human's attention, but not a
+// failure. A ladder whose last rung never closes an issue is a real problem for
+// most projects and a deliberate choice for some, and only the project knows
+// which — so it is said, and the exit code is left alone.
+const STATES = ['ok', 'missing', 'broken', 'skipped', 'warn']
 
 // A row is a check. `fix` is the exact command to run, or null when there is
 // nothing to fix.
@@ -57,6 +61,7 @@ function runChecks(state = {}) {
     projectCheck(state.project, state.tracker, state.remote),
     keyCheck(state.key, state.tracker),
     remoteCheck(state.remote),
+    ladderCheck(state.ladder, state.tracker),
     mcpCheck(state.mcp, state.tracker, state.project, state.remote),
   ]
   // `missing` is a declined opt-in, so it must not fail the run. Only a
@@ -64,6 +69,67 @@ function runChecks(state = {}) {
   return { ok: !checks.some((c) => c.state === 'broken'), checks }
 }
 
+/**
+ * The deployment ladder's shape, when one is declared.
+ *
+ * WHAT COULD FOOL THIS CHECK, and why it is a `warn` rather than a refusal: a
+ * workspace can close an issue by automation (a merged PR, a linked release)
+ * rather than by the last rung's own type, and a ladder that stops at a
+ * `started` state is then perfectly healthy. Only the project knows which it is.
+ *
+ * It needs the workspace's state TYPES, which only the API transport returns —
+ * `--workspace-states` and the MCP path carry names alone. Without them the row
+ * is `skipped`: not knowing a type is not evidence of a bad one.
+ */
+function ladderCheck(s = {}, tracker = {}) {
+  if (!tracker.present) return row('ladder', 'ladder', 'skipped', 'no tracker configured')
+  const stages = Array.isArray(s.stages) ? s.stages : []
+  if (!stages.length) {
+    return row('ladder', 'ladder', 'skipped', 'no deployment ladder declared')
+  }
+
+  const summary = stages.map((st) => `${st.key} -> ${st.state}`).join(', ')
+  const states = Array.isArray(s.workspaceStates) ? s.workspaceStates : null
+  if (!states) {
+    return row('ladder', 'ladder', 'skipped', `${stages.length} rung(s), unchecked: ${summary}`)
+  }
+
+  const byName = new Map(
+    states.filter((st) => st && typeof st.name === 'string').map((st) => [st.name.toLowerCase().trim(), st]),
+  )
+  // A list that arrived EMPTY, or held nothing with a name, cannot prove a rung
+  // is absent — it is a lookup that saw nothing, not a workspace without these
+  // states. Accusing every rung off that would be the exact absence-as-evidence
+  // mistake the negative-checks rule exists for.
+  if (!byName.size) {
+    return row('ladder', 'ladder', 'skipped', `${stages.length} rung(s), unchecked: ${summary}`)
+  }
+  const unknown = stages.filter((st) => !byName.has(String(st.state).toLowerCase().trim()))
+  if (unknown.length) {
+    return row(
+      'ladder',
+      'ladder',
+      'broken',
+      `rung state(s) not in this workspace: ${unknown.map((st) => `${st.key} -> "${st.state}"`).join(', ')}` +
+        ' — Linear silently ignores an unknown state, so these would move nothing',
+      '/spec-linear-setup',
+    )
+  }
+
+  const last = stages[stages.length - 1]
+  const type = (byName.get(String(last.state).toLowerCase().trim()) || {}).type
+  if (type !== 'completed') {
+    return row(
+      'ladder',
+      'ladder',
+      'warn',
+      `ends at "${last.state}" (type: ${type || 'unknown'}) — an issue finishing the ladder never reaches a ` +
+        'completed state. Add a final rung, or ignore this if Linear automation closes them.',
+    )
+  }
+  return row('ladder', 'ladder', 'ok', `${stages.length} rung(s): ${summary}`)
+}
+
 function scaffoldCheck(s = {}) {
   if (!s.specsDir) {
     return row('scaffold', 'scaffold', 'missing', 'no specs/ folder', 'skitterspec init')

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,8 +132,93 @@ function ticketsInRange(commits) {
   return {
     tickets: [...seen.entries()].map(([ref, count]) => ({ ref, commits: count })),
     unreferenced,
+    ignored,
     total: (commits || []).length,
   }
 }
 
-module.exports = { ticketsInRange, refsInBody }
+/**
+ * Split a release's tickets into the ones a stage move may touch and the ones it
+ * must not, with a reason for every exclusion.
+ *
+ * Three reasons to leave a ticket alone, and each is a case where acting would
+ * be worse than not acting:
+ *
+ *   - **foreign** — the ref is not this repo's team. A range can carry another
+ *     team's ref (a shared dependency, a quoted ticket), and writing to a team
+ *     this repo was never configured for is the worst failure available here.
+ *   - **unlinked** — the ref is this team's, but no spec in the repo claims it.
+ *     It may be tracker-only work, or a typo in a trailer. Either way nothing
+ *     here knows what it is, so it is reported, not moved.
+ *   - **unfinished** — a spec that has not reached the ceded bucket. Its code
+ *     really is in the release (it landed via `/spec-to-main`), but push still
+ *     owns its workflow state and would bounce it straight back. Exactly one
+ *     writer per issue at any moment beats a visible flip-flop.
+ *
+ * Pure: it takes the spec list as data, so the rules are testable without a repo.
+ */
+function partitionStageMoves({ tickets, teamKey, specs, cededBucket = 'complete' }) {
+  const bucketOf = new Map()
+  for (const spec of specs || []) {
+    if (spec && spec.identifier) bucketOf.set(spec.identifier, spec.bucket)
+  }
+  const key = String(teamKey || '').trim().toUpperCase()
+  const movable = []
+  const foreign = []
+  const unlinked = []
+  const unfinished = []
+  for (const ticket of tickets || []) {
+    const ref = ticket && ticket.ref
+    if (!ref) continue
+    if (key && !ref.toUpperCase().startsWith(`${key}-`)) {
+      foreign.push(ticket)
+    } else if (!bucketOf.has(ref)) {
+      unlinked.push(ticket)
+    } else if (bucketOf.get(ref) !== cededBucket) {
+      unfinished.push({ ...ticket, bucket: bucketOf.get(ref) })
+    } else {
+      movable.push(ticket)
+    }
+  }
+  return { movable, foreign, unlinked, unfinished }
+}
+
+/**
+ * Whether moving from `fromState` to the rung `toKey` runs against the declared
+ * order — and if so, how to say it.
+ *
+ * WARNS, never refuses. A rollback from test and a hotfix going straight to prod
+ * are both legitimate, and a check that blocked either would be wrong on healthy
+ * input. An issue that is on no rung yet is entering the ladder, which is the
+ * normal case and says nothing.
+ *
+ * `lifecycleStates` is the bucket map's own state names, and a state among them
+ * means the issue is at its LIFECYCLE position, not on a rung — even when the
+ * two names coincide. They routinely do: `states.complete` and a final `prod`
+ * rung are both naturally "Done", and without this a spec that had merely been
+ * completed would read as already deployed to prod, so its first real deploy
+ * would be warned about as a move backwards. Bucket wins over ladder here for
+ * the same reason it wins in `bucketForState`.
+ *
+ * @returns {string|null}
+ */
+function stageOrderWarning(stages, fromState, toKey, lifecycleStates = []) {
+  const list = Array.isArray(stages) ? stages : []
+  const to = list.findIndex((s) => s && s.key === toKey)
+  if (to < 0) return null
+  const want = String(fromState || '').toLowerCase().trim()
+  if (!want) return null
+  const lifecycle = new Set(
+    (Array.isArray(lifecycleStates) ? lifecycleStates : [])
+      .filter((n) => typeof n === 'string')
+      .map((n) => n.toLowerCase().trim()),
+  )
+  if (lifecycle.has(want)) return null
+  const from = list.findIndex((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want)
+  if (from < 0) return null
+  if (to < from) return `moves back from "${list[from].key}"`
+  if (to > from + 1) return `skips ${to - from - 1} rung(s) from "${list[from].key}"`
+  return null
+}
+
+module.exports = { ticketsInRange, refsInBody, onlyIgnoredPaths, partitionStageMoves, stageOrderWarning }

package/src/vendor/sync-core/index.js

@@ -13,7 +13,7 @@
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
  */
 
-const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions } = require('./src/normalize.js')
+const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify } = require('./src/compare.js')
 const { readBase, writeBase } = require('./src/base.js')
 const { push, recordPush, projectionOf } = require('./src/push.js')
@@ -39,6 +39,9 @@ module.exports = {
   titleFromText,
   validateStates,
   stateSuggestions,
+  stageForState,
+  remoteStage,
+  LADDER_ORIGIN_BUCKET,
   hashField,
   stableStringify,
   readBase,

package/src/vendor/sync-core/src/compare.js

@@ -43,9 +43,28 @@ function hashField(value) {
 // The spec ISSUE fields the repo owns and pushes: prose + workflow state.
 // Priority, labels, cycles and comments are Linear-native triage — one-way sync
 // neither pushes nor reads them, so a PM's triage is never clobbered.
+//
+// The COMBINED hash, retained for snapshots written before the fields were split
+// (and read by any older CLI still pointed at this repo). New pushes diff
+// `issueFields` below; this stays so neither direction breaks on the other.
 function specIssueHash(p) {
   return hashField({ description: p.description ?? null, state: p.status ?? null })
 }
+
+// Per-field hashes of the same two values.
+//
+// They are hashed SEPARATELY because they have different owners once a spec is
+// finished. The repo owns the description forever, but the workflow state is
+// handed off: a deploy pipeline (see `release.stages`) moves the issue past
+// `complete`, and welding the two meant any prose edit re-emitted the state and
+// dragged the issue back. Diffing them apart is what lets a push touch the
+// description without re-asserting a state someone else now owns.
+function specIssueFieldHashes(p) {
+  return {
+    description: hashField(p.description ?? null),
+    state: hashField(p.status ?? null),
+  }
+}
 // A phase SUB-ISSUE: its name, goal and state (all repo-owned).
 const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
 
@@ -63,7 +82,11 @@ function snapshotOf(projection) {
     return out
   }
   return {
+    // Both shapes are written: `issueFields` is what a current push diffs, and
+    // `issue` keeps a snapshot readable by anything still expecting the combined
+    // hash. Cheap insurance — two SHA-1s of text already in hand.
     issue: specIssueHash(p),
+    issueFields: specIssueFieldHashes(p),
     subIssues: byId(p.subIssues, subIssueHash),
   }
 }
@@ -92,12 +115,43 @@ function planChanges(projection, snapshot) {
   }
 
   const plan = { subIssues }
-  if (snap.issue !== specIssueHash(p)) {
-    plan.issue = { description: p.description ?? null, state: p.status ?? null }
-  }
+  const issue = issueChanges(p, snap)
+  if (issue) plan.issue = issue
   return plan
 }
 
+/**
+ * What changed about the spec issue itself — `{description}`, `{state}`, or
+ * both, or null when neither did.
+ *
+ * Three states, not two: a snapshot may carry the split hashes, only the old
+ * combined one, or nothing at all. Only the first can say which field moved.
+ *
+ * The other two are UNKNOWN, and route to the harmless branch — today's welded
+ * behaviour, sending both fields. Sending a state that did not change is
+ * redundant; withholding one that did would leave the mirror silently stale, and
+ * that is the failure worth avoiding. The push rewrites the snapshot in the new
+ * shape, so a spec passes through `unknown` exactly once.
+ */
+function issueChanges(projection, snapshot) {
+  const p = projection || {}
+  const snap = snapshot || {}
+  const both = () => ({ description: p.description ?? null, state: p.status ?? null })
+
+  const fields = snap.issueFields
+  if (fields === null || typeof fields !== 'object' || Array.isArray(fields)) {
+    // No split hashes recorded: an old snapshot, or no snapshot at all (a
+    // create, which needs both fields anyway).
+    return snap.issue === specIssueHash(p) ? null : both()
+  }
+
+  const want = specIssueFieldHashes(p)
+  const changed = {}
+  if (fields.description !== want.description) changed.description = p.description ?? null
+  if (fields.state !== want.state) changed.state = p.status ?? null
+  return Object.keys(changed).length ? changed : null
+}
+
 // True when a plan would push nothing.
 function isEmptyPlan(plan) {
   return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length
@@ -105,6 +159,8 @@ function isEmptyPlan(plan) {
 
 module.exports = {
   planChanges,
+  issueChanges,
+  specIssueFieldHashes,
   snapshotOf,
   isEmptyPlan,
   hashField,