@skitterbyte/skitterspec-linear 9.1.0 → 9.2.0

package/README.md

@@ -56,12 +56,14 @@ fuller guide):
 On top of the base skills (`/spec`, `/spec-go`, isolation, …):
 
 - **`/spec-status`** — read-only drift report: what the next push would create /
-  update, plus any workflow-state drift. Changes nothing.
+  update, any workflow-state drift, and any phase whose status signals disagree
+  (see **Phase status** below). Changes nothing.
 - **`/spec-push`** — repo → Linear, one-way. Diffs the spec against a committed
   last-pushed snapshot and applies only what changed (issue description + state,
   phase sub-issues), stamping the returned ids back into the spec.
 - **`spec-sync` CLI** (`skitterspec-linear spec-sync …`) — the deterministic
-  engine behind the skills, for CI / local runs.
+  engine behind the skills, for CI / local runs:
+  `normalize` · `push` · `stamp` · `record` · `status` · `linked`.
 
 The shared `/spec`, `/spec-bug` and `/spec-go` skills come composed with the
 Linear steps filled in: `/spec` asks which Linear **Project** the spec belongs to,
@@ -83,8 +85,10 @@ spec, and a smoke test. Per-field docs live in `specs/.core/linear.config.md`.
 **What pushes:** the spec is one Linear **issue** — the spec body travels as its
 **`description`**, each phase as a **sub-issue** (phase name → title, `**Goal:**`
 → description, phase emoji → state), and the spec's lifecycle folder sets the
-issue's **workflow state**. Tasks are **not** synced — they stay in the repo phase
-files. Priority, labels, cycles and comments are **Linear-native triage** — the
+issue's **workflow state**. A phase's **tasks are mirrored** into its sub-issue's
+description as a read-only checklist (`mapping.tasks: "checklist"`, the default;
+`"none"` keeps the Goal line alone) — no issue is created per task, and a box
+ticked in Linear is overwritten by the next push. Priority, labels, cycles and comments are **Linear-native triage** — the
 PM's to set in Linear; one-way sync neither pushes nor reads them, so they're
 never clobbered. A workflow-state a teammate moves in Linear is surfaced by
 `/spec-status` as drift and overwritten on the next push. **Last-pushed snapshots**
@@ -105,6 +109,13 @@ replaces the description with the spec. A bug-labelled issue routes to
 `/spec-bug`, which adopts it the same way. `skitterspec-linear spec-sync linked`
 lists what's already adopted, so an issue never becomes two specs.
 
+**Phase status.** A phase's state in Linear comes from the `⬜`/`🔄`/`✅` on its
+phase-file **heading** — not from its `> **Status:**` line and not from the
+overview's phase-index row, which are the human mirrors of it. A heading carrying
+no emoji reads as *not started*, so `spec-sync normalize|push|status` warn when
+the emoji is missing or when the three disagree, rather than quietly mirroring a
+finished phase as backlog. The warnings never block a push.
+
 Branch naming that embeds the Linear id lives in the isolation config
 (`env.config.json` → `branch.pattern` with `{identifier}`, `branch.identifierField:
 "linear_identifier"`), not in `linear.config.json`.

package/assets/core/SETUP.md

@@ -3,8 +3,9 @@
 A start-to-finish guide to getting `/spec-status` and `/spec-push` working against
 a real Linear workspace. Sync is **one-way**: the repo is the source of truth and
 the linked Linear **issue** is a **generated mirror** — content is pushed up, never
-read back or merged. A spec is a Linear issue and each phase a sub-issue; tasks are
-not synced. Covers the **Linear side** (connecting the MCP server, finding your
+read back or merged. A spec is a Linear issue and each phase a sub-issue, with the
+phase's tasks mirrored into that sub-issue's description as a read-only
+checklist. Covers the **Linear side** (connecting the MCP server, finding your
 team) that the config reference (`linear.config.md`) assumes you already have.
 
 > The whole feature is **opt-in**: until `specs/.core/linear.config.json` exists,

package/assets/core/linear.config.json.example

@@ -11,7 +11,7 @@
   "mapping": {
     "specFolder": "issue",
     "phases": "subissue",
-    "tasks": "none"
+    "tasks": "checklist"
   },
   "states": {
     "backlog": "Backlog",

package/assets/core/linear.config.md

@@ -3,7 +3,8 @@
 Opt-in config for the Linear sync (`/spec-status`, `/spec-push`, and the
 Linear-aware paths of `/spec` and `/spec-go`). Sync is **one-way**: the repo is
 the source of truth and the Linear **issue** is a **generated mirror**. A spec is
-a Linear issue and each phase a sub-issue; tasks are not synced. Content is
+a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
+that sub-issue's description as a read-only checklist. Content is
 pushed up and never read back or merged — `/spec-push` diffs the spec against a
 committed **last-pushed snapshot** and applies only what changed; `/spec-status`
 is a read-only drift report. The `sync.fieldOwnership` map now just selects the
@@ -41,11 +42,14 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   },
 
   // How a spec's parts map onto Linear objects: a spec is an Issue, each phase a
-  // sub-issue (a child issue), tasks are not synced. These are the defaults.
+  // sub-issue (a child issue). `tasks` selects how a phase's checkboxes reach
+  // that sub-issue: "checklist" mirrors them into its description (default),
+  // "none" leaves the description as the phase's Goal line alone. Either way no
+  // issue is created per task. These are the defaults.
   "mapping": {
     "specFolder": "issue",
     "phases": "subissue",
-    "tasks": "none"
+    "tasks": "checklist"
   },
 
   // Map the spec's lifecycle bucket → the Linear ISSUE workflow-state name. Used
@@ -112,8 +116,18 @@ recreates:
 - **Phases → sub-issues.** Each phase file maps to a child issue (`parentId` = the
   spec issue). The link id lives in the phase file's frontmatter
   (`linear_issue_id`); its title ← the phase h1, its description ← the phase
-  `**Goal:**` line, its state ← the phase heading emoji (⬜/🔄/✅).
-- **Tasks are not synced.** Task checkboxes stay in the repo phase files only.
+  `**Goal:**` line plus its task checklist (see below), its state ← the phase
+  heading emoji (⬜/🔄/✅).
+- **Tasks are mirrored, not synced.** With `mapping.tasks: "checklist"` (the
+  default) a phase's checkboxes are rendered into its sub-issue's description as
+  a markdown checklist — nesting and `[x]` state preserved, any legacy inline
+  `(KEY-123)` stripped. No issue is created per task and nothing is read back, so
+  a box ticked in Linear is overwritten by the next push. Set `"none"` to keep
+  the description as the Goal line alone.
+
+  Turning this on (or off) changes every sub-issue's description, so the first
+  `/spec-push` afterwards reports every already-linked sub-issue as an update.
+  That is expected — they update in place and no duplicates are minted.
 
 Unlinked local items (a spec with no `linear_identifier`, a phase with no
 `linear_issue_id`) are created in Linear on the next `/spec-push`, which stamps

package/assets/skills/spec/SKILL.md

@@ -289,7 +289,8 @@ below (nothing to do here without one).
 If it's absent, skip this phase entirely — the spec stays local-only and `/spec`
 behaves exactly as above. When present, after writing the spec, link it to Linear
 so status and discussion live there while the repo stays the co-authoring surface.
-A spec is a Linear **issue**; each phase is a **sub-issue**; tasks are not synced:
+A spec is a Linear **issue**; each phase is a **sub-issue**, carrying that
+phase's tasks in its description as a read-only checklist:
 
 - **Discover the Linear MCP tools at runtime** (don't hardcode names). If Linear
   isn't connected/authed, relay the fix and stop — leave the spec written and
@@ -301,19 +302,20 @@ A spec is a Linear **issue**; each phase is a **sub-issue**; tasks are not synce
 - **Create a sub-issue per phase** (the `mapping.phases` target — `subissue` by
   default): a child issue with `parentId` = the spec issue, named from each phase
   file, in execution order.
-- **Add the frontmatter block** to `00-overview.md` (above the `#` title) so the
-  spec is linkable:
-
-  ```yaml
-  ---
-  linear_identifier: "<TEAM-123>"
-  linear_url: "https://linear.app/..."
-  last_synced_at: "<ISO-8601 now>"
-  ---
+- **Stamp the ids** so the spec is linkable — one call, no hand-edited
+  frontmatter:
+
+  ```
+  skitterspec spec-sync stamp <spec> \
+    --issue TEAM-123 --url https://linear.app/… \
+    --sub 01-<slug>=TEAM-124 --sub 02-<slug>=TEAM-125
   ```
 
-  Stamp each phase file's `linear_issue_id` with its sub-issue id. (Status is not
-  stored in frontmatter — it comes from the spec's lifecycle folder.)
+  It writes `linear_identifier`/`linear_url` onto `00-overview.md` and each phase
+  file's `linear_issue_id`, validating every ref and id **before** touching a
+  file — on any problem it changes nothing and exits non-zero, so a typo can't
+  leave the spec pointing at an issue that isn't there. (Status is not stored in
+  frontmatter — it comes from the spec's lifecycle folder.)
 - **Write the initial base sidecar** so the spec starts clean and non-diverged —
   run `skitterspec spec-sync record <spec>` to capture the local snapshot as the
   committed base (`sync.baseDir`). `/spec-status` should report in-sync right after.

package/assets/skills/spec-push/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: spec-push
-description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. A spec is a Linear issue and each phase a sub-issue; tasks are not synced. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (issue description/state, phase sub-issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
+description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. A spec is a Linear issue and each phase a sub-issue, with the phase's tasks mirrored read-only into that sub-issue's description. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (issue description/state, phase sub-issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
 ---
 
 # /spec-push — send a spec up to Linear (one-way)
 
 Repo → Linear. The repo is the **source of truth**; Linear is a **generated
 mirror**. A spec is a Linear **issue**; each phase is a **sub-issue** (a child
-issue). Tasks are not synced — they live only in the repo phase files. This skill
+issue), and a phase's tasks are mirrored into that sub-issue's description as a
+read-only checklist — never as issues of their own. This skill
 computes what changed since the last push and applies it — it never reads Linear
 content back or merges. A person editing the mirror in Linear will see it
 overwritten on the next push.
@@ -62,22 +63,37 @@ config — Linear silently ignores an unknown issue state.
    **mints** it: run the picker in **Picking the Linear Project** below, then
    create it with `save_issue` (`team` = `linear.teamId`; `project` = the picked
    id; `title` from the spec title; `description` from `plan.issue.description`;
-   state from `plan.issue.state` via `config.states`). Stamp the returned
-   identifier into `00-overview.md` frontmatter as `linear_identifier` (and
-   `linear_url`). If it already exists and `plan.issue` is present, **update it by
-   id and send no `project`** — its placement is Linear's from then on.
+   state from `plan.issue.state` via `config.states`). Keep the returned
+   identifier and url for step 5 — don't hand-edit frontmatter. If it already
+   exists and `plan.issue` is present, **update it by id and send no `project`**
+   — its placement is Linear's from then on.
 2. **Sub-issues create** → for each, `save_issue` with `parentId` = the spec
-   issue id (`name` → title, `goal` → description, `state` via `config.states`);
-   stamp the returned id into its phase file as `linear_issue_id` (`ref` is the
-   phase-file basename).
+   issue id (`name` → title, `goal` → description, `state` via `config.states`).
+   Keep each returned id against its `ref` (the phase-file basename).
 3. **Sub-issues update** → `save_issue` by `id` (title/description/state).
 
 Priority, labels, cycles and comments are Linear-native triage — do **not** push
 them; they're the PM's.
 
-## 5. Record the snapshot
+## 5. Stamp the ids, then record the snapshot
 
-After everything applied and the ids are stamped into the files:
+Write every id you collected back into the spec in **one** call — the engine
+does the file edits, so there is no hand-editing of frontmatter:
+
+```
+skitterspec spec-sync stamp <spec> \
+  --issue SKI-11 --url https://linear.app/… \
+  --sub 01-outbox=SKI-12 --sub 02-api=SKI-13
+```
+
+Pass `--issue`/`--url` only on the push that minted the spec issue; pass one
+`--sub <ref>=<id>` for every sub-issue **created** in step 4.2 (updates already
+have their id). It validates every ref and id **before** writing anything and
+exits non-zero having changed nothing if any is wrong — so a typo can't leave the
+spec half-stamped, pointing at an issue that isn't there. Fix what it reports and
+re-run; it is safe to repeat.
+
+Then record what was pushed:
 
 ```
 skitterspec spec-sync record <spec>

package/assets/skills/spec-review/SKILL.md

@@ -60,6 +60,19 @@ reading the code, do that instead of asking.
   creating a `0N-<slug>.md` file **and** a matching overview index row, or drop a
   dead phase by removing both. Keep the index and files in sync; **preserve
   completed `[x]` history**.
+- **A phase's status is the `⬜`/`🔄`/`✅` on its H1** — `# Phase 2 — <goal> 🔄`.
+  It is mirrored in that file's `> **Status:**` line and in the matching
+  `00-overview.md` phase-index row, but the **heading is the authoritative one**:
+  tooling reads it, and a heading carrying no emoji reads as *not started*. So a
+  finished phase marked only by a `**Status:** done` line is silently wrong
+  everywhere except the file itself. Set all three together.
+- **Especially when you create phase files.** Migrating a legacy spec (a bare
+  `<name>.md`, or a `00-overview.md` with inline phases) into the folder +
+  phase-file form means authoring `0N-<slug>.md` headings from scratch — carry
+  each phase's real status onto its H1 as you split it out, rather than
+  defaulting every new file to `⬜`. A ticketing provider projects that emoji as
+  the phase's state in the tracker, so getting it wrong mirrors a
+  complete phase as not-started.
 - Tick tasks already satisfied by the code; re-open `## Open questions` for
   anything still undecided.
 - Add a dated **Changelog** entry summarising the review (e.g. `- <date> —

package/bin/skitterspec-linear.js

@@ -15,7 +15,11 @@ const { specSanitise } = require('../src/vendor/linear/cli-sanitise.js')
 async function main(argv) {
   const [cmd, ...rest] = argv
   if (cmd === 'spec-sync') {
-    await specSync(rest)
+    // Propagate the exit code, like spec-sanitise below. Dropping it made
+    // `status --workspace-states` (a bad state name) and `stamp` (a refused
+    // write) both look successful to any caller checking $?, which is exactly
+    // what the /spec-push skill does before it applies a plan.
+    process.exitCode = await specSync(rest)
     return
   }
   if (cmd === 'spec-sanitise') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

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

@@ -10,12 +10,13 @@
  *
  *   spec-sync normalize <spec>   print the local projection (JSON)
  *   spec-sync push <spec>        print the create/update PLAN the skill applies
+ *   spec-sync stamp <spec>       write returned ids back into the spec files
  *   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.
+ * The `/spec-push` skill: `push` → apply the plan over MCP → `stamp` the returned
+ * ids into the repo → `record`. There is no pull — Linear is not read for content.
  */
 
 const fs = require('node:fs')
@@ -34,6 +35,10 @@ const {
   isEmptyPlan,
   remoteWorkflowState,
   validateStates,
+  lintPhases,
+  writeFrontmatter,
+  stampSubIssueId,
+  listPhaseFiles,
 } = require('../sync-core')
 
 const { loadLinearConfig } = require('./config.js')
@@ -131,6 +136,24 @@ function specSyncLinked(dir, config, flags, out) {
   out.write(lines.join('\n') + '\n')
 }
 
+// Phase-status warnings for a spec, one formatted line each.
+//
+// A spec states each phase's status three times — the phase file's h1 emoji, its
+// `> **Status:**` line, and the overview phase-index row — and only the h1 is
+// read. Get it wrong and the phase projects as `backlog`, pushes cleanly, and is
+// recorded as intended: invisible. So every subcommand that reads a projection
+// reports these, and none of them treats one as fatal — a legacy spec must still
+// push. See sync-core `lintPhases`.
+function warningLines(snapshotDir, config) {
+  return lintPhases(snapshotDir, config).map((w) => `  warning ${w.file}: ${w.message}`)
+}
+
+// Emit warnings on stderr, keeping stdout pure for a machine-readable payload.
+function warnToErr(snapshotDir, config, err) {
+  const lines = warningLines(snapshotDir, config)
+  if (lines.length) err.write(lines.join('\n') + '\n')
+}
+
 function resolveOrExit(specArg, dir, out) {
   if (!specArg) return null
   const snapshotDir = resolveSnapshotDir(specArg, dir)
@@ -142,26 +165,29 @@ function resolveOrExit(specArg, dir, out) {
 }
 
 // `spec-sync normalize <spec>` — print the local projection as JSON.
-function specSyncNormalize(dir, config, specArg, out) {
+function specSyncNormalize(dir, config, specArg, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
   if (!snapshotDir) return
+  // stdout is the projection and nothing else — callers pipe it into jq.
+  warnToErr(snapshotDir, config, err)
   out.write(JSON.stringify(projectionOf(snapshotDir, config), null, 2) + '\n')
 }
 
 // `spec-sync push <spec> [--json]` — print the create/update PLAN diffed against
 // the last-pushed snapshot. Machine-readable by default; the /spec-push skill
 // applies it over MCP then calls `record`.
-function specSyncPush(dir, config, specArg, flags, out) {
+function specSyncPush(dir, config, specArg, flags, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
   if (!snapshotDir) return
   const identifier = specIdentifier(snapshotDir, config)
   const r = push({ dir, snapshotDir, identifier, config })
   if (flags.json || !out.isTTY) {
+    warnToErr(snapshotDir, config, err)
     out.write(JSON.stringify(r.plan, null, 2) + '\n')
     return
   }
   const p = r.plan
-  const lines = [`spec-sync push: ${identifier}`]
+  const lines = [`spec-sync push: ${identifier}`, ...warningLines(snapshotDir, config)]
   if (r.empty) lines.push('  nothing to push — mirror matches the last push')
   else {
     if (p.issue) lines.push('  issue: description/state')
@@ -172,6 +198,89 @@ function specSyncPush(dir, config, specArg, flags, out) {
   out.write(lines.join('\n') + '\n')
 }
 
+// A tracker id as it appears in a spec: `SKI-42`. Deliberately strict — the
+// whole point of `stamp` is that a mistyped id is caught here rather than
+// re-minting a duplicate issue on the next push.
+const ID_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/
+
+// Resolve a `--sub` ref to a phase file in the spec folder. Accepts the ref as
+// the plan emits it (`01-outbox`) or with its extension (`01-outbox.md`).
+function resolvePhaseFile(snapshotDir, ref) {
+  const want = String(ref).replace(/\.md$/, '')
+  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
+}
+
+/**
+ * `spec-sync stamp <spec> --issue KEY-N [--url URL] --sub <ref>=KEY-M …`
+ *
+ * Write the ids a push just returned back into the spec: `linear_identifier` /
+ * `linear_url` onto the overview, `linear_issue_id` onto each phase file. This
+ * was prose in `/spec-push` telling the agent to hand-edit N files — the step
+ * most likely to go wrong at scale, because one mistyped id makes the next push
+ * treat the phase as unlinked and mint a duplicate issue.
+ *
+ * Validates EVERYTHING before writing ANYTHING: a bad ref or id fails the whole
+ * command with nothing touched. A half-stamped spec is worse than an unstamped
+ * one — it looks linked while pointing at the wrong object.
+ *
+ * `record` stays a separate call: this writes the repo, that writes the snapshot,
+ * and the skill sequences them.
+ */
+function specSyncStamp(dir, config, specArg, flags, out) {
+  const snapshotDir = resolveOrExit(specArg, dir, out)
+  if (!snapshotDir) return 1
+
+  const problems = []
+  if (flags.issue != null && !ID_RE.test(flags.issue)) {
+    problems.push(`--issue ${flags.issue} is not an id like SKI-42`)
+  }
+  if (flags.url != null && !/^https?:\/\//.test(flags.url)) {
+    problems.push(`--url ${flags.url} is not an http(s) URL`)
+  }
+
+  const subs = []
+  for (const raw of flags.subs) {
+    const eq = String(raw).indexOf('=')
+    if (eq === -1) {
+      problems.push(`--sub ${raw} is not <ref>=<id> (e.g. --sub 01-outbox=SKI-43)`)
+      continue
+    }
+    const ref = raw.slice(0, eq)
+    const id = raw.slice(eq + 1)
+    const file = resolvePhaseFile(snapshotDir, ref)
+    if (!file) problems.push(`--sub ${ref}: no phase file in ${path.relative(dir, snapshotDir)}`)
+    if (!ID_RE.test(id)) problems.push(`--sub ${ref}=${id}: not an id like SKI-42`)
+    if (file && ID_RE.test(id)) subs.push({ ref, id, file })
+  }
+
+  if (!problems.length && flags.issue == null && !subs.length) {
+    problems.push('nothing to stamp — pass --issue and/or --sub <ref>=<id>')
+  }
+
+  if (problems.length) {
+    // Every problem at once: fixing them one round-trip at a time is the same
+    // slow hand-editing this command replaces.
+    out.write(['spec-sync stamp: refusing to write — nothing was changed', ...problems.map((p) => `  ${p}`)].join('\n') + '\n')
+    return 1
+  }
+
+  const lines = [`spec-sync stamp: ${path.relative(dir, snapshotDir)}`]
+  if (flags.issue != null || flags.url != null) {
+    const written = writeFrontmatter(snapshotDir, config, {
+      linear_identifier: flags.issue,
+      linear_url: flags.url,
+    })
+    lines.push(`  overview: ${written.join(', ')}`)
+  }
+  for (const s of subs) {
+    stampSubIssueId(snapshotDir, s.file, s.id)
+    lines.push(`  ${s.file}: linear_issue_id = ${s.id}`)
+  }
+  lines.push('  next: skitterspec spec-sync record <spec>')
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
 // `spec-sync record <spec>` — write the last-pushed snapshot from the CURRENT
 // files. The skill calls this AFTER applying the plan and stamping new ids.
 function specSyncRecord(dir, config, specArg, out) {
@@ -191,7 +300,7 @@ function specSyncStatus(dir, config, specArg, flags, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
   if (!snapshotDir) return
   const identifier = specIdentifier(snapshotDir, config)
-  const lines = [`spec-sync status: ${identifier}`]
+  const lines = [`spec-sync status: ${identifier}`, ...warningLines(snapshotDir, config)]
 
   if (flags.workspaceStates && fs.existsSync(flags.workspaceStates)) {
     const names = JSON.parse(fs.readFileSync(flags.workspaceStates, 'utf-8'))
@@ -234,15 +343,19 @@ function specSyncStatus(dir, config, specArg, flags, out) {
 
 async function specSync(rest, io = {}) {
   const out = io.out || process.stdout
+  const err = io.err || process.stderr
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
-  const flags = { json: false, remote: null, workspaceStates: null }
+  const flags = { json: false, remote: null, workspaceStates: null, issue: null, url: null, subs: [] }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
     else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
     else if (args[i] === '--workspace-states') flags.workspaceStates = path.resolve(args[++i])
+    else if (args[i] === '--issue') flags.issue = args[++i]
+    else if (args[i] === '--url') flags.url = args[++i]
+    else if (args[i] === '--sub') flags.subs.push(args[++i])
     else positional.push(args[i])
   }
   dir = path.resolve(dir)
@@ -258,11 +371,13 @@ async function specSync(rest, io = {}) {
 
   switch (sub) {
     case 'normalize':
-      specSyncNormalize(dir, config, positional[0], out)
+      specSyncNormalize(dir, config, positional[0], out, err)
       return 0
     case 'push':
-      specSyncPush(dir, config, positional[0], flags, out)
+      specSyncPush(dir, config, positional[0], flags, out, err)
       return 0
+    case 'stamp':
+      return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
       specSyncRecord(dir, config, positional[0], out)
       return 0
@@ -273,6 +388,7 @@ async function specSync(rest, io = {}) {
       return 0
     default:
       out.write('Usage: skitterspec spec-sync <normalize|push|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+        '       skitterspec spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]\n' +
         '       skitterspec spec-sync linked [--json]\n')
       return 0
   }

package/src/vendor/linear/config.js

@@ -37,6 +37,13 @@ const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
 
 const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
 
+// How a phase's task list is projected into its sub-issue description.
+//   checklist — mirror the tasks as a read-only markdown checklist (default)
+//   none      — sub-issue description is the phase's `**Goal:**` line alone
+// Tasks are never read back either way; the repo stays the source of truth and a
+// box ticked in the tracker is overwritten by the next push.
+const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
+
 const DEFAULT_CONFIG = Object.freeze({
   // `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
@@ -52,7 +59,9 @@ const DEFAULT_CONFIG = Object.freeze({
   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' }),
+  // 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' }),
   // 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;
@@ -183,6 +192,15 @@ function mergeConfig(base, parsed) {
     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
+    // degradation the phase-status lint exists to stamp out.
+    if (!TASK_MAPPINGS.includes(base.mapping.tasks)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: mapping.tasks = ${JSON.stringify(base.mapping.tasks)} ` +
+          `(expected one of ${TASK_MAPPINGS.join('|')})`,
+      )
+    }
   }
 
   if (isObject(parsed.states)) {
@@ -247,4 +265,5 @@ module.exports = {
   DEFAULT_CONFIG,
   CONFIG_FILE,
   OWNERSHIP,
+  TASK_MAPPINGS,
 }

package/src/vendor/linear/mcp.js

@@ -4,7 +4,8 @@
  * The Linear MCP boundary — the one place that knows concrete Linear tool names.
  *
  * 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
+ * with a `parentId`); a phase's tasks are mirrored into its sub-issue
+ * description, never created as issues. `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

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

@@ -10,15 +10,16 @@
  * over its API. No remote content is read or merged.
  */
 
-const { normalizeLocal, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates } = require('./src/normalize.js')
+const { normalizeLocal, lintPhases, 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, stampSubIssueId, stampIssueId, findPhaseFileByTitle } = require('./src/write.js')
+const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 
 module.exports = {
   normalizeLocal,
+  lintPhases,
   readSnapshot,
   parseFrontmatter,
   projectionOf,
@@ -38,5 +39,6 @@ module.exports = {
   stampSubIssueId,
   stampIssueId,
   findPhaseFileByTitle,
+  listPhaseFiles,
   sanitizeSpecMarkdown,
 }

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

@@ -253,14 +253,53 @@ function phaseTitle(body) {
   return t || null
 }
 
+// The raw ⬜/🔄/✅ on a phase file's h1, or undefined when it carries none.
+// Kept separate from `phaseStateBucket` because the LINT has to tell "absent"
+// apart from "not-started" — the projection deliberately cannot (see below).
+function headingEmoji(body) {
+  const h1 = /^#\s+(.*)$/m.exec(body)
+  return h1 ? (h1[1].match(/[⬜🔄✅]/u) || [])[0] : undefined
+}
+
+// The `> **Status:** …` line's value, or null when the file has none. This is
+// the human mirror of the heading emoji, not a source of truth — `lintPhases`
+// cross-checks it, and nothing else reads it.
+function phaseStatusLine(body) {
+  const m = /^>.*\*\*Status:\*\*\s*(.+?)\s*$/m.exec(body)
+  return m ? m[1] : null
+}
+
+// Read a `> **Status:**` value leniently into the canonical vocabulary: an emoji
+// if it carries one, else a word we recognise. Returns null for anything else —
+// the line is free prose, and warning on an unrecognised phrasing would train
+// the warning away.
+// `pending` is deliberately NOT here: "pending review" matches as not-started
+// but means roughly the opposite, and a false positive is worse than a missed
+// check — it teaches the reader to ignore the warning.
+const STATUS_WORDS = [
+  [/\b(not[\s-]?started|todo|to[\s-]do|planned)\b/i, 'not-started'],
+  [/\b(in[\s-]?progress|started|doing|wip)\b/i, 'in-progress'],
+  [/\b(done|complete[d]?|finished|shipped)\b/i, 'done'],
+]
+function statusLineValue(line) {
+  if (!line) return null
+  const emoji = (line.match(/[⬜🔄✅]/u) || [])[0]
+  if (emoji) return EMOJI_STATUS[emoji]
+  for (const [re, status] of STATUS_WORDS) if (re.test(line)) return status
+  return 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.
+//
+// That fallback conflates "author marked it not-started" with "author used a
+// format we don't parse", which is silent corruption: the wrong state pushes
+// cleanly and `record` then commits it as the INTENDED value. The fix is not
+// leniency here — one convention beats two — it is `lintPhases`, which warns.
 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'
+  return PHASE_STATE_BUCKET[EMOJI_STATUS[headingEmoji(body)]] || 'backlog'
 }
 
 // Parse a task line (already stripped of its leading "- ") into a keyed item:
@@ -303,7 +342,15 @@ function readPhaseFiles(snapshotDir) {
       // 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 tasks = findTaskBlocks(body.split('\n')).map((b) => `[${b.mark}] ${b.text}`)
+      // Rendered as markdown checklist lines, ready to drop into a sub-issue
+      // description: indentation kept so nesting survives, the bullet marker
+      // normalised to `-`, 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.
+      const tasks = findTaskBlocks(body.split('\n')).map((b) => {
+        const parsed = parseTaskLine(`[${b.mark}] ${b.text}`)
+        return `${b.indent}- [${b.mark}] ${parsed ? parsed.text : b.text}`
+      })
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -312,11 +359,85 @@ function readPhaseFiles(snapshotDir) {
         name: phaseTitle(body),
         goal: goal.trim(),
         state: phaseStateBucket(body),
+        // Lint-only signals. `emoji` is undefined when the heading carries none
+        // — the distinction `state` throws away; `statusLine` is the raw
+        // `> **Status:**` value. Neither affects the projection.
+        emoji: headingEmoji(body),
+        statusLine: phaseStatusLine(body),
         tasks,
       }
     })
 }
 
+// --- phase-status lint ------------------------------------------------------
+
+/**
+ * Warn where a phase's status signals are absent or disagree.
+ *
+ * A spec carries the same status in three places — the phase file's h1 emoji,
+ * its `> **Status:**` line, and the `00-overview.md` phase-index row — and only
+ * the h1 is load-bearing. Writing the other two correctly while leaving the h1
+ * bare projects a finished phase as `backlog`, pushes cleanly, and records the
+ * wrong value as intended. Nothing looks wrong anywhere.
+ *
+ * Returns `[{ file, code, message }]`, `code` being `missing-status-emoji` or
+ * `status-disagreement`. Pure aside from reads; callers decide how loud to be
+ * (today: printed, never fatal).
+ */
+function lintPhases(snapshotDir, config) {
+  const phases = readPhaseFiles(snapshotDir)
+  if (!phases.length) return []
+
+  // The overview may be absent (a legacy bare `<name>.md` spec) — that is not
+  // itself a lint failure, it just removes one of the three cross-checks.
+  let indexRows = []
+  try {
+    const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+    const raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
+    const { sections } = parseSections(parseFrontmatter(raw).body)
+    indexRows = parsePhaseIndex(sections.Phases)
+  } catch {
+    indexRows = []
+  }
+
+  const warnings = []
+  phases.forEach((phase, i) => {
+    if (!phase.emoji) {
+      warnings.push({
+        file: phase.file,
+        code: 'missing-status-emoji',
+        message: `no ⬜/🔄/✅ in the heading — projecting as not-started`,
+      })
+      // Without a heading emoji there is nothing to disagree WITH: the other two
+      // signals can't be checked against a value that was never expressed.
+      return
+    }
+
+    const heading = EMOJI_STATUS[phase.emoji]
+
+    const fromLine = statusLineValue(phase.statusLine)
+    if (fromLine && fromLine !== heading) {
+      warnings.push({
+        file: phase.file,
+        code: 'status-disagreement',
+        message: `heading says ${heading} but its Status line says ${fromLine}`,
+      })
+    }
+
+    // Match the index row by phase title, falling back to position — a renamed
+    // phase shouldn't silently drop the check.
+    const row = indexRows.find((r) => r.name === phase.name) || indexRows[i]
+    if (row && row.status !== heading) {
+      warnings.push({
+        file: phase.file,
+        code: 'status-disagreement',
+        message: `heading says ${heading} but the overview phase-index row says ${row.status}`,
+      })
+    }
+  })
+  return warnings
+}
+
 // --- ownership-driven field set ---------------------------------------------
 
 // Reduce an `extracted` map to exactly the configured field keys, defaulting a
@@ -359,6 +480,22 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
   return canonicalizeMarkdown(parts.join('\n\n')) || null
 }
 
+// A phase sub-issue's description: its `**Goal:**` line, plus the phase's task
+// list as a markdown checklist when `mapping.tasks` is `checklist`.
+//
+// The checklist is a READ-ONLY mirror like everything else here — the repo is
+// the source of truth, so a box ticked in the tracker is overwritten on the next
+// 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 phase.goal
+  const parts = []
+  if (phase.goal) parts.push(phase.goal, '')
+  parts.push('## Tasks', '', ...phase.tasks)
+  return parts.join('\n')
+}
+
 /**
  * Normalize a local spec snapshot into the configured field set.
  */
@@ -376,6 +513,7 @@ function normalizeLocal(snapshotDir, config) {
   // 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 tasksMode = (config.mapping && config.mapping.tasks) || 'checklist'
   const extracted = {
     description: buildDescription(
       title,
@@ -386,11 +524,12 @@ function normalizeLocal(snapshotDir, config) {
     // 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.
+    // Linear issue state via `config.states` at push time. Tasks ride along in
+    // the description as a read-only checklist (`mapping.tasks`), never as
+    // individually-synced objects.
     subIssues: phases
       .filter((p) => p.name)
-      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: p.goal, state: p.state })),
+      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: subIssueBody(p, tasksMode), 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:
@@ -526,6 +665,7 @@ function validateStates(config, workspaceStates) {
 
 module.exports = {
   normalizeLocal,
+  lintPhases,
   readSnapshot,
   parseFrontmatter,
   parseSections,