@skitterbyte/skitterspec-linear 10.1.0 → 10.2.0

package/src/vendor/linear/config.js

@@ -17,7 +17,7 @@
  * Shape (see assets/core/linear.config.md for field docs):
  *   {
  *     linear:   { teamKey, teamId, projectId },
- *     intake:   { label, bugLabels },
+ *     intake:   { label, bugLabels, hotfixLabels },
  *     mapping:  { specFolder, phases, tasks },
  *     states:   { backlog, "in-progress", complete, cancelled },
  *     snapshot: { overviewFile },
@@ -53,7 +53,30 @@ const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
 //              already carries an id keeps projecting either way — one-way sync
 //              has no delete, so withholding a LINKED sub-issue would freeze it
 //              in the tracker rather than remove it.
-const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred'])
+//   inline   — never: each phase becomes a SECTION of the spec issue's own
+//              description instead, and the `## Phases` index stays as its table
+//              of contents. For work nobody will pick up phase by phase — 250
+//              finished specs are 250 issues worth reading and 669 sub-issues
+//              worth nobody's attention. Keeps an already-linked phase's
+//              sub-issue for the same reason `deferred` does.
+//
+// `mapping.phases` takes one of these as a scalar (one mode for the whole repo)
+// OR a map keyed by lifecycle bucket — `{ "backlog": "subissue", "complete":
+// "deferred" }` — because a repo can want assignable sub-issues for work in
+// flight and something else entirely for work that finished long ago. A bucket
+// the map omits gets DEFAULT_PHASE_MODE, so a partial map adds an exception
+// rather than silently suppressing phases everywhere it is silent.
+const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline'])
+const DEFAULT_PHASE_MODE = 'subissue'
+
+// How `spec-sync apply` reaches Linear. `api` talks to the GraphQL API directly;
+// `mcp` prints the plan for the skill to apply over MCP, as it always has.
+const TRANSPORTS = Object.freeze(['api', 'mcp'])
+
+// The environment variable a Linear personal API key is read from, unless
+// `auth.keyEnv` names another. The config names the VARIABLE, never the key —
+// nothing secret is ever written to the repo.
+const DEFAULT_KEY_ENV = 'LINEAR_API_KEY'
 
 const DEFAULT_CONFIG = Object.freeze({
   // `projectId` is the project picker's DEFAULT, not a mandate: `/spec` and the
@@ -65,14 +88,18 @@ const DEFAULT_CONFIG = Object.freeze({
   linear: Object.freeze({ teamKey: '', teamId: '', projectId: '' }),
   // Issue intake (`/spec <ISSUE-REF>`, `/spec --from-issue`). `label` is the
   // inbox filter — issues carrying it are what the web app files; `bugLabels`
-  // route an issue to `/spec-bug` instead of `/spec`. Both empty = no inbox to
-  // browse (a bare issue ref still works) and no bug routing.
-  intake: Object.freeze({ label: '', bugLabels: Object.freeze([]) }),
+  // route an issue to `/spec-bug` instead of `/spec`, and `hotfixLabels` route it
+  // to `/spec-hotfix` — a bug that has to be patched on the released version, not
+  // fixed on main. All empty = no inbox to browse (a bare issue ref still works)
+  // and no routing. `hotfixLabels` wins over `bugLabels` on an issue carrying
+  // both: production is the more specific destination, and the cost of getting it
+  // wrong is asymmetric — a fix that lands only on main never reaches prod.
+  intake: Object.freeze({ label: '', bugLabels: Object.freeze([]), hotfixLabels: Object.freeze([]) }),
   // A spec is a Linear ISSUE; each phase is a SUB-ISSUE of it; tasks are not
   // synced (they live only in the repo phase files).
   // A spec is an ISSUE; each phase a SUB-ISSUE of it. `tasks` selects how the
   // phase's checkboxes reach that sub-issue's description — see TASK_MAPPINGS.
-  mapping: Object.freeze({ specFolder: 'issue', phases: 'subissue', tasks: 'checklist' }),
+  mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist' }),
   // Linear ISSUE workflow-state names — the spec issue's state (from the folder
   // bucket) and each sub-issue's state (from the phase emoji) both map through
   // this one table. They must match the workspace's issue states exactly;
@@ -85,6 +112,12 @@ const DEFAULT_CONFIG = Object.freeze({
   }),
   snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
   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.
+  auth: Object.freeze({ keyEnv: DEFAULT_KEY_ENV }),
+  // `transport` is the default for `spec-sync apply --via`. Empty means "decide
+  // at run time": use the API when a key is present, MCP when it isn't.
+  apply: Object.freeze({ transport: '' }),
   sync: Object.freeze({
     baseDir: 'specs/.core/linear-base',
     backupDir: 'specs/.core/linear-backups',
@@ -108,6 +141,11 @@ const DEFAULT_CONFIG = Object.freeze({
   }),
 })
 
+// The lifecycle buckets a per-bucket `mapping.phases` map may key on. Derived
+// from `states` rather than restated: both maps key on the spec's folder bucket,
+// so they cannot drift apart.
+const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
+
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -116,11 +154,17 @@ function isObject(value) {
 function defaults() {
   return {
     linear: { ...DEFAULT_CONFIG.linear },
-    intake: { label: DEFAULT_CONFIG.intake.label, bugLabels: [...DEFAULT_CONFIG.intake.bugLabels] },
+    intake: {
+      label: DEFAULT_CONFIG.intake.label,
+      bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
+      hotfixLabels: [...DEFAULT_CONFIG.intake.hotfixLabels],
+    },
     mapping: { ...DEFAULT_CONFIG.mapping },
     states: { ...DEFAULT_CONFIG.states },
     snapshot: { ...DEFAULT_CONFIG.snapshot },
     branch: { ...DEFAULT_CONFIG.branch },
+    auth: { ...DEFAULT_CONFIG.auth },
+    apply: { ...DEFAULT_CONFIG.apply },
     sync: {
       baseDir: DEFAULT_CONFIG.sync.baseDir,
       backupDir: DEFAULT_CONFIG.sync.backupDir,
@@ -164,6 +208,47 @@ function mergeFieldOwnership(base, parsed) {
   }
 }
 
+// Merge (and validate) `mapping.phases` in either of its two forms: a scalar
+// mode for the whole repo, or a map of lifecycle bucket → mode. Loud on a bad
+// key or value, like fieldOwnership and mapping.tasks — a misspelt bucket would
+// otherwise read as a deliberate default and go on minting the sub-issues the
+// config was written to stop.
+function mergePhaseMapping(base, parsed) {
+  const value = parsed.phases
+  if (typeof value === 'string') {
+    if (value.trim()) base.phases = value.trim()
+  } else if (isObject(value)) {
+    const byBucket = {}
+    for (const [bucket, mode] of Object.entries(value)) {
+      if (!LIFECYCLE_BUCKETS.includes(bucket)) {
+        throw new Error(
+          `Invalid ${CONFIG_FILE}: mapping.phases.${bucket} is not a lifecycle bucket ` +
+            `(expected one of ${LIFECYCLE_BUCKETS.join('|')})`,
+        )
+      }
+      if (!PHASE_MAPPINGS.includes(mode)) {
+        throw new Error(
+          `Invalid ${CONFIG_FILE}: mapping.phases.${bucket} = ${JSON.stringify(mode)} ` +
+            `(expected one of ${PHASE_MAPPINGS.join('|')})`,
+        )
+      }
+      byBucket[bucket] = mode
+    }
+    base.phases = byBucket
+  } else if (value !== undefined) {
+    throw new Error(
+      `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(value)} ` +
+        `(expected one of ${PHASE_MAPPINGS.join('|')}, or a map of lifecycle bucket to mode)`,
+    )
+  }
+  if (typeof base.phases === 'string' && !PHASE_MAPPINGS.includes(base.phases)) {
+    throw new Error(
+      `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(base.phases)} ` +
+        `(expected one of ${PHASE_MAPPINGS.join('|')}, or a map of lifecycle bucket to mode)`,
+    )
+  }
+}
+
 // 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) {
@@ -197,11 +282,13 @@ function mergeConfig(base, parsed) {
     if (Array.isArray(parsed.intake.bugLabels)) {
       base.intake.bugLabels = stringList(parsed.intake.bugLabels)
     }
+    if (Array.isArray(parsed.intake.hotfixLabels)) {
+      base.intake.hotfixLabels = stringList(parsed.intake.hotfixLabels)
+    }
   }
 
   if (isObject(parsed.mapping)) {
     assign(base.mapping, parsed.mapping, 'specFolder', 'string')
-    assign(base.mapping, parsed.mapping, 'phases', 'string')
     assign(base.mapping, parsed.mapping, 'tasks', 'string')
     // Loud on a typo, like fieldOwnership above. Quietly falling back would make
     // a misspelt value look like a deliberate `none` — the same silent
@@ -212,12 +299,7 @@ function mergeConfig(base, parsed) {
           `(expected one of ${TASK_MAPPINGS.join('|')})`,
       )
     }
-    if (!PHASE_MAPPINGS.includes(base.mapping.phases)) {
-      throw new Error(
-        `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(base.mapping.phases)} ` +
-          `(expected one of ${PHASE_MAPPINGS.join('|')})`,
-      )
-    }
+    mergePhaseMapping(base.mapping, parsed.mapping)
   }
 
   if (isObject(parsed.states)) {
@@ -234,6 +316,22 @@ function mergeConfig(base, parsed) {
     assign(base.branch, parsed.branch, 'pattern', 'string')
   }
 
+  if (isObject(parsed.auth)) {
+    assign(base.auth, parsed.auth, 'keyEnv', 'string')
+  }
+
+  if (isObject(parsed.apply)) {
+    assign(base.apply, parsed.apply, 'transport', 'string?')
+    // Loud on a typo, like the mapping enums: a misspelt transport must not
+    // quietly fall back to MCP and look like a deliberate choice.
+    if (base.apply.transport && !TRANSPORTS.includes(base.apply.transport)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: apply.transport = ${JSON.stringify(base.apply.transport)} ` +
+          `(expected one of ${TRANSPORTS.join('|')})`,
+      )
+    }
+  }
+
   if (isObject(parsed.sync)) {
     assign(base.sync, parsed.sync, 'baseDir', 'string')
     assign(base.sync, parsed.sync, 'backupDir', 'string')
@@ -279,9 +377,13 @@ function loadLinearConfig(dir = process.cwd()) {
 module.exports = {
   loadLinearConfig,
   mergeConfig,
+  defaults,
   DEFAULT_CONFIG,
   CONFIG_FILE,
   OWNERSHIP,
   TASK_MAPPINGS,
   PHASE_MAPPINGS,
+  LIFECYCLE_BUCKETS,
+  TRANSPORTS,
+  DEFAULT_KEY_ENV,
 }

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