@skitterbyte/skitterspec-linear 11.0.0 → 12.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

@@ -444,6 +444,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
@@ -682,6 +700,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 +732,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 +740,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 +752,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

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/cli-sync.js

@@ -242,6 +242,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 +250,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`,
@@ -483,6 +502,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'))

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

@@ -94,7 +94,9 @@ function snapshotOf(projection) {
 /**
  * Diff the local projection against the last-pushed snapshot.
  * @returns {{ issue?: object, subIssues: {create,update} }}
- *   create items carry a `ref` (local handle) and no id; update items carry both
+ *   `unstamped` (when present) lists phases whose stamp is missing while the
+ *   snapshot still remembers an unminted-for id — ambiguous, so neither created
+ *   nor updated. create items carry a `ref` (local handle) and no id; update items carry both
  *   — the `ref` because the read-back check matches sub-issues to phases BY ref,
  *   and an update with only an id makes every one of them look unmatched.
  *   `plan.issue` (when present) is the spec issue's description + state; the push
@@ -105,16 +107,37 @@ function planChanges(projection, snapshot) {
   const snap = snapshot || {}
   const snapS = snap.subIssues || {}
 
+  // Ids the last push minted that no phase claims any more. A phase file's stamp
+  // is the only link back to its sub-issue, and it lives in frontmatter — so a
+  // whole-file rewrite, a hand edit or a bad merge drops it while the sub-issue
+  // carries on existing. This snapshot is the only memory that it was ever
+  // minted, and nothing else in the push path re-reads the tracker.
+  const claimed = new Set()
+  for (const s of p.subIssues || []) if (s.id != null) claimed.add(String(s.id))
+  const unclaimed = Object.keys(snapS).filter((id) => !claimed.has(id))
+
   const subIssues = { create: [], update: [] }
+  const unstamped = []
   for (const s of p.subIssues || []) {
     if (s.id == null) {
-      subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
+      // THREE STATES, NOT TWO. "No stamp" means "new phase" only when every id
+      // the snapshot remembers is still claimed. With an unclaimed id sitting
+      // beside an unstamped phase the two readings — a new phase, and a phase
+      // whose stamp was lost — are indistinguishable from here, so this routes to
+      // the harmless branch and mints nothing. Being wrong this way costs a
+      // re-stamp; the other way cost a duplicate sub-issue and a manual cancel.
+      if (unclaimed.length) {
+        unstamped.push({ ref: s.ref, name: s.name, candidates: unclaimed.slice() })
+      } else {
+        subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
+      }
     } else if (snapS[String(s.id)] !== subIssueHash(s)) {
       subIssues.update.push({ ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state })
     }
   }
 
   const plan = { subIssues }
+  if (unstamped.length) plan.unstamped = unstamped
   const issue = issueChanges(p, snap)
   if (issue) plan.issue = issue
   return plan