@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

package/src/gating.js

@@ -0,0 +1,155 @@
+'use strict'
+
+/**
+ * Release gating — the loader, the header reader, and the check.
+ *
+ * The feature records ONE decision per spec: does this ship behind a feature
+ * flag, or land live? Skitterspec never learns how a project does flags; it asks
+ * the question, cites the project's own documentation, and reads back what was
+ * written. Strictly opt-in: with `specs/.core/gating.config.json` absent, every
+ * function here reports "not configured" and nothing else changes.
+ *
+ * Mirrors `src/env/config.js` (frozen defaults, merge known keys only, never
+ * throws on absence) so the two opt-in configs behave alike.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const CONFIG_FILE = path.join('specs', '.core', 'gating.config.json')
+
+// Only these two buckets are ever read.
+//
+// A SPEC WRITTEN BEFORE GATING WAS ADOPTED HAS NO HEADER AND IS NOT BROKEN. That
+// is the blind spot this check would otherwise walk into: "no Gating: line" is
+// evidence of an unanswered question only for a spec that could have been asked,
+// and every finished or abandoned spec predates the question by definition. They
+// are excluded STRUCTURALLY rather than by a filter someone must remember — a
+// completed spec is not in range, so no future edit can make it fire. Pre-existing
+// specs still in flight ARE reported, deliberately: they are live work, the
+// question genuinely still applies, and the report never blocks anything.
+const ACTIVE_BUCKETS = ['backlog', 'in-progress']
+
+const DEFAULT_CONFIG = Object.freeze({
+  guidance: '',
+  default: 'none: <reason>',
+})
+
+/**
+ * Load `specs/.core/gating.config.json`. Returns `{ config, present }`;
+ * `present:false` means the project has not adopted gating, which is read as
+ * "this project does not use feature flags" — never as an error.
+ */
+function loadGatingConfig(dir = process.cwd()) {
+  const base = { ...DEFAULT_CONFIG }
+  let raw
+  try {
+    raw = fs.readFileSync(path.join(dir, CONFIG_FILE), 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { config: base, present: false }
+    throw error
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
+  }
+  if (parsed && typeof parsed === 'object') {
+    if (typeof parsed.guidance === 'string') base.guidance = parsed.guidance.trim()
+    if (typeof parsed.default === 'string' && parsed.default.trim()) {
+      base.default = parsed.default.trim()
+    }
+  }
+  return { config: base, present: true }
+}
+
+/**
+ * Read a spec's `> **Gating:** …` blockquote field from `00-overview.md`.
+ *
+ * Returns `{ raw, kind }` with four kinds, because there are four states and
+ * collapsing them is what made the omission invisible in the first place:
+ *
+ *   flag     a flag name — ships behind it
+ *   none     `none: <reason>` — deliberately not flagged, and why
+ *   invalid  present but says nothing: empty, or a bare `none` with no reason
+ *   missing  no field at all
+ *
+ * `invalid` and `missing` are kept apart on purpose. A bare `none` is someone
+ * answering without deciding; a missing line is nobody having been asked. They
+ * want different words.
+ */
+function readGatingField(specPath) {
+  const overview = path.join(specPath, '00-overview.md')
+  let raw
+  try {
+    raw = fs.readFileSync(overview, 'utf-8')
+  } catch {
+    return { raw: null, kind: 'missing' }
+  }
+  const m = /^>\s*\*\*Gating:\*\*\s*(.*)$/m.exec(raw)
+  if (!m) return { raw: null, kind: 'missing' }
+  const value = m[1].trim().replace(/^["'`]|["'`]$/g, '')
+  if (!value) return { raw: value, kind: 'invalid' }
+  const bare = /^none\b/i.test(value)
+  if (bare) {
+    // `none` alone, or `none:` with nothing after it, is a shrug rather than a
+    // decision — the reason half is the whole point of recording it.
+    const reason = value.replace(/^none\b:?/i, '').trim()
+    return { raw: value, kind: reason ? 'none' : 'invalid' }
+  }
+  return { raw: value, kind: 'flag' }
+}
+
+// Active specs on disk, as `{ folder, bucket, path }`. A bucket that does not
+// exist is simply empty — git does not store empty directories, so a missing
+// `specs/backlog/` is the ordinary state of a project with nothing queued.
+function activeSpecs(dir) {
+  const out = []
+  for (const bucket of ACTIVE_BUCKETS) {
+    const root = path.join(dir, 'specs', bucket)
+    let entries
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) out.push({ folder: e.name, bucket, path: path.join(root, e.name) })
+    }
+  }
+  return out
+}
+
+/**
+ * Check specs for a recorded gating decision.
+ *
+ * Advisory by construction: it returns findings and says nothing about what the
+ * caller should do. Nothing here exits, throws on a finding, or blocks.
+ *
+ * @returns {{configured: boolean, findings: Array<{folder, bucket, kind, raw}>,
+ *            checked: number, guidance: string}}
+ */
+function checkGating(dir, specs) {
+  const { config, present } = loadGatingConfig(dir)
+  if (!present) return { configured: false, findings: [], checked: 0, guidance: '' }
+  const targets = specs && specs.length ? specs : activeSpecs(dir)
+  const findings = []
+  for (const spec of targets) {
+    const { kind, raw } = readGatingField(spec.path)
+    if (kind === 'missing' || kind === 'invalid') {
+      findings.push({ folder: spec.folder, bucket: spec.bucket, kind, raw })
+    }
+  }
+  return { configured: true, findings, checked: targets.length, guidance: config.guidance }
+}
+
+module.exports = {
+  CONFIG_FILE,
+  DEFAULT_CONFIG,
+  ACTIVE_BUCKETS,
+  loadGatingConfig,
+  readGatingField,
+  activeSpecs,
+  checkGating,
+}

package/src/init.js

@@ -153,7 +153,7 @@ function assertComposedAssets() {
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], removed: [], customized: [], healed: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], healed: [], warnings: [] }
 
 function resetReport() {
   for (const k of Object.keys(report)) report[k].length = 0
@@ -293,6 +293,25 @@ function writeFile(dir, target, content, { force }) {
   if (link && link.isSymbolicLink() && !fs.existsSync(target)) {
     fs.unlinkSync(target)
   }
+  // A LIVE symlink is the opposite case, and `--force` is what makes it
+  // dangerous: `writeFileSync` follows the link, so forcing would write composed
+  // content — seam markers resolved, provider text spliced in — straight through
+  // it and into whatever it points at. In a checkout that dogfoods its own
+  // assets that is `packages/*/assets`, i.e. the SOURCE the link exists to keep
+  // live. Refuse: the staleness `--force` was reached for is a smaller problem
+  // than corrupting the file it would overwrite.
+  //
+  // WHAT WOULD MAKE THIS LIE: a HARD link. It has no distinguishing lstat — it
+  // simply is the file — so it takes the same corrupting path and nothing here
+  // can see it. Out of scope deliberately, and said out loud rather than left to
+  // be discovered; nothing in this project's install creates one.
+  //
+  // It cannot fire in an ordinary consumer install, because nothing there is
+  // linked — `skitterspec update` writes copies by design.
+  if (force && link && link.isSymbolicLink() && fs.existsSync(target)) {
+    report.refused.push(rel(dir, target))
+    return
+  }
   if (fs.existsSync(target)) {
     if (!force) {
       report.skipped.push(rel(dir, target))
@@ -444,6 +463,24 @@ function installIsolation(dir, { enabled, workspaceMode }, opts) {
   trustWorktreeRoot(dir)
 }
 
+// Activate opt-in release gating: write specs/.core/gating.config.json from the
+// example asset, so /spec and friends start asking whether a change ships behind
+// a feature flag and recording the answer.
+//
+// Only called when the operator opts in, and NEVER on `update` — for the same
+// reason as isolation: adopting a policy is a deliberate choice, not something a
+// re-sync flips on. Idempotent; copyAsset never clobbers an existing config
+// without --force, so an operator's edited `guidance` survives a re-init.
+function installGating(dir, { enabled }, opts) {
+  if (!enabled) return
+  copyAsset(
+    dir,
+    path.join('core', 'gating.config.json.example'),
+    path.join(dir, 'specs', '.core', 'gating.config.json'),
+    opts,
+  )
+}
+
 // Seed the absolute worktree root into .claude/settings.local.json (gitignored)
 // so the operator enabling isolation isn't prompted on every edit into a
 // freshly-provisioned worktree. Best-effort: an unreadable config or malformed
@@ -481,6 +518,67 @@ function trustWorktreeRoot(dir) {
   }
 }
 
+// Is the CLAUDE.md section this project has installed the one we ship?
+//
+// THREE answers, not two. `differs` deliberately does NOT mean "stale": the
+// block is a COPY, so a difference is either an out-of-date copy or the user's
+// own edit, and from here those read identically. Rule 4 of
+// `.claude/rules/negative-checks.md` — route the unknown case to the harmless
+// branch, which here means reporting a difference and naming the fix rather
+// than accusing them of being behind.
+//
+// WHAT WOULD FOOL THIS: absent markers mean the section was never installed, OR
+// that someone stripped it deliberately (`stripClaudeMdSection` exists and is
+// reachable from `reset`). Neither is a fault, so both answer `not installed`
+// and neither is reported as a problem.
+function claudeMdSectionState(dir) {
+  const target = path.join(dir, 'CLAUDE.md')
+  if (!fs.existsSync(target)) return 'not installed'
+  const existing = fs.readFileSync(target, 'utf8')
+  if (!existing.includes(SPEC_MARKER_START) || !existing.includes(SPEC_MARKER_END)) {
+    return 'not installed'
+  }
+  const shipped = fs.readFileSync(path.join(ASSETS, 'claude-md-section.md'), 'utf8').trim()
+  const start = existing.indexOf(SPEC_MARKER_START) + SPEC_MARKER_START.length
+  const installed = existing.slice(start, existing.indexOf(SPEC_MARKER_END)).trim()
+  return installed === shipped ? 'fresh' : 'differs'
+}
+
+// `update --check`: say what `update` would change, write nothing, exit 0.
+// It reports; `update` without the flag stays the only thing that touches a
+// file. This exists because the section is a copy and a copy goes quietly out
+// of date — this repo's own was a whole spec behind the template it ships,
+// through a spec about that template, with every test green.
+function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  const manifest = readManifest(dir)
+  const rows = []
+  // Mirror `resyncManagedFile`'s decision exactly rather than re-deriving it:
+  // missing → it would create; customized → it would KEEP yours and say so;
+  // pristine → it would write only when the shipped content actually differs.
+  for (const { relPath, abs, bundled } of managedTargets(dir)) {
+    const state = managedState(dir, relPath, manifest, bundled)
+    if (state === 'missing') rows.push([relPath, 'missing — would be created'])
+    else if (state === 'customized') rows.push([relPath, 'your edit — kept (--force overwrites)'])
+    else if (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
+  }
+  const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
+  // A healthy area says NOTHING. A report that lists what is already fine is a
+  // report people learn to skim, and then the one line that mattered is missed.
+  if (section === 'differs') {
+    rows.push([
+      'CLAUDE.md (spec workflow section)',
+      'differs from the shipped one — `update` would replace it (it is a copy, so this is either your edit or an out-of-date one)',
+    ])
+  }
+  if (!rows.length) log('skitterspec update --check: everything is up to date.')
+  else {
+    log('skitterspec update --check: `skitterspec update` would:')
+    for (const [name, why] of rows) log(`  ${name} — ${why}`)
+  }
+  return { rows, section }
+}
+
 function installClaudeMd(dir, { mode }) {
   const section = fs.readFileSync(path.join(ASSETS, 'claude-md-section.md'), 'utf8').trim()
   const block = `${SPEC_MARKER_START}\n${section}\n${SPEC_MARKER_END}\n`
@@ -663,6 +761,15 @@ function printReport(dir, mode, { diff = false } = {}) {
   )
   line('manifest repaired', report.healed)
   line('unchanged', report.skipped)
+  if (report.refused.length) {
+    process.stdout.write('\nrefused (a symlink — writing would overwrite what it points at):\n')
+    for (const it of report.refused) process.stdout.write(`  ${it}\n`)
+    process.stdout.write(
+      '  These are links into the shipped assets. --force would follow them and\n' +
+        '  write composed content into the source. Unlink one to take the copy\n' +
+        '  (rm <path>, then re-run), or leave it linked and edit the asset.\n',
+    )
+  }
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
@@ -682,6 +789,13 @@ function printReport(dir, mode, { diff = false } = {}) {
       ' at /spec-start (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
+  const gatingOn = fs.existsSync(path.join(dir, 'specs', '.core', 'gating.config.json'))
+  const gatingNote = gatingOn
+    ? 'Release gating is ON: /spec asks whether a change ships behind a feature' +
+      ' flag and records the answer on the spec (skitterspec gating check reports' +
+      ' any that have none).\n'
+    : 'Release gating is opt-in: re-run with --gating (or copy' +
+      ' specs/.core/gating.config.json.example → gating.config.json) to enable it.\n'
   // A provider superset ships its own `spec-<provider>-setup` skill; the base
   // ships none. Discovering it from what was actually installed keeps this file
   // tracker-free — it never has to know which tracker (if any) is in the box.
@@ -707,6 +821,7 @@ function printReport(dir, mode, { diff = false } = {}) {
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
       isolationNote +
+      gatingNote +
       trackerNote,
   )
 }
@@ -714,7 +829,7 @@ function printReport(dir, mode, { diff = false } = {}) {
 // `mode` here is the INSTALL mode ('init' | 'update'), long-standing and
 // unrelated to the config's own `mode` key — which arrives as `workspaceMode`
 // precisely so the two cannot be confused at a call site.
-async function init({ dir, force, claudeMd, mode, isolation, workspaceMode }) {
+async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   resetReport()
 
@@ -726,6 +841,7 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode }) {
   installCore(dir, { force })
   // Adopting isolation writes the live env.config.json — init only, never update.
   if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
+  if (mode !== 'update') installGating(dir, { enabled: gating }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
   // Record what we wrote (and migrate a pre-manifest repo) so a later resync can
@@ -737,6 +853,10 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode }) {
 
 module.exports = {
   init,
+  // A snapshot of the last run's report, for tests that need to assert on what a
+  // run DECIDED rather than only on what it left on disk. Copied, so a caller
+  // cannot mutate the live report between phases of a run.
+  lastReport: () => JSON.parse(JSON.stringify(report)),
   SKILLS,
   COMMANDS,
   RULES,
@@ -747,6 +867,8 @@ module.exports = {
   writeManifest,
   managedTargets,
   managedState,
+  claudeMdSectionState,
+  checkSync,
   isExistingSetup,
   resync,
   reset,

package/src/prompts.js

@@ -11,7 +11,7 @@
  * is `'worktree'` otherwise (the value the config defaults to anyway).
  */
 
-async function promptSetup({ isolationSeed = false } = {}) {
+async function promptSetup({ isolationSeed = false, gatingSeed = false } = {}) {
   const prompts = require('prompts')
 
   let cancelled = false
@@ -48,6 +48,14 @@ async function promptSetup({ isolationSeed = false } = {}) {
         },
       ],
     },
+    {
+      // Orthogonal to isolation, so it is asked unconditionally rather than
+      // nested under it — a project can adopt either, both, or neither.
+      type: 'confirm',
+      name: 'gating',
+      message: 'Record a release-gating decision on each spec — flag, or land live?',
+      initial: gatingSeed,
+    },
   ]
 
   const ans = await prompts(questions, { onCancel })
@@ -59,6 +67,7 @@ async function promptSetup({ isolationSeed = false } = {}) {
   return {
     isolation: Boolean(ans.isolation),
     mode: ans.mode === 'checkout' ? 'checkout' : 'worktree',
+    gating: Boolean(ans.gating),
   }
 }
 

package/src/vendor/linear/api.js

@@ -29,6 +29,10 @@ const ENDPOINT = 'https://api.linear.app/graphql'
 const MAX_RETRIES = 5
 const MAX_BACKOFF_MS = 60_000
 
+// Linear's hard per-page ceiling on a connection. `listIssues` pages against
+// this rather than trusting a caller's `first` to be under it.
+const PAGE_SIZE = 250
+
 const { storePath, readStore, resolveTeamKey } = require('./credentials.js')
 
 /**
@@ -96,7 +100,22 @@ function resolveApiKey(config, env = process.env, deps = {}) {
 
 // Fields we read back on every write. `identifier` and `url` are what the skill
 // stamps into the spec; `description` is what `spec-sync verify` compares.
-const ISSUE_FIELDS = 'id identifier url title description state { id name }'
+// `assignee` rides along so `spec-sync status` can report assignment drift from
+// the same read-back the state drift already uses — one read, not two; it is
+// also the "who holds this" column of the listing.
+// `priority`, `sortOrder` and `parent` are here for `listIssues`: one query has
+// to answer every column the listing prints (Linear's own backlog order) and
+// the discriminator it filters on (a phase sub-issue carries `parent`, a spec
+// issue does not). Requesting them on the read/create/update paths too costs
+// nothing and keeps one field list.
+const ISSUE_FIELDS =
+  'id identifier url title description priority sortOrder state { id name } assignee { id name } parent { id }'
+
+// What we read back about a person. `name` is the handle Linear shows on an
+// issue; `displayName` is the short @-handle; `active` distinguishes a current
+// member from a deactivated one, which matters because a deactivated user still
+// resolves by id and can still be assigned.
+const USER_FIELDS = 'id name displayName email active'
 
 /**
  * A GraphQL caller bound to one key. Throws a clear Error on transport failure,
@@ -234,6 +253,90 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
       if (data && data.team) return (data.team.projects && data.team.projects.nodes) || []
       return (data && data.projects && data.projects.nodes) || []
     },
+    // WHO THIS KEY BELONGS TO. A personal API key is issued to a person, so the
+    // workspace can answer "who am I" without anyone configuring it — which is
+    // why identity needs no repo config in the common case.
+    //
+    // The exception this cannot see: a SHARED or bot key, where the viewer is
+    // the bot and not the human at the keyboard. That is what
+    // `spec-sync whoami --set` exists to override, and why nothing treats this
+    // answer as unarguable.
+    async readViewer() {
+      const data = await call(`query { viewer { ${USER_FIELDS} } }`)
+      return (data && data.viewer) || null
+    },
+    // Find a person by name or email — the fallback when the viewer is not the
+    // right answer, and how `/spec-claim --to` resolves a teammate.
+    //
+    // Search AND paging, not a choice between them: a bare listing is the whole
+    // team (fine for five people, useless for five hundred), while search alone
+    // cannot answer "show me everyone". `query` omitted lists; `cursor` walks.
+    // `first` is capped at 250 to match what Linear will return in one page.
+    async searchUsers(query, { limit = 50, cursor = null } = {}) {
+      const term = typeof query === 'string' ? query.trim() : ''
+      // `or` over name and email: someone searching "jane" and someone pasting
+      // "jane@acme.com" are asking the same question.
+      const filter = term
+        ? { or: [{ name: { containsIgnoreCase: term } }, { email: { containsIgnoreCase: term } }] }
+        : {}
+      const data = await call(
+        `query($filter: UserFilter, $first: Int, $after: String) {
+           users(filter: $filter, first: $first, after: $after) {
+             nodes { ${USER_FIELDS} }
+             pageInfo { hasNextPage endCursor }
+           } }`,
+        { filter, first: Math.min(Math.max(1, limit), 250), after: cursor || null },
+      )
+      const users = (data && data.users) || {}
+      const page = users.pageInfo || {}
+      return {
+        users: users.nodes || [],
+        // Null rather than absent when the page is the last one, so a caller
+        // loops on a value rather than on the presence of a key.
+        nextCursor: page.hasNextPage ? page.endCursor || null : null,
+      }
+    },
+    // The listing's one read. Paging is done HERE rather than by the caller so
+    // `first` means what it says — Linear caps a page at 250, and a caller that
+    // asked for 400 and silently got 250 is exactly the "no silent caps" failure
+    // this feature exists to avoid. `first: null` means "everything", which is
+    // what lets the listing report a truthful `showing 5 of 23` instead of a
+    // total it only assumed. The returned `pageInfo` is the LAST page's, so
+    // `hasNextPage` still tells a capped caller that more exist.
+    //
+    // API-only, like `listIssueStates` — see the operation-contract test.
+    async listIssues({ teamId, stateIds, assigneeId, parentless, first = null, after = null, includeArchived = false } = {}) {
+      const filter = {}
+      if (teamId) filter.team = { id: { eq: teamId } }
+      if (stateIds && stateIds.length) filter.state = { id: { in: stateIds } }
+      if (assigneeId) filter.assignee = { id: { eq: assigneeId } }
+      // Linear's IssueFilter spells "has no parent" as a null check on the
+      // relation; there is no `isOrphan`-style boolean.
+      if (parentless) filter.parent = { null: true }
+
+      const query = `query($filter: IssueFilter, $first: Int, $after: String, $includeArchived: Boolean) {
+        issues(filter: $filter, first: $first, after: $after, includeArchived: $includeArchived) {
+          nodes { ${ISSUE_FIELDS} }
+          pageInfo { hasNextPage endCursor }
+        }
+      }`
+
+      const nodes = []
+      let cursor = after
+      let pageInfo = { hasNextPage: false, endCursor: null }
+      for (;;) {
+        const want = first === null ? PAGE_SIZE : Math.min(PAGE_SIZE, first - nodes.length)
+        if (want <= 0) break
+        const data = await call(query, { filter, first: want, after: cursor, includeArchived: !!includeArchived })
+        const conn = (data && data.issues) || {}
+        for (const node of conn.nodes || []) nodes.push(node)
+        pageInfo = conn.pageInfo || { hasNextPage: false, endCursor: null }
+        if (!pageInfo.hasNextPage) break
+        cursor = pageInfo.endCursor
+        if (first !== null && nodes.length >= first) break
+      }
+      return { nodes, pageInfo }
+    },
     // The team's CURRENT key, which is what `retarget` compares stamped
     // identifiers against. Read from Linear rather than `config.linear.teamKey`
     // on purpose: the config key is itself one of the things that goes stale