@skitterbyte/skitterspec-linear 15.0.0 → 17.0.0

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

@@ -54,6 +54,8 @@ const {
   isEmptyRetarget,
   dirtyPaths,
   phaseModeFor,
+  ownsField,
+  remoteDescriptionEdited,
 } = require('../sync-core')
 
 const {
@@ -477,6 +479,13 @@ function specSyncStamp(dir, config, specArg, flags, out) {
  * the skills that call it) writes the field. A push that resolved identity for
  * itself would quietly re-assign a spec to whoever happened to run it — which is
  * how a teammate pushing someone else's branch would steal their work.
+ *
+ * **And it refuses where the write could not travel.** Two preconditions, for
+ * one reason: an unlinked spec has no issue, and a repo that does not own
+ * `assignee` has no field. In either case the stamp would sit in the file doing
+ * nothing while this command's success line promised `next: push it, so Linear
+ * agrees`. The failure mode being guarded is not a silent skip — it is a true-
+ * sounding sentence, which is worse, because nothing later contradicts it.
  */
 function specSyncAssign(dir, config, specArg, flags, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
@@ -492,6 +501,23 @@ function specSyncAssign(dir, config, specArg, flags, out) {
   // An unlinked spec has no issue to assign. Refusing beats stamping a field
   // that would sit in the file doing nothing until someone noticed.
   if (!identifier) problems.push(`${rel} is not linked to Linear — /spec-push it first`)
+  // AND THE SAME REASONING FOR THE FIELD ITSELF. `toFieldSet` drops a field the
+  // repo does not own, so a stamp written here would never reach the tracker —
+  // while this command's success line says `next: push it, so Linear agrees`.
+  // That is not a silent skip, it is an assertion that is untrue, and the cost
+  // is someone believing a spec is assigned for as long as it takes them to
+  // look. `/spec-claim` already refuses on this; the engine beneath it did not.
+  //
+  // Applies to `--release` too. Nothing it could clear was ever pushed, so
+  // releasing is inert here as well, and one command in this function acting on
+  // a field the repo declares it does not own is the inconsistency that would
+  // teach the next reader the check is optional.
+  if (!ownsField(config, 'assignee')) {
+    problems.push(
+      'this repo does not own the assignee field — set sync.fieldOwnership.assignee ' +
+        `to "push" in ${CONFIG_FILE}`,
+    )
+  }
 
   if (problems.length) {
     out.write(
@@ -600,12 +626,45 @@ function specSyncStatus(dir, config, specArg, flags, out) {
       lines.push('  drift: none — Linear workflow-state matches the spec')
     }
     lines.push(...assigneeLines(remote, projection, plan))
+    lines.push(...descriptionDriftLines(remote, snapshot, identifier))
   }
 
   out.write(lines.join('\n') + '\n')
   return 0
 }
 
+/**
+ * The description half of the drift report: has somebody edited the issue's
+ * description on Linear since the repo last pushed it?
+ *
+ * ITS OWN BRANCH, NOT THE `drift:` ONE ABOVE. Workflow-state and description
+ * are independent facts about the same issue — a PM can move the state, edit
+ * the prose, or both — and folding them together would let either hide behind
+ * the other.
+ *
+ * SILENT ON EVERYTHING EXCEPT A POSITIVE ANSWER, which is the whole discipline
+ * here. `remoteDescriptionEdited` returns `null` for every cannot-tell — a
+ * snapshot written before this feature existed (which is every snapshot, on the
+ * first run after an upgrade), a `--remote` file that carries no description,
+ * a description that is not a string — and none of those is evidence that
+ * anything happened. There is deliberately no "drift: none" counterpart either:
+ * the state line has one because it is always askable, and this one is not.
+ * (`.claude/rules/negative-checks.md`.)
+ */
+function descriptionDriftLines(remote, snapshot, identifier) {
+  if (remoteDescriptionEdited(snapshot, remote) !== true) return []
+  const lines = [
+    `  drift: ${identifier}'s description was edited on Linear since the last push`,
+    '         (repo wins on next push — read it before pushing)',
+  ]
+  // The URL, so the reader can go and look. This reports only THAT it changed
+  // and never what it now says: the text is the reader's to read on Linear, and
+  // pulling it in here would put a whole description into whatever is running
+  // this — the same rule the rendered diff already follows.
+  if (remote && typeof remote.url === 'string' && remote.url) lines.push(`         ${remote.url}`)
+  return lines
+}
+
 /**
  * The assignee half of the drift report — nothing at all unless the repo opted
  * `assignee` into `sync.fieldOwnership` (`projection.assignee` is then
@@ -1024,7 +1083,10 @@ function gatherState(dir, flags) {
   // but has not yet reports as "not cached", with `whoami` as the fix, rather
   // than as a fault: not having asked is not the same as having no answer.
   if (config) {
-    const owned = !!(config.sync && config.sync.fieldOwnership && 'assignee' in config.sync.fieldOwnership)
+    // `ownsField`, not `'assignee' in …`: the key is present in every config
+    // once the defaults carry it, so the membership test would read as opted-in
+    // for a repo that declined with `"assignee": "none"`.
+    const owned = ownsField(config, 'assignee')
     state.identity = { owned }
     if (owned) {
       const store = readStore(storePath(flags.env || process.env))
@@ -1851,6 +1913,154 @@ function configuredVocabularyLines(config, names) {
  * Degrades rather than blocks: no key, or a Linear that will not answer, exits 0
  * with an empty list and says why. A missing picker must never fail `/spec`.
  */
