@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/src/env/provision.js

@@ -230,6 +230,60 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
   return ok
 }
 
+/**
+ * The `-f <composeFile>` argument for a `docker compose` invocation.
+ *
+ * ONLY when the configured file is known to be present, and that condition is
+ * the whole point. `docker.composeFile` was read, normalised and validated by
+ * the config loader and then never passed to docker at all, so a project naming
+ * a non-default file was silently relying on docker's own discovery instead.
+ * Passing it unconditionally would fix that project and BREAK the mirror image
+ * of it — one whose compose file is `compose.yaml` (a name docker finds by
+ * itself) while this key sits at its untouched default of `docker-compose.yml`.
+ *
+ * So the flag is added on the positive signal and omitted otherwise, which
+ * leaves docker's discovery exactly as it is for everyone it was already
+ * working for.
+ */
+function composeFileArg(config, present) {
+  const file = config && config.docker && config.docker.composeFile
+  return present === true && file ? ` -f ${file}` : ''
+}
+
+/**
+ * Does this spec want a Docker stack?
+ *
+ * ONE function, called by `planUp` and by the `up` command in `cli.js`. They
+ * used to each carry their own copy and the copies disagreed: the CLI read
+ * `spec.stack === 'docker'` with no fallback, so a header-less spec allocated no
+ * registry slot, while the planner fell back to the master switch and emitted
+ * `docker compose up -d` anyway — a stack brought up on a port offset derived
+ * from a slot that was never allocated.
+ *
+ * A SPEC WITH NO `Stack:` HEADER NEEDS THE COMPOSE FILE TO BE PRESENT. The
+ * master switch alone is not evidence that there is a stack to bring up: it is
+ * a project-wide default, and `/spec` has written the header on every spec for
+ * some time, so the specs reaching this fallback are legacy or hand-written. The
+ * compose file is the positive signal that the escalation would land on
+ * something real (`.claude/rules/negative-checks.md` rule 1).
+ *
+ * WHAT WOULD FOOL THIS, deliberately unhandled: a project whose compose file is
+ * generated during `setup` rather than committed. It does not exist when the
+ * plan is built, so a header-less spec there resolves to `worktree`. The answer
+ * is an explicit `> **Stack:** worktree + docker` header, which is checked first
+ * and never consults this at all — so being wrong costs a header, not a stack.
+ *
+ * `composeFilePresent` undefined means the caller did not look, which is
+ * cannot-tell rather than false. It routes to no escalation, the harmless
+ * branch: a missing stack surfaces as a header to add, where a spurious one
+ * surfaces as `docker compose` failing mid-provision (rule 4).
+ */
+function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
+  const stack =
+    spec.stack || (config.docker.enabled && composeFilePresent === true ? 'docker' : 'worktree')
+  return { stack, wantsDocker: stack === 'docker' && config.docker.enabled && !docs }
+}
+
 /**
  * Plan a provisioning run.
  *
@@ -238,18 +292,34 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
  * @param {object} alloc { slot, attached } — attached:true when the slot already
  *                       existed in the registry (re-run → attach, don't clobber).
  * @param {object} config normalised env config.
+ * @param {object} opts  { docs } — documents mode (see below). Optional.
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
  *                     envContents, commands, seedCommands,
- *                     setupCommands, attached }
+ *                     setupCommands, docs, attached }
  */
