@skitterbyte/skitterspec-linear 8.0.5 → 9.1.0

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

@@ -253,6 +253,16 @@ function phaseTitle(body) {
   return t || null
 }
 
+// A phase's status (from its heading emoji ⬜/🔄/✅) mapped to a state bucket the
+// `states` table understands, so a sub-issue lands in the matching Linear issue
+// state. Unknown/absent → backlog.
+const PHASE_STATE_BUCKET = { 'not-started': 'backlog', 'in-progress': 'in-progress', done: 'complete' }
+function phaseStateBucket(body) {
+  const h1 = /^#\s+(.*)$/m.exec(body)
+  const emoji = h1 ? (h1[1].match(/[⬜🔄✅]/u) || [])[0] : undefined
+  return PHASE_STATE_BUCKET[EMOJI_STATUS[emoji]] || 'backlog'
+}
+
 // Parse a task line (already stripped of its leading "- ") into a keyed item:
 // its checkbox state, its text, and the inline Linear issue identifier if present
 // (`… (SKI-123)`). Returns null for a non-task line.
@@ -297,9 +307,11 @@ function readPhaseFiles(snapshotDir) {
       return {
         phase: file.replace(/\.md$/, ''),
         file,
-        id: data.linear_milestone_id != null ? String(data.linear_milestone_id) : null,
+        // The sub-issue id, stamped back into the phase file on first push.
+        id: data.linear_issue_id != null ? String(data.linear_issue_id) : null,
         name: phaseTitle(body),
         goal: goal.trim(),
+        state: phaseStateBucket(body),
         tasks,
       }
     })
@@ -350,47 +362,39 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
 /**
  * Normalize a local spec snapshot into the configured field set.
  */
+// The spec's lifecycle bucket from its folder — the source of truth for status
+// (specs live in specs/<bucket>/<name>/). Maps directly to a `states` key.
+const LIFECYCLE_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
+function bucketFromPath(snapshotDir) {
+  const parent = path.basename(path.dirname(snapshotDir))
+  return LIFECYCLE_BUCKETS.includes(parent) ? parent : null
+}
+
 function normalizeLocal(snapshotDir, config) {
   const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
-  // Phases sync as first-class Milestones whenever `milestones` is in the pushed
-  // projection, so strip the `## Phases` index from the description to avoid
-  // duplicating it (as prose AND as milestones) in the Linear mirror.
-  const milestonesProjected = !!(config.sync.fieldOwnership && 'milestones' in config.sync.fieldOwnership)
+  // Phases sync as sub-issues whenever `subIssues` is in the pushed projection,
+  // so strip the `## Phases` index from the description to avoid duplicating it
+  // (as prose AND as sub-issues) in the Linear mirror.
+  const phasesProjected = !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership)
   const extracted = {
     description: buildDescription(
       title,
       sections,
       config.sync.localOnlySections,
-      milestonesProjected ? ['Phases'] : [],
+      phasesProjected ? ['Phases'] : [],
     ),
-    // Milestone projection items. `ref` is the phase-file basename — the local
-    // handle the push skill stamps a newly-created milestone id back into.
-    milestones: phases
+    // Sub-issue projection: one per phase. `ref` is the phase-file basename — the
+    // local handle the push skill stamps a newly-created sub-issue id back into.
+    // `state` is the phase's status bucket (from its heading emoji), mapped to a
+    // Linear issue state via `config.states` at push time. Tasks are NOT
+    // projected — they live only in the repo phase files.
+    subIssues: phases
       .filter((p) => p.name)
-      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: p.goal })),
-    // Issue projection items across all phases. `title` is the first-sentence
-    // Linear title; `description` is the full task text (the mirror keeps both).
-    // `ref` = the collapsed text the push skill matches to stamp a new id in;
-    // `milestoneRef` links the issue to its milestone (id if linked, else phase).
-    tasks: phases.flatMap((p) =>
-      p.tasks
-        .map(parseTaskLine)
-        .filter(Boolean)
-        .map((t) => ({
-          id: t.id,
-          ref: t.text,
-          title: titleFromText(t.text),
-          description: t.text,
-          done: t.done,
-          milestoneRef: p.id || p.phase,
-        })),
-    ),
-    phaseBodies: phases.map((p) => ({ phase: p.phase, goal: p.goal })),
-    acceptanceCriteria: sections['Acceptance criteria'] || null,
-    taskBreakdown: phases.map((p) => ({ phase: p.phase, tasks: p.tasks })),
-    workflowState: frontmatter.spec_status != null ? String(frontmatter.spec_status) : null,
-    priority: frontmatter.priority != null ? frontmatter.priority : null,
-    labels: Array.isArray(frontmatter.labels) ? frontmatter.labels : [],
+      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: p.goal, state: p.state })),
+    // Status is the spec's lifecycle bucket. The folder is the source of truth;
+    // an explicit `spec_status` frontmatter key overrides it if present.
+    workflowState:
+      frontmatter.spec_status != null ? String(frontmatter.spec_status) : bucketFromPath(snapshotDir),
   }
   return toFieldSet(extracted, config)
 }
@@ -422,23 +426,36 @@ function canonicalRemoteStatus(state) {
   return s
 }
 
-// The real Linear projection carries the project's workflow state in `status`
-// (an object `{ name, type }`); accept a bare string / legacy `state` too.
-function remoteStateName(project) {
-  const st = project.status != null ? project.status : project.state
+// The real Linear issue carries its workflow state in `state` (an object
+// `{ name, type }`); accept `status` / a bare string too for robustness.
+function remoteStateName(issue) {
+  const st = issue.state != null ? issue.state : issue.status
   if (st == null) return null
   if (typeof st === 'object') return st.name != null ? st.name : st.type != null ? st.type : null
   return st
 }
 
-// The ONE thing one-way sync reads back: the mirror's current workflow state,
-// mapped to the local lifecycle bucket, so `/spec-status` can report a drift
-// ("Linear says Done, your spec says In Progress"). Read-only — it never writes.
-function remoteWorkflowState(project, config) {
-  const name = remoteStateName(project || {})
+// The ONE thing one-way sync reads back: the mirror issue's current workflow
+// state, mapped to the local lifecycle bucket, so `/spec-status` can report a
+// drift ("Linear says Done, your spec says In Progress"). Read-only — never writes.
+function remoteWorkflowState(issue, config) {
+  const name = remoteStateName(issue || {})
   return name != null ? bucketForState(name, config) : null
 }
 
+// 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
+// `text`. Backticks and `_` are KEPT: task labels lean on inline code
+// (`` `DbFoo` ``) and identifiers use snake_case, and neither breaks a title.
+function stripTitleMarkup(t) {
+  return t
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // [text](url) -> text
+    .replace(/\*/g, '') // bold/italic markers (incl. a dangling ** from a cut)
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 // Trim a trailing parenthetical whose opener has no matching close — so a cut
 // title never ends on a dangling `(`/`[`.
 function dropUnclosedBracket(t) {
@@ -469,6 +486,7 @@ function titleFromText(text, max = 100) {
     const after = s[i + 1]
     if (after !== undefined && !/\s/.test(after)) continue // not a sentence end
     if (/\d/.test(s[i - 1] || '') && /\d/.test(after || '')) continue // 7.0.2, 3.14
+    if (/(?:^|[^\w])\d+$/.test(s.slice(0, i))) continue // list ordinal "1." "2."
     if (/(^|\s)(e\.g|i\.e|etc|vs|no|fig|cf)$/i.test(s.slice(0, i))) continue // abbrev
     title = s.slice(0, i) // drop the terminator
     break
@@ -494,7 +512,7 @@ function titleFromText(text, max = 100) {
     }
     title = dropUnclosedBracket(t).replace(/[\s.,:;—–([]+$/, '').trim()
   }
-  return title
+  return stripTitleMarkup(title)
 }
 
 // Which configured state NAMES are absent from the live workspace. The skill

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

@@ -19,18 +19,16 @@ const { normalizeLocal } = require('./normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
 const { readBase, writeBase } = require('./base.js')
 
-// Build the one-way projection from a local snapshot: the project prose + status,
-// and the milestone/issue items. `status` is the local lifecycle bucket; the
-// skill maps it to the Linear project-state NAME via config.states at apply time.
+// Build the one-way projection from a local snapshot: the spec issue's prose +
+// status, and its phase sub-issues. `status` is the local lifecycle bucket; the
+// skill maps it (and each sub-issue's `state`) to the Linear issue-state NAME via
+// config.states at apply time.
 function projectionOf(snapshotDir, config) {
   const local = normalizeLocal(snapshotDir, config)
   return {
     description: local.description ?? null,
     status: local.workflowState ?? null,
-    priority: local.priority ?? null,
-    labels: Array.isArray(local.labels) ? local.labels : [],
-    milestones: Array.isArray(local.milestones) ? local.milestones : [],
-    issues: Array.isArray(local.tasks) ? local.tasks : [],
+    subIssues: Array.isArray(local.subIssues) ? local.subIssues : [],
   }
 }
 

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

@@ -1,16 +1,16 @@
 'use strict'
 
 /**
- * Push-side writeback: after `push` creates milestones/issues in Linear, the
- * skill stamps each returned id back into the repo so the next push updates
- * rather than recreates. Everything here edits the repo in place:
+ * Push-side writeback: after `push` creates the spec issue + phase sub-issues in
+ * Linear, the skill stamps each returned id back into the repo so the next push
+ * updates rather than recreates. Everything here edits the repo in place:
  *
- *   - `stampMilestoneId(dir, file, id)` — add/update `linear_milestone_id` in a
- *     phase file's frontmatter (locate the file with `findPhaseFileByTitle`).
- *   - `stampIssueId(dir, text, id)` — append `(ID)` to the matching task line,
- *     re-wrapped in the file's own style.
+ *   - `stampSubIssueId(dir, file, id)` — add/update `linear_issue_id` in a phase
+ *     file's frontmatter (locate the file with `findPhaseFileByTitle`).
  *   - `writeFrontmatter(dir, config, patch)` — patch `00-overview.md` frontmatter
- *     (e.g. `last_synced_at`).
+ *     (e.g. the spec issue's `spec_identifier`, `last_synced_at`).
+ *   - `stampIssueId(dir, text, id)` — legacy: append `(ID)` to a task line
+ *     (tasks are no longer synced; kept for the sanitise/util paths).
  *
  * No remote read, no pull writeback — the repo is the source of truth.
  */
@@ -90,7 +90,7 @@ function listPhaseFiles(snapshotDir) {
 }
 
 // Find the phase file whose h1 title matches `name` (used to stamp a freshly
-// created milestone's id back into the phase it came from).
+// created sub-issue's id back into the phase it came from).
 function findPhaseFileByTitle(snapshotDir, name) {
   const want = String(name).trim()
   for (const file of listPhaseFiles(snapshotDir)) {
@@ -106,12 +106,13 @@ function findPhaseFileByTitle(snapshotDir, name) {
   return null
 }
 
-// Add/update linear_milestone_id in a phase file's frontmatter (in place).
-function stampMilestoneId(snapshotDir, file, id) {
+// Add/update linear_issue_id in a phase file's frontmatter (in place) — the
+// sub-issue id for that phase.
+function stampSubIssueId(snapshotDir, file, id) {
   const p = path.join(snapshotDir, file)
   const raw = fs.readFileSync(p, 'utf-8')
   const { fmLines, body, had } = splitFrontmatter(raw)
-  const patched = patchFrontmatterLines(fmLines, { linear_milestone_id: String(id) })
+  const patched = patchFrontmatterLines(fmLines, { linear_issue_id: String(id) })
   const fm = `---\n${patched.join('\n')}\n---\n`
   fs.writeFileSync(p, had ? fm + body : fm + '\n' + raw, 'utf-8')
 }
@@ -144,6 +145,6 @@ module.exports = {
   serialize,
   listPhaseFiles,
   findPhaseFileByTitle,
-  stampMilestoneId,
+  stampSubIssueId,
   stampIssueId,
 }