@skitterbyte/skitterspec-linear 10.6.0 → 10.8.0

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.

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

@@ -1,73 +0,0 @@
----
-name: spec-live
-description: Test a spec on your already-running dev server by checking its branch out in the primary checkout — no second stack, no proxy. `spec-live <spec>` takes the running instance for that spec; `spec-live main` releases it. Runs `skitterspec spec-env live`. Opt-in — needs specs/.core/env.config.json. Code-only specs; stateful (Docker/migration) specs use /spec-connect. Use when the user says "/spec-live", "go live with <spec>", "take the instance for <spec>", or "test <spec> on the running server".
----
-
-# /spec-live — put one spec live on the running instance
-
-Instead of running a second dev stack for a spec (that's `/spec-connect`), **reuse
-the one instance you already have**: rebase the spec's branch onto base, hand it
-from its worktree to the **primary checkout**, and let your running dev server
-hot-reload it. You test at your normal URL, with one process. The branch that's
-checked out in the primary checkout **is** the lock — exactly one spec is live at
-a time, and `/spec-live main` hands the instance back.
-
-This skill is **opt-in**: it needs `specs/.core/env.config.json`. If isolation is
-absent, say so and stop.
-
-**Code-only.** Live overlay refuses a **stateful** spec — one whose `> **Stack:**`
-is `worktree + docker`, or whose branch changes migrations (per
-`env.config.json` → `live.migrations`). Those keep their isolated stack; use
-`/spec-connect` for them. It also **always refuses a `Type: Hotfix` spec** — its
-branch is built on an old release tag, so hot-reloading it onto the running dev
-server could break the shared instance; test a hotfix with `/spec-connect`. The
-engine enforces all of this and prints why.
-
-## 1. Identify the target
-
-- Use the spec named as an argument. The literal `main` means **release** (hand
-  the instance back to base). Else use the spec **currently in context**; if
-  unclear, ask.
-
-## 2. Make sure a dev server is running
-
-`live take` **verifies** a dev server is up on your canonical ports and switches
-the branch under it — it does **not** start one. If nothing is listening it
-refuses; start your dev server first (however you normally run it, or
-`skitterspec spec-env dev up <spec>`). (Projects with no `dev` servers configured
-have nothing to hot-reload — the switch still happens, with a warning.)
-
-## 3. Take (or release)
-
-```
-skitterspec spec-env live take <spec>   # rebase → detach worktree → checkout in primary
-skitterspec spec-env live release        # hand the instance back to base, re-isolate the branch
-skitterspec spec-env live abort          # crash recovery (see below)
-skitterspec spec-env live status         # who's live (branch in the primary checkout + receipt)
-```
-
-**Take** rebases the branch onto base, frees it from its worktree
-(`switch --detach`), checks it out in the primary checkout, then writes a receipt
-(`.spec-env/live.json`). Relay its output. **If it reports the rebase hit
-conflicts**, it left everything untouched — rebase the branch in its worktree,
-resolve, then retry. **If it says a spec already holds the instance**, release it
-first. If it warns dependencies changed, restart your dev server after the switch.
-
-**Release** (`/spec-live main`) is the graceful exit of an unfinished session:
-`skitterspec spec-env live release` reads the live spec from the receipt, checks
-base back out in the primary checkout, re-attaches the branch to its worktree, and
-clears the receipt. Commit any fixes to the branch first — it refuses on a dirty
-tree rather than discard them. (To *finish* a live spec instead of releasing it,
-use `/spec-complete`, which is live-aware.)
-
-**Abort** is crash recovery, for when a session died mid-take and left the primary
-checkout on a feature branch: `skitterspec spec-env live abort` restores base from
-the receipt and re-isolates. It refuses if the primary checkout has uncommitted
-changes (it won't discard them) — commit or stash first.
-
-## 4. Report
-
-Echo which spec is now live on the primary checkout (and any warning), that it was
-released / recovered, or — for `status` — which branch the primary checkout is on
-and whether the instance is free. Fixes you make while live commit straight onto
-the spec's branch.