+/**
+ * `reattach` — point a spec back at the issue it already has.
+ *
+ * A spec whose `linear_identifier` is gone had no way back: the next push read
+ * it as unlinked and minted a second issue over a perfectly good one. That is
+ * the SKS-283/284 incident — a stray `sed '1s/…'` clobbered a stamped phase
+ * file's opening `---`, and the duplicate had to be cancelled by hand.
+ *
+ * THREE ANSWERS, AND ONLY ONE ACTS. Exactly one unclaimed candidate is stamped;
+ * none says so; more than one refuses and names them. Choosing between two is
+ * the guess `claimPending` refuses to make, and this refuses it for the same
+ * reason.
+ *
+ * WHAT WOULD FOOL A FUZZY VERSION: a title that merely reads similarly. A
+ * near-match is not evidence (`.claude/rules/negative-checks.md` rule 1), and
+ * acting on one would re-point a spec at somebody else's issue — so the match is
+ * EXACT. The cost is that a **renamed** spec is not found, which `--to` answers
+ * and which is said out loud rather than discovered.
+ *
+ * IT WRITES AN ID AND NOTHING ELSE. No title, no description, no state: this is
+ * the one command whose shape makes a pull tempting, and the one-way rule holds
+ * here exactly as everywhere. The next push overwrites the mirror.
+ */
+async function specSyncReattach(dir, config, specArg, flags, out) {
+  const snapshotDir = resolveOrExit(specArg, dir, out)
+  if (!snapshotDir) return 1
+
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const already = linkedIdentifier(path.join(snapshotDir, overviewFile))
+  if (already) {
+    // A linked spec is not broken, and re-pointing one is a different act with
+    // different consequences. Refuse rather than quietly moving it.
+    out.write(`spec-sync reattach: already linked to ${already} — nothing to reattach\n`)
+    return 1
+  }
+
+  const key = resolveApiKey(config, flags.env || process.env)
+  if (!key.ok && !flags.adapter) {
+    out.write(`spec-sync reattach: ${key.error}\n`)
+    return 1
+  }
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  const teamId = (config.linear && config.linear.teamId) || null
+
+  let chosen = null
+  if (flags.to) {
+    if (!ID_RE.test(flags.to)) {
+      out.write(`spec-sync reattach: --to ${flags.to} is not an id like SKI-42\n`)
+      return 1
+    }
+    // NAMED, so nothing is searched and nothing is matched. This is the escape
+    // for a spec whose title has changed since it was linked.
+    const found = await adapter.readIssue(flags.to)
+    if (!found || !found.identifier) {
+      out.write(`spec-sync reattach: no issue ${flags.to}\n`)
+      return 1
+    }
+    chosen = found
+  } else {
+    const title = String(readSnapshot(snapshotDir, config).title || '').trim()
+    if (!title) {
+      out.write('spec-sync reattach: the spec has no title to match on — name one with --to <ISSUE-REF>\n')
+      return 1
+    }
+    let candidates
+    try {
+      candidates = await adapter.searchIssues({ query: title, teamId })
+    } catch (error) {
+      out.write(`spec-sync reattach: ${error.message}\n`)
+      return 1
+    }
+    // The candidate set is what NO spec already holds: an issue another spec is
+    // linked to is not an orphan, it is somebody's live mirror.
+    const claimed = new Set(listSpecs(dir, config).map((sp) => sp.identifier).filter(Boolean))
+    const unclaimed = (candidates || [])
+      .filter((i) => i && i.identifier && !claimed.has(i.identifier))
+      .filter((i) => String(i.title || '').trim() === title)
+
+    if (unclaimed.length === 0) {
+      out.write(
+        `spec-sync reattach: no unclaimed issue titled "${title}" — name one with --to <ISSUE-REF>\n`,
+      )
+      return 1
+    }
+    if (unclaimed.length > 1) {
+      out.write(
+        `spec-sync reattach: ${unclaimed.length} unclaimed issues match — name one with --to <ISSUE-REF>:\n` +
+          unclaimed.map((i) => `  ${i.identifier}  ${i.title}\n`).join(''),
+      )
+      return 1
+    }
+    chosen = unclaimed[0]
+  }
+
+  const lines = [`spec-sync reattach: ${chosen.identifier}`]
+  writeFrontmatter(snapshotDir, config, {
+    linear_identifier: chosen.identifier,
+    linear_url: chosen.url || null,
+  })
+
+  // THE PHASES TOO, or it says it did not. A spec issue with unlinked phases is
+  // half a link: the next push mints a sub-issue per phase beside the ones
+  // already there — the same duplicate, one level down.
+  let children = []
+  try {
+    children = (await adapter.listSubIssues(chosen.id || chosen.identifier)) || []
+  } catch {
+    // A parent whose children cannot be listed is not a parent with none.
+    children = null
+  }
+  if (children === null) {
+    lines.push('  phases not checked — could not list the issue\'s children')
+  } else {
+    // The projection already knows every phase's file and the title it pushes
+    // as the sub-issue's — so the match here is against exactly what a push
+    // would have created, rather than a second reading of the same headings.
+    for (const ph of projectionOf(snapshotDir, config).subIssues || []) {
+      // Already linked — leave it. Reattach fills gaps; it does not re-point
+      // phases that are fine.
+      if (ph.id) continue
+      const ref = ph.ref
+      // `resolvePhaseFile`, exactly as `apply` does it, so a ref resolves to the
+      // same file on both paths rather than by a second spelling of the rule.
+      const file = resolvePhaseFile(snapshotDir, ref)
+      if (!file) continue
+      const phaseTitle = String(ph.name || '').trim()
+      const hits = children.filter((c) => String(c.title || '').trim() === phaseTitle)
+      if (hits.length === 1) {
+        stampSubIssueId(snapshotDir, file, hits[0].identifier)
+        lines.push(`  phase ${ref} → ${hits[0].identifier}`)
+      } else if (hits.length > 1) {
+        // Refused individually, never for the whole run: the spec issue is
+        // linked and one ambiguous phase should not undo that.
+        lines.push(`  phase ${ref}: ${hits.length} children match "${phaseTitle}" — left unlinked`)
+      } else {
+        lines.push(`  phase ${ref}: no child matches "${phaseTitle}" — left unlinked`)
+      }
+    }
+  }
+
+  if (flags.json) {
+    out.write(JSON.stringify({ spec: path.basename(snapshotDir), identifier: chosen.identifier }, null, 2) + '\n')
+  } else {
+    out.write(lines.join('\n') + '\n')
+  }
+  return 0
+}
+
 async function specSyncProjects(dir, config, flags, out) {
   const key = resolveApiKey(config, flags.env || process.env)
   const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
@@ -2340,11 +2550,86 @@ async function specSyncList(dir, config, flags, out) {
  *
  * Every id is stamped the moment its object exists — see `specSyncApply`.
  */
-async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states }) {
+/**
+ * A refusal, as the lines a reader acts on. Pure.
+ *
+ * Two questions, and the old single line answered neither: **what was refused**
+ * and **can waiting help**. `Linear API error: usage limit exceeded` reads like
+ * a throttle, so an hour went into checking a rate limit that was untouched —
+ * while Linear's own explanation, naming the free-plan issue cap and how to
+ * clear it, sat in `extensions.userPresentableMessage`.
+ *
+ * WHAT WOULD FOOL A LOOSER VERSION: treating "no verdict" as retryable. An error
+ * that said nothing about itself — every MCP-path error, every older Linear
+ * response — gets exactly the line it always got and no claim in either
+ * direction (`.claude/rules/negative-checks.md` rule 4).
+ */
+function describeRefusal(error) {
+  const message = (error && error.message) || String(error)
+  const presentable = error && error.userPresentableMessage
+  const code = error && error.code
+  const metric = error && error.meta && error.meta.usageMetric
+  const retryable = error && error.retryable
+
+  // Nothing to add. Say what was always said, and stop.
+  if (!presentable && retryable !== false) return [message]
+
+  const lines = []
+  lines.push(
+    retryable === false
+      ? 'Linear refused this write — not a rate limit, so waiting will not help.'
+      : message,
+  )
+  // The presentable message usually repeats the short one; printing both reads
+  // as two problems, so the short one is dropped where the long one says it.
+  if (presentable) lines.push(`  ${presentable}`)
+  else if (retryable === false) lines.push(`  ${message}`)
+  const tail = [code, metric].filter(Boolean)
+  if (tail.length) lines.push(`  (${tail.join(' · ')})`)
+  return lines
+}
+
+/**
+ * Apply a plan, and say what landed even when it throws.
+ *
+ * A thin wrapper, because the caller has to answer a question the inner
+ * function's `result` knows and a thrown error does not carry: **was anything
+ * written?** That decides whether re-running is a resume or a fresh start, and
+ * the failure line claimed `ids stamped so far are saved` on both paths —
+ * including the one where nothing had been created.
+ *
+ * Counted from what was actually stamped, never inferred from which call
+ * failed: the second reading goes wrong the moment the order changes.
+ */
+async function applyOneSpec(args) {
+  const progress = {}
+  try {
+    return await applyOneSpecInner({ ...args, progress })
+  } catch (error) {
+    const r = progress.result
+    if (error && typeof error === 'object' && error.stamped === undefined) {
+      error.stamped = r ? (r.issue ? 1 : 0) + Object.keys(r.subIssues || {}).length : 0
+      // THE ONE CASE A RE-RUN MAKES WORSE. `created` is what Linear holds;
+      // `stamped` is what the repo recorded. They part company when a create
+      // lands and its stamp cannot be written — and then the next plan still
+      // reads the spec as unlinked, so re-running mints a SECOND issue beside a
+      // perfectly good one. The identifiers travel out so the caller can name
+      // them and send the reader to `reattach` instead.
+      error.created = progress.created || []
+      error.orphans = error.created.slice(error.stamped)
+    }
+    throw error
+  }
+}
+
+async function applyOneSpecInner({ dir, config, snapshotDir, plan, adapter, teamId, project, states, progress, forceNew = false }) {
   const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
   const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
   const lines = []
   const result = { issue: null, subIssues: {} }
+  // Handed out immediately, so a throw from anywhere below still reports what
+  // had been stamped by the time it happened.
+  if (progress) progress.result = result
   const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states) : null)
 
   // Resolve every state id BEFORE the first write, so a bad config.states value