-function planUp(spec, alloc, config, ctx) {
+function planUp(spec, alloc, config, ctx, opts = {}) {
   const { slot, attached } = alloc
 
-  // Per-spec escalation: bring Docker up only when this spec's Stack is `docker`,
-  // gated by the project master switch. A spec resolved without an explicit stack
-  // (legacy/tests) follows the master switch — preserving pre-`Stack` behaviour.
-  const stack = spec.stack || (config.docker.enabled ? 'docker' : 'worktree')
-  const wantsDocker = stack === 'docker' && config.docker.enabled
+  // DOCUMENTS MODE — a worktree to write a spec in, not to run code in.
+  //
+  // `/spec` provisions before it writes the spec folder, so that authoring never
+  // touches the base branch. What it needs is a checkout on a branch; what it
+  // does not need is `pnpm install --frozen-lockfile` and a database, to write
+  // markdown. So this mode keeps the fork and drops everything whose only
+  // purpose is making the tree runnable.
+  //
+  // It is not a lesser provision that has to be undone: `/spec-start` re-runs
+  // `up` over the same worktree WITHOUT this flag, and the setup commands run
+  // then — at the first moment the tree is used for code.
+  const docs = opts.docs === true
+
+  // Per-spec escalation, decided in ONE place (`resolveStack`) so the planner and
+  // the CLI cannot answer it differently — which they did, for exactly the
+  // header-less spec this gate is about.
+  const { wantsDocker } = resolveStack(spec, config, {
+    docs,
+    composeFilePresent: ctx ? ctx.composeFilePresent : undefined,
+  })
 
   // Slot, port block and `.env` are Docker-only. A worktree-only spec takes none
   // of them: no registry slot, no PORT_OFFSET, no `.env`.
@@ -298,7 +368,10 @@ function planUp(spec, alloc, config, ctx) {
       : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
   if (wantsDocker) {
-    commands.push(`docker compose --project-name ${spec.projectName} up -d`)
+    commands.push(
+      `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
+        ` --project-name ${spec.projectName} up -d`,
+    )
   }
 
   // The tree gate. A worktree forks from the base branch's tree, so an
@@ -325,7 +398,16 @@ function planUp(spec, alloc, config, ctx) {
     envContents,
     commands: gate.blocked ? [] : [...gate.commands, ...commands],
     seedCommands: gate.blocked ? [] : seedCommands,
-    setupCommands: gate.blocked ? [] : setupCommands,
+    // Documents mode drops these, and keeps the seed commands above. The two are
+    // not the same kind of thing: seeding links the gitignored files a worktree
+    // has none of — cheap, and a spec author may well want `.env` present —
+    // while `setup` is the expensive half that exists to make the tree run.
+    setupCommands: gate.blocked || docs ? [] : setupCommands,
+    // Reported so a caller reading `--json` can tell a documents worktree from a
+    // full one POSITIVELY, rather than inferring it from what is missing. An
+    // empty `setupCommands` also describes a project that configured no setup
+    // at all, and those two must not read alike.
+    docs,
     attached,
   }
 }
@@ -347,6 +429,12 @@ function planUp(spec, alloc, config, ctx) {
  *    refusal — it is the re-run, and the answer is "already attached".
  *
  * There is no bootstrap: the primary checkout already has its dependencies.
+ *
+ * AND THAT IS WHY `--docs` IS INERT HERE, rather than unimplemented. Documents
+ * mode exists to skip making a fresh tree runnable; this mode makes no fresh
+ * tree, so there is nothing for it to skip. The flag is accepted and changes
+ * nothing, because a caller passing it is asking for a cheap checkout and gets
+ * one — refusing would make `/spec` mode-aware for no behavioural difference.
  */
 function planCheckoutUp(spec, ctx, config) {
   const base = ctx.base || (config && config.baseBranch) || 'main'
@@ -388,4 +476,12 @@ function planCheckoutUp(spec, ctx, config) {
   return result
 }
 
-module.exports = { planUp, planCheckoutUp, planSpecCommit, seedCommandFor, worktreeCd }
+module.exports = {
+  planUp,
+  planCheckoutUp,
+  planSpecCommit,
+  seedCommandFor,
+  worktreeCd,
+  resolveStack,
+  composeFileArg,
+}

package/src/env/registry.js

@@ -34,7 +34,7 @@ function readRegistry(rootDir, config) {
   try {
     raw = fs.readFileSync(file, 'utf-8')
   } catch (error) {
-    if (error.code === 'ENOENT') return { slots: {} }
+    if (error.code === 'ENOENT') return { slots: {}, specless: {} }
     throw error
   }
   let parsed
@@ -43,14 +43,24 @@ function readRegistry(rootDir, config) {
   } catch (error) {
     throw new Error(`Invalid registry ${config.registry}: ${error.message}`)
   }
-  return { slots: isObject(parsed.slots) ? { ...parsed.slots } : {} }
+  return {
+    slots: isObject(parsed.slots) ? { ...parsed.slots } : {},
+    specless: isObject(parsed.specless) ? { ...parsed.specless } : {},
+  }
 }
 
 // Persist the registry, creating its parent dir as needed.
 function writeRegistry(rootDir, config, registry) {
   const file = registryPath(rootDir, config)
   fs.mkdirSync(path.dirname(file), { recursive: true })
-  fs.writeFileSync(file, JSON.stringify({ slots: registry.slots }, null, 2) + '\n')
+  // `specless` is written only when it holds something, so a project that never
+  // ran `/no-spec` keeps a registry file byte-identical to the one it had
+  // before this key existed.
+  const payload = { slots: registry.slots }
+  if (registry.specless && Object.keys(registry.specless).length) {
+    payload.specless = registry.specless
+  }
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2) + '\n')
 }
 
 /**
@@ -60,14 +70,19 @@ function writeRegistry(rootDir, config, registry) {
  */
 function allocateSlot(registry, name) {
   const slots = { ...registry.slots }
+  // CARRIED THROUGH, NOT REBUILT. Every one of these helpers returns a whole
+  // registry, so a helper that forgets a key silently deletes it on the next
+  // write — which is how a `/no-spec` branch would have become unresolvable the
+  // moment any Docker spec was provisioned beside it.
+  const specless = { ...(registry.specless || {}) }
   if (Object.prototype.hasOwnProperty.call(slots, name)) {
-    return { registry: { slots }, slot: slots[name] }
+    return { registry: { slots, specless }, slot: slots[name] }
   }
   const used = new Set(Object.values(slots))
   let slot = 0
   while (used.has(slot)) slot++
   slots[name] = slot
-  return { registry: { slots }, slot }
+  return { registry: { slots, specless }, slot }
 }
 
 /**
@@ -77,7 +92,7 @@ function allocateSlot(registry, name) {
 function freeSlot(registry, name) {
   const slots = { ...registry.slots }
   delete slots[name]
-  return { slots }
+  return { slots, specless: { ...(registry.specless || {}) } }
 }
 
 // Port block base for a slot.
@@ -85,6 +100,51 @@ function portOffset(slot, config) {
   return config.docker.portBase + slot * config.docker.portsPerSpec
 }
 
+/**
+ * Record a SPECLESS branch — `/no-spec` work, which has a worktree and a branch
+ * and no spec document anywhere.
+ *
+ * A SEPARATE KEY RATHER THAN A SLOT, and that is the whole design of it. A slot
+ * means a reserved port block, which mechanical work does not want; and every
+ * consumer of `slots` reads an entry there as "this spec runs a Docker stack".
+ * Sharing the map would have made `/no-spec` allocate ports it never binds and
+ * appear as a stateful spec in `status`.
+ *
+ * It is what makes a specless name RESOLVABLE. Without a record, "no spec folder
+ * for this name" is indistinguishable from a typo — and `resolve.js` would have
+ * to treat every unknown name as possibly-specless, which is exactly the
+ * absence-as-evidence this codebase refuses (`.claude/rules/negative-checks.md`
+ * rule 1). This is the positive signal: the engine wrote this name down.
+ *
+ * Idempotent, and pure — returns a new registry object.
+ */
+function recordSpecless(registry, name, entry = {}) {
+  const specless = { ...(registry.specless || {}) }
+  specless[name] = { ...(specless[name] || {}), ...entry }
+  return { slots: { ...registry.slots }, specless }
+}
+
+/**
+ * Forget a specless branch. Idempotent: forgetting an absent one is a clean
+ * no-op, which is what lets teardown call it without looking first.
+ */
+function forgetSpecless(registry, name) {
+  const specless = { ...(registry.specless || {}) }
+  delete specless[name]
+  return { slots: { ...registry.slots }, specless }
+}
+
+// Is this name a recorded specless branch? Pure, and the positive signal
+// `resolve.js` asks for before it will resolve a name with no spec folder.
+function isSpecless(registry, name) {
+  return Object.prototype.hasOwnProperty.call((registry && registry.specless) || {}, name)
+}
+
+// Every recorded specless name, sorted so output is stable. Pure.
+function speclessNames(registry) {
+  return Object.keys((registry && registry.specless) || {}).sort()
+}
+
 module.exports = {
   registryPath,
   readRegistry,
@@ -92,4 +152,8 @@ module.exports = {
   allocateSlot,
   freeSlot,
   portOffset,
+  recordSpecless,
+  forgetSpecless,
+  isSpecless,
+  speclessNames,
 }

package/src/env/resolve.js

@@ -167,7 +167,37 @@ function parsePhase(text, name) {
 }
 
 /**
- * The spec's own `## Problem` and `## Impact`, for the page's header.
+ * The tracker ticket a spec is linked to, as `{ id, url }`, or null.
+ *
+ * Read straight out of the overview's frontmatter, where every provider stamps
+ * it. The base is tracker-free, so this knows nothing about Linear beyond the
+ * two key names a provider writes — an unlinked spec, or a project with no
+ * provider installed, simply has neither and gets `null`.
+ *
+ * ONLY http(s) URLS SURVIVE. The value comes out of a file someone edits, and
+ * the page turns it into an `href`; `javascript:` in that position is script
+ * execution on a page served over the network. An id with an unusable url is
+ * still worth having, so the id is kept and the link dropped rather than the
+ * whole ticket.
+ */
+function readTicket(text) {
+  const fm = /^---\n([\s\S]*?)\n---/.exec(text)
+  if (!fm) return null
+  const field = (name) => {
+    const m = new RegExp(`^${name}:\\s*(.*)$`, 'm').exec(fm[1])
+    if (!m) return null
+    const v = m[1].trim().replace(/^["']|["']$/g, '').trim()
+    return v || null
+  }
+  const id = field('linear_identifier')
+  if (!id) return null
+  const url = field('linear_url')
+  return { id, url: url && /^https?:\/\//i.test(url) ? url : null }
+}
+
+/**
+ * The spec's own `## Problem` and `## Impact`, plus its tracker ticket, for the
+ * page's header.
  *
  * WHAT WOULD FOOL THIS: a spec that renames those headings, or a legacy bare
  * `<name>.md` with no overview at all. Both yield `null`, which the caller
@@ -183,10 +213,14 @@ function readOverview(specDir, { overviewFile = '00-overview.md' } = {}) {
   }
   const problem = sectionOf(text, 'Problem') || sectionOf(text, 'Symptom')
   const impact = impactRows(sectionOf(text, 'Impact'))
-  if (!problem && !impact) return null
+  const ticket = readTicket(text)
+  // The ticket counts towards "is there anything to say": a spec linked to a
+  // tracker but carrying neither section still has a header worth drawing.
+  if (!problem && !impact && !ticket) return null
   return {
     ...(problem ? { problem } : {}),
     ...(impact ? { impact } : {}),
+    ...(ticket ? { ticket } : {}),
   }
 }
 
@@ -434,11 +468,68 @@ function assertPrimaryOnMain(config, git) {
  * That is `bug-spec-env-cwd-anchor`'s fix and it is deliberately untouched here;
  * only which *file* is read moves.
  */
+/**
+ * Resolve a SPECLESS branch — `/no-spec` work — to the same shape `resolveSpec`
+ * returns, minus every field that comes from a spec document.
+ *
+ * `bucket`, `path`, `stack` and `baseRef` are null rather than invented: there
+ * is no document to read them from, and a plausible default would make a
+ * consumer believe it had read one. `specless: true` is the flag every caller
+ * branches on, so "is there a spec here?" is a field rather than an inference
+ * from a missing `path`.
+ *
+ * The branch is `chore/{slug}` by default — `branch.pattern` already carries a
+ * `{type}`, so nothing about branch naming is special-cased here. A recorded
+ * entry may name its own `branch`, which wins: the record is what the worktree
+ * was actually created against, and re-deriving it would go wrong the moment a
+ * project changed its pattern under a standing branch.
+ *
+ * Pure but for `repoInfo`, like `resolveSpec`.
+ */
+function resolveSpecless(name, dir, config, entry = {}) {
+  const { repo, repoSlug } = repoInfo(dir)
+  const slug = name
+  const tokens = { repo, repoSlug, slug }
+  const spec = {
+    folder: name,
+    bucket: null,
+    path: null,
+    type: (entry && entry.type) || 'chore',
+    slug,
+    stack: 'worktree',
+    baseRef: null,
+    specless: true,
+  }
+  const branch = (entry && entry.branch) || branchFor(spec, config)
+  const worktreeRoot = expandTokens(config.worktree.root, tokens)
+  const worktreeFolder = expandTokens(config.worktree.folderPattern, tokens)
+  return {
+    ...spec,
+    repo,
+    repoSlug,
+    branch,
+    worktreeRoot,
+    worktreeFolder,
+    worktreePath: path.resolve(dir, worktreeRoot, worktreeFolder),
+    projectName: expandTokens(config.docker.projectNamePattern, tokens),
+  }
+}
+
 function resolveSpec(specArg, dir, config, opts = {}) {
   const searchDirs = opts.searchDirs || []
   const preferDirs = opts.preferDirs || []
   const found = findSpecFolder(specArg, dir, searchDirs, preferDirs)
   if (!found) {
+    // A SPECLESS BRANCH, but only on the registry's word. `/no-spec` work has a
+    // worktree and a branch and no spec document anywhere, so it can never be
+    // found by looking under `specs/**` — and "not found there" is not evidence
+    // of it, because a typo looks identical (`.claude/rules/negative-checks.md`
+    // rule 1). The caller passes the registry's specless map, and being named in
+    // it is the positive signal; without one, nothing changes and the error
+    // below is thrown exactly as before.
+    if (opts.specless && Object.prototype.hasOwnProperty.call(opts.specless, specArg)) {
+      return resolveSpecless(specArg, dir, config, opts.specless[specArg])
+    }
     // Name the roots we looked under: the usual cause is a spec that only exists
     // on its own branch, and the message should say where we didn't find it.
     throw new Error(
@@ -455,7 +546,19 @@ function resolveSpec(specArg, dir, config, opts = {}) {
   // A hotfix forks its worktree from a release tag (its `Base version`) instead
   // of base HEAD; every other type resolves to baseRef:null (fork from HEAD).
   const baseRef = type === 'hotfix' ? readBaseVersionField(found.path) : null
-  const spec = { folder: found.folder, bucket: found.bucket, path: found.path, type, slug, stack, baseRef }
+  // `specless: false` is written out rather than left off, so every consumer
+  // reads the same field on every resolution instead of treating `undefined` as
+  // an answer.
+  const spec = {
+    folder: found.folder,
+    bucket: found.bucket,
+    path: found.path,
+    type,
+    slug,
+    stack,
+    baseRef,
+    specless: false,
+  }
   const branch = branchFor(spec, config)
 
   const worktreeRoot = expandTokens(config.worktree.root, tokens)
@@ -519,23 +622,43 @@ function collectSpecFolders(roots) {
  * spec that was authored on its branch and never committed to the primary
  * checkout.
  */
-function allSpecs(dir, config, worktreePaths) {
+function allSpecs(dir, config, worktreePaths, specless = {}) {
   const searchDirs = [...worktreePaths]
   const specs = []
   for (const folder of collectSpecFolders([dir, ...searchDirs])) {
     try {
       const spec = resolveSpec(folder, dir, config, { searchDirs })
-      specs.push({ folder: spec.folder, slug: spec.slug, worktreePath: spec.worktreePath })
+      specs.push({
+        folder: spec.folder,
+        slug: spec.slug,
+        worktreePath: spec.worktreePath,
+        specless: false,
+      })
     } catch {
       // Unresolvable folder (not a real spec) — skip.
     }
   }
+  // SPECLESS BRANCHES ARE LISTED TOO, and they have to be added here rather than
+  // found: `collectSpecFolders` scans `specs/**`, where by definition they are
+  // not. Leaving them out is what would make a `/no-spec` worktree invisible to
+  // `status` and to every bare resolution — the outcome decision 7 rejected for
+  // a plain git branch, arrived at by omission instead.
+  for (const name of Object.keys(specless).sort()) {
+    const spec = resolveSpecless(name, dir, config, specless[name])
+    specs.push({
+      folder: spec.folder,
+      slug: spec.slug,
+      worktreePath: spec.worktreePath,
+      specless: true,
+    })
+  }
   return specs
 }
 
 module.exports = {
   BUCKETS,
   resolveSpec,
+  resolveSpecless,
   liveWorktreePaths,
   collectSpecFolders,
   allSpecs,