@skitterbyte/skitterspec-linear 10.6.0 → 10.7.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,19 @@ 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([])
+
 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 +125,10 @@ 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.
+  release: Object.freeze({ stages: DEFAULT_RELEASE_STAGES }),
   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 +180,7 @@ function defaults() {
     mapping: { ...DEFAULT_CONFIG.mapping },
     states: { ...DEFAULT_CONFIG.states },
     snapshot: { ...DEFAULT_CONFIG.snapshot },
+    release: { stages: DEFAULT_CONFIG.release.stages.map((s) => ({ ...s })) },
     branch: { ...DEFAULT_CONFIG.branch },
     auth: { ...DEFAULT_CONFIG.auth },
     apply: { ...DEFAULT_CONFIG.apply },
@@ -249,6 +268,55 @@ 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) 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 +380,10 @@ function mergeConfig(base, parsed) {
     assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
   }
 
+  if (isObject(parsed.release)) {
+    mergeReleaseStages(base.release, parsed.release)
+  }
+
   if (isObject(parsed.branch)) {
     assign(base.branch, parsed.branch, 'pattern', 'string')
   }
@@ -350,7 +422,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 +447,25 @@ 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
+}
+
 module.exports = {
   loadLinearConfig,
+  releaseStages,
+  stageFor,
   mergeConfig,
   defaults,
   DEFAULT_CONFIG,

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

@@ -77,4 +77,88 @@ function ticketsInRange(commits) {
   }
 }
 
-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, 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,

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

@@ -818,10 +818,31 @@ 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
+}
+
 // 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) || {}
@@ -829,6 +850,7 @@ function bucketForState(state, config) {
   for (const [bucket, name] of Object.entries(states)) {
     if (typeof name === 'string' && name.toLowerCase().trim() === want) return bucket
   }
+  if (stageForState(state, config)) return LADDER_ORIGIN_BUCKET
   return want
 }
 
@@ -860,6 +882,13 @@ 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)
+}
+
 // A Linear issue title is plain text, so markdown emphasis is noise there — and
 // worse, an emphasis run cut mid-title (or a bold LABEL like `**1. Foo**`) can
 // leave a dangling `**`. Strip `*` emphasis markers and unwrap `[text](url)` to
@@ -932,11 +961,26 @@ 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.
+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
+}
+
 // 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 = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
+  const configured = configuredStateNames(config)
   const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
   return configured.filter((name) => !have.has(name.toLowerCase().trim()))
 }
@@ -971,13 +1015,29 @@ function stateSuggestions(config, workspaceStates) {
     if (have.has(configured.toLowerCase().trim())) continue
     const words = BUCKET_WORDS[bucket] || []
     const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
-    out.push({ bucket, configured, suggestion })
+    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
 }
 
 module.exports = {
   stateSuggestions,
+  configuredStateNames,
   normalizeLocal,
   phaseProjection,
   phaseModeFor,
@@ -994,5 +1054,8 @@ module.exports = {
   canonicalizeMarkdown,
   joinEmphasisAcrossBreaks,
   bucketForState,
+  stageForState,
+  remoteStage,
   remoteWorkflowState,
+  LADDER_ORIGIN_BUCKET,
 }

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

@@ -1,59 +0,0 @@
----
-name: spec-connect
-description: Point your local canonical origin (localhost:3000/:8080) at a spec's running dev servers so you can test a worktree's UI/API changes at the normal URL — or `spec-connect main` to hand the ports back to your main checkout. Runs `skitterspec spec-env connect` (a small bundled reverse proxy). Opt-in — needs specs/.core/env.config.json with a `dev` block. Use when the user says "/spec-connect", "test <spec> locally", "point local at <spec>", or "connect to <spec>".
----
-
-# /spec-connect — expose one spec on the canonical ports
-
-Make `http://localhost:<frontPort>` serve a **spec's** warm dev servers instead of
-your main checkout's, so you can test a worktree's UI/API at the exact URL you
-always use — no bookmark, base-URL, or OAuth-callback changes. **Exclusive:** one
-spec is exposed at a time. `spec-connect main` stops the proxy and hands the ports
-back to your primary checkout.
-
-This skill is **opt-in**: it needs `specs/.core/env.config.json` with a `dev`
-block (host dev servers + their `frontPort`s). If isolation or `dev` is absent,
-say so and stop.
-
-**Lighter alternative for a code-only spec:** `/spec-live` reuses the dev server
-you already have running (it branch-switches the primary checkout) instead of
-starting a second stack — no proxy, one process. Prefer it for code-only specs;
-use `/spec-connect` when a spec has its own Docker stack, or to run several stacks
-in parallel.
-
-## 1. Identify the target
-
-- Use the spec named as an argument. The literal `main` means **disconnect**
-  (hand the ports back to the primary checkout). Else use the spec **currently in
-  context**; if unclear, ask.
-
-## 2. Make sure the spec's dev servers are running
-
-`connect` proxies to a spec's dev servers on its reserved port block — it does
-**not** start them. If they aren't up yet, start them first:
-
-```
-skitterspec spec-env dev up <spec>
-```
-
-(This is automatic under `/spec-go`; run it by hand only when connecting a spec
-whose servers you stopped.)
-
-## 3. Connect (or disconnect)
-
-```
-skitterspec spec-env connect <spec>     # expose <spec> on the canonical ports
-skitterspec spec-env connect main       # stop the proxy — main owns the ports
-```
-
-The engine (re)starts a small bundled Node reverse proxy and **prints** the
-canonical URL → spec-port mapping. **If it reports a canonical port is in use**,
-your **main dev server still holds it** — stop main on that port, then re-run
-(the proxy can't share a port main is bound to). Relay the printed message.
-
-## 4. Report
-
-Echo which spec is now on the canonical ports (and the URLs), or that the proxy
-was stopped and main owns them again. Switching to a different spec is just
-`spec-connect <other>` — the dev servers stay warm, so it's a near-instant
-re-point.