@@ -2358,6 +2643,43 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
   // 1. The spec issue. No identifier yet → this push mints it.
   let parentId = null
   if (!identifier) {
+    // REFUSE TO MINT A TWIN. This is the guard SKS-284 needed: the push was
+    // creating because the spec read as unlinked, while SKS-283 sat unclaimed
+    // with exactly this title. An EXACT match held by no spec is a positive
+    // signal that the issue already exists.
+    //
+    // WHAT WOULD FOOL A FUZZY VERSION: a title that merely reads similarly.
+    // Being wrong here BLOCKS a legitimate push, so a near-match must never
+    // count (`.claude/rules/negative-checks.md` rule 1) — and the cost, a
+    // renamed spec that is not recognised, is answered by `reattach --to`.
+    //
+    // Only on a MINT. An update already has its issue, and checking one would
+    // find its own mirror.
+    if (!forceNew && adapter.searchIssues) {
+      const wanted = String(plan.title || readSnapshot(snapshotDir, config).title || '').trim()
+      if (wanted) {
+        let found = []
+        try {
+          found = (await adapter.searchIssues({ query: wanted, teamId })) || []
+        } catch {
+          // A search we could not run is not evidence of an orphan. Carry on and
+          // mint — the cannot-tell case goes to the harmless branch, which here
+          // is the one that does the work the caller asked for (rule 4).
+          found = []
+        }
+        const claimed = new Set(listSpecs(dir, config).map((sp) => sp.identifier).filter(Boolean))
+        const twin = found.find(
+          (i) => i && i.identifier && !claimed.has(i.identifier) && String(i.title || '').trim() === wanted,
+        )
+        if (twin) {
+          throw new Error(
+            `${twin.identifier} is already titled "${wanted}" and no spec claims it — ` +
+              `adopt it with \`spec-sync reattach ${path.basename(snapshotDir)} --to ${twin.identifier}\`, ` +
+              'or pass --force-new to create a second',
+          )
+        }
+      }
+    }
     const created = await adapter.createIssue(withoutNull({
       title: readSnapshot(snapshotDir, config).title,
       teamId,
@@ -2370,6 +2692,10 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
     }))
     if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
     parentId = created.id
+    // NOTED BEFORE IT IS STAMPED. The stamp can fail — a read-only tree, a
+    // permission error — and then this identifier exists in Linear with nothing
+    // in the repo pointing at it. Recorded here so the failure can name it.
+    if (progress) (progress.created = progress.created || []).push(created.identifier)
     // Stamped NOW: an interrupt after this point must not mint a second issue.
     writeFrontmatter(snapshotDir, config, { linear_identifier: created.identifier, linear_url: created.url })
     result.issue = { id: created.id, identifier: created.identifier, url: created.url }
@@ -2379,6 +2705,22 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
     if (!existing || !existing.id) throw new Error(`no Linear issue found for ${identifier}`)
     parentId = existing.id
     result.issue = { id: existing.id, identifier: existing.identifier, url: existing.url }
+
+    // SOMEONE ELSE EDITED THE DESCRIPTION SINCE WE LAST PUSHED, and this write
+    // is about to replace it. Said here because this is the one moment the
+    // engine has both halves in hand for free — the read-back it already does,
+    // and the snapshot on disk — so no extra round trip buys the warning.
+    //
+    // A WARNING AND NEVER A REFUSAL. One-way sync means the repo wins, and that
+    // is not in question; what was wrong was winning silently. Turning this
+    // into a gate would stop a legitimate push over a typo fix, and the whole
+    // point is that only a person can judge which it was. The exit code is
+    // untouched, deliberately.
+    if (remoteDescriptionEdited(readBase(dir, identifier, config), existing) === true) {
+      lines.push(
+        `  !! ${identifier}'s description was edited on Linear since the last push — this replaces it`,
+      )
+    }
     if (plan.issue) {
       const updates = withoutNull({
         description: plan.issue.description,
@@ -2405,6 +2747,7 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
       stateId: stateId(sub.state),
     }))
     if (!created || !created.identifier) throw new Error(`Linear returned no issue for sub-issue ${sub.ref}`)
+    if (progress) (progress.created = progress.created || []).push(created.identifier)
     const file = resolvePhaseFile(snapshotDir, sub.ref)
     if (!file) throw new Error(`no phase file for ref ${sub.ref}`)
     stampSubIssueId(snapshotDir, file, created.identifier)
@@ -2757,7 +3100,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
     out.write(`spec-sync apply: ${error.message}\n`)
     return 1
   }
