@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

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

@@ -9,7 +9,7 @@
  * provider-neutral engine (`@skitterbyte/skitterspec-sync-core`):
  *
  *   spec-sync normalize <spec>   print the local projection (JSON)
- *   spec-sync push <spec>        print the create/update PLAN the skill applies
+ *   spec-sync plan <spec>        print the create/update PLAN the skill applies
  *                                (requires --workspace-states; see stateCheckFailure)
  *   spec-sync stamp <spec>       write returned ids back into the spec files
  *   spec-sync record <spec>      write the last-pushed snapshot (after apply)
@@ -44,6 +44,7 @@ const {
   stateSuggestions,
   lintPhases,
   writeFrontmatter,
+  deleteFrontmatter,
   stampSubIssueId,
   listPhaseFiles,
   compareStored,
@@ -52,6 +53,7 @@ const {
   deriveRecordedKey,
   isEmptyRetarget,
   dirtyPaths,
+  phaseModeFor,
 } = require('../sync-core')
 
 const {
@@ -69,11 +71,16 @@ const { runChecks } = require('./doctor.js')
 const {
   storePath,
   storeMode,
+  readStore,
+  userForTeam,
   fingerprint,
   writeKey,
+  writeUser,
   writeKeyCommand,
   removeKey,
+  removeUser,
 } = require('./credentials.js')
+const { resolveIdentity, displayNameOf } = require('./identity.js')
 
 // Resolve a spec argument to its snapshot dir. Accepts a spec name/folder found
 // under specs/** (preferred) or a literal path to a snapshot directory.
@@ -212,7 +219,7 @@ function specSyncNormalize(dir, config, specArg, out, err) {
   out.write(JSON.stringify(projectionOf(snapshotDir, config), null, 2) + '\n')
 }
 
-// `spec-sync push <spec> [--json]` — print the create/update PLAN diffed against
+// `spec-sync plan <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, err) {
@@ -231,7 +238,7 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
     return 0
   }
   const p = r.plan
-  const lines = [`spec-sync push: ${identifier}`, ...warningLines(snapshotDir, config)]
+  const lines = [`spec-sync plan: ${identifier}`, ...warningLines(snapshotDir, config)]
   if (p.legacy) lines.push(...legacyLines(p.legacy))
   if (p.phasesDeferred) lines.push(...deferredLines(p.phasesDeferred))
   lines.push(...phaseModeLines(p.phaseMode, r.projection.status))
@@ -242,6 +249,7 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
     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)')
   }
+  lines.push(...unstampedLines(p))
   out.write(lines.join('\n') + '\n')
   return 0
 }
@@ -249,6 +257,24 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
 // `mapping.phases: 'deferred'` is holding phases back. Said plainly wherever a
 // plan or a status report is printed, because the alternative reading of a spec
 // with no sub-issues is that its phase files failed to parse.
+// Phases whose stamp is missing while the snapshot still remembers an id nobody
+// claims. Reported OUTSIDE the empty-plan branch on purpose: a plan carrying
+// nothing but these is "empty" for applying, and saying `up to date` about it
+// would hide the one thing the operator has to act on.
+function unstampedLines(plan) {
+  const u = (plan && plan.unstamped) || []
+  if (!u.length) return []
+  const lines = [
+    `  unstamped: ${u.length} phase(s) have no linear_issue_id, and ${
+      u[0].candidates.length
+    } sub-issue(s) from the last push are unclaimed —`,
+    '    not creating, since a lost stamp and a new phase look identical from here.',
+  ]
+  for (const item of u) lines.push(`    ${item.ref} — could be: ${item.candidates.join(', ')}`)
+  lines.push('    re-stamp the phase file (linear_issue_id) and push again.')
+  return lines
+}
+
 function deferredLines(n) {
   return [
     `  ${n} phase(s) deferred — mapping.phases is "deferred" and this spec has not started`,
@@ -314,7 +340,7 @@ function stateCheckFailure(config, flags) {
   if (flags.skipStateCheck) return null
   if (!flags.workspaceStates) {
     return [
-      'spec-sync push: refusing — the configured issue states have not been validated',
+      'spec-sync plan: refusing — the configured issue states have not been validated',
       '  pass --workspace-states <file> (a JSON array of the workspace\'s issue',
       '  workflow-state names, which /spec-push fetches over MCP), or',
       '  --skip-state-check to push anyway.',
@@ -323,20 +349,20 @@ function stateCheckFailure(config, flags) {
     ]
   }
   if (!fs.existsSync(flags.workspaceStates)) {
-    return [`spec-sync push: refusing — no such --workspace-states file: ${flags.workspaceStates}`]
+    return [`spec-sync plan: refusing — no such --workspace-states file: ${flags.workspaceStates}`]
   }
   let names
   try {
     names = JSON.parse(fs.readFileSync(flags.workspaceStates, 'utf-8'))
   } catch (error) {
-    return [`spec-sync push: refusing — --workspace-states is not valid JSON: ${error.message}`]
+    return [`spec-sync plan: refusing — --workspace-states is not valid JSON: ${error.message}`]
   }
   const list = Array.isArray(names) ? names : []
   const missing = validateStates(config, list)
   if (missing.length) {
     // Say what IS available, and what to use instead. "Done is not a state" sends
     // you to the Linear UI to go and look; naming the replacement does not.
-    const lines = ['spec-sync push: refusing — configured state name(s) not in the workspace', '']
+    const lines = ['spec-sync plan: refusing — configured state name(s) not in the workspace', '']
     for (const { label, configured, suggestion } of stateSuggestions(config, list)) {
       lines.push(`  ${label}: "${configured}" is not an issue state in this workspace`)
       if (suggestion) lines.push(`    use "${suggestion}" instead`)
@@ -435,6 +461,77 @@ function specSyncStamp(dir, config, specArg, flags, out) {
   return 0
 }
 
+/**
+ * `spec-sync assign <spec> [--to <id> [--name <n>]] [--release] [--json]`
+ *
+ * Record — or release — who owns a spec, by stamping `linear_assignee_id` /
+ * `linear_assignee_name` into the overview frontmatter. The counterpart to
+ * `spec-sync stamp`, which does the same job for issue ids.
+ *
+ * **It writes the repo and nothing else.** Pushing is the caller's next step,
+ * deliberately: the repo is the source of truth, so ownership changes here and
+ * the mirror catches up like any other edit. Splitting it that way also means a
+ * failed push leaves the claim recorded rather than lost.
+ *
+ * **Stamping is explicit, and never inferred by a push.** Only this verb (and
+ * the skills that call it) writes the field. A push that resolved identity for
+ * itself would quietly re-assign a spec to whoever happened to run it — which is
+ * how a teammate pushing someone else's branch would steal their work.
+ */
+function specSyncAssign(dir, config, specArg, flags, out) {
+  const snapshotDir = resolveOrExit(specArg, dir, out)
+  if (!snapshotDir) return 1
+
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
+  const rel = path.relative(dir, snapshotDir)
+
+  const problems = []
+  if (flags.release && flags.to) problems.push('--release and --to are opposites — pass one')
+  if (!flags.release && !flags.to) problems.push('nothing to do — pass --to <user-id> or --release')
+  // An unlinked spec has no issue to assign. Refusing beats stamping a field
+  // that would sit in the file doing nothing until someone noticed.
+  if (!identifier) problems.push(`${rel} is not linked to Linear — /spec-push it first`)
+
+  if (problems.length) {
+    out.write(
+      ['spec-sync assign: refusing to write — nothing was changed', ...problems.map((p) => `  ${p}`)].join('\n') + '\n',
+    )
+    return 1
+  }
+
+  if (flags.release) {
+    const removed = deleteFrontmatter(snapshotDir, config, ['linear_assignee_id', 'linear_assignee_name'])
+    if (flags.json) {
+      out.write(JSON.stringify({ spec: rel, issue: identifier, released: removed.length > 0 }, null, 2) + '\n')
+      return 0
+    }
+    out.write(
+      (removed.length
+        ? `spec-sync assign: ${rel} released (${identifier})\n`
+        : `spec-sync assign: ${rel} records no assignee — nothing to release\n`) +
+        '  next: push it, so Linear is unassigned too\n',
+    )
+    return 0
+  }
+
+  writeFrontmatter(snapshotDir, config, {
+    linear_assignee_id: flags.to,
+    // Display only — the projection never sends it. It exists so a reader (and
+    // `/spec-claim`) can name the person without a Linear round trip.
+    linear_assignee_name: flags.name || null,
+  })
+  if (flags.json) {
+    out.write(
+      JSON.stringify({ spec: rel, issue: identifier, id: flags.to, name: flags.name || null }, null, 2) + '\n',
+    )
+    return 0
+  }
+  const who = flags.name ? `${flags.name} (${flags.to})` : flags.to
+  out.write(`spec-sync assign: ${rel} assigned to ${who} (${identifier})\n  next: push it, so Linear agrees\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) {
@@ -483,6 +580,7 @@ function specSyncStatus(dir, config, specArg, flags, out) {
     const u = plan.subIssues.update.length
     lines.push(`  push: pending — ${n} to create, ${u} to update${plan.issue ? ', issue changed' : ''}`)
   }
+  lines.push(...unstampedLines(plan))
 
   if (flags.remote && fs.existsSync(flags.remote)) {
     const remote = JSON.parse(fs.readFileSync(flags.remote, 'utf-8'))
@@ -501,12 +599,54 @@ function specSyncStatus(dir, config, specArg, flags, out) {
     } else {
       lines.push('  drift: none — Linear workflow-state matches the spec')
     }
+    lines.push(...assigneeLines(remote, projection, plan))
   }
 
   out.write(lines.join('\n') + '\n')
   return 0
 }
 
+/**
+ * The assignee half of the drift report — nothing at all unless the repo opted
+ * `assignee` into `sync.fieldOwnership` (`projection.assignee` is then
+ * `undefined`, and a project that opted out must see no trace of the feature).
+ *
+ * The line says what will ACTUALLY happen, which is not the same as whether the
+ * two sides differ. A spec with no recorded assignee never overwrites Linear's,
+ * so printing "repo wins on next push" against a PM's assignment would be both
+ * an accusation and a lie — the same trap the `stage` branch above documents.
+ * The plan is the only honest witness to that, so it is what gets asked.
+ */
+function assigneeLines(remote, projection, plan) {
+  if (!projection || projection.assignee === undefined) return []
+  const remoteUser = remote && remote.assignee ? remote.assignee : null
+  const remoteName = remoteUser ? remoteUser.name || remoteUser.id : null
+  const local = projection.assignee || null
+  const willPush = !!(plan && plan.issue && 'assignee' in plan.issue)
+
+  if (!remoteUser && !local) return ['  assignee: none — the spec records nobody, and neither does Linear']
+  if (remoteUser && local && remoteUser.id === local) return [`  assignee: ${remoteName} — matches the spec`]
+
+  // The two sides differ. WHICH LINE IS HONEST depends on the plan, not on the
+  // disagreement — there are three ways to differ and only one is drift.
+  if (willPush) {
+    const to = local || 'nobody'
+    return [`  drift: Linear assignee is ${remoteName || 'nobody'} but the spec records ${to} (repo wins on next push)`]
+  }
+  if (!local) {
+    // Decision 6, reported: the spec never recorded anyone, so nothing is sent
+    // and this assignment is safe where it is.
+    return [`  assignee: Linear has ${remoteName}; the spec records nobody and will not overwrite it`]
+  }
+  // Recorded, already pushed, and changed in Linear since. The snapshot says we
+  // are in sync, so nothing re-asserts it — and claiming "repo wins" here would
+  // promise a correction that will never come.
+  return [
+    `  assignee: Linear shows ${remoteName || 'nobody'} but the spec records ${local} — ` +
+      'already pushed, so it will not be re-sent',
+  ]
+}
+
 /**
  * `spec-sync verify <spec> --stored <file>` — compare what the tracker STORED
  * against what we sent, and report any lost text.
@@ -879,6 +1019,21 @@ function gatherState(dir, flags) {
       : { ok: false, error: `no key for ${state.tracker.teamKey || state.tracker.teamId}${why ? ` — ${why}` : ''}` }
   }
 
+  // Identity, read from the CACHE ONLY — deliberately no network call, because
+  // doctor is offline until `--check-remote`. A key that could derive an identity
+  // but has not yet reports as "not cached", with `whoami` as the fix, rather
+  // than as a fault: not having asked is not the same as having no answer.
+  if (config) {
+    const owned = !!(config.sync && config.sync.fieldOwnership && 'assignee' in config.sync.fieldOwnership)
+    state.identity = { owned }
+    if (owned) {
+      const store = readStore(storePath(flags.env || process.env))
+      const cached = store.ok ? userForTeam(store.store, state.tracker.teamId) : null
+      if (cached) Object.assign(state.identity, { ok: true, id: cached.id, name: cached.name, source: 'store' })
+      else state.identity.error = 'no identity cached yet — run `spec-sync whoami` to resolve it'
+    }
+  }
+
   state._config = config
   // Declared here, checked only if `--check-remote` fetches the state TYPES the
   // shape check needs (see `ladderCheck`). Offline, the row stays `skipped`.
@@ -1733,6 +1888,451 @@ async function specSyncProjects(dir, config, flags, out) {
   return 0
 }
 
+// Linear's PRIORITY is an enum, not a magnitude: 1=Urgent, 2=High, 3=Medium,
+// 4=Low — and 0 means "nobody set one", not "lowest". Sorting on the raw number
+// would float every unprioritised issue to the top, which is exactly backwards,
+// so 0 is ranked last explicitly.
+const priorityRank = (issue) => {
+  const p = Number(issue && issue.priority)
+  return !Number.isFinite(p) || p === 0 ? Number.POSITIVE_INFINITY : p
+}
+
+const UNPRIORITISED = (issues) => issues.length > 0 && issues.every((i) => priorityRank(i) === Infinity)
+
+/**
+ * Linear's own Backlog order, reproduced — which is the only reason to ask
+ * Linear this rather than `ls specs/backlog/`.
+ *
+ * `sortOrder` is a float and LOWER sorts higher: it is the position Linear
+ * stores when someone drags a card, never a score. Created-date is deliberately
+ * not consulted — created order is the thing this ordering exists to replace.
+ *
+ * The identifier tie-break is what makes the listing reproducible: without it
+ * two issues a person never dragged apart share a `sortOrder`, and the rows
+ * reorder between runs on nothing but the order Linear happened to return.
+ */
+function backlogOrder(a, b) {
+  const pa = priorityRank(a)
+  const pb = priorityRank(b)
+  if (pa !== pb) return pa - pb
+  const sa = Number(a && a.sortOrder)
+  const sb = Number(b && b.sortOrder)
+  const na = Number.isFinite(sa) ? sa : 0
+  const nb = Number.isFinite(sb) ? sb : 0
+  if (na !== nb) return na - nb
+  return String((a && a.identifier) || '').localeCompare(
+    String((b && b.identifier) || ''),
+    'en',
+    { numeric: true },
+  )
+}
+
+// What a row says when Linear holds an issue this branch has no spec file for.
+const UNLINKED = '— (not linked here)'
+
+/** `2/5 — Wire the toggle`, or nothing at all when no phase is in progress. */
+function phaseLabel(phase) {
+  if (!phase) return ''
+  const base = `${phase.n}/${phase.total}${phase.title ? ` — ${phase.title}` : ''}`
+  return phase.alsoInProgress > 0 ? `${base} (+${phase.alsoInProgress} more in progress)` : base
+}
+
+const sameState = (a, b) => String(a || '').toLowerCase() === String(b || '').toLowerCase()
+
+/**
+ * Phase order among a spec issue's children — the order `/spec-push` minted them
+ * in, which is phase-file order. That is the **identifier**, numerically, so
+ * `SKS-9` stays ahead of `SKS-10`.
+ *
+ * `sortOrder` is deliberately NOT consulted, though it is fetched for `--next`.
+ * It is the position in Linear's Backlog view, and for sub-issues it tracks
+ * nothing about the plan: this repo's own SKS-115 carries -105486, -108489,
+ * -109484, -5066, -10982 across phases 1-5, which sorts phase 4 last and would
+ * have printed a spec on phase 4 as "5/5". Nor is `backlogOrder` reused — a
+ * priority set on one phase would renumber the spec, and "phase 3 of 5" is a
+ * position in the plan, never a ranking.
+ *
+ * KNOWN BLIND SPOT: a phase inserted between two existing ones mints a HIGHER
+ * identifier than its position, so it numbers as if appended. Phase files are
+ * appended in practice, and the alternative — reading the local phase files —
+ * cannot number a spec that is not on this branch, which is the case the
+ * listing exists for.
+ */
+function phaseOrder(a, b) {
+  return String((a && a.identifier) || '').localeCompare(
+    String((b && b.identifier) || ''),
+    'en',
+    { numeric: true },
+  )
+}
+
+/**
+ * `spec-sync list [--state <name> …|--all] [--next N] [--limit N] [--archived]
+ * [--json]`
+ * — every spec issue Linear holds, with the local spec folder that owns it.
+ *
+ * Linear answers what is live and who holds it; the repo answers what each
+ * issue is CALLED on disk, because `/spec-start` moves a spec to
+ * `specs/in-progress/` on that spec's own branch — so `ls specs/` on the base
+ * branch is wrong about exactly the specs you most want to see.
+ */
+async function specSyncList(dir, config, flags, out) {
+  // `--next N` is the top of the BACKLOG in Linear's own order, so it fixes the
+  // scope itself. Combined with --state/--all one of them would have to lose,
+  // silently — the failure this feature exists to avoid. Refuse instead, before
+  // any transport work, so the answer does not depend on whether a key is set.
+  const next = Number.isFinite(flags.next) && flags.next > 0 ? flags.next : null
+
+  // Exactly one scope selector. Each of these FIXES the set of states, so any
+  // two of them means one wins silently — and a scope the user did not get is
+  // the same failure as a cap they were not told about (decision 4). Checked
+  // before any transport work, so the answer never depends on whether a key is
+  // set. `--state` is repeatable and counts once: several names are one scope.
+  const scopeFlags = [
+    next !== null && '--next',
+    flags.all === true && '--all',
+    flags.stateArgs.length > 0 && '--state',
+    flags.inProgress === true && '--in-progress',
+  ].filter(Boolean)
+  if (scopeFlags.length > 1) {
+    out.write(
+      [
+        `spec-sync list: ${scopeFlags.join(' and ')} each pick the scope, so they cannot be combined`,
+        '  use one of them — they are alternatives, not filters that stack.',
+      ].join('\n') + '\n',
+    )
+    return 1
+  }
+
+  // `--mine` and `--by` are the same question asked two ways. Combining them
+  // has no reading, and picking one would answer a question nobody asked.
+  if (flags.mine && flags.by) {
+    out.write(
+      [
+        'spec-sync list: --mine and --by both filter by assignee, so they cannot be combined',
+        '  use --mine for your own, or --by <user> for someone else.',
+      ].join('\n') + '\n',
+    )
+    return 1
+  }
+
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+  const teamId = (config.linear && config.linear.teamId) || null
+
+  const degrade = (reason) => {
+    if (flags.json) out.write(JSON.stringify({ transport, specs: null, reason }, null, 2) + '\n')
+    else out.write(`spec-sync list: ${reason}\n`)
+    return 0
+  }
+  if (transport === 'mcp') {
+    return degrade(
+      `transport = mcp — ${key.ok ? '--via mcp was requested' : key.error}; list issues over MCP instead`,
+    )
+  }
+  if (!key.ok) return degrade(key.error)
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+
+  // The scope. `--all` drops the state filter; `--state` names states directly;
+  // the default reads the two live buckets out of `config.states` rather than
+  // restating them, so a workspace that renamed "Backlog" needs no second edit.
+  const wantedNames = next !== null
+    ? [config.states.backlog]
+    : flags.inProgress === true
+      ? [config.states['in-progress']]
+      : flags.all === true
+        ? null
+        : flags.stateArgs.length
+          ? flags.stateArgs
+          : [config.states.backlog, config.states['in-progress']]
+
+  let stateIds = null
+  if (wantedNames) {
+    let workspaceStates
+    try {
+      workspaceStates = await adapter.listIssueStates(teamId)
+    } catch (error) {
+      return degrade(`could not read the workspace's issue states (${error.message})`)
+    }
+    // A POSITIVE signal, not an absence: this is the workspace's FULL state
+    // list, freshly read, so a name missing from it is genuinely missing rather
+    // than merely outside a narrower query. Linear silently ignores an unknown
+    // state, so an unchecked name would return an empty listing that looks like
+    // "no specs" — see .claude/rules/negative-checks.md.
+    const byName = new Map(
+      workspaceStates.filter((s) => s && s.name).map((s) => [String(s.name).toLowerCase(), s]),
+    )
+    const missing = wantedNames.filter((n) => !byName.has(String(n).toLowerCase()))
+    if (missing.length) {
+      out.write(
+        [
+          `spec-sync list: unknown state ${missing.map((n) => `"${n}"`).join(', ')}`,
+          `  the workspace has: ${workspaceStates.map((s) => s.name).join(', ')}`,
+          '  fix specs/.core/linear.config.json → states, or pass --state with one of those.',
+        ].join('\n') + '\n',
+      )
+      return 1
+    }
+    stateIds = wantedNames.map((n) => byName.get(String(n).toLowerCase()).id)
+  }
+
+  // --- who holds it (decision 9) --------------------------------------------
+  //
+  // Both filters reuse `feat-linear-assignment`'s identity rather than keeping a
+  // second copy: `--mine` through `resolveIdentity`, `--by` through the same
+  // user search `spec-sync users` runs.
+  let assignee = null
+  if (flags.mine) {
+    const who = await resolveIdentity(config, flags.env || process.env, { adapter })
+    if (!who.ok) {
+      // Exit 0, list NOTHING, and never prompt. An unresolvable identity is an
+      // ordinary state — a shared or bot key, an offline machine, a repo
+      // mid-setup — not a fault. The one thing that must not happen is dropping
+      // the filter and printing the whole team's work under a `--mine` heading.
+      const line = `spec-sync list: --mine needs to know who you are, and it does not (${who.reason})`
+      if (flags.json) {
+        out.write(JSON.stringify({ transport: 'api', scope: null, specs: null, reason: line }, null, 2) + '\n')
+      } else {
+        out.write(
+          [line, '  run `spec-sync whoami --set <id>` to say so, or use --by <user>.'].join('\n') + '\n',
+        )
+      }
+      return 0
+    }
+    assignee = { id: who.id, name: who.name }
+  } else if (flags.by) {
+    // Resolved through Linear, never a hand-typed id — a wrong uuid filters to
+    // nothing and looks exactly like "that person has no specs".
+    let found
+    try {
+      found = await adapter.searchUsers(String(flags.by), { limit: 50 })
+    } catch (error) {
+      return degrade(`could not search users (${error.message}); Linear is unreachable`)
+    }
+    const users = (found && found.users) || []
+    // Unlike --mine above, these two exit NON-ZERO: the argument is wrong and
+    // only the caller can fix it, which is the same shape as an unknown --state.
+    // Never fall back to the whole team — the heading would promise one person.
+    if (!users.length) {
+      out.write(
+        [
+          `spec-sync list: no Linear user matches ${JSON.stringify(String(flags.by))}`,
+          '  `spec-sync users <term>` lists who the workspace has.',
+        ].join('\n') + '\n',
+      )
+      return 1
+    }
+    if (users.length > 1) {
+      const lines = [`spec-sync list: ${users.length} users match ${JSON.stringify(String(flags.by))}`]
+      for (const u of users.slice(0, 10)) {
+        lines.push(`  ${displayNameOf(u) || '(unnamed)'}${u.email ? `  ${u.email}` : ''}`)
+      }
+      if (users.length > 10) lines.push(`  … and ${users.length - 10} more`)
+      lines.push('  narrow it — an email address matches exactly one person.')
+      out.write(lines.join('\n') + '\n')
+      return 1
+    }
+    assignee = { id: users[0].id, name: displayNameOf(users[0]) }
+  }
+
+  let page
+  try {
+    page = await adapter.listIssues({
+      teamId,
+      stateIds,
+      assigneeId: assignee ? assignee.id : null,
+      parentless: true,
+      first: null,
+      includeArchived: !!flags.archived,
+    })
+  } catch (error) {
+    return degrade(`could not list issues (${error.message}); Linear is unreachable`)
+  }
+
+  // Filtered again here, not merely in the query: `parent { id }` is the
+  // structural discriminator between a spec issue and a phase sub-issue
+  // (decision 2), and it is cheap enough to assert on the data we actually got
+  // rather than trust that the filter was applied.
+  const issues = (page.nodes || []).filter((n) => n && !(n.parent && n.parent.id))
+
+  // Ordered BEFORE projection, so the comparator reads Linear's own fields
+  // (`priority`, `sortOrder`) rather than a row shape that never carried them.
+  // Only `--next` reorders: the plain listing keeps Linear's return order, which
+  // is what every existing caller already reads.
+  const ordered = next === null ? issues : issues.slice().sort(backlogOrder)
+
+  const byIdentifier = new Map(
+    listSpecs(dir, config)
+      .filter((s) => s.identifier)
+      .map((s) => [s.identifier, s]),
+  )
+  // Identifier → Linear uuid, for the phase lookup below. Kept beside the rows
+  // rather than on them, so the --json shape stays exactly what it prints.
+  const uuidOf = new Map(ordered.map((i) => [i.identifier, i.id]))
+
+  const rows = ordered.map((issue) => {
+    const local = byIdentifier.get(issue.identifier) || null
+    return {
+      identifier: issue.identifier || '',
+      title: issue.title || '',
+      state: (issue.state && issue.state.name) || '',
+      // An issue with no local match is REPORTED, not dropped. A teammate's
+      // unlanded spec, or one authored inside another spec's worktree, is not
+      // on this branch at all — which is the very gap the listing exists to
+      // close, so hiding it would defeat the command.
+      spec: local ? local.spec : null,
+      bucket: local ? local.bucket : null,
+      assignee: (issue.assignee && issue.assignee.name) || null,
+      // Filled in below for in-progress rows only; `null` on every row that was
+      // never looked up, so the shape does not vary by state.
+      phase: null,
+      url: issue.url || null,
+    }
+  })
+
+  const total = rows.length
+  // `--next N` IS a cap, and announces itself as one (decision 4) — the count
+  // line below reports it the same way `--limit` is reported.
+  const limit = next !== null
+    ? next
+    : Number.isFinite(flags.limit) && flags.limit > 0
+      ? flags.limit
+      : null
+  const shown = limit === null ? rows : rows.slice(0, limit)
+  const capFlag = next !== null ? '--next' : '--limit'
+  // The heading has to name the filter as well as the states: `showing 2 of 2`
+  // under a bare "live" heading reads as the whole team's work when it is one
+  // person's.
+  const held = assignee ? `, assigned to ${assignee.name || assignee.id}` : ''
+  const scope =
+    (next !== null
+      ? `next ${next}`
+      : flags.inProgress === true
+        ? `in progress (${wantedNames.join(', ')})`
+        : flags.all === true
+          ? 'all states'
+          : `${flags.stateArgs.length ? 'states' : 'live'} (${wantedNames.join(', ')})`) + held
+  // Said whenever it is true, not treated as an edge case: a workspace where
+  // nobody has set a priority is the common one, and there the order is a
+  // person's drag-order rather than a ranking. Reading it as a ranking is the
+  // mistake this line exists to prevent.
+  const unprioritised = next !== null && UNPRIORITISED(ordered)
+
+  // --- the current phase, on in-progress rows only (decision 8) --------------
+  //
+  // One extra Linear call per in-progress row, and NONE for any other — a
+  // backlog listing costs exactly what it did before. Run over `shown`, not
+  // `rows`, so a capped listing does not pay for phases it will not print.
+  const inProgressState = config.states['in-progress']
+  const phaseFailures = []
+  for (const row of shown) {
+    if (!sameState(row.state, inProgressState)) continue
+    // An `inline`-mode spec keeps its phases in the issue DESCRIPTION, so there
+    // are no children to read. Asking anyway would report "no phase in progress"
+    // for a spec that is mid-build — an absence that means nothing. The bucket
+    // is the local one where we have it; where we do not, Linear's own state is
+    // in-progress by construction, which is the bucket that mode resolves for.
+    if (phaseModeFor(row.bucket || 'in-progress', config) === 'inline') continue
+
+    const uuid = uuidOf.get(row.identifier)
+    if (!uuid) continue
+    let children
+    try {
+      children = await adapter.listSubIssues(uuid)
+    } catch (error) {
+      // Bias the unknown case to inaction: a failed lookup leaves the row
+      // without a phase and says so once, rather than failing the whole
+      // listing or printing a phase it never read.
+      phaseFailures.push(row.identifier)
+      continue
+    }
+    const phases = (children || []).slice().sort(phaseOrder)
+    const live = phases.filter((c) => c && sameState(c.state && c.state.name, inProgressState))
+    if (!live.length) continue
+    row.phase = {
+      n: phases.indexOf(live[0]) + 1,
+      total: phases.length,
+      title: (live[0].title || '').trim(),
+      // More than one phase in progress is a real shape, not an error — two
+      // people can work a spec at once. Report the count rather than picking
+      // one silently.
+      alsoInProgress: live.length - 1,
+    }
+  }
+
+  if (flags.json) {
+    out.write(
+      JSON.stringify(
+        {
+          transport: 'api',
+          scope,
+          archived: !!flags.archived,
+          showing: shown.length,
+          total,
+          ...(next !== null ? { unprioritised } : {}),
+          assignedTo: assignee,
+          specs: shown,
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return 0
+  }
+
+  const lines = [
+    `spec-sync list: transport = api, ${scope} — showing ${shown.length} of ${total}` +
+      (next !== null ? ' in backlog' : ''),
+  ]
+  if (unprioritised) {
+    lines.push("  every candidate is unprioritised — this is Linear's manual Backlog order, not a ranking")
+  }
+  // Say what was NOT shown, every time (decisions 4 and 5). A listing that
+  // implies a completeness it never verified is this command's failure mode.
+  lines.push(
+    flags.archived
+      ? '  archived issues included'
+      : '  archived issues excluded (--archived to include)',
+  )
+  if (limit !== null && total > shown.length) {
+    lines.push(`  ${total - shown.length} more not shown — ${capFlag} ${total} for all of them`)
+  }
+  if (page.pageInfo && page.pageInfo.hasNextPage) {
+    lines.push('  ! Linear reported further pages it did not return — this listing may be short')
+  }
+  if (phaseFailures.length) {
+    lines.push(
+      `  ! could not read the phases of ${phaseFailures.join(', ')} — those rows show no phase`,
+    )
+  }
+  lines.push('')
+  if (!shown.length) {
+    lines.push('  no spec issues in scope')
+  } else {
+    const idW = Math.max(...shown.map((r) => r.identifier.length))
+    const stW = Math.max(...shown.map((r) => r.state.length))
+    const pad = ' '.repeat(idW + stW + 4)
+    const specW = Math.max(...shown.map((r) => (r.spec || UNLINKED).length))
+    for (const row of shown) {
+      // Who holds it, and where the work is — the two things the repo could not
+      // have told them. Appended rather than columnised further: both are empty
+      // on most rows, and padding for a column that is usually blank buys
+      // nothing but width.
+      const held = [row.assignee, phaseLabel(row.phase)].filter(Boolean).join(' · ')
+      lines.push(
+        `  ${row.identifier.padEnd(idW)}  ${row.state.padEnd(stW)}  ` +
+          (held ? `${(row.spec || UNLINKED).padEnd(specW)}  ${held}` : row.spec || UNLINKED),
+      )
+      if (row.title) lines.push(`  ${pad}${row.title}`)
+    }
+    lines.push('')
+    lines.push('  start one with: /spec-start <name>')
+  }
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
 /**
  * Apply one spec's plan. Returns what happened rather than printing it, so the
  * single-spec command and the bulk loop report in their own voices while sharing
@@ -1764,6 +2364,9 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
       projectId: project || (config.linear && config.linear.projectId) || null,
       description: plan.issue && plan.issue.description,
       stateId: stateId(plan.issue && plan.issue.state),
+      // Assert only. An issue being minted has no assignee to retract, so
+      // `withoutNull` dropping a null here is exactly right.
+      assigneeId: (plan.issue && plan.issue.assignee) || null,
     }))
     if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
     parentId = created.id
@@ -1777,10 +2380,18 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
     parentId = existing.id
     result.issue = { id: existing.id, identifier: existing.identifier, url: existing.url }
     if (plan.issue) {
-      await adapter.updateIssue(existing.id, withoutNull({
+      const updates = withoutNull({
         description: plan.issue.description,
         stateId: stateId(plan.issue.state),
-      }))
+      })
+      // APPLIED AFTER `withoutNull`, and that ordering is the whole point: null
+      // is MEANINGFUL for this field — it is how Linear unassigns an issue — so
+      // passing it through the stripper would drop exactly the clear that
+      // finishing a spec depends on, and the mirror would keep a finished spec
+      // assigned forever. The plan only carries the key when there is something
+      // to say, so `in` is the test, not truthiness.
+      if ('assignee' in plan.issue) updates.assigneeId = plan.issue.assignee ?? null
+      await adapter.updateIssue(existing.id, updates)
       lines.push(`  issue updated: ${identifier}`)
     }
   }
@@ -1841,6 +2452,196 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
   return { result, lines, lost }
 }
 
+/**
+ * `spec-sync whoami [--json] [--set <id> [--name <n>]] [--unset]`
+ *
+ * Report — and cache — who the operator is in Linear, which is the fact
+ * assignment rests on. See `identity.js` for why it is derived rather than
+ * configured.
+ *
+ * **Exit code 0 even when the answer is "unknown".** This deliberately differs
+ * from `credentials status`, which exits 1 with no key: that command is a
+ * READINESS check, and a missing key means the thing you asked about cannot
+ * work. This one answers a question, and "nobody is identified here" is a valid
+ * answer — a shared key, an offline machine, a repo mid-setup. Exiting non-zero
+ * would make every caller treat an ordinary state as a fault, which is how an
+ * advisory check turns into one that accuses.
+ *
+ * A successful DERIVE is cached; a read from the cache is not re-written. The
+ * caching lives here rather than in `resolveIdentity` so that asking the
+ * question never has a side effect — see that module's header.
+ */
+async function specSyncWhoami(dir, config, flags, out) {
+  const env = flags.env || process.env
+  const file = storePath(env)
+  const teamId = (config.linear && config.linear.teamId) || ''
+  const teamKey = (config.linear && config.linear.teamKey) || ''
+  const label = teamKey ? `${teamId} (${teamKey})` : teamId
+
+  // The store is keyed by team, so without one there is nowhere to read from or
+  // write to. That IS a broken config rather than an ordinary unknown, so unlike
+  // the rest of this command it exits non-zero.
+  if (!teamId) {
+    out.write(
+      'spec-sync whoami: no linear.teamId in specs/.core/linear.config.json.\n' +
+        '  Identity is stored per team — run `spec-sync init-config` first.\n',
+    )
+    return 1
+  }
+
+  if (flags.unset) {
+    const r = removeUser(file, teamId, {})
+    if (!r.ok) {
+      out.write(`spec-sync whoami: ${r.reason}\n`)
+      return 1
+    }
+    out.write(
+      r.removed
+        ? `spec-sync whoami: forgot the identity for ${label} (the API key is untouched)\n`
+        : `spec-sync whoami: no identity stored for ${label} — nothing to forget\n`,
+    )
+    return 0
+  }
+
+  if (flags.set) {
+    const r = writeUser(file, teamId, { id: flags.set, name: flags.name }, {})
+    if (!r.ok) {
+      out.write(`spec-sync whoami: ${r.reason}\n`)
+      return 1
+    }
+    if (flags.json) {
+      out.write(
+        JSON.stringify({ id: flags.set, name: flags.name || null, source: 'set', store: r.path }, null, 2) + '\n',
+      )
+      return 0
+    }
+    const shown = flags.name ? `${flags.name} (${flags.set})` : flags.set
+    out.write(`spec-sync whoami: identity for ${label} set to ${shown} in ${r.path} (600)\n`)
+    return 0
+  }
+
+  const identity = await resolveIdentity(config, env, { adapter: flags.adapter, fetch: flags.fetch })
+
+  if (identity.ok && identity.source === 'viewer') {
+    // Cache what the network just told us, so the next `/spec-start` costs no
+    // call. A failed write is not fatal: we HAVE the answer, and re-deriving it
+    // next time is a slower success, not a wrong one.
+    const cached = writeUser(file, teamId, { id: identity.id, name: identity.name }, {})
+    if (!cached.ok) identity.cacheWarning = cached.reason
+  }
+
+  if (flags.json) {
+    out.write(
+      JSON.stringify(
+        {
+          team: label,
+          store: file,
+          ok: identity.ok,
+          id: identity.id || null,
+          name: identity.name || null,
+          source: identity.source,
+          reason: identity.ok ? null : identity.reason || null,
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return 0
+  }
+
+  if (!identity.ok) {
+    out.write(
+      [
+        'spec-sync whoami: unknown — no identity for this workspace',
+        `  ${identity.reason}`,
+        '  Set one by hand:',
+        '    skitterspec spec-sync whoami --set <linear-user-id> --name "<your name>"',
+        '  Find the id with: skitterspec spec-sync users <name-or-email>',
+      ].join('\n') + '\n',
+    )
+    return 0
+  }
+
+  const where = identity.source === 'store' ? `cached in ${file}` : 'derived from the API key'
+  const lines = [
+    `spec-sync whoami: ${identity.name || '(unnamed)'} <${identity.id}>`,
+    `  team:   ${label}`,
+    `  source: ${where}`,
+  ]
+  if (identity.cacheWarning) lines.push(`  note:   not cached — ${identity.cacheWarning}`)
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
+/**
+ * `spec-sync users [<query>] [--json] [--limit N] [--cursor C]`
+ *
+ * Find a person by name or email. Both halves matter: search is what makes this
+ * usable in a workspace of hundreds, and the bare listing is what answers "show
+ * me everyone" in one of five. Linear's user query does both, so this is one
+ * command rather than a `users` and a `search-users`.
+ *
+ * The engine answers on the API path and steps aside on the MCP path — the same
+ * contract `states` and `projects` follow.
+ */
+async function specSyncUsers(dir, config, query, flags, out) {
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+
+  if (transport === 'mcp') {
+    if (flags.json) {
+      out.write(
+        JSON.stringify({ transport: 'mcp', reason: key.ok ? 'requested' : key.error, users: null }, null, 2) + '\n',
+      )
+      return 0
+    }
+    out.write(
+      [
+        'spec-sync users: transport = mcp',
+        `  ${key.ok ? '--via mcp was requested' : key.error}`,
+        '  search the workspace over MCP with the user-list tool',
+      ].join('\n') + '\n',
+    )
+    return 0
+  }
+  if (!key.ok) {
+    out.write(`spec-sync users: refusing — ${key.error}\n`)
+    return 1
+  }
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  let page
+  try {
+    page = await adapter.searchUsers(query || '', { limit: flags.limit || 50, cursor: flags.cursor || null })
+  } catch (error) {
+    out.write(`spec-sync users: ${error.message}\n`)
+    return 1
+  }
+
+  const users = (page && page.users) || []
+  if (flags.json) {
+    out.write(
+      JSON.stringify({ transport: 'api', users, nextCursor: (page && page.nextCursor) || null }, null, 2) + '\n',
+    )
+    return 0
+  }
+  if (!users.length) {
+    out.write(`spec-sync users: no match for ${JSON.stringify(query || '')}\n`)
+    return 0
+  }
+  const lines = [`spec-sync users: ${users.length} match(es)`]
+  for (const u of users) {
+    // A deactivated user still resolves by id and can still be assigned, so the
+    // marker is the difference between a valid pick and a silently dead one.
+    const inactive = u && u.active === false ? '  [deactivated]' : ''
+    const email = u && u.email ? `  ${u.email}` : ''
+    lines.push(`  ${displayNameOf(u) || '(unnamed)'} <${u && u.id}>${email}${inactive}`)
+  }
+  if (page && page.nextCursor) lines.push(`  … more — re-run with --cursor ${page.nextCursor}`)
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
 /**
  * `spec-sync apply <spec> --plan <file> [--via api|mcp] [--project <id>]`
  * `spec-sync apply --all <bucket> [--via api|mcp] [--json]`
@@ -1886,7 +2687,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
     if (!flags.plan) {
       out.write(
         'spec-sync apply: refusing to run without --plan <file>.\n' +
-          '  Get one with: skitterspec spec-sync push <spec> --json > plan.json\n' +
+          '  Get one with: skitterspec spec-sync plan <spec> --json > plan.json\n' +
           '  Or apply a whole bucket at once with --all <bucket>.\n',
       )
       return 1
@@ -2136,6 +2937,12 @@ function specSyncInitConfig(dir, flags, out) {
   // shape — a blank key or a duplicate fails there, in one place, rather than
   // being re-checked here and drifting from the loader.
   if (flags.stages.length) draft.release = { stages: flags.stages }
+  // Assignment is opt-in and rides `fieldOwnership` rather than a key of its
+  // own. Only `assignee` is written: the loader merges this map PER KEY onto the
+  // defaults, so restating the other three would freeze today's defaults into
+  // the file and quietly opt the repo out of any later change to them — the very
+  // thing "only the keys that differ" exists to avoid.
+  if (flags.assign) draft.sync = { fieldOwnership: { assignee: 'push' } }
 
   for (const bucket of Object.keys(flags.stateNames)) {
     if (!LIFECYCLE_BUCKETS.includes(bucket)) {
@@ -2492,7 +3299,7 @@ async function specSync(rest, io = {}) {
   // after the loop.
   const unknownFlags = []
   const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null, plan: null, via: null, project: null, all: null,
-    mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null, stages: [] }
+    mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, stateArgs: [], statesFile: null, stages: [], limit: null, next: null, archived: false, assign: false, mine: false, by: null, inProgress: false }
   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
@@ -2504,7 +3311,16 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--mcp') flags.mcp = path.resolve(args[++i])
     else if (args[i] === '--plan') flags.plan = path.resolve(args[++i])
     else if (args[i] === '--via') flags.via = args[++i]
-    else if (args[i] === '--all') flags.all = args[++i]
+    // `apply --all <bucket>` takes a value; `list --all` is a bare boolean. Read
+    // off the subcommand rather than guessing from the next token — `list --all
+    // --json` would otherwise swallow `--json` as the bucket and silently drop it.
+    else if (args[i] === '--all') flags.all = sub === 'list' ? true : args[++i]
+    else if (args[i] === '--archived') flags.archived = true
+    else if (args[i] === '--limit') flags.limit = Number(args[++i])
+    else if (args[i] === '--next') flags.next = Number(args[++i])
+    else if (args[i] === '--mine') flags.mine = true
+    else if (args[i] === '--by') flags.by = args[++i]
+    else if (args[i] === '--in-progress') flags.inProgress = true
     else if (args[i] === '--project') flags.project = args[++i]
     else if (args[i] === '--workspace-states') flags.workspaceStates = path.resolve(args[++i])
     else if (args[i] === '--skip-state-check') flags.skipStateCheck = true
@@ -2515,6 +3331,17 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--yes') flags.yes = true
     else if (args[i] === '--check-remote') flags.remoteCheck = true
     else if (args[i] === '--stdin') flags.stdin = true
+    // `whoami --set <id> --name <n>`. Unlike `--key`, a user id and a name are
+    // NOT secrets — they appear on every issue in Linear — so passing them as
+    // arguments is safe and there is no hidden-prompt equivalent to reach for.
+    else if (args[i] === '--set') flags.set = String(args[++i] || '').trim()
+    else if (args[i] === '--name') flags.name = String(args[++i] || '').trim()
+    else if (args[i] === '--unset') flags.unset = true
+    else if (args[i] === '--to') flags.to = String(args[++i] || '').trim()
+    else if (args[i] === '--release') flags.release = true
+    else if (args[i] === '--assign') flags.assign = true
+    else if (args[i] === '--limit') flags.limit = Number(args[++i]) || 0
+    else if (args[i] === '--cursor') flags.cursor = String(args[++i] || '').trim()
     else if (args[i] === '--command') flags.command = String(args[++i] || '').trim()
     else if (args[i] === '--key') {
       // Consumed and DELIBERATELY DISCARDED. A secret in argv is visible in
@@ -2531,10 +3358,15 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--bug-labels') flags.bugLabels = labelList(args[++i])
     else if (args[i] === '--hotfix-labels') flags.hotfixLabels = labelList(args[++i])
     else if (args[i] === '--state') {
-      // `--state complete=Shipped`, repeatable. Only the buckets a workspace
-      // actually renamed get written; the rest keep the defaults.
-      const [bucket, ...rest] = String(args[++i] || '').split('=')
+      // Two readings of one flag, kept apart rather than overloaded:
+      // `init-config --state complete=Shipped` is a bucket=name PAIR, while
+      // `list --state "In Progress"` is a bare Linear state NAME. Both are
+      // recorded — `stateNames` for the former, the raw value in `stateArgs`
+      // for the latter — so neither command has to infer which it was given.
+      const raw = String(args[++i] || '').trim()
+      const [bucket, ...rest] = raw.split('=')
       flags.stateNames[String(bucket).trim()] = rest.join('=').trim()
+      if (raw) flags.stateArgs.push(raw)
     } else if (args[i] === '--stage') {
       // `--stage test="On Test"`, repeatable. Order matters and is the order
       // given, so the ladder is written exactly as the operator listed it.
@@ -2603,8 +3435,20 @@ async function specSync(rest, io = {}) {
   switch (sub) {
     case 'normalize':
       return specSyncNormalize(dir, config, positional[0], out, err) || 0
-    case 'push':
+    case 'plan':
       return specSyncPush(dir, config, positional[0], flags, out, err) || 0
+    // RETIRED NAME, deliberately recognised rather than left to fall through to
+    // the usage block. `push` named the one subcommand that writes nothing — it
+    // computes a plan with no network access, while `apply` does the writing —
+    // and it collided with both the /spec-push skill and `git push`. A silent
+    // alias would keep the old name alive forever; a generic "unknown
+    // subcommand" would throw away the one hint that makes the break cheap.
+    case 'push':
+      err.write(
+        'spec-sync push was renamed to spec-sync plan.\n' +
+          'It computes the create/update plan and writes nothing; `spec-sync apply` applies it.\n',
+      )
+      return 1
     case 'stamp':
       return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
@@ -2613,8 +3457,16 @@ async function specSync(rest, io = {}) {
       return specSyncStatus(dir, config, positional[0], flags, out) || 0
     case 'projects':
       return (await specSyncProjects(dir, config, flags, out)) || 0
+    case 'list':
+      return (await specSyncList(dir, config, flags, out)) || 0
     case 'states':
       return (await specSyncStates(dir, config, flags, out)) || 0
+    case 'whoami':
+      return (await specSyncWhoami(dir, config, flags, out)) || 0
+    case 'assign':
+      return specSyncAssign(dir, config, positional[0], flags, out)
+    case 'users':
+      return (await specSyncUsers(dir, config, positional[0], flags, out)) || 0
     case 'released':
       return (await specSyncReleased(dir, config, positional[0], flags, out)) || 0
     case 'stage':
@@ -2635,13 +3487,17 @@ async function specSync(rest, io = {}) {
     default:
       out.write('Usage: skitterspec spec-sync <normalize|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
         '       skitterspec spec-sync credentials <status|set|unset> [--stdin] [--json]\n' +
-        '       skitterspec spec-sync push <spec> --workspace-states <file> [--json] [--skip-state-check]\n' +
+        '       skitterspec spec-sync plan <spec> --workspace-states <file> [--json] [--skip-state-check]\n' +
         '       skitterspec spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]\n' +
         '       skitterspec spec-sync states [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync projects [--via api|mcp] [--json]\n' +
+        '       skitterspec spec-sync whoami [--set <id> [--name N]] [--unset] [--json]\n' +
+        '       skitterspec spec-sync users [<name-or-email>] [--limit N] [--cursor C] [--json]\n' +
+        '       skitterspec spec-sync assign <spec> --to <id> [--name N] | --release [--json]\n' +
         '       skitterspec spec-sync apply <spec> --plan <file> [--via api|mcp] [--project id] [--json]\n' +
         '       skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync verify <spec> --stored <file>\n' +
+        '       skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
         '       skitterspec spec-sync linked [--json]\n' +
         '       skitterspec spec-sync ref [<spec>] [--json]\n' +
         '       skitterspec spec-sync released [<range>] [--json]\n' +
@@ -2650,6 +3506,7 @@ async function specSync(rest, io = {}) {
         '       skitterspec spec-sync doctor [--check-remote] [--mcp <file>] [--json]\n' +
         '       skitterspec spec-sync init-config --team-id <id> [--team-key K] [--project-id id]\n' +
         '                    [--intake-label L] [--bug-labels a,b] [--hotfix-labels a,b]\n' +
+        '                    [--assign]\n' +
         '                    [--state <bucket>=<name> …] [--states <file>] [--force] [--json]\n')
       return 0
   }