@skitterbyte/skitterspec-linear 8.0.4 → 9.0.0

package/src/vendor/linear/cli-sync.js

@@ -12,6 +12,7 @@
  *   spec-sync push <spec>        print the create/update PLAN the skill applies
  *   spec-sync record <spec>      write the last-pushed snapshot (after apply)
  *   spec-sync status <spec>      read-only drift report (never writes)
+ *   spec-sync linked             list every spec's linear_identifier (offline)
  *
  * The `/spec-push` skill: `push` → apply the plan over MCP → stamp returned ids
  * into the repo → `record`. There is no pull — Linear is not read for content.
@@ -20,10 +21,11 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
-const { findSpecFolder } = require('../../env/resolve.js')
+const { BUCKETS, findSpecFolder } = require('../../env/resolve.js')
 const {
   normalizeLocal,
   readSnapshot,
+  parseFrontmatter,
   readBase,
   push,
   recordPush,
@@ -58,6 +60,77 @@ function specIdentifier(snapshotDir, config) {
   return path.basename(snapshotDir)
 }
 
+// Read a spec's `linear_identifier` without throwing: an unlinked spec, an
+// unreadable file and a spec with no frontmatter all read as `null`.
+function linkedIdentifier(overviewPath) {
+  let raw
+  try {
+    raw = fs.readFileSync(overviewPath, 'utf-8')
+  } catch {
+    return null
+  }
+  const { data } = parseFrontmatter(raw)
+  return data.linear_identifier ? String(data.linear_identifier) : null
+}
+
+// Every spec under specs/<bucket>/, paired with the Linear issue it is linked to
+// (`null` when it has never been pushed). Folder specs read `snapshot.overviewFile`;
+// legacy bare `<name>.md` specs read the file itself. Sorted for stable output.
+function listSpecs(dir, config) {
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const specs = []
+  for (const bucket of BUCKETS) {
+    const root = path.join(dir, 'specs', bucket)
+    let entries
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      let name
+      let overviewPath
+      if (entry.isDirectory()) {
+        name = entry.name
+        overviewPath = path.join(root, name, overviewFile)
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        name = entry.name.slice(0, -3)
+        overviewPath = path.join(root, entry.name)
+      } else {
+        continue
+      }
+      specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath) })
+    }
+  }
+  return specs.sort((a, b) => a.spec.localeCompare(b.spec))
+}
+
+/**
+ * `spec-sync linked` — which Linear issues are already adopted by a spec.
+ *
+ * Offline and read-only: the intake seam (`/spec <ISSUE-REF>`,
+ * `/spec --from-issue`) subtracts these from the inbox and refuses to adopt an
+ * issue twice, without reading Linear back.
+ */
+function specSyncLinked(dir, config, flags, out) {
+  const specs = listSpecs(dir, config)
+  if (flags.json) {
+    out.write(JSON.stringify(specs, null, 2) + '\n')
+    return
+  }
+  if (!specs.length) {
+    out.write('spec-sync linked: no specs found under specs/\n')
+    return
+  }
+  const lines = ['spec-sync linked:']
+  for (const s of specs) {
+    lines.push(`  ${s.identifier || '—'}\t${s.spec}  (${s.bucket})`)
+  }
+  const n = specs.filter((s) => s.identifier).length
+  lines.push(`  ${n}/${specs.length} linked`)
+  out.write(lines.join('\n') + '\n')
+}
+
 function resolveOrExit(specArg, dir, out) {
   if (!specArg) return null
   const snapshotDir = resolveSnapshotDir(specArg, dir)
@@ -91,11 +164,9 @@ function specSyncPush(dir, config, specArg, flags, out) {
   const lines = [`spec-sync push: ${identifier}`]
   if (r.empty) lines.push('  nothing to push — mirror matches the last push')
   else {
-    if (p.project) lines.push('  project: description/status')
-    if (p.milestones.create.length) lines.push(`  milestones create: ${p.milestones.create.map((m) => m.name).join(', ')}`)
-    if (p.milestones.update.length) lines.push(`  milestones update: ${p.milestones.update.map((m) => m.id).join(', ')}`)
-    if (p.issues.create.length) lines.push(`  issues create: ${p.issues.create.length}`)
-    if (p.issues.update.length) lines.push(`  issues update: ${p.issues.update.map((i) => i.id).join(', ')}`)
+    if (p.issue) lines.push('  issue: description/state')
+    if (p.subIssues.create.length) lines.push(`  sub-issues create: ${p.subIssues.create.map((s) => s.name).join(', ')}`)
+    if (p.subIssues.update.length) lines.push(`  sub-issues update: ${p.subIssues.update.map((s) => s.id).join(', ')}`)
     lines.push('  (run with --json for the full plan the skill applies)')
   }
   out.write(lines.join('\n') + '\n')
@@ -128,7 +199,7 @@ function specSyncStatus(dir, config, specArg, flags, out) {
     if (missing.length) {
       out.write(
         `spec-sync status: ERROR — configured state name(s) not in the workspace: ${missing.join(', ')}. ` +
-          `Linear silently ignores an unknown project status; fix specs/.core/linear.config.json.\n`,
+          `Linear silently ignores an unknown issue state; fix specs/.core/linear.config.json.\n`,
       )
       return 1
     }
@@ -141,9 +212,9 @@ function specSyncStatus(dir, config, specArg, flags, out) {
   if (!snapshot) lines.push('  push: never pushed — everything is pending')
   else if (isEmptyPlan(plan)) lines.push('  push: up to date — nothing changed since the last push')
   else {
-    const n = plan.milestones.create.length + plan.issues.create.length
-    const u = plan.milestones.update.length + plan.issues.update.length
-    lines.push(`  push: pending — ${n} to create, ${u} to update${plan.project ? ', project changed' : ''}`)
+    const n = plan.subIssues.create.length
+    const u = plan.subIssues.update.length
+    lines.push(`  push: pending — ${n} to create, ${u} to update${plan.issue ? ', issue changed' : ''}`)
   }
 
   if (flags.remote && fs.existsSync(flags.remote)) {
@@ -197,10 +268,14 @@ async function specSync(rest, io = {}) {
       return 0
     case 'status':
       return specSyncStatus(dir, config, positional[0], flags, out) || 0
+    case 'linked':
+      specSyncLinked(dir, config, flags, out)
+      return 0
     default:
-      out.write('Usage: skitterspec spec-sync <normalize|push|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n')
+      out.write('Usage: skitterspec spec-sync <normalize|push|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+        '       skitterspec spec-sync linked [--json]\n')
       return 0
   }
 }
 
-module.exports = { specSync }
+module.exports = { specSync, listSpecs }

package/src/vendor/linear/config.js

@@ -16,7 +16,8 @@
  *
  * Shape (see assets/core/linear.config.md for field docs):
  *   {
- *     linear:   { teamKey, teamId, initiativeId },
+ *     linear:   { teamKey, teamId, projectId },
+ *     intake:   { label, bugLabels },
  *     mapping:  { specFolder, phases, tasks },
  *     states:   { backlog, "in-progress", complete, cancelled },
  *     snapshot: { overviewFile },
@@ -37,16 +38,29 @@ const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
 const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
 
 const DEFAULT_CONFIG = Object.freeze({
-  linear: Object.freeze({ teamKey: '', teamId: '', initiativeId: '' }),
-  mapping: Object.freeze({ specFolder: 'project', phases: 'milestone', tasks: 'issue' }),
-  // Linear PROJECT statuses (mapping.specFolder is `project`) — NOT issue-status
-  // names. Linear silently no-ops save_project on an unknown status (200,
-  // unchanged), so these must match the workspace exactly; `validateStates`
-  // checks them at push/status time.
+  // `projectId` is the project picker's DEFAULT, not a mandate: `/spec` and the
+  // first `/spec-push` offer the team's projects and pre-select this one; empty
+  // means "None (team only)" is pre-selected. It is passed on the issue-create
+  // call only and never stored in the spec or the snapshot, so a PM re-homing the
+  // issue in Linear is invisible to sync. (The old `initiativeId` grouped
+  // Projects, which no longer exist.)
+  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([]) }),
+  // 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).
+  mapping: Object.freeze({ specFolder: 'issue', phases: 'subissue', tasks: 'none' }),
+  // 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;
+  // `validateStates` checks them at push/status time.
   states: Object.freeze({
     backlog: 'Backlog',
     'in-progress': 'In Progress',
-    complete: 'Completed',
+    complete: 'Done',
     cancelled: 'Canceled',
   }),
   snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
@@ -55,22 +69,21 @@ const DEFAULT_CONFIG = Object.freeze({
     baseDir: 'specs/.core/linear-base',
     backupDir: 'specs/.core/linear-backups',
     // One-way (repo → Linear): the projection field set the repo owns and pushes
-    // — the project `description`, `milestones` (one per phase), `tasks` (one
-    // issue each), and the lifecycle `workflowState`. There is no pull. Priority,
+    // — the issue `description`, its `subIssues` (one per phase, name + goal +
+    // state), and the lifecycle `workflowState`. There is no pull. Priority,
     // labels, cycles and comments are Linear-native triage — deliberately NOT in
     // the set, so the PM's triage is never touched. The `push` marker is retained
     // for shape; any key you add joins the pushed projection.
     fieldOwnership: Object.freeze({
       description: 'push',
-      milestones: 'push',
-      tasks: 'push',
+      subIssues: 'push',
       workflowState: 'push',
     }),
     localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
     // Fields that are keyed collections (arrays of objects with a stable id),
     // compared/merged per item rather than as one opaque value. Map field name →
     // the item's id property. Empty by default — a workspace opts a field in
-    // (e.g. { milestones: "id", tasks: "id" }) once the body round-trip is wired.
+    // (e.g. { subIssues: "ref" }) once the body round-trip is wired.
     keyedFields: Object.freeze({}),
   }),
 })
@@ -83,6 +96,7 @@ function isObject(value) {
 function defaults() {
   return {
     linear: { ...DEFAULT_CONFIG.linear },
+    intake: { label: DEFAULT_CONFIG.intake.label, bugLabels: [...DEFAULT_CONFIG.intake.bugLabels] },
     mapping: { ...DEFAULT_CONFIG.mapping },
     states: { ...DEFAULT_CONFIG.states },
     snapshot: { ...DEFAULT_CONFIG.snapshot },
@@ -110,6 +124,11 @@ function assign(base, parsed, key, type) {
   }
 }
 
+// Normalise an array config value to trimmed, non-empty strings.
+function stringList(value) {
+  return value.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
+}
+
 // Merge (and validate) sync.fieldOwnership. Any key the caller lists joins the
 // compared field set; the value MUST be one of both|pull|push.
 function mergeFieldOwnership(base, parsed) {
@@ -150,7 +169,14 @@ function mergeConfig(base, parsed) {
   if (isObject(parsed.linear)) {
     assign(base.linear, parsed.linear, 'teamKey', 'string?')
     assign(base.linear, parsed.linear, 'teamId', 'string?')
-    assign(base.linear, parsed.linear, 'initiativeId', 'string?')
+    assign(base.linear, parsed.linear, 'projectId', 'string?')
+  }
+
+  if (isObject(parsed.intake)) {
+    assign(base.intake, parsed.intake, 'label', 'string?')
+    if (Array.isArray(parsed.intake.bugLabels)) {
+      base.intake.bugLabels = stringList(parsed.intake.bugLabels)
+    }
   }
 
   if (isObject(parsed.mapping)) {
@@ -179,9 +205,7 @@ function mergeConfig(base, parsed) {
     mergeFieldOwnership(base.sync.fieldOwnership, parsed.sync.fieldOwnership)
     mergeKeyedFields(base.sync.keyedFields, parsed.sync.keyedFields)
     if (Array.isArray(parsed.sync.localOnlySections)) {
-      base.sync.localOnlySections = parsed.sync.localOnlySections
-        .filter((s) => typeof s === 'string' && s.trim())
-        .map((s) => s.trim())
+      base.sync.localOnlySections = stringList(parsed.sync.localOnlySections)
     }
   }
 

package/src/vendor/linear/mcp.js

@@ -3,38 +3,40 @@
 /**
  * The Linear MCP boundary — the one place that knows concrete Linear tool names.
  *
- * `discoverLinear(tools)` resolves the operations the sync needs (read/update a
- * Project, list/create/update Milestones + Issues) against the *connected*
- * server's advertised tool list at runtime, rather than hardcoding names that
- * drift. If Linear isn't connected (empty / zero-match tool list) it returns a
- * clean `{ ok:false, error }` so the caller can stop and do nothing destructive.
+ * A spec is a Linear **issue** and each phase a **sub-issue** (a child issue
+ * with a `parentId`); tasks are not synced. `discoverLinear(tools)` resolves the
+ * issue operations the sync needs (read / create / update an issue, optionally
+ * list a parent's children) against the *connected* server's advertised tool
+ * list at runtime, rather than hardcoding names that drift. If Linear isn't
+ * connected (empty / zero-match tool list) it returns a clean `{ ok:false,
+ * error }` so the caller can stop and do nothing destructive.
  *
  * `makeAdapter(callTool, resolved)` wraps a generic `callTool(name, args)` (the
- * skill's MCP invoker) into the typed async operations push/pull consume. Tests
- * inject a fake adapter directly (an in-memory Project), so the engine stays
- * offline and deterministic; production wires `callTool` to the real MCP server.
+ * skill's MCP invoker) into the typed async operations push consumes. Tests
+ * inject a fake `callTool`, so the engine stays offline and deterministic;
+ * production wires `callTool` to the real MCP server.
  */
 
 // Canonical operations, and the regexes that match a Linear MCP tool name to
 // each. Ordered patterns: first match wins. Matched against the real connected
-// Linear MCP server: it exposes a single upsert `save_*` tool per object (create
-// when no id, update when id given) rather than separate create/update verbs, so
-// each write op accepts `save_*` as well as the legacy `create_`/`update_` names.
+// Linear MCP server: it exposes a single upsert `save_issue` tool (create when
+// no id, update when id given) rather than separate create/update verbs, so each
+// write op accepts `save_issue` as well as the legacy `create_`/`update_` names.
 const MATCHERS = {
-  projectRead: [/get_?project\b/i, /read_?project/i, /project_?get/i],
-  projectUpdate: [/save_?project/i, /update_?project/i, /project_?update/i],
-  projectCreate: [/save_?project/i, /create_?project/i, /project_?create/i],
-  milestoneList: [/list_?.*milestone/i, /milestones?_?list/i, /get_?.*milestones?/i],
-  milestoneCreate: [/save_?.*milestone/i, /create_?.*milestone/i, /milestone_?create/i],
-  milestoneUpdate: [/save_?.*milestone/i, /update_?.*milestone/i, /milestone_?update/i],
-  issueList: [/list_?issues?/i, /issues?_?list/i, /get_?issues?/i],
+  issueRead: [/get_?issue\b/i, /read_?issue/i, /issue_?get/i],
   issueCreate: [/save_?issue/i, /create_?issue/i, /issue_?create/i],
   issueUpdate: [/save_?issue/i, /update_?issue/i, /issue_?update/i],
+  // list only — NOT `get_issues?`, which would greedily claim the singular
+  // `get_issue` (first-name-wins) and leave issueRead/issueList conflated.
+  issueList: [/list_?issues?/i, /issues?_?list/i],
+  // The team's Linear Projects, for the `/spec` + `/spec-push` project picker.
+  // Plural-only for the same reason as issueList: `get_project` is a read.
+  projectList: [/list_?projects?/i, /projects?_?list/i],
 }
 
-// The minimum the push/pull engine can't run without. Milestone/issue ops are
-// optional in Phase 2 (project description round-trips first).
-const REQUIRED = ['projectRead', 'projectUpdate']
+// The minimum the push engine can't run without: read an issue back and
+// create/upsert one (which also covers sub-issues via a `parentId`).
+const REQUIRED = ['issueRead', 'issueCreate']
 
 // Normalise a tools argument (array of strings or {name} objects) to names.
 function toolNames(tools) {
@@ -70,7 +72,7 @@ function discoverLinear(tools) {
       ok: false,
       error:
         `Linear MCP is connected but missing required tools: ${missing.join(', ')}. ` +
-        'Check the linear server exposes project read + update.',
+        'Check the linear server exposes issue read + create.',
       resolved,
       missing,
     }
@@ -90,41 +92,46 @@ function makeAdapter(callTool, resolved) {
     return name
   }
   return {
-    // Linear's project-read tool keys on `query` (accepts a UUID, key, or slug).
-    async readProject(id) {
-      return callTool(need('projectRead'), { query: id })
+    // Linear's issue-read tool keys on `query` (accepts a UUID, identifier, or
+    // title). Used to read a mirror issue's workflow state for drift reporting.
+    async readIssue(id) {
+      return callTool(need('issueRead'), { query: id })
     },
-    // `save_project` upserts: with `id` it updates, without it creates. Create
-    // needs a name and at least one team (`addTeams`).
-    async createProject(project) {
-      return callTool(need('projectCreate'), { ...project })
+    // The SPEC issue. `save_issue` upserts: without `id` it creates, with `id` it
+    // updates. Create needs `title` + `team`; `project` (optional) groups it.
+    async createIssue(issue) {
+      return callTool(need('issueCreate'), { ...issue })
     },
-    async updateProject(id, updates) {
-      return callTool(need('projectUpdate'), { id, ...updates })
-    },
-    // List a project's milestones (the pull read side). Most Linear reads also
-    // return milestones inline on the project via includeMilestones — this is the
-    // explicit list op for callers that need it on its own.
-    async listMilestones(projectId) {
-      return callTool(need('milestoneList'), { project: projectId })
+    async updateIssue(id, updates) {
+      return callTool(need('issueUpdate'), { id, ...updates })
     },
-    // `save_milestone` requires the owning `project`; upserts on `id`.
-    async createMilestone(projectId, milestone) {
-      return callTool(need('milestoneCreate'), { project: projectId, ...milestone })
+    // A phase SUB-ISSUE: a child issue carrying `parentId` = the spec issue.
+    // Same upsert tool, so it inherits create-on-no-id / update-on-id.
+    async createSubIssue(parentId, subIssue) {
+      return callTool(need('issueCreate'), { parentId, ...subIssue })
     },
-    async updateMilestone(projectId, id, updates) {
-      return callTool(need('milestoneUpdate'), { project: projectId, id, ...updates })
+    async updateSubIssue(id, updates) {
+      return callTool(need('issueUpdate'), { id, ...updates })
     },
-    // Issues (tasks). List the project's issues (pull read side); `save_issue`
-    // upserts on `id`, attached to the project (and optionally a milestone).
-    async listIssues(projectId) {
-      return callTool(need('issueList'), { project: projectId })
+    // List a spec issue's sub-issues (read side, for drift). Optional op.
+    async listSubIssues(parentId) {
+      return callTool(need('issueList'), { parentId })
     },
-    async createIssue(projectId, issue) {
-      return callTool(need('issueCreate'), { project: projectId, ...issue })
+    // The intake inbox: issues matching a label and/or a free-text query, scoped
+    // to a team. Rides the same discovered list op as `listSubIssues` — Linear's
+    // `list_issues` filters on all three — so intake adds no new required tool.
+    // Omitted filters are left off the call rather than sent empty.
+    async searchIssues({ label, query, teamId } = {}) {
+      const args = {}
+      if (label) args.label = label
+      if (query) args.query = query
+      if (teamId) args.team = teamId
+      return callTool(need('issueList'), args)
     },
-    async updateIssue(id, updates) {
-      return callTool(need('issueUpdate'), { id, ...updates })
+    // The team's projects, for the project picker. Optional: a server without a
+    // project-list tool just means the picker is unavailable, never a failed push.
+    async listProjects(teamId) {
+      return callTool(need('projectList'), teamId ? { team: teamId } : {})
     },
   }
 }

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

@@ -10,16 +10,17 @@
  * over its API. No remote content is read or merged.
  */
 
-const { normalizeLocal, readSnapshot, remoteWorkflowState, titleFromText, validateStates } = require('./src/normalize.js')
+const { normalizeLocal, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates } = require('./src/normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify } = require('./src/compare.js')
 const { readBase, writeBase } = require('./src/base.js')
 const { push, recordPush, projectionOf } = require('./src/push.js')
-const { writeFrontmatter, stampMilestoneId, stampIssueId, findPhaseFileByTitle } = require('./src/write.js')
+const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 
 module.exports = {
   normalizeLocal,
   readSnapshot,
+  parseFrontmatter,
   projectionOf,
   planChanges,
   snapshotOf,
@@ -34,7 +35,7 @@ module.exports = {
   readBase,
   writeBase,
   writeFrontmatter,
-  stampMilestoneId,
+  stampSubIssueId,
   stampIssueId,
   findPhaseFileByTitle,
   sanitizeSpecMarkdown,

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

@@ -6,7 +6,7 @@
  * One-way sync (repo → Linear) records what it last pushed per spec at
  * `{sync.baseDir}/{identifier}.base.json`, committed so each worktree carries its
  * own snapshot. The snapshot is a set of content hashes
- * (`{ project, milestones: {id:hash}, issues: {id:hash} }`, see compare.js
+ * (`{ issue, subIssues: {id:hash} }`, see compare.js
  * `snapshotOf`); `planChanges` diffs the current projection against it to decide
  * create/update/skip — no remote read. After a successful push the engine
  * rewrites it (`writeBase`). Generic JSON read/write; the shape is the caller's.

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

@@ -40,19 +40,20 @@ function hashField(value) {
 // --- content hashes (id / local handles excluded, so they never affect the
 //     diff — an id stamped in after a create must not read as an edit) ---------
 
-// The project fields the repo owns and pushes: prose + workflow state. Priority,
-// labels, cycles and comments are Linear-native triage — one-way sync neither
-// pushes nor reads them, so a PM's triage is never clobbered.
-function projectHash(p) {
-  return hashField({ description: p.description ?? null, status: p.status ?? null })
+// The spec ISSUE fields the repo owns and pushes: prose + workflow state.
+// Priority, labels, cycles and comments are Linear-native triage — one-way sync
+// neither pushes nor reads them, so a PM's triage is never clobbered.
+function specIssueHash(p) {
+  return hashField({ description: p.description ?? null, state: p.status ?? null })
 }
-const milestoneHash = (m) => hashField({ name: m.name ?? null, goal: m.goal ?? null })
-const issueHash = (t) => hashField({ title: t.title ?? null, description: t.description ?? null, done: !!t.done })
+// A phase SUB-ISSUE: its name, goal and state (all repo-owned).
+const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
 
 /**
- * The snapshot to commit after a successful push: a content hash per object that
- * currently has an id. Create items (id == null) aren't recorded until the skill
- * stamps their returned id and the next projection includes it.
+ * The snapshot to commit after a successful push: the spec-issue hash plus a
+ * content hash per sub-issue that currently has an id. Create items (id == null)
+ * aren't recorded until the skill stamps their returned id and the next
+ * projection includes it.
  */
 function snapshotOf(projection) {
   const p = projection || {}
@@ -62,54 +63,42 @@ function snapshotOf(projection) {
     return out
   }
   return {
-    project: projectHash(p),
-    milestones: byId(p.milestones, milestoneHash),
-    issues: byId(p.issues, issueHash),
+    issue: specIssueHash(p),
+    subIssues: byId(p.subIssues, subIssueHash),
   }
 }
 
 /**
  * Diff the local projection against the last-pushed snapshot.
- * @returns {{ project?: object, milestones: {create,update}, issues: {create,update} }}
+ * @returns {{ issue?: object, subIssues: {create,update} }}
  *   create items carry a `ref` (local handle) and no id; update items carry `id`.
+ *   `plan.issue` (when present) is the spec issue's description + state; the push
+ *   skill applies `config.linear.projectId` grouping on top of it.
  */
 function planChanges(projection, snapshot) {
   const p = projection || {}
   const snap = snapshot || {}
-  const snapM = snap.milestones || {}
-  const snapI = snap.issues || {}
+  const snapS = snap.subIssues || {}
 
-  const milestones = { create: [], update: [] }
-  for (const m of p.milestones || []) {
-    if (m.id == null) milestones.create.push({ ref: m.ref, name: m.name, goal: m.goal })
-    else if (snapM[String(m.id)] !== milestoneHash(m)) milestones.update.push({ id: m.id, name: m.name, goal: m.goal })
-  }
-
-  const issues = { create: [], update: [] }
-  for (const t of p.issues || []) {
-    if (t.id == null) {
-      issues.create.push({ ref: t.ref, title: t.title, description: t.description, done: !!t.done, milestoneRef: t.milestoneRef })
-    } else if (snapI[String(t.id)] !== issueHash(t)) {
-      issues.update.push({ id: t.id, title: t.title, description: t.description, done: !!t.done })
+  const subIssues = { create: [], update: [] }
+  for (const s of p.subIssues || []) {
+    if (s.id == null) {
+      subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
+    } else if (snapS[String(s.id)] !== subIssueHash(s)) {
+      subIssues.update.push({ id: s.id, name: s.name, goal: s.goal, state: s.state })
     }
   }
 
-  const plan = { milestones, issues }
-  if (snap.project !== projectHash(p)) {
-    plan.project = { description: p.description ?? null, status: p.status ?? null }
+  const plan = { subIssues }
+  if (snap.issue !== specIssueHash(p)) {
+    plan.issue = { description: p.description ?? null, state: p.status ?? null }
   }
   return plan
 }
 
 // True when a plan would push nothing.
 function isEmptyPlan(plan) {
-  return (
-    !plan.project &&
-    !plan.milestones.create.length &&
-    !plan.milestones.update.length &&
-    !plan.issues.create.length &&
-    !plan.issues.update.length
-  )
+  return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length
 }
 
 module.exports = {
@@ -118,7 +107,6 @@ module.exports = {
   isEmptyPlan,
   hashField,
   stableStringify,
-  projectHash,
-  milestoneHash,
-  issueHash,
+  specIssueHash,
+  subIssueHash,
 }