-  const shared = { dir, config, adapter, teamId, project: flags.project, states }
+  const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew }
 
   if (!bulk) {
     const lines = ['spec-sync apply: transport = api']
@@ -2767,8 +3110,25 @@ async function specSyncApply(dir, config, specArg, flags, out) {
     } catch (error) {
       // Whatever landed before the failure is already stamped, so re-running
       // resumes rather than duplicating — say so instead of leaving it ambiguous.
+      const said = describeRefusal(error)
       out.write(
-        [...lines, `  !! ${error.message}`, '  ids stamped so far are saved — re-run to resume without duplicating'].join('\n') + '\n',
+        [
+          ...lines,
+          `  !! ${said[0]}`,
+          ...said.slice(1).map((l) => `  ${l}`),
+          // THREE ENDINGS, and the third is the one a re-run makes worse.
+          // Something exists in Linear that the repo does not record, so the
+          // next plan still reads this spec as unlinked and re-running mints a
+          // second issue beside it. Name what exists and send the reader to
+          // `reattach` instead.
+          error && error.orphans && error.orphans.length
+            ? `  ${error.orphans.join(', ')} ${error.orphans.length === 1 ? 'exists' : 'exist'} in Linear but could not be ` +
+              'recorded — reattach rather than re-running, or a second will be minted:\n' +
+              `    skitterspec spec-sync reattach ${plan && plan.spec ? plan.spec : '<spec>'} --to ${error.orphans[0]}`
+            : error && error.stamped
+              ? '  ids stamped so far are saved — re-run to resume without duplicating'
+              : '  nothing was created — re-run once the cause is resolved',
+        ].join('\n') + '\n',
       )
       return 1
     }
@@ -2937,12 +3297,17 @@ function specSyncInitConfig(dir, flags, out) {
   // shape — a blank key or a duplicate fails there, in one place, rather than
   // being re-checked here and drifting from the loader.
   if (flags.stages.length) draft.release = { stages: flags.stages }
-  // Assignment is opt-in and rides `fieldOwnership` rather than a key of its
-  // own. Only `assignee` is written: the loader merges this map PER KEY onto the
+  // Assignment ships ON, so the flag is the OPT-OUT and it writes `none`. The
+  // previous `--assign` is gone rather than kept as a no-op: a flag whose meaning
+  // the default flip inverted, still accepted and doing nothing, is the
+  // record-and-do-nothing shape this project is against — and an unknown flag
+  // already fails loudly, which is a better answer than silence.
+  //
+  // Only `assignee` is written: the loader merges this map PER KEY onto the
   // defaults, so restating the other three would freeze today's defaults into
   // the file and quietly opt the repo out of any later change to them — the very
   // thing "only the keys that differ" exists to avoid.
-  if (flags.assign) draft.sync = { fieldOwnership: { assignee: 'push' } }
+  if (flags.noAssign) draft.sync = { fieldOwnership: { assignee: 'none' } }
 
   for (const bucket of Object.keys(flags.stateNames)) {
     if (!LIFECYCLE_BUCKETS.includes(bucket)) {
@@ -3246,6 +3611,279 @@ function repoConfigKeyCommand(dir) {
   }
 }
 
+// --- preserve: the reporter's original, kept before the spec replaces it ------
+
+/**
+ * The marker that makes preserving idempotent.
+ *
+ * An HTML comment, so it does not render in Linear's comment body — the reader
+ * sees a clean quote, and the machine sees a string it can match on. It is
+ * matched with `includes`, never parsed, so a Linear that reformats the
+ * surrounding markdown cannot detach it from the comment it identifies.
+ *
+ * WHAT WOULD FOOL THIS: a Linear that strips HTML comments on save. Then every
+ * run reads as "not yet preserved" and posts again. That is why
+ * `originalPreserved` ALSO matches the visible lead-in — two independent
+ * signals, either of which is enough, so losing one degrades to a duplicate
+ * check rather than to duplicate comments.
+ */
+const PRESERVE_MARKER = '<!-- skitterspec:original-report -->'
+
+// The visible half of the marker — a heading a human reads, and the fallback
+// the idempotence check falls back to if the HTML comment does not survive.
+const PRESERVE_HEADING = '**Original report**'
+
+/**
+ * Compose the preserving comment. Pure: no I/O, no clock, no randomness — the
+ * caller supplies everything, which is what makes this testable without a
+ * network and deterministic under `--json`.
+ *
+ * The description is quoted VERBATIM and never reflowed. Canonicalising it here
+ * would defeat the point: this comment exists precisely because the generated
+ * description is a canonicalised projection, and the thing worth keeping is
+ * what the reporter actually typed.
+ */
+function preserveComment(description, specName) {
+  return [
+    `${PRESERVE_HEADING} — preserved before this issue became a spec.`,
+    '',
+    `This issue's description is now a generated mirror of \`${specName}\`, ` +
+      'pushed from the repo. Edit the spec, not this issue. This is what was filed:',
+    '',
+    '---',
+    '',
+    String(description),
+    '',
+    PRESERVE_MARKER,
+  ].join('\n')
+}
+
+/**
+ * Has this issue already been preserved?
+ *
+ * Two signals, either sufficient: the hidden marker, and the visible lead-in.
+ * A POSITIVE match is what stops a second post, so the cost of being wrong runs
+ * one way only — a missed match posts a duplicate comment, which is untidy; a
+ * spurious match would silently skip preserving the one thing this exists for.
+ * Both signals are therefore specific enough that ordinary prose cannot trip
+ * them, and neither is an absence (`.claude/rules/negative-checks.md` rule 1).
+ */
+function originalPreserved(comments) {
+  if (!Array.isArray(comments)) return false
+  return comments.some((c) => {
+    const body = c && typeof c.body === 'string' ? c.body : ''
+    return body.includes(PRESERVE_MARKER) || body.startsWith(PRESERVE_HEADING)
+  })
+}
+
+/**
+ * `spec-sync preserve <spec> [--text <file>] [--json]` — post the issue's
+ * current description as a comment, before a push replaces it with the spec.
+ *
+ * ORDERING IS THE CORRECTNESS CONDITION. Run before the linking push, this
+ * captures the reporter's words. Run after it, it would capture the generated
+ * spec and report success — so the snapshot check below warns about exactly
+ * that, and the adoption skills order the call explicitly.
+ *
+ * EVERY CANNOT-TELL EXITS 0 AND SAYS NOTHING BEYOND WHY. Preserving is a
+ * best-effort courtesy on top of adoption: an unresolvable issue, a description
+ * that is absent, a project that declined — none of those is a reason to fail
+ * the skill that called this, and none is evidence that anything went wrong.
+ */
+async function specSyncPreserve(dir, config, specArg, flags, out) {
+  const snapshotDir = resolveOrExit(specArg, dir, out)
+  if (!snapshotDir) return 1
+  const specName = path.basename(snapshotDir)
+  const say = (result) => {
+    if (flags.json) out.write(JSON.stringify(result, null, 2) + '\n')
+    // NO LINES MEANS NO OUTPUT, not a blank one. The opt-out is the case this
+    // is for: a project that declined must see nothing, and a bare newline is
+    // still a trace of a feature it turned off.
+    else if (result.lines.length) out.write(result.lines.join('\n') + '\n')
+    return 0
+  }
+
+  // The opt-out, checked first: a project that declined must see no trace of
+  // the feature, including a line about why it did nothing.
+  if (!(config.intake && config.intake.preserveOriginal)) {
+    return say({ spec: specName, preserved: false, reason: 'declined', lines: [] })
+  }
+
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
+  if (!identifier) {
+    return say({
+      spec: specName,
+      preserved: false,
+      reason: 'unlinked',
+      lines: [`spec-sync preserve: ${specName} is not linked to an issue — nothing to preserve`],
+    })
+  }
+
+  // ALREADY PUSHED, so the description on the issue is this spec's own mirror
+  // rather than anyone's original. A warning and not a refusal: a snapshot can
+  // be absent for reasons that have nothing to do with ordering (never
+  // committed, a fresh worktree), so this reads as "you may be late", never as
+  // "you are wrong".
+  const late = readBase(dir, identifier, config)
+    ? [
+        `  note: ${identifier} has been pushed before, so its description is already`,
+        '        the generated mirror — preserve runs before the linking push',
+      ]
+    : []
+
+  // `--text <file>` is the MCP path's supply line: the engine cannot call an
+  // MCP tool, so the skill reads the issue and hands the description over in a
+  // file, exactly as `--workspace-states` and `--stored` already do.
+  let description = null
+  if (flags.text) {
+    try {
+      description = fs.readFileSync(flags.text, 'utf-8')
+    } catch (error) {
+      out.write(`spec-sync preserve: cannot read --text ${flags.text}: ${error.message}\n`)
+      return 1
+    }
+  }
+
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+
+  if (transport === 'mcp' && description == null) {
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'mcp',
+      marker: PRESERVE_MARKER,
+      lines: [
+        'spec-sync preserve: transport = mcp (no writes made here)',
+        key.ok ? '  --via mcp was requested' : `  ${key.error}`,
+        ...late,
+        `  read ${identifier}'s description, check its comments for the marker`,
+        `    ${PRESERVE_MARKER}`,
+        '  and if it is absent, post this comment with the Linear comment tool:',
+        '',
+        ...preserveComment('<the description you just read>', specName).split('\n').map((l) => `    ${l}`),
+      ],
+    })
+  }
+
+  if (transport === 'mcp') {
+    // A description was supplied, so the body can be composed here even though
+    // the post itself belongs to the skill.
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'mcp',
+      marker: PRESERVE_MARKER,
+      body: preserveComment(description, specName),
+      lines: [
+        'spec-sync preserve: transport = mcp (no writes made here)',
+        ...late,
+        `  check ${identifier}'s comments for ${PRESERVE_MARKER}, and if absent post:`,
+        '',
+        ...preserveComment(description, specName).split('\n').map((l) => `    ${l}`),
+      ],
+    })
+  }
+
+  if (!key.ok) {
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'no-key',
+      lines: [`spec-sync preserve: skipped — ${key.error}`],
+    })
+  }
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  let issue
+  try {
+    issue = await adapter.readIssue(identifier)
+  } catch (error) {
+    // Unreachable is not evidence that nothing needs preserving — it is no
+    // evidence at all, so it exits 0 and the caller carries on (rule 4).
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'unreachable',
+      lines: [`spec-sync preserve: could not read ${identifier} — ${error.message}`],
+    })
+  }
+  if (!issue || !issue.id) {
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'not-found',
+      lines: [`spec-sync preserve: no Linear issue found for ${identifier}`],
+    })
+  }
+
+  // A description that is not a string was never read, and one that is empty
+  // has nothing in it worth keeping. Both are silent no-ops rather than an
+  // empty comment claiming to preserve something.
+  const text = description != null ? description : issue.description
+  if (typeof text !== 'string' || !text.trim()) {
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'no-description',
+      lines: [`spec-sync preserve: ${identifier} has no description to preserve`],
+    })
+  }
+
+  let comments
+  try {
+    comments = await adapter.listComments(issue.id)
+  } catch (error) {
+    // THE CANNOT-TELL BRANCH THAT MATTERS. Without the listing there is no way
+    // to know whether this already ran, and the two readings cost differently:
+    // skipping loses the original, posting again leaves a duplicate. Duplicate
+    // is the harmless one, so a failed read does not stop the write.
+    comments = null
+    late.push(`  note: could not list ${identifier}'s comments (${error.message}) — posting anyway`)
+  }
+  if (comments && originalPreserved(comments)) {
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'already',
+      lines: [`spec-sync preserve: ${identifier} already carries the original report — nothing posted`],
+    })
+  }
+
+  const body = preserveComment(text, specName)
+  try {
+    await adapter.createComment(issue.id, body)
+  } catch (error) {
+    return say({
+      spec: specName,
+      identifier,
+      preserved: false,
+      reason: 'refused',
+      lines: [`spec-sync preserve: Linear refused the comment on ${identifier} — ${error.message}`],
+    })
+  }
+
+  return say({
+    spec: specName,
+    identifier,
+    preserved: true,
+    reason: 'posted',
+    lines: [
+      `spec-sync preserve: ${identifier} — original report preserved as a comment`,
+      ...late,
+      `  ${text.length} characters kept verbatim; the push may now replace the description`,
+    ],
+  })
+}
+
 // Read stdin to completion (for `--stdin`).
 function readAllStdin(input) {
   return new Promise((resolve, reject) => {
@@ -3299,7 +3937,7 @@ async function specSync(rest, io = {}) {
   // after the loop.
   const unknownFlags = []
   const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null, plan: null, via: null, project: null, all: null,
-    mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, stateArgs: [], statesFile: null, stages: [], limit: null, next: null, archived: false, assign: false, mine: false, by: null, inProgress: false }
+    mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, stateArgs: [], statesFile: null, stages: [], limit: null, next: null, archived: false, noAssign: false, mine: false, by: null, inProgress: false, text: null }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
@@ -3308,6 +3946,9 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--apply') flags.apply = true
     else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
     else if (args[i] === '--stored') flags.stored = path.resolve(args[++i])
+    // `preserve --text <file>`: the description to keep, when the caller read it
+    // over MCP and the engine cannot.
+    else if (args[i] === '--text') flags.text = path.resolve(args[++i])
     else if (args[i] === '--mcp') flags.mcp = path.resolve(args[++i])
     else if (args[i] === '--plan') flags.plan = path.resolve(args[++i])
     else if (args[i] === '--via') flags.via = args[++i]
@@ -3328,6 +3969,9 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--url') flags.url = args[++i]
     else if (args[i] === '--sub') flags.subs.push(args[++i])
     else if (args[i] === '--force') flags.force = true
+    // Distinct from `--force`, deliberately. That one overrides other guards;
+    // this one says "the duplicate title is real, create a second issue".
+    else if (args[i] === '--force-new') flags.forceNew = true
     else if (args[i] === '--yes') flags.yes = true
     else if (args[i] === '--check-remote') flags.remoteCheck = true
     else if (args[i] === '--stdin') flags.stdin = true
@@ -3339,7 +3983,7 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--unset') flags.unset = true
     else if (args[i] === '--to') flags.to = String(args[++i] || '').trim()
     else if (args[i] === '--release') flags.release = true
-    else if (args[i] === '--assign') flags.assign = true
+    else if (args[i] === '--no-assign') flags.noAssign = true
     else if (args[i] === '--limit') flags.limit = Number(args[++i]) || 0
     else if (args[i] === '--cursor') flags.cursor = String(args[++i] || '').trim()
     else if (args[i] === '--command') flags.command = String(args[++i] || '').trim()
@@ -3449,6 +4093,8 @@ async function specSync(rest, io = {}) {
           'It computes the create/update plan and writes nothing; `spec-sync apply` applies it.\n',
       )
       return 1
+    case 'reattach':
+      return specSyncReattach(dir, config, positional[0], flags, out)
     case 'stamp':
       return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
@@ -3479,6 +4125,8 @@ async function specSync(rest, io = {}) {
       return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
     case 'verify':
       return specSyncVerify(dir, config, positional[0], flags, out) || 0
+    case 'preserve':
+      return (await specSyncPreserve(dir, config, positional[0], flags, out)) || 0
     case 'linked':
       specSyncLinked(dir, config, flags, out)
       return 0
@@ -3497,19 +4145,21 @@ async function specSync(rest, io = {}) {
         '       skitterspec spec-sync apply <spec> --plan <file> [--via api|mcp] [--project id] [--json]\n' +
         '       skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync verify <spec> --stored <file>\n' +
+        '       skitterspec spec-sync preserve <spec> [--text <file>] [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
         '       skitterspec spec-sync linked [--json]\n' +
         '       skitterspec spec-sync ref [<spec>] [--json]\n' +
         '       skitterspec spec-sync released [<range>] [--json]\n' +
         '       skitterspec spec-sync stage <key> [<range>] [--apply] [--json]\n' +
+        '       skitterspec spec-sync reattach <spec> [--to <ISSUE-REF>] [--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' +
         '                    [--intake-label L] [--bug-labels a,b] [--hotfix-labels a,b]\n' +
-        '                    [--assign]\n' +
+        '                    [--no-assign]\n' +
         '                    [--state <bucket>=<name> …] [--states <file>] [--force] [--json]\n')
       return 0
   }
 }
 
-module.exports = { specSync, listSpecs, promptHidden }
+module.exports = { specSync, listSpecs, promptHidden, describeRefusal }