@skitterbyte/skitterspec-linear 10.1.0 → 10.3.0

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

@@ -307,7 +307,10 @@ function phaseStateBucket(body) {
 // its checkbox state, its text, and the inline Linear issue identifier if present
 // (`… (SKI-123)`). Returns null for a non-task line.
 function parseTaskLine(line) {
-  const m = /^\[([ xX])\]\s*(.*)$/.exec(line)
+  // Any single-character mark, matching the parser (`TASK_START_RE`). Only
+  // `x`/`X` is done — every other mark (`~`, `>`, `-` …) is a project's own
+  // vocabulary, carried through verbatim rather than coerced to unchecked.
+  const m = /^\[([^\]])\]\s*(.*)$/.exec(line)
   if (!m) return null
   const done = m[1].toLowerCase() === 'x'
   let text = m[2].trim()
@@ -320,44 +323,31 @@ function parseTaskLine(line) {
   return { id, text, done }
 }
 
-/**
- * Split a phase's task blocks into the `##` sections they were written under.
- *
- * The checklist used to be one flat list under a hardcoded `## Tasks`, so a
- * criterion written under `## Acceptance` arrived in the mirror as an ordinary
- * open task. Nothing was lost — it was just unreadable.
- *
- * Grouping is done by MAPPING blocks onto headings, not by re-parsing the body
- * section by section: `findTaskBlocks` tracks open task subtrees across a
- * continuous body, and slicing that body at every heading would change what a
- * block claims at a section boundary. A heading inside a fence is not a heading
- * (`fenceMask`), and the phase file's own `#` H1 is not a section.
- *
- * @returns {Array<{heading:string|null, tasks:string[]}>} in source order;
- *   `heading` is null for blocks that precede every heading, and a heading with
- *   no blocks under it never appears.
- */
-function groupTasksByHeading(lines, blocks, renderTask) {
-  const inFence = fenceMask(lines)
-  const headings = []
-  for (let i = 0; i < lines.length; i++) {
-    if (inFence[i]) continue
-    const m = /^(#{2,6})\s+(.*\S)\s*$/.exec(lines[i])
-    if (m) headings.push({ line: i, heading: `${m[1]} ${m[2]}` })
-  }
+// Tasks used to be grouped onto their source headings here, because the body was
+// rebuilt from harvested task lines and the headings had to be put back. The
+// projection now emits the phase file itself, so the headings never leave in the
+// first place (bug-phase-content-dropped) and the grouping is gone with them.
 
-  const groups = []
-  for (const b of blocks) {
-    let heading = null
-    for (const h of headings) {
-      if (h.line >= b.start) break
-      heading = h.heading
-    }
-    const last = groups[groups.length - 1]
-    if (last && last.heading === heading) last.tasks.push(renderTask(b))
-    else groups.push({ heading, tasks: [renderTask(b)] })
-  }
-  return groups
+// The phase's stated purpose, in either shape people actually write it: an
+// inline `**Goal:** …` paragraph, or a `## Goal` section. Only the inline form
+// was recognised — so the phase files written the other way (4 of the 96 in this
+// repo, all of them recent) projected an empty goal.
+function phaseGoal(body) {
+  const inline = /\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body)
+  if (inline) return inline[1]
+  return parseSections(body).sections.Goal || ''
+}
+
+// One task block back to a single markdown line. `findTaskBlocks` also returns
+// the plain sub-bullets written underneath a task; they carry no checkbox, so
+// they render as the bullet their author used — emitting `- [ ]` here would
+// invent a task that does not exist in the repo. Any inline `(KEY-123)` stamped
+// on a legacy task line is stripped: those ids were per-task issues we no longer
+// create, and they read as noise in the mirror.
+function renderTaskBlockLine(b) {
+  const parsed = parseTaskLine(`[${b.checkbox ? b.mark : ' '}] ${b.text}`)
+  const text = parsed ? parsed.text : b.text
+  return b.checkbox ? `${b.indent}- [${b.mark}] ${text}` : `${b.indent}${b.marker} ${text}`
 }
 
 // Read the phase files (01-*.md, 02-*.md …) in execution order. Each yields its
@@ -382,25 +372,13 @@ function readPhaseFiles(snapshotDir) {
       // Collapsed, not just captured: the goal becomes a milestone description,
       // and Linear may canonicalize a soft line break away on save. Collapsing
       // both sides keeps a wrapped goal from diffing forever.
-      const goal = collapseHyphenAware((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
+      const goal = collapseHyphenAware(phaseGoal(body))
       // Rendered as markdown checklist lines, ready to drop into a sub-issue
       // description: indentation kept so nesting survives, each bullet keeping
-      // the marker its author wrote, and any inline `(KEY-123)` stamped on a legacy task
-      // line stripped — those ids were per-task issues we no longer create, and
-      // they read as noise in the mirror.
+      // the marker its author wrote.
       const lines = body.split('\n')
-      const renderTask = (b) => {
-        // `findTaskBlocks` also returns the plain sub-bullets written underneath
-        // a task. They carry no checkbox, so they render as the bullet their
-        // author used — emitting `- [ ]` here would invent a task that does not
-        // exist in the repo.
-        const parsed = parseTaskLine(`[${b.checkbox ? b.mark : ' '}] ${b.text}`)
-        const text = parsed ? parsed.text : b.text
-        return b.checkbox ? `${b.indent}- [${b.mark}] ${text}` : `${b.indent}${b.marker} ${text}`
-      }
       const blocks = findTaskBlocks(lines)
-      const tasks = blocks.map(renderTask)
-      const taskGroups = groupTasksByHeading(lines, blocks, renderTask)
+      const tasks = blocks.map(renderTaskBlockLine)
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -415,7 +393,11 @@ function readPhaseFiles(snapshotDir) {
         emoji: headingEmoji(body),
         statusLine: phaseStatusLine(body),
         tasks,
-        taskGroups,
+        // The raw body and the parsed blocks, so `subIssueBody` can project the
+        // file rather than rebuild it from fragments. Not part of the pushed
+        // field set — `toFieldSet` picks the projection's keys explicitly.
+        lines,
+        blocks,
       }
     })
 }
@@ -539,19 +521,127 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
 // push. Without it a sub-issue is a title and one sentence, which is too thin to
 // act on; with it the phase is legible to someone working in the tracker without
 // tasks becoming individually-synced objects again.
-function subIssueBody(phase, tasksMode) {
-  if (tasksMode !== 'checklist' || !phase.tasks.length) return flattenNestedTables(phase.goal)
-  const parts = []
-  if (phase.goal) parts.push(phase.goal, '')
-  // One section per source heading, in source order. Checkboxes written before
-  // any heading keep the `## Tasks` default, so a phase file with a single task
-  // section — every one in this repo's corpus but two — projects unchanged.
-  const groups = phase.taskGroups && phase.taskGroups.length ? phase.taskGroups : [{ heading: null, tasks: phase.tasks }]
-  groups.forEach((group, i) => {
-    if (i) parts.push('')
-    parts.push(group.heading || '## Tasks', '', ...group.tasks)
+function subIssueBody(phase, tasksMode, localOnlySections) {
+  if (tasksMode !== 'checklist') return flattenNestedTables(phase.goal)
+  return flattenNestedTables(projectPhaseBody(phase, localOnlySections))
+}
+
+/**
+ * Project a phase file into its sub-issue body: the file as written, with each
+ * task bullet replaced by its rendered single-line form.
+ *
+ * This used to REBUILD the body from two harvested fragments — the `**Goal:**`
+ * paragraph and the task lines `findTaskBlocks` claimed — and silently dropped
+ * everything neither covered: prose, whole `##` sections, and any table or
+ * fenced block nested under a task. `buildDescription` never had that problem
+ * because it projects the overview section by section, so the fix is to make the
+ * phase body work the same way — lossless by construction rather than by
+ * enumerating the shapes we remembered.
+ *
+ * Only two things are deliberately left out, and both are pushed as their own
+ * field, so keeping them would duplicate:
+ *
+ *   - the `#` h1, projected as the sub-issue's `name`;
+ *   - the `> **Status:**` line, projected as its `state`.
+ *
+ * Local-only sections are stripped exactly as they are from the description.
+ */
+function projectPhaseBody(phase, localOnlySections) {
+  const skip = new Set(localOnlySections || [])
+  const lines = phase.lines || []
+  const inFence = fenceMask(lines)
+  // Where each task block starts, so the walk can emit its rendered form and
+  // jump the lines it claims. Line-indexed splicing is what `task-block.js` is
+  // built for; everything it does NOT claim is content, and passes through.
+  const blockAt = new Map()
+  for (const b of phase.blocks || []) blockAt.set(b.start, b)
+
+  const out = []
+  let dropping = false // inside a local-only section
+  let seenTitle = false
+  for (let i = 0; i < lines.length; i++) {
+    const block = blockAt.get(i)
+    if (block) {
+      if (!dropping) out.push(renderTaskBlockLine(block))
+      i = block.end - 1
+      continue
+    }
+    const line = lines[i]
+    if (!inFence[i]) {
+      const h2 = /^##\s+(.*\S)\s*$/.exec(line)
+      if (h2) dropping = skip.has(h2[1].trim())
+      if (!seenTitle && /^#\s+/.test(line)) {
+        seenTitle = true
+        continue
+      }
+      if (/^>\s*\*\*Status:\*\*/.test(line)) continue
+    }
+    if (!dropping) out.push(line)
+  }
+  // Collapse the blank runs the removals leave behind, and trim the ends.
+  return out
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+// Phases inline as `###`, hanging under the `## Phases` index that lists them.
+// The body they carry is a whole document in its own right and starts at `##`,
+// so it demotes to sit under that heading rather than break out of it.
+const INLINE_PHASE_LEVEL = 3
+const MAX_HEADING_LEVEL = 6
+
+/**
+ * Shift every heading in a projected phase body `by` levels, so an inlined phase
+ * nests under the `###` that introduces it.
+ *
+ * Projected for a sub-issue the body is the whole description and its `## Tasks`
+ * is correctly top-level. Inlined it is a subsection, and an undemoted `## Tasks`
+ * would read as a sibling of `## Problem` — pulling every following phase under
+ * it in the outline. Only the `#` run length changes; the content is the same
+ * bytes either way, which is the point of sharing one composer.
+ */
+function demoteHeadings(body, by) {
+  const lines = body.split('\n')
+  const inFence = fenceMask(lines)
+  return lines
+    .map((line, i) => {
+      if (inFence[i]) return line
+      const h = /^(#{1,6})(\s)/.exec(line)
+      if (!h) return line
+      return '#'.repeat(Math.min(h[1].length + by, MAX_HEADING_LEVEL)) + line.slice(h[1].length)
+    })
+    .join('\n')
+}
+
+// The phase file's h1 exactly as written — `Phase 2 — The inline projection 🔄`.
+// `projectPhaseBody` drops it because a sub-issue projects the title as `name`
+// and the emoji as `state`; inlined there are no such fields, so this heading is
+// the only place either can live, and the raw line is where both still are.
+function phaseHeading(phase) {
+  for (const line of phase.lines || []) {
+    const h1 = /^#\s+(.*\S)\s*$/.exec(line)
+    if (h1) return h1[1]
+  }
+  return phase.name
+}
+
+/**
+ * Append the inlined phases to the spec issue's description as `###` sections.
+ *
+ * The body is `subIssueBody`'s — the SAME composer the sub-issue form uses, so
+ * `inline` inherits its fidelity guarantee instead of growing a second extractor
+ * that drops content, which is exactly what the reporting project had to
+ * hand-roll before this existed.
+ */
+function withInlinePhases(description, inlined, tasksMode, localOnlySections) {
+  if (!inlined.length) return description
+  const sections = inlined.map((phase) => {
+    const body = demoteHeadings(subIssueBody(phase, tasksMode, localOnlySections) || '', INLINE_PHASE_LEVEL - 1)
+    const heading = '#'.repeat(INLINE_PHASE_LEVEL) + ` ${phaseHeading(phase)}`
+    return body ? `${heading}\n\n${body}` : heading
   })
-  return flattenNestedTables(parts.join('\n'))
+  return [description, ...sections].filter(Boolean).join('\n\n') || null
 }
 
 /**
@@ -570,6 +660,35 @@ function bucketFromPath(snapshotDir) {
 // the states in which phases are not yet worth minting as sub-issues.
 const UNSTARTED_BUCKETS = ['backlog', 'cancelled']
 
+// The mode a bucket gets when a per-bucket `mapping.phases` map omits it. Adding
+// a bucket to the map is therefore an EXCEPTION for that bucket, not a switch
+// that silently suppresses phases everywhere the map is silent. Matches the
+// scalar default in the provider's config so both forms start from one place.
+const DEFAULT_PHASE_MODE = 'subissue'
+
+/**
+ * The phase mode configured for one lifecycle bucket.
+ *
+ * `mapping.phases` is EITHER a scalar — one mode for the whole repo, which is
+ * what every config was before per-bucket mapping — or a map keyed by lifecycle
+ * bucket (`{ backlog: 'subissue', complete: 'inline' }`), because a repo can
+ * legitimately want assignable sub-issues for work in flight and none at all for
+ * 250 finished specs. A scalar resolves to itself for every bucket, so existing
+ * configs are unchanged.
+ *
+ * The SINGLE place a mode is decided: the projection and the description's
+ * `## Phases` index both read it, so they cannot disagree about one spec.
+ */
+function phaseModeFor(bucket, config) {
+  const configured = config && config.mapping && config.mapping.phases
+  if (typeof configured === 'string') return configured
+  if (configured && typeof configured === 'object' && !Array.isArray(configured)) {
+    const mode = configured[bucket]
+    return typeof mode === 'string' ? mode : DEFAULT_PHASE_MODE
+  }
+  return DEFAULT_PHASE_MODE
+}
+
 /**
  * Which phases the projection sends, and how many the `deferred` mapping is
  * holding back. Pure — split out so both the projection and the CLI's "N phases
@@ -591,10 +710,25 @@ function specStatus(snapshotDir, frontmatter) {
 
 function phaseProjection(phases, workflowState, config) {
   const named = phases.filter((p) => p.name)
-  const deferring =
-    (config.mapping && config.mapping.phases) === 'deferred' && UNSTARTED_BUCKETS.includes(workflowState)
-  const projected = deferring ? named.filter((p) => p.id != null) : named
-  return { projected, withheld: named.length - projected.length }
+  const mode = phaseModeFor(workflowState, config)
+  // `deferred` and `inline` both send only phases that ALREADY carry an id, and
+  // for the same reason: one-way sync has no delete op, so withholding a live
+  // sub-issue would freeze it in the tracker rather than remove it (Decision 4).
+  // They differ only in where an unlinked phase goes — nowhere yet, or into the
+  // spec issue's own description.
+  const deferring = mode === 'deferred' && UNSTARTED_BUCKETS.includes(workflowState)
+  const projected = deferring || mode === 'inline' ? named.filter((p) => p.id != null) : named
+  const unlinked = named.filter((p) => p.id == null)
+  return {
+    projected,
+    // Held back until the work starts. Nothing carries them meanwhile, which is
+    // why the `## Phases` index stays and the CLI says how many.
+    withheld: deferring ? unlinked.length : 0,
+    // Rendered into the description instead. Deliberately NOT counted as
+    // withheld: nothing is missing from the mirror, so a report that said "N
+    // phases deferred" would be describing the opposite of what happened.
+    inlined: mode === 'inline' ? unlinked : [],
+  }
 }
 
 function normalizeLocal(snapshotDir, config) {
@@ -606,22 +740,34 @@ function normalizeLocal(snapshotDir, config) {
   // status — so the issue's state and its sub-issues always agree on whether the
   // work has started, however that status was arrived at.
   const workflowState = specStatus(snapshotDir, frontmatter)
-  const { projected, withheld } = phaseProjection(phases, workflowState, config)
-
-  // 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. While deferral is holding
-  // a phase back, that index is the ONLY place the phase appears — stripping it
-  // too would leave a backlog issue with no phase breakdown at all — so it stays
-  // until the sub-issues arrive to replace it.
-  const phasesProjected =
-    !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership) && withheld === 0
+  const { projected, withheld, inlined } = phaseProjection(phases, workflowState, config)
+
+  // Strip the `## Phases` index only when the SUB-ISSUES replace it: they carry
+  // every phase, so keeping the index would duplicate the list as prose AND as
+  // objects. It stays whenever they do not — while deferral holds a phase back
+  // the index is the only place that phase appears, and under `inline` there are
+  // no new sub-issues at all, so it is the issue's only table of contents
+  // (Decision 3).
+  //
+  // Keyed on the resolved MODE rather than on `subIssues` being an owned field:
+  // ownership says WHICH fields sync, which is a different question from how
+  // phases are shaped, and `inline` answers the second one per spec (Decision 5).
+  // Ownership still gets a say — an unowned `subIssues` pushes no sub-issues at
+  // all, so the index has to stay there too.
+  const syncsSubIssues = !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership)
+  const phasesCarriedBySubIssues =
+    syncsSubIssues && phaseModeFor(workflowState, config) !== 'inline' && withheld === 0
   const extracted = {
-    description: buildDescription(
-      title,
-      sections,
+    description: withInlinePhases(
+      buildDescription(
+        title,
+        sections,
+        config.sync.localOnlySections,
+        phasesCarriedBySubIssues ? ['Phases'] : [],
+      ),
+      inlined,
+      tasksMode,
       config.sync.localOnlySections,
-      phasesProjected ? ['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.
@@ -633,7 +779,7 @@ function normalizeLocal(snapshotDir, config) {
       id: p.id,
       ref: p.phase,
       name: p.name,
-      goal: subIssueBody(p, tasksMode),
+      goal: subIssueBody(p, tasksMode, config.sync.localOnlySections),
       state: p.state,
     })),
     workflowState,
@@ -819,6 +965,7 @@ module.exports = {
   stateSuggestions,
   normalizeLocal,
   phaseProjection,
+  phaseModeFor,
   phasesWithheld,
   lintPhases,
   readSnapshot,

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

@@ -15,7 +15,7 @@
  * Date.now(). `recordPush` writes the snapshot sidecar.
  */
 
-const { normalizeLocal, phasesWithheld } = require('./normalize.js')
+const { normalizeLocal, phasesWithheld, phaseModeFor } = require('./normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
 const { readBase, writeBase } = require('./base.js')
 const { detectLegacyMirror } = require('./legacy.js')
@@ -34,6 +34,11 @@ function projectionOf(snapshotDir, config) {
     // only — `snapshotOf`/`specIssueHash` read named fields, so this never
     // reaches a hash and cannot make an unchanged spec look edited.
     phasesWithheld: phasesWithheld(snapshotDir, config),
+    // The phase mode that resolved for THIS spec's bucket. Reporting only, on
+    // the same terms: a spec with no sub-issues has to read as deliberate rather
+    // than as phase files that failed to parse, and with `mapping.phases` now a
+    // per-bucket map, which mode applied is no longer readable off the config.
+    phaseMode: phaseModeFor(local.workflowState, config),
   }
 }
 
@@ -51,6 +56,10 @@ function push({ dir, snapshotDir, identifier, config }) {
   // because `--json` routes warnings to stderr and the skill applying the plan
   // is the consumer that most needs to know the missing sub-issues are deliberate.
   if (projection.phasesWithheld) plan.phasesDeferred = projection.phasesWithheld
+  // Always set, unlike the two above: the skill relaying this should not have to
+  // know that an absent field means `subissue`. `isEmptyPlan` and `snapshotOf`
+  // both read named fields, so an extra key cannot make a spec look edited.
+  plan.phaseMode = projection.phaseMode
   return { ok: true, empty: isEmptyPlan(plan), plan, projection }
 }
 

package/src/vendor/sync-core/src/task-block.js

@@ -16,15 +16,23 @@ const DEFAULT_WIDTH = 80
 
 // Start of a task bullet. The continuation lines that follow are any indented,
 // non-empty lines that are not themselves a bullet or heading.
-const TASK_START_RE = /^([ \t]*)-\s*\[([ xX])\]\s*(.*)$/
+//
+// The mark is ANY single character, not just ` `/`x`. Projects use `[~]` for
+// in-progress, `[>]` for deferred, `[-]` for dropped, and a parser that only
+// knew ` xX` matched none of them — so the whole bullet was claimed by no block
+// and vanished from the mirror (bug-phase-content-dropped). What the mark MEANS
+// is nobody's business here; it is carried through verbatim and re-emitted as
+// written. Only `x`/`X` counts as done (see `parseTaskLine`).
+const TASK_START_RE = /^([ \t]*)-\s*\[([^\]])\]\s*(.*)$/
 const CONTINUATION_RE = /^[ \t]+\S/
 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]\]/
+// at any indent. (A bare list marker is ambiguous; a checkbox never is.) Any
+// mark, matching TASK_START_RE.
+const CHECKBOX_RE = /^[ \t]*[-*+]\s*\[[^\]]\]/
 // A bare list bullet — no checkbox — captured with its marker so a sub-bullet
 // is re-rendered as the `-`/`*`/`1.` its author wrote.
 const BULLET_RE = /^([ \t]*)([-*+]|\d+\.)\s+(.*)$/
@@ -181,7 +189,9 @@ function findTaskBlocks(lines) {
         indent: t[1],
         marker: '-',
         checkbox: true,
-        mark: t[2].toLowerCase() === 'x' ? 'x' : ' ',
+        // Case-folded for `x` (the one mark whose meaning we act on), otherwise
+        // verbatim — a project's `~`/`>`/`-` must round-trip as written.
+        mark: t[2].toLowerCase() === 'x' ? 'x' : t[2],
         text: collapseHyphenAware(parts.join('\n')),
       })
       open.push(indent)
@@ -189,9 +199,10 @@ function findTaskBlocks(lines) {
       continue
     }
 
-    // A bare bullet is claimed ONLY inside an open task's subtree. Outside one
-    // it is ordinary prose in the phase file: the projection is the task list,
-    // not the whole body, and widening it here would mirror a Notes section.
+    // A bare bullet is claimed ONLY inside an open task's subtree — there it is
+    // part of the task and must be re-rendered with it. Outside one it is
+    // ordinary prose, which the projection now passes through verbatim, so
+    // claiming it here would only re-wrap a list nobody asked us to touch.
     if (!open.length) continue
     const b = BULLET_RE.exec(line)
     if (!b) continue