@skitterbyte/skitterspec-jira 1.0.0 → 2.0.0

package/src/vendor/provider-kit/src/released.js

@@ -7,16 +7,25 @@
  * names never reach it. A commit's `Refs:` trailer is therefore the only place
  * the ticket survives into the range a release scans — see the
  * `commit-trailers` rule. Nothing here is tracker-specific: the identifier
- * shape (`KEY-123`) and the team-key prefix are common to the trackers this
- * scans for, which is why the module lives in the kit.
+ * shape defaults to `KEY-123` (Linear, Jira), and a provider whose refs look
+ * different (GitHub's `#123`) passes its own `refPattern`.
  *
  * The parsing half is pure and takes commits as data, so the rules below are
  * testable without git. Reading the range, and enriching refs with issue titles,
  * belong to the caller.
  */
 
-// An issue identifier: uppercase team key, dash, number.
+// An issue identifier: uppercase team key, dash, number. The default, used
+// whenever a caller passes no `refPattern`.
 const IDENTIFIER_RE = /\b[A-Z][A-Z0-9]*-\d+\b/g
+// A GitHub issue ref in the same repo: `#123`.
+//
+// WHAT WOULD FOOL IT: `#` is also how a commit says "issue number" in prose and
+// how `owner/repo#123` names ANOTHER repo's issue. Prose is excluded by the
+// trailer anchor (only a `Refs:` line is scanned); the cross-repo form is
+// excluded by the lookbehind, so a ref into some other repo never lands on this
+// one's release.
+const GITHUB_REF_RE = /(?<![\w/.-])#\d+\b/g
 // A `Refs:` trailer line. Anchored, so it is a line of its own — never prose
 // that happens to mention the word.
 const TRAILER_RE = /^Refs:[ \t]*(.+?)[ \t]*$/
@@ -34,7 +43,8 @@ const TRAILER_RE = /^Refs:[ \t]*(.+?)[ \t]*$/
  * which is worse than missing a ticket: the missing one is noticed when someone
  * looks for it, the invented one never is.
  */
-function refsInBody(body) {
+function refsInBody(body, refPattern) {
+  const pattern = asGlobal(refPattern) || IDENTIFIER_RE
   const found = []
   let fenced = false
   for (const raw of String(body || '').split('\n')) {
@@ -48,11 +58,19 @@ function refsInBody(body) {
     if (/^ {4,}|\t/.test(line)) continue
     const m = TRAILER_RE.exec(line.trim() === line ? line : line.trimStart())
     if (!m) continue
-    for (const id of m[1].match(IDENTIFIER_RE) || []) found.push(id)
+    for (const id of m[1].match(pattern) || []) found.push(id)
   }
   return found
 }
 
+// `String.prototype.match` only returns every hit for a GLOBAL regex; a
+// provider passing `/#\d+/` would otherwise get its first ref and lose the rest
+// in silence. Anything that is not a RegExp is no pattern at all.
+function asGlobal(pattern) {
+  if (!(pattern instanceof RegExp)) return null
+  return pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`)
+}
+
 /**
  * Whether a commit's changed paths are ENTIRELY bookkeeping.
  *
@@ -103,10 +121,18 @@ function onlyIgnoredPaths(paths, ignorePaths) {
  * Fold commits into the report a release needs.
  *
  * @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}}
+ * @param {{ignorePaths?:string[], refPattern?:RegExp, foreignPatterns?:RegExp[]}} [options]
+ *   `ignorePaths` marks bookkeeping — see `onlyIgnoredPaths`. Omitted (or
+ *   empty) means nothing is ignored, so the report is what it was before the
+ *   filter existed. `refPattern` is this provider's ref shape (see
+ *   `refsInBody`). `foreignPatterns` are OTHER trackers' ref shapes this repo
+ *   used before — a repo that moved from Linear to GitHub still has
+ *   `Refs: SKS-29` all through its history, and those commits were referenced,
+ *   just not to this tracker. They are counted as `historical` rather than
+ *   `unreferenced`, which exists to surface a MISSED trailer.
+ * @returns {{tickets: Array<{ref:string, commits:number}>, unreferenced:number, ignored:number, total:number, historical?:number}}
+ *   `historical` is present only when `foreignPatterns` was given, so a
+ *   provider that never moved trackers sees exactly the shape it always did.
  *   `tickets` is deduped in FIRST-SEEN order: a ticket touched by eight commits
  *   is listed once, where it first appears, not eight times. `ignored` is
  *   reported rather than merely subtracted — a filter that removes commits in
@@ -114,9 +140,12 @@ function onlyIgnoredPaths(paths, ignorePaths) {
  */
 function ticketsInRange(commits, options = {}) {
   const ignorePaths = (options && options.ignorePaths) || []
+  const refPattern = options && options.refPattern
+  const foreign = ((options && options.foreignPatterns) || []).map(asGlobal).filter(Boolean)
   const seen = new Map()
   let unreferenced = 0
   let ignored = 0
+  let historical = 0
   for (const commit of commits || []) {
     if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
       // Not counted as unreferenced either: that number exists to surface a
@@ -124,103 +153,67 @@ function ticketsInRange(commits, options = {}) {
       ignored++
       continue
     }
-    const refs = [...new Set(refsInBody(commit && commit.body))]
+    const refs = [...new Set(refsInBody(commit && commit.body, refPattern))]
     if (!refs.length) {
-      unreferenced++
+      // A POSITIVE signal, never an absence: only a trailer that actually
+      // carries an older tracker's ref makes a commit historical. A commit with
+      // no trailer at all is still the gap `unreferenced` is there to name.
+      if (foreign.some((p) => refsInBody(commit && commit.body, p).length)) historical++
+      else unreferenced++
       continue
     }
     for (const ref of refs) seen.set(ref, (seen.get(ref) || 0) + 1)
   }
-  return {
+  const report = {
     tickets: [...seen.entries()].map(([ref, count]) => ({ ref, commits: count })),
     unreferenced,
     ignored,
     total: (commits || []).length,
   }
+  if (foreign.length) report.historical = historical
+  return report
 }
 
 /**
- * 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:
+ * Name the spec behind each ticket a range contains, so a consumer can act on
+ * a release without a second lookup.
  *
- *   - **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.
+ * A ref no spec has stamped keeps `spec: null` and `url: null` — never a guess
+ * from a similar folder name. It may be tracker-only work, or a typo in a
+ * trailer, and a consumer acting on an invented match is worse than one told
+ * there was none.
  *
- * Pure: it takes the spec list as data, so the rules are testable without a repo.
+ * Pure: it takes the spec list as data (`listSpecs` rows), so it is 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)
+function nameTickets(tickets, specs) {
+  const byRef = new Map()
+  for (const s of specs || []) {
+    if (s && s.identifier && !byRef.has(s.identifier)) byRef.set(s.identifier, s)
   }
-  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 }
+  return (tickets || []).map((t) => {
+    const s = byRef.get(t.ref)
+    return { ...t, spec: s ? s.spec : null, url: s ? s.url || null : null }
+  })
 }
 
-/**
- * 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()),
+// The answer a removed release verb gives (`release`, `stage`). Exit 1, not a
+// quiet 0: a pipeline still calling one must learn it no longer mirrors
+// anything, rather than go on believing it does.
+function refuseRemovedVerb(out, program, verb) {
+  out.write(
+    `${program} ${verb}: removed — skitterspec no longer writes release or deploy state; ` +
+      `\`${program} released <range> --json\` lists the tickets a range contains, for your own tooling to act on\n`,
   )
-  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
+  return 1
 }
 
-module.exports = { ticketsInRange, refsInBody, onlyIgnoredPaths, partitionStageMoves, stageOrderWarning }
+module.exports = {
+  ticketsInRange,
+  refuseRemovedVerb,
+  nameTickets,
+  refsInBody,
+  onlyIgnoredPaths,
+  IDENTIFIER_RE,
+  GITHUB_REF_RE,
+}

package/src/vendor/provider-kit/src/specs.js

@@ -14,7 +14,16 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
-const { BUCKETS, findSpecFolder } = require('../../../env/resolve.js')
+const { execFileSync } = require('node:child_process')
+
+const {
+  BUCKETS,
+  findSpecFolder,
+  resolveSpec,
+  liveWorktreePaths,
+  resolvePrimaryCheckout,
+} = require('../../../env/resolve.js')
+const { loadEnvConfig } = require('../../../env/config.js')
 const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
 
 function makeSpecHelpers({ program = 'spec-sync' } = {}) {
@@ -45,22 +54,32 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
   // Read a spec's stamped identifier without throwing: an unlinked spec, an
   // unreadable file and a spec with no frontmatter all read as `null`.
   function linkedIdentifier(overviewPath, config) {
-    const field = fieldsOf(config).identifier
+    return linkedFields(overviewPath, config).identifier
+  }
+
+  // The stamped identifier AND url, each `null` when absent. The url is only
+  // ever what a push stamped — never built from the identifier, because a url
+  // constructed here would be a guess about a tracker's address scheme.
+  function linkedFields(overviewPath, config) {
+    const fields = fieldsOf(config)
     let raw
     try {
       raw = fs.readFileSync(overviewPath, 'utf-8')
     } catch {
-      return null
+      return { identifier: null, url: null }
     }
     const { data } = parseFrontmatter(raw)
-    return data[field] ? String(data[field]) : null
+    return {
+      identifier: data[fields.identifier] ? String(data[fields.identifier]) : null,
+      url: fields.url && data[fields.url] ? String(data[fields.url]) : null,
+    }
   }
 
   // Every spec under specs/<bucket>/, paired with the tracker issue it is
   // linked to (`null` when it has never been pushed). Folder specs read
   // `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
   // itself. Sorted for stable output.
-  function listSpecs(dir, config) {
+  function listSpecs(dir, config, options = {}) {
     const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
     const specs = []
     for (const bucket of BUCKETS) {
@@ -83,12 +102,75 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
         } else {
           continue
         }
-        specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath, config) })
+        const linked = linkedFields(overviewPath, config)
+        const row = { spec: name, bucket, identifier: linked.identifier }
+        // Opt-in, so every listing that never asked for a url keeps its shape.
+        if (options.urls) row.url = linked.url
+        specs.push(row)
       }
     }
     return specs.sort((a, b) => a.spec.localeCompare(b.spec))
   }
 
+  // `listSpecs`, but each spec's BUCKET read from where that spec actually
+  // lives. `/spec-start` moves a spec to `in-progress/` on its own branch, so
+  // on the base branch an in-flight spec still reads `backlog` — and a spec
+  // authored in its own worktree and not yet landed is not here at all. Each
+  // live worktree is read too, and a spec found in ITS OWN worktree (the path
+  // `resolveSpec` names for it) wins over every other copy. `source` says
+  // which: `here`, `worktree`, or `other-tree` for a spec only some other
+  // worktree carries.
+  //
+  // WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is
+  // still live, so a finished spec can read from a stale tree. And with no
+  // `env.config.json` there is no worktree layout to resolve, so this is
+  // exactly `listSpecs` — the current tree's answer, as before.
+  function listSpecsLive(dir, config) {
+    const here = listSpecs(dir, config).map((s) => ({ ...s, source: 'here' }))
+    const git = (args) => {
+      try {
+        return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+      } catch {
+        return null
+      }
+    }
+    let primary
+    let env
+    try {
+      primary = resolvePrimaryCheckout(dir, git) || dir
+      env = loadEnvConfig(primary)
+    } catch {
+      return here
+    }
+    if (!env.present) return here
+    // Compared as REAL paths: git reports a worktree resolved through
+    // symlinks (macOS /var → /private/var) where `resolveSpec` does not.
+    const real = (p) => {
+      try {
+        return fs.realpathSync(p)
+      } catch {
+        return path.resolve(p)
+      }
+    }
+    const self = real(dir)
+    const byName = new Map(here.map((s) => [s.spec, s]))
+    for (const listed of liveWorktreePaths(git)) {
+      const tree = real(listed)
+      if (tree === self) continue
+      for (const s of listSpecs(tree, config)) {
+        let own = null
+        try {
+          own = real(resolveSpec(s.spec, primary, env.config, { searchDirs: [tree] }).worktreePath)
+        } catch {
+          own = null
+        }
+        if (own === tree) byName.set(s.spec, { ...s, source: 'worktree' })
+        else if (!byName.has(s.spec)) byName.set(s.spec, { ...s, source: 'other-tree' })
+      }
+    }
+    return [...byName.values()].sort((a, b) => a.spec.localeCompare(b.spec))
+  }
+
   // Resolve a spec argument to its folder, or null with a message on stdout.
   // EVERY failure path here must print and EVERY caller must return a non-zero
   // code: a push skill checks $? before it applies a plan, so a resolve failure
@@ -160,7 +242,7 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
     return lines
   }
 
-  return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
+  return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr, verifyLines }
 }
 
 module.exports = { makeSpecHelpers }

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

@@ -13,8 +13,8 @@
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
  */
 
-const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
-const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited } = require('./src/compare.js')
+const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
+const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
 const { readBase, writeBase } = require('./src/base.js')
 const { push, recordPush, projectionOf } = require('./src/push.js')
 const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
@@ -41,12 +41,11 @@ module.exports = {
   push,
   recordPush,
   remoteWorkflowState,
+  remoteStateReading,
+  stateNamesFor,
   titleFromText,
   validateStates,
   stateSuggestions,
-  stageForState,
-  remoteStage,
-  LADDER_ORIGIN_BUCKET,
   hashField,
   stableStringify,
   readBase,
@@ -66,6 +65,7 @@ module.exports = {
   // Did someone else edit the tracker's description since the last push?
   // Three-valued; `null` is cannot-tell and must never be reported as drift.
   remoteDescriptionEdited,
+  remoteSubIssueEdited,
   // Provider seams: the frontmatter field vocabulary and the markdown dialect
   // a provider's config supplies (`config.fields` / `config.dialect`).
   fieldsOf,

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

@@ -58,12 +58,12 @@ function specIssueHash(p) {
 
 // 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.
+// They are hashed SEPARATELY because skitterspec tells the tracker about its
+// own transitions and nothing else. The description is resent whenever it
+// changes; the state only when the spec itself moves. Welding the two meant any
+// prose edit re-emitted the state and dragged back an issue someone had moved
+// on the tracker — which is theirs to do. Diffing them apart is what lets a
+// push touch the description without re-asserting a state.
 function specIssueFieldHashes(p, config) {
   const hashes = {
     description: hashField(p.description ?? null),
@@ -137,6 +137,30 @@ function remoteDescriptionEdited(snapshot, remote, config) {
 
   return hashField(stream(text, config)) !== recorded
 }
+
+/**
+ * The same question for one phase SUB-ISSUE: has its body been edited on the
+ * tracker since the last push? It matters most where the tracker renders a
+ * phase's task list as clickable boxes — GitHub does — because ticking one
+ * there is an edit the next push replaces.
+ *
+ * The same three answers and the same cannot-tells as above, plus one of its
+ * own: no `subIssueStreams` in the snapshot, or none for this id. Every
+ * snapshot written before this existed lacks it, and a phase whose body was
+ * never sent (no goal) has nothing recorded.
+ *
+ * @param {object|null} snapshot  the committed last-pushed snapshot
+ * @param {string} id             the sub-issue's id as the snapshot keys it
+ * @param {object|null} remote    what the tracker currently holds for it
+ * @returns {boolean|null}
+ */
+function remoteSubIssueEdited(snapshot, id, remote, config) {
+  const streams = snapshot && snapshot.subIssueStreams
+  if (!streams || typeof streams !== 'object' || Array.isArray(streams)) return null
+  const recorded = streams[String(id)]
+  if (typeof recorded !== 'string' || !recorded) return null
+  return remoteDescriptionEdited({ issueFields: { descriptionStream: recorded } }, remote, config)
+}
 // 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 })
 
@@ -160,6 +184,13 @@ function snapshotOf(projection, config) {
     issue: specIssueHash(p),
     issueFields: specIssueFieldHashes(p, config),
     subIssues: byId(p.subIssues, subIssueHash),
+    // Recorded and never planned on, like `descriptionStream`: `planChanges`
+    // reads `subIssues` by name, so this key cannot make a push pending. Only a
+    // phase whose body is actually sent (a string goal) gets one.
+    subIssueStreams: byId(
+      (p.subIssues || []).filter((s) => s && typeof s.goal === 'string'),
+      (s) => hashField(stream(s.goal, config)),
+    ),
   }
 }
 
@@ -295,6 +326,7 @@ function isEmptyPlan(plan) {
 module.exports = {
   planChanges,
   remoteDescriptionEdited,
+  remoteSubIssueEdited,
   issueChanges,
   specIssueFieldHashes,
   snapshotOf,

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

@@ -570,6 +570,15 @@ const UNSTARTED_BUCKETS = ['backlog', 'cancelled']
 // Buckets where a spec is FINISHED, and so has nobody working on it.
 const TERMINAL_BUCKETS = ['complete', 'cancelled']
 
+// A phase's state once its SPEC's bucket has a say. Cancelling a spec abandons
+// every phase not already done — left alone, those sub-issues stay open in
+// Backlog under a closed parent, which reads as work still owed. A phase that
+// was finished keeps `complete`: it shipped before the spec was dropped.
+function phaseStateUnder(workflowState, phaseState) {
+  if (workflowState === 'cancelled' && phaseState !== 'complete') return 'cancelled'
+  return phaseState
+}
+
 /**
  * The Linear user this spec is assigned to, AS PROJECTED — which is not simply
  * what the frontmatter records.
@@ -714,7 +723,7 @@ function normalizeLocal(snapshotDir, config) {
       ref: p.phase,
       name: p.name,
       goal: subIssueBody(p, tasksMode, config.sync.localOnlySections, dialect),
-      state: p.state,
+      state: phaseStateUnder(workflowState, p.state),
     })),
     workflowState,
     // Who is building this. `toFieldSet` drops it unless the repo listed
@@ -742,39 +751,27 @@ function phasesWithheld(snapshotDir, config) {
 
 // --- remote projection ------------------------------------------------------
 
-// The lifecycle bucket a deployment ladder descends FROM. A spec is handed over
-// to the deploy pipeline once it is finished, so every rung sits downstream of
-// `complete` — a ticket on "On Test" is a completed spec that has been deployed,
-// not a spec that moved somewhere else.
-const LADDER_ORIGIN_BUCKET = 'complete'
-
-// The declared ladder rung with this state name, or null.
-function stageForState(state, config) {
-  if (state == null) return null
-  const want = String(state).toLowerCase().trim()
-  const stages = (config && config.release && config.release.stages) || []
-  if (!Array.isArray(stages)) return null
-  return stages.find((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want) || null
+// Every tracker state NAME that means this bucket: the one push writes
+// (`states[bucket]`) first, then its read-only aliases (`stateAliases[bucket]`,
+// from the array form of `states`). Readers use the whole list; writers only
+// ever use `states[bucket]`, so an alias can never be written.
+function stateNamesFor(bucket, config) {
+  const primary = config && config.states && config.states[bucket]
+  const aliases = (config && config.stateAliases && config.stateAliases[bucket]) || []
+  return [primary, ...(Array.isArray(aliases) ? aliases : [])].filter((n) => typeof n === 'string' && n)
 }
 
 // Map a remote workflow-state name back to the local lifecycle bucket (the
 // vocabulary `spec_status` uses) via config.states, so local and remote
 // workflowState hash equal when semantically equal. Falls back to a lowercased
 // raw value when the state isn't one of the configured names.
-//
-// A DECLARED DEPLOYMENT STAGE reads as `complete`, deliberately. Without this
-// the fallback lowercases it — "On Test" becomes "on test", which equals no
-// bucket — and every deployed spec reports as drifted forever, for the whole
-// time it sits in the pipeline. The project told us these states are downstream
-// of a finished spec, so they are not a disagreement about where the spec is.
 function bucketForState(state, config) {
   if (state == null) return null
   const states = (config && config.states) || {}
   const want = String(state).toLowerCase().trim()
-  for (const [bucket, name] of Object.entries(states)) {
-    if (typeof name === 'string' && name.toLowerCase().trim() === want) return bucket
+  for (const bucket of Object.keys(states)) {
+    if (stateNamesFor(bucket, config).some((name) => name.toLowerCase().trim() === want)) return bucket
   }
-  if (stageForState(state, config)) return LADDER_ORIGIN_BUCKET
   return want
 }
 
@@ -809,11 +806,20 @@ function remoteWorkflowState(issue, config) {
   return name != null ? bucketForState(name, config) : null
 }
 
-// The declared ladder rung a remote issue is currently sitting on, or null.
-// Pairs with `remoteWorkflowState`: that says which bucket the issue maps to,
-// this says whether it got there by being deployed. Read-only.
-function remoteStage(issue, config) {
-  return stageForState(remoteStateName(issue || {}, config), config)
+// What the drift report needs to know about a remote issue's state: its name,
+// the bucket it maps to, and whether it maps to one at all. Null when the
+// payload carried no state — a cannot-tell, never an answer.
+//
+// AN UNMAPPED STATE IS NOT A DISAGREEMENT. A tracker grows states skitterspec
+// never names ("Blocked", "Next Sprint"), and a ticket a person moved into one
+// is not wrong about the spec — it is somewhere push does not manage, and push
+// will not move it until the spec itself moves. `mapped` is what lets a report
+// say that rather than accuse it.
+function remoteStateReading(issue, config) {
+  const name = remoteStateName(issue || {}, config)
+  if (name == null) return null
+  const bucket = bucketForState(name, config)
+  return { name: String(name), bucket, mapped: LIFECYCLE_BUCKETS.includes(bucket) }
 }
 
 // A Linear issue title is plain text, so markdown emphasis is noise there — and
@@ -888,24 +894,16 @@ function titleFromText(text, max = 100) {
   return stripTitleMarkup(title)
 }
 
-// Every state NAME the config points at: the lifecycle bucket map, plus the
-// project's deployment ladder when it declares one. Both reach Linear the same
-// way and fail the same way, so both are checked by the same lookup.
+// Every state NAME the config points at: the lifecycle bucket map.
 function configuredStateNames(config) {
-  const names = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
-  const stages = (config && config.release && config.release.stages) || []
-  for (const stage of Array.isArray(stages) ? stages : []) {
-    if (stage && typeof stage.state === 'string') names.push(stage.state)
-  }
-  return names
+  // The WRITTEN names only. An alias is never written, so one the workspace
+  // lacks cannot strand a push; `stateSuggestions` still names it in reports.
+  return Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
 }
 
 // Which configured state NAMES are absent from the live workspace. The skill
 // fetches the workspace's project-status names over MCP and passes them here;
 // a non-empty result means a typo/rename that Linear would silently no-op.
-//
-// A project with no `release.stages` contributes nothing here, so the ladder
-// cannot make this accuse a config that was fine before it existed.
 function validateStates(config, workspaceStates) {
   const configured = configuredStateNames(config)
   const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
@@ -944,21 +942,6 @@ function stateSuggestions(config, workspaceStates) {
     const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
     out.push({ bucket, configured, suggestion, label: `states.${bucket}` })
   }
-  // Deployment-ladder rungs, reported the same way. No suggestion is offered:
-  // BUCKET_WORDS describes lifecycle vocabulary, and a stage name is the
-  // project's own — guessing "On Test" meant "In Progress" would be worse than
-  // saying nothing.
-  const stages = (config && config.release && config.release.stages) || []
-  for (const stage of Array.isArray(stages) ? stages : []) {
-    if (!stage || typeof stage.state !== 'string') continue
-    if (have.has(stage.state.toLowerCase().trim())) continue
-    out.push({
-      bucket: null,
-      configured: stage.state,
-      suggestion: null,
-      label: `release.stages[${stage.key}]`,
-    })
-  }
   return out
 }
 
@@ -982,8 +965,7 @@ module.exports = {
   canonicalRemoteStatus,
   bucketForState,
   LIFECYCLE_BUCKETS,
-  stageForState,
-  remoteStage,
   remoteWorkflowState,
-  LADDER_ORIGIN_BUCKET,
+  remoteStateReading,
+  stateNamesFor,
 }