@skitterbyte/skitterspec-linear 8.0.4 → 9.0.0

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

@@ -16,7 +16,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
-const { findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
+const { fenceMask, findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
 
 // --- markdown / frontmatter parsing -----------------------------------------
 
@@ -57,6 +57,7 @@ function parseScalar(v) {
 // heading text → its content (until the next `## `). The H1 `# ` is the title.
 function parseSections(body) {
   const lines = body.split('\n')
+  const inFence = fenceMask(lines)
   let title = null
   const sections = {}
   let current = null
@@ -64,9 +65,12 @@ function parseSections(body) {
   const flush = () => {
     if (current !== null) sections[current] = buf.join('\n').trim()
   }
-  for (const line of lines) {
-    const h1 = /^#\s+(.*)$/.exec(line)
-    const h2 = /^##\s+(.*)$/.exec(line)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // A `#`/`##` inside a fenced code block is example text, not a real heading —
+    // treat it as body content so it can't start a phantom section.
+    const h1 = inFence[i] ? null : /^#\s+(.*)$/.exec(line)
+    const h2 = inFence[i] ? null : /^##\s+(.*)$/.exec(line)
     if (h1 && title === null) {
       title = h1[1].trim()
       continue
@@ -249,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.
@@ -293,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,
       }
     })
@@ -346,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)
 }
@@ -418,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) {
@@ -465,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
@@ -490,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/task-block.js

@@ -22,6 +22,38 @@ const BLOCK_BREAK_RE = /^[ \t]*(?:[-*+]\s|\d+\.\s|#{1,6}\s|>|\||```)/
 // A list-marker line (unordered or ordered). Distinguished from other block
 // breaks because a wrapped continuation can legitimately begin with one.
 const LIST_MARKER_RE = /^[ \t]*(?:[-*+]|\d+\.)\s/
+// A checkbox bullet — unambiguously a task, so it always starts its own block,
+// at any indent. (A bare list marker is ambiguous; a checkbox never is.)
+const CHECKBOX_RE = /^[ \t]*[-*+]\s*\[[ xX]\]/
+
+// Mark every line that lies inside a fenced code block — the opening fence, its
+// content, and the closing fence all count as `true`. Line scanners that hunt
+// for markdown structure (task bullets, section headings) use this to ignore an
+// EXAMPLE of that structure shown inside a fence: a spec that documents a
+// checklist format in a ``` block must not have those example bullets harvested
+// as real tasks (and pushed as real tracker issues). Supports ``` and ~~~ fences
+// of any length ≥ 3; a closing fence is a bare marker (no info string) of the
+// same character and at least the opening length.
+function fenceMask(lines) {
+  const mask = new Array(lines.length).fill(false)
+  let open = null // the opening marker string (``` or ~~~ …), or null
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim()
+    if (open) {
+      mask[i] = true
+      if (/^(`{3,}|~{3,})$/.test(trimmed) && trimmed[0] === open[0] && trimmed.length >= open.length) {
+        open = null
+      }
+      continue
+    }
+    const m = /^[ \t]*(`{3,}|~{3,})/.exec(lines[i])
+    if (m) {
+      open = m[1]
+      mask[i] = true
+    }
+  }
+  return mask
+}
 
 // Collapse a wrapped bullet's lines into the single logical line the rest of the
 // sync engine (and Linear) works in.
@@ -81,27 +113,34 @@ function spanMask(body) {
  */
 function findTaskBlocks(lines) {
   const blocks = []
+  const inFence = fenceMask(lines)
   for (let i = 0; i < lines.length; i++) {
+    if (inFence[i]) continue // an example bullet inside a ``` block is not a task
     const m = TASK_START_RE.exec(lines[i])
     if (!m) continue
     const parts = [m[3]]
     // The hanging indent: where the bullet's text starts (marker width). A
-    // continuation aligns AT this column; a genuine nested bullet is SHALLOWER.
+    // wrapped continuation aligns exactly AT this column.
     const hang = lines[i].length - m[3].length
     let j = i + 1
     for (; j < lines.length; j++) {
       const l = lines[j]
       if (!l.trim()) break
+      if (inFence[j]) break // a fence opening ends the bullet, never continues it
       if (!CONTINUATION_RE.test(l)) break
       if (BLOCK_BREAK_RE.test(l)) {
-        // A list-marker line is a real nested/sibling bullet only when indented
-        // shallower than the hanging indent. AT/after it, a line beginning with
-        // -/*/+/N. is wrapped continuation text, not a new bullet — keep it (else
-        // the task is truncated and its stamped id no longer matches, which makes
-        // the next push create a duplicate issue). Headings, quotes, tables and
-        // fences always break.
+        // Indent alone can't tell a nested child from a wrapped continuation —
+        // both sit at the hanging indent. The *marker* is the reliable signal:
+        //   - a checkbox (- [ ] / - [x]) is unambiguously a task → always break;
+        //   - a bare marker (-/*/+/N.) is wrapped continuation prose ONLY when it
+        //     sits exactly at the hang; shallower or deeper it's a real sub/
+        //     sibling list → break. (Keeping the at-hang continuation preserves
+        //     the task's stamped id, so the next push updates instead of
+        //     creating a duplicate issue.)
+        //   - headings, quotes, tables and fences always break.
+        if (CHECKBOX_RE.test(l)) break
         const indent = l.length - l.trimStart().length
-        if (!LIST_MARKER_RE.test(l) || indent < hang) break
+        if (!LIST_MARKER_RE.test(l) || indent !== hang) break
       }
       parts.push(l.trim())
     }
@@ -192,6 +231,7 @@ function inferWidth(lines, fallback = DEFAULT_WIDTH) {
 }
 
 module.exports = {
+  fenceMask,
   findTaskBlocks,
   renderTaskBlock,
   wrapEmphasisAware,

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,
 }