@skitterbyte/skitterspec-linear 12.0.0 → 13.0.0

package/src/vendor/linear/config.js

@@ -164,6 +164,14 @@ const DEFAULT_CONFIG = Object.freeze({
     // labels, cycles and comments are Linear-native triage — deliberately NOT in
     // the set, so the PM's triage is never touched. The `push` marker is retained
     // for shape; any key you add joins the pushed projection.
+    //
+    // `assignee` is the one field that OPTS IN this way rather than shipping on:
+    // add `"assignee": "push"` and the issue is assigned to whoever is building
+    // the spec, and released when it completes. Left out (the default) the whole
+    // feature is inert — nothing is written, no hash is recorded in a snapshot,
+    // and `status` prints no assignee line. It is deliberately not a new config
+    // key: this map is already the documented extension point, and assignment is
+    // exactly "one more field the repo owns".
     fieldOwnership: Object.freeze({
       description: 'push',
       subIssues: 'push',

package/src/vendor/linear/credentials.js

@@ -106,6 +106,34 @@ function keyForTeam(store, teamId) {
   return typeof key === 'string' && key.trim() ? key.trim() : null
 }
 
+/**
+ * The Linear IDENTITY recorded for one team, or null.
+ *
+ * Identity lives here rather than in the repo's `linear.config.json` for the
+ * same reason the key does: that file is COMMITTED, so a user id written there
+ * would follow the repo to every teammate who clones it and assign their specs
+ * to whoever set it up. Who you are is a fact about this machine and this
+ * workspace, which is exactly what this store is keyed for.
+ *
+ * Unlike a key, an identity is NOT a secret — it is a name and a public user id,
+ * both of which appear on every issue in Linear. So it may be printed, passed as
+ * an argument, and returned in an error.
+ */
+function userForTeam(store, teamId) {
+  if (!teamId) return null
+  const teams = store && store.teams
+  const entry = teams && typeof teams === 'object' ? teams[teamId] : null
+  if (!entry || typeof entry !== 'object') return null
+  const user = entry.user
+  if (!user || typeof user !== 'object') return null
+  // The id is what the assignment is actually made with, so an entry without one
+  // is not a partial identity — it is no identity at all.
+  const id = typeof user.id === 'string' && user.id.trim() ? user.id.trim() : null
+  if (!id) return null
+  const name = typeof user.name === 'string' && user.name.trim() ? user.name.trim() : null
+  return { id, name }
+}
+
 // Last 4 characters, for reporting that a key exists without revealing it.
 function fingerprint(key) {
   if (typeof key !== 'string' || !key) return null
@@ -153,6 +181,69 @@ function writeKey(file, teamId, key, deps = {}) {
   return { ok: true, path: file, created }
 }
 
+/**
+ * Record the Linear identity for one team, preserving that team's key (or
+ * `keyCommand`) and every other team's entry.
+ *
+ * Same store, same 0600 / 0700 guards, same refusal on an over-permissive file
+ * as `writeKey` — the file holds a key whether or not this particular write
+ * carries one, so relaxing the guard here would relax it for the key too.
+ *
+ * Returns `{ ok: true, path, created }` or `{ ok: false, reason }`.
+ */
+function writeUser(file, teamId, user, deps = {}) {
+  const mkdir = deps.mkdir || fs.mkdirSync
+  const write = deps.write || fs.writeFileSync
+  const chmod = deps.chmod || fs.chmodSync
+  const exists = deps.exists || fs.existsSync
+
+  if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+  const id = user && typeof user.id === 'string' ? user.id.trim() : ''
+  if (!id) return { ok: false, reason: 'no user id — nothing stored' }
+  const name = user && typeof user.name === 'string' ? user.name.trim() : ''
+
+  const created = !exists(file)
+  let store = { version: 1, teams: {} }
+  if (!created) {
+    const current = readStore(file, deps)
+    if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
+    store = current.store
+    if (!store.teams || typeof store.teams !== 'object') store.teams = {}
+    if (!store.version) store.version = 1
+  }
+
+  // Spread the existing entry, exactly as `writeKey` does: recording an identity
+  // must never cost the user the key sitting beside it.
+  store.teams[teamId] = { ...(store.teams[teamId] || {}), user: name ? { id, name } : { id } }
+
+  mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+  chmod(file, 0o600)
+  return { ok: true, path: file, created }
+}
+
+/**
+ * Forget the identity recorded for one team, leaving that team's KEY in place.
+ *
+ * Deliberately not `removeKey`'s shape. That one drops the whole team entry,
+ * which is right when the key is what you are revoking; here it would sign the
+ * user out of Linear entirely because they corrected their own name. A store or
+ * entry that isn't there is a clean no-op, not an error.
+ */
+function removeUser(file, teamId, deps = {}) {
+  const write = deps.write || fs.writeFileSync
+  const current = readStore(file, deps)
+  if (!current.ok) {
+    if (current.code === 'absent') return { ok: true, path: file, removed: false }
+    return { ok: false, reason: current.reason, code: current.code }
+  }
+  const entry = current.store.teams && current.store.teams[teamId]
+  if (!entry || !entry.user) return { ok: true, path: file, removed: false }
+  delete entry.user
+  write(file, JSON.stringify(current.store, null, 2) + '\n', { mode: 0o600 })
+  return { ok: true, path: file, removed: true }
+}
+
 /**
  * Remove one team's entry, leaving every other team intact. A store or entry
  * that isn't there is a clean no-op, not an error.
@@ -288,11 +379,14 @@ module.exports = {
   storePath,
   readStore,
   keyForTeam,
+  userForTeam,
   fingerprint,
   writeKey,
+  writeUser,
   writeKeyCommand,
   resolveTeamKey,
   removeKey,
+  removeUser,
   storeMode,
   DIR_NAME,
   FILE_NAME,

package/src/vendor/linear/doctor.js

@@ -60,6 +60,7 @@ function runChecks(state = {}) {
     trackerCheck(state.tracker),
     projectCheck(state.project, state.tracker, state.remote),
     keyCheck(state.key, state.tracker),
+    identityCheck(state.identity, state.tracker),
     remoteCheck(state.remote),
     ladderCheck(state.ladder, state.tracker),
     mcpCheck(state.mcp, state.tracker, state.project, state.remote),
@@ -255,6 +256,40 @@ function keyCheck(s = {}, tracker = {}) {
   return row('key', 'key', 'ok', `${s.fingerprint || 'set'} from ${s.source || 'unknown'}`)
 }
 
+/**
+ * Who this machine is in Linear — the fact assignment rests on.
+ *
+ * WHAT WOULD MAKE THIS CHECK ACCUSE THE INNOCENT, and why it does not:
+ *
+ *   - **A project that never opted in.** Assignment is opt-in through
+ *     `sync.fieldOwnership.assignee`; without it nothing reads an identity, so
+ *     reporting one as missing would tell a healthy project to fix something it
+ *     deliberately does not use. That is `skipped`, and it is the common case.
+ *   - **An identity that is merely underivable.** No key, offline, a shared
+ *     credential — all ordinary, all `missing` rather than `broken`, because the
+ *     lifecycle skills skip assignment and carry on. Nothing here fails a run.
+ *
+ * So the only states it can produce are `skipped`, `missing` and `ok`. There is
+ * deliberately no `broken`: being unable to name you is never evidence that
+ * something is wrong with the install.
+ */
+function identityCheck(s = {}, tracker = {}) {
+  if (!tracker.present) return row('identity', 'identity', 'skipped', 'no tracker configured')
+  if (!s.owned) {
+    return row('identity', 'identity', 'skipped', 'assignment not enabled (sync.fieldOwnership.assignee)')
+  }
+  if (!s.ok) {
+    return row(
+      'identity',
+      'identity',
+      'missing',
+      s.error || 'no Linear identity for this workspace',
+      'skitterspec spec-sync whoami',
+    )
+  }
+  return row('identity', 'identity', 'ok', `${s.name || s.id} from ${s.source === 'store' ? 'the credentials store' : 'the API key'}`)
+}
+
 function remoteCheck(s = {}) {
   if (!s.checked) {
     return row('remote', 'remote', 'skipped', 'pass --check-remote to verify against Linear')

package/src/vendor/linear/identity.js

@@ -0,0 +1,105 @@
+'use strict'
+
+/**
+ * "Who am I in this Linear workspace?" — the question assignment rests on.
+ *
+ * The answer is DERIVED, not configured. A Linear personal API key is issued to
+ * a person, so the workspace can be asked directly (`viewer` on the API path,
+ * `get_user "me"` over MCP). That is why assignment needs no repo config in the
+ * common case, and why there is no `linear.userId`: `specs/.core/linear.config.json`
+ * is committed, so an id written there would follow the repo to every teammate
+ * who clones it and assign their specs to whoever set it up.
+ *
+ * Resolution order, first hit wins:
+ *
+ *   1. the user-level credentials store  (`source: 'store'`)  — no network
+ *   2. the credential itself, via `viewer` (`source: 'viewer'`)
+ *   3. nothing                            (`source: 'unknown'`)
+ *
+ * **Unknown is a normal state, not a failure** — the same contract
+ * `resolveApiKey` holds for a missing key. A shared/bot key answers `viewer`
+ * with the bot; an offline machine answers with nothing; neither is a broken
+ * install, and both are why `spec-sync whoami --set` exists. So this returns a
+ * structured result the caller branches on, never an exception.
+ *
+ * It also NEVER PROMPTS and NEVER WRITES. Prompting belongs to the skill that
+ * has a human in front of it, and caching belongs to the command that decided
+ * the answer was worth keeping — a resolver that wrote to disk as a side effect
+ * of being asked a question would cache a bot's identity the first time CI ran.
+ */
+
+const { resolveApiKey, makeApiAdapter } = require('./api.js')
+const { storePath, readStore, userForTeam } = require('./credentials.js')
+
+/**
+ * Resolve the current user's Linear identity.
+ *
+ * @returns {Promise<object>} `{ ok: true, id, name, source }` where `source` is
+ *   `'store'` or `'viewer'`; otherwise `{ ok: false, source: 'unknown', reason }`.
+ *   `reason` explains what was tried, so "no key" and "Linear rejected the key"
+ *   stay distinguishable — an unexplained "unknown" is what makes people
+ *   re-enter a name that was never the problem.
+ */
+async function resolveIdentity(config, env = process.env, deps = {}) {
+  const teamId = (config && config.linear && config.linear.teamId) || ''
+  // The store is keyed by team, so with no teamId there is nothing to look up.
+  // Fall through rather than fail: `viewer` does not need a team, and a repo
+  // mid-setup should still be able to answer who you are.
+  const file = (deps.storePath || storePath)(env)
+
+  if (teamId) {
+    const result = (deps.readStore || readStore)(file)
+    if (result.ok) {
+      const cached = (deps.userForTeam || userForTeam)(result.store, teamId)
+      if (cached) return { ok: true, id: cached.id, name: cached.name, source: 'store', path: file }
+    }
+    // A store that is present but unusable (over-permissive, malformed) is NOT
+    // reported as an identity failure — the key resolution below hits the same
+    // file and reports it properly. Duplicating it here would print the same
+    // permissions warning twice for one cause.
+  }
+
+  const key = (deps.resolveApiKey || resolveApiKey)(config, env)
+  if (!key.ok) {
+    return { ok: false, source: 'unknown', reason: key.error, envVar: key.envVar, path: file }
+  }
+
+  const adapter = deps.adapter || makeApiAdapter({ apiKey: key.key, fetch: deps.fetch })
+  let viewer
+  try {
+    viewer = await adapter.readViewer()
+  } catch (error) {
+    // Offline, revoked key, Linear down. All are "cannot tell", which routes to
+    // the harmless branch: the caller skips assignment rather than guessing.
+    return { ok: false, source: 'unknown', reason: error.message, path: file }
+  }
+
+  const id = viewer && typeof viewer.id === 'string' ? viewer.id.trim() : ''
+  if (!id) {
+    return { ok: false, source: 'unknown', reason: 'Linear returned no viewer for this key', path: file }
+  }
+  return {
+    ok: true,
+    id,
+    name: displayNameOf(viewer),
+    email: (viewer && viewer.email) || null,
+    source: 'viewer',
+    path: file,
+  }
+}
+
+/**
+ * The name to show for a Linear user, preferring the one Linear itself puts on
+ * an issue. Falls back through `displayName` and `email` so a user with an odd
+ * profile still reads as a person rather than a UUID.
+ */
+function displayNameOf(user) {
+  if (!user || typeof user !== 'object') return null
+  for (const field of ['name', 'displayName', 'email']) {
+    const value = user[field]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return null
+}
+
+module.exports = { resolveIdentity, displayNameOf }

package/src/vendor/linear/mcp.js

@@ -33,6 +33,14 @@ const MATCHERS = {
   // The team's Linear Projects, for the `/spec` + `/spec-push` project picker.
   // Plural-only for the same reason as issueList: `get_project` is a read.
   projectList: [/list_?projects?/i, /projects?_?list/i],
+  // "Who am I" — Linear's user-read tool takes the literal string `me`, which is
+  // the MCP path's equivalent of the API's `viewer`.
+  userRead: [/get_?user\b/i, /user_?get/i],
+  // The user search behind `/spec-claim --to` and the identity fallback.
+  // Singular/plural split is load-bearing here exactly as it is for issues:
+  // `\b` on userRead stops it claiming `list_users`, and userList's `list_`
+  // prefix stops it claiming `get_user`.
+  userList: [/list_?users?/i, /users?_?list/i],
 }
 
 // The minimum the push engine can't run without: read an issue back and
@@ -134,6 +142,24 @@ function makeAdapter(callTool, resolved) {
     async listProjects(teamId) {
       return callTool(need('projectList'), teamId ? { team: teamId } : {})
     },
+    // "Who am I". Linear's user-read tool accepts the literal `me` alongside an
+    // id, name or email — so the MCP path answers identity without a config
+    // entry, exactly as the API path does through `viewer`.
+    //
+    // Optional, like `listProjects`: a server without a user-read tool means
+    // identity has to be set by hand (`spec-sync whoami --set`), never a failed
+    // push. `REQUIRED` is deliberately unchanged.
+    async readViewer() {
+      return callTool(need('userRead'), { query: 'me' })
+    },
+    // Find a person by name or email. Linear's `list_users` takes an optional
+    // `query` and pages, so search and listing are one tool rather than two.
+    async searchUsers(query, { limit } = {}) {
+      const args = {}
+      if (query) args.query = query
+      if (limit) args.limit = limit
+      return callTool(need('userList'), args)
+    },
   }
 }
 

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

@@ -13,11 +13,11 @@
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
  */
 
-const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
+const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = 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, listPhaseFiles } = require('./src/write.js')
+const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 const { detectLegacyMirror } = require('./src/legacy.js')
 const { compareStored } = require('./src/verify.js')
@@ -26,6 +26,9 @@ const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPa
 
 module.exports = {
   normalizeLocal,
+  // Exported for `spec-sync list`: an `inline`-mode spec has no phase sub-issues
+  // to read, so the listing must resolve the mode rather than assume `subissue`.
+  phaseModeFor,
   lintPhases,
   readSnapshot,
   parseFrontmatter,
@@ -47,6 +50,7 @@ module.exports = {
   readBase,
   writeBase,
   writeFrontmatter,
+  deleteFrontmatter,
   stampSubIssueId,
   stampIssueId,
   findPhaseFileByTitle,

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

@@ -60,10 +60,16 @@ function specIssueHash(p) {
 // dragged the issue back. Diffing them apart is what lets a push touch the
 // description without re-asserting a state someone else now owns.
 function specIssueFieldHashes(p) {
-  return {
+  const hashes = {
     description: hashField(p.description ?? null),
     state: hashField(p.status ?? null),
   }
+  // ONLY WHEN THE FIELD IS IN PLAY. A repo that has not opted `assignee` into
+  // `sync.fieldOwnership` must not accumulate assignee hashes in its snapshots —
+  // "the feature is inert" has to include the files it writes, or opting in later
+  // would find a history of hashes it never agreed to.
+  if (p.assignee !== undefined) hashes.assignee = hashField(p.assignee ?? null)
+  return hashes
 }
 // A phase SUB-ISSUE: its name, goal and state (all repo-owned).
 const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
@@ -159,19 +165,59 @@ function planChanges(projection, snapshot) {
 function issueChanges(projection, snapshot) {
   const p = projection || {}
   const snap = snapshot || {}
-  const both = () => ({ description: p.description ?? null, state: p.status ?? null })
+  const both = () => {
+    const out = { description: p.description ?? null, state: p.status ?? null }
+    // ASSERT, NEVER CLEAR, on this path. There are no split hashes here, so
+    // whether an assignee was ever pushed is unknown — and the harmless reading
+    // of "unknown" is to send one we have and stay silent about one we don't.
+    if (p.assignee != null) out.assignee = p.assignee
+    return out
+  }
 
   const fields = snap.issueFields
   if (fields === null || typeof fields !== 'object' || Array.isArray(fields)) {
     // No split hashes recorded: an old snapshot, or no snapshot at all (a
     // create, which needs both fields anyway).
-    return snap.issue === specIssueHash(p) ? null : both()
+    if (snap.issue !== specIssueHash(p)) return both()
+    // Description and state are unchanged — but the COMBINED HASH SAYS NOTHING
+    // ABOUT THE ASSIGNEE, which was never one of its inputs. Absence of evidence
+    // again, and the two directions are not equally safe: asserting an assignee
+    // the repo actually recorded costs one redundant write, while staying quiet
+    // would strand it until some unrelated prose edit happened to push. Clearing
+    // is still never guessed at. The push rewrites the snapshot in the split
+    // shape, so a spec passes through here exactly once.
+    return p.assignee != null ? { assignee: p.assignee } : null
   }
 
   const want = specIssueFieldHashes(p)
   const changed = {}
   if (fields.description !== want.description) changed.description = p.description ?? null
   if (fields.state !== want.state) changed.state = p.status ?? null
+
+  // ASSIGNEE — AN ABSENT SNAPSHOT KEY MEANS "NEVER PUSHED", NOT "WAS NULL".
+  //
+  // What would fool this check: every spec linked before assignee existed has a
+  // snapshot with no `assignee` key, and so does every spec in a repo that never
+  // opted the field in. Read that absence as `null` and the first push after
+  // upgrade computes null → null → "unchanged"… except where a PM had assigned
+  // the issue in Linear, which the repo would then silently clear. The bill for
+  // getting this wrong is somebody else's triage, workspace-wide, in one command.
+  //
+  // So absence is routed to the harmless branch: assert an assignee we actually
+  // have, and never send a clear at something we never set.
+  // (`.claude/rules/negative-checks.md` — prefer a positive signal to an absence,
+  // and bias the unknown case toward inaction.)
+  if (want.assignee !== undefined) {
+    if (fields.assignee === undefined) {
+      if (p.assignee != null) changed.assignee = p.assignee
+    } else if (fields.assignee !== want.assignee) {
+      // A recorded hash IS a positive signal that the repo pushed this field
+      // before, so a change to null here is a retraction of our own assignment
+      // rather than a guess at someone else's.
+      changed.assignee = p.assignee ?? null
+    }
+  }
+
   return Object.keys(changed).length ? changed : null
 }
 

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

@@ -675,6 +675,30 @@ function bucketFromPath(snapshotDir) {
 // the states in which phases are not yet worth minting as sub-issues.
 const UNSTARTED_BUCKETS = ['backlog', 'cancelled']
 
+// Buckets where a spec is FINISHED, and so has nobody working on it.
+const TERMINAL_BUCKETS = ['complete', 'cancelled']
+
+/**
+ * The Linear user this spec is assigned to, AS PROJECTED — which is not simply
+ * what the frontmatter records.
+ *
+ * The BUCKET decides, not the stamp's presence. A spec that is live (`backlog`,
+ * `in-progress`) projects whoever the repo recorded; a finished one projects
+ * `null`, so completing a spec hands the issue back with no unassign step for
+ * anyone to remember. The stamp itself is deliberately left in the spec file:
+ * `> **Developer:**` and the frontmatter are the durable record of who actioned
+ * the work, and that outlives the assignment.
+ *
+ * `null` here does NOT mean "clear it in Linear" on its own — see
+ * `issueChanges`, where an assignee that was never pushed is left alone rather
+ * than retracted. That is what stops this wiping a PM's triage.
+ */
+function assigneeFor(workflowState, frontmatter) {
+  if (TERMINAL_BUCKETS.includes(String(workflowState))) return null
+  const id = frontmatter && frontmatter.linear_assignee_id
+  return typeof id === 'string' && id.trim() ? id.trim() : null
+}
+
 // The mode a bucket gets when a per-bucket `mapping.phases` map omits it. Adding
 // a bucket to the map is therefore an EXCEPTION for that bucket, not a switch
 // that silently suppresses phases everywhere the map is silent. Matches the
@@ -798,6 +822,11 @@ function normalizeLocal(snapshotDir, config) {
       state: p.state,
     })),
     workflowState,
+    // Who is building this. `toFieldSet` drops it unless the repo listed
+    // `assignee` in `sync.fieldOwnership`, so the opt-in costs no extra check
+    // here — an un-opted-in repo simply has no such key on its projection, and
+    // every downstream reader treats that as "the field is not in play".
+    assignee: assigneeFor(workflowState, frontmatter),
   }
   return toFieldSet(extracted, config)
 }
@@ -1039,6 +1068,7 @@ module.exports = {
   stateSuggestions,
   configuredStateNames,
   normalizeLocal,
+  assigneeFor,
   phaseProjection,
   phaseModeFor,
   phasesWithheld,

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

@@ -26,7 +26,7 @@ const { detectLegacyMirror } = require('./legacy.js')
 // config.states at apply time.
 function projectionOf(snapshotDir, config) {
   const local = normalizeLocal(snapshotDir, config)
-  return {
+  const projection = {
     description: local.description ?? null,
     status: local.workflowState ?? null,
     subIssues: Array.isArray(local.subIssues) ? local.subIssues : [],
@@ -40,6 +40,16 @@ function projectionOf(snapshotDir, config) {
     // per-bucket map, which mode applied is no longer readable off the config.
     phaseMode: phaseModeFor(local.workflowState, config),
   }
+  // ASSIGNEE IS SET ONLY WHEN THE FIELD IS IN PLAY, and the distinction between
+  // `undefined` and `null` is load-bearing all the way down: `undefined` means
+  // the repo never opted in, so no hash is recorded and no op is ever emitted;
+  // `null` means opted in with nobody assigned, which CAN legitimately clear a
+  // previously-pushed assignee. Defaulting the key to null here would collapse
+  // the two and make an un-opted-in repo start clearing assignees on its next
+  // push. `normalizeLocal` omits the key entirely when `sync.fieldOwnership`
+  // does not list it.
+  if ('assignee' in local) projection.assignee = local.assignee ?? null
+  return projection
 }
 
 function push({ dir, snapshotDir, identifier, config }) {

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

@@ -77,6 +77,43 @@ function writeFrontmatter(snapshotDir, config, patch) {
   return Object.keys(clean)
 }
 
+/**
+ * Remove keys from `00-overview.md` frontmatter. Returns the keys actually
+ * removed (absent ones are a clean no-op, not an error).
+ *
+ * A separate function because `writeFrontmatter` SKIPS nullish values by
+ * design — that is what lets a caller pass a sparse patch without clearing the
+ * fields it left out, and it means "remove this key" is inexpressible there. A
+ * released assignment has to actually leave the file: setting it empty would
+ * leave a spec claiming to be assigned to nobody in particular, and the
+ * projection reads presence, not emptiness.
+ */
+function deleteFrontmatter(snapshotDir, config, keys) {
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const file = path.join(snapshotDir, overviewFile)
+  const raw = fs.readFileSync(file, 'utf-8')
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  if (!had) return []
+
+  const drop = new Set(keys)
+  const removed = []
+  const kept = fmLines.filter((line) => {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (kv && drop.has(kv[1])) {
+      removed.push(kv[1])
+      return false
+    }
+    return true
+  })
+  if (!removed.length) return []
+
+  // An emptied block is dropped entirely rather than left as `---\n---`, which
+  // some markdown renderers show as a horizontal rule.
+  const next = kept.length ? `---\n${kept.join('\n')}\n---\n${body}` : body
+  fs.writeFileSync(file, next, 'utf-8')
+  return removed
+}
+
 // Phase files in a snapshot dir (01-*.md …), execution order.
 function listPhaseFiles(snapshotDir) {
   try {
@@ -142,6 +179,7 @@ function stampIssueId(snapshotDir, text, id) {
 
 module.exports = {
   writeFrontmatter,
+  deleteFrontmatter,
   splitFrontmatter,
   serialize,
   listPhaseFiles,

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Reuben Greaves
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.