@skitterbyte/skitterspec 22.1.0 → 22.2.0

package/assets/rules/spec-reports.md

@@ -201,6 +201,16 @@ escape hatch is what let a whole class of runs go on asking questions nobody was
 listening for. Where a watch is unavailable the wait is the turn ending, which
 every harness can do.
 
+**Run it under a persistent watch primitive where the harness has one** — one
+that lives for the whole session and whose deliberate stop is an explicit act
+(Claude Code: the `Monitor` tool with `persistent: true`, ended by `TaskStop`).
+A backgrounded shell is reclaimed on a long idle — that is the death the next
+paragraph recovers from — where a session-length primitive is designed to
+survive it. Where the harness has none, background the command exactly as
+before. The engine's wait stays the one watcher either way: its heartbeat goes
+to stderr, so stdout carries only the start line and the arrival, and the exit
+ends the watch.
+
 **A watch that dies is re-armed, silently, on the same window.** A backgrounded
 wait does not always survive a long idle: three sessions lost theirs over one
 lunch break, and two in another were killed at 43 and 30 minutes. So a wait that
@@ -212,11 +222,17 @@ would strand exactly that pass.
 **Say nothing when you do it.** Nothing happened and the window is unchanged; a
 line on every death turns a working loop into a stream of non-events.
 
-**An operator who stopped it is not a death.** Re-arming over a deliberate stop
-makes the wait unstoppable, which is worse than a wait that stops. Where the two
-cannot be told apart, treat it as deliberate and leave it
-(`.claude/rules/negative-checks.md` rule 4): the cost of being wrong is one
-`/spec-reviewed`, against a loop nobody can break.
+**An operator who stopped it is not a death** — re-arming over a deliberate
+stop makes the wait unstoppable, which is worse than a wait that stops. But a
+deliberate stop is an **explicit act with positive evidence**: this session
+called TaskStop, or the operator said to stop waiting. A bare killed-task
+notification carries neither and is read as a **death**. This clause once said
+to treat the ambiguous kill as deliberate, and that safe branch ate the
+recovery whole: every observed kill was the harness reclaiming an idle shell
+and none was a person, so the case it protected against does not occur — while
+the `/spec-reviewed` it charged was paid on every idle review. The deliberate
+stop is the positive signal, so its absence is what a death looks like
+(`.claude/rules/negative-checks.md` rule 1).
 
 **It is bounded by the age of the window, not by a count of retries.** Keep
 re-arming while the window is younger than **12 hours**, then stop. A count means

package/assets/skills/no-spec/SKILL.md

@@ -113,7 +113,9 @@ because writing it means reading the diff, and that spend is the user's call.
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Run the engine's wait in the background, and end your turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <name> --since <the timestamp>

package/assets/skills/spec/SKILL.md

@@ -396,7 +396,9 @@ the verdict — and the reader's conclusion is about what the page showed them.
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Run the engine's wait in the background, and end your turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <spec> --since <the timestamp>

package/assets/skills/spec-bug/SKILL.md

@@ -232,8 +232,9 @@ skitterspec spec-env review arm <spec>
 
 **Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
 than reading a second copy here: note the moment, run
-`skitterspec spec-env review wait <spec> --since <that moment>` in the
-background, end your turn, and let `--claim-since` pick the one pass that
+`skitterspec spec-env review wait <spec> --since <that moment>` under the
+harness's persistent watch primitive where one exists (else in the
+background), end your turn, and let `--claim-since` pick the one pass that
 arrived inside the window. **Do not compose a watcher**, and do not give the
 wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
 The banner it describes is what this skill emits in place of a `Review` row,

package/assets/skills/spec-diff/SKILL.md

@@ -614,7 +614,9 @@ already arrived. Those get the `Review` row, no question, and nothing is owed.
 
 1. **Note the moment**, as an ISO timestamp, before you start. That instant is
    the entire scope of what may be claimed without a person naming it.
-2. **Run the engine's wait in the background, and end the turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <spec> --since <timestamp>

package/assets/skills/spec-next/SKILL.md

@@ -436,7 +436,9 @@ reading — and that is the gap the whole gate exists to close.
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Run the engine's wait in the background, and end your turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <spec> --since <the timestamp>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.1.0",
+  "version": "22.2.0",
   "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -856,9 +856,42 @@ function specEnvNospec(dir, config, name, flags = {}) {
 }
 
 function specEnvUp(dir, config, specArg, flags = {}) {
-  const spec = resolveSpecWithWorktree(dir, config, specArg)
   const docs = flags.docs === true
 
+  // THE AUTHORING LANE — `up <name> --docs` for a spec that is not written yet.
+  // `/spec` provisions BEFORE it writes a line (feat-main-is-a-landing-zone
+  // phase 2), so the name resolves to nothing at exactly the moment this runs.
+  // It opens only on a positive signal, all three parts: the not-found refusal
+  // itself (by code, never by message), `--docs`, and a spec-shaped name — so a
+  // typo'd `up` without the flag, or with a name no spec could have, refuses
+  // exactly as before. Worktree mode only: in checkout mode `/spec` writes
+  // where the session stands and there is nothing to provision first.
+  let spec
+  let authoring = false
+  try {
+    spec = resolveSpecWithWorktree(dir, config, specArg)
+  } catch (err) {
+    const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix)-./.test(specArg)
+    if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
+      throw err
+    }
+    // Record first, then plan — the same order `nospec` keeps, for the same
+    // reason: the record is what makes the name resolvable (a bare `resolve`
+    // in the fresh worktree must name this spec before its folder exists), so
+    // a caller that runs the printed commands must never own a worktree the
+    // engine cannot name. `spec: true` is what makes the record resolve with
+    // the spec's own type and slug rather than as `/no-spec` work.
+    const beforeAuth = readRegistry(dir, config)
+    const resolved = resolveSpecless(specArg, dir, config, { spec: true })
+    writeRegistry(
+      dir,
+      config,
+      recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
+    )
+    spec = resolved
+    authoring = true
+  }
+
   // Checkout mode: the branch is built in the primary checkout, so none of the
   // worktree machinery below applies — no slot, no trust entry and no bootstrap.
   // Handled first precisely so none of that runs by accident.
@@ -898,8 +931,13 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   const upGit = gitReader(dir)
   const upStatus = upGit(['status', '--porcelain'])
   const upDirtyPaths = dirtyPaths(upGit)
-  const upOnFork = specOnForkPoint(dir, upGit, spec)
-  const upSpecUntracked = specIsUntracked(dir, upGit, spec)
+  // An authoring run does not ask whether the spec is on the fork point — it is
+  // known to be nowhere, and that is the healthy state of the lane, not the
+  // "would fork without the spec it is for" refusal. `onFork: undefined` is the
+  // gate's cannot-tell branch, which allows (negative-checks rule 4). The
+  // untracked read is skipped the same way: there is no folder to ask about.
+  const upOnFork = authoring ? { onFork: undefined, foundOn: null } : specOnForkPoint(dir, upGit, spec)
+  const upSpecUntracked = authoring ? false : specIsUntracked(dir, upGit, spec)
 
   // Trust the shared worktree root so edits into the freshly-provisioned worktree
   // don't prompt. One absolute entry (the root) covers every spec; self-heals on
@@ -988,6 +1026,12 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   if (plan.docs) {
     out.push('  docs:      documents only — no setup commands, no docker')
   }
+  // Positive, so an operator reading the plan knows the missing spec folder is
+  // the lane working rather than something the engine failed to find.
+  if (authoring) {
+    out.push('  authoring: no spec document yet — /spec writes it in the worktree')
+    out.push(`  recorded:  added to ${config.registry} until the spec is written`)
+  }
   if (trust.reason === 'malformed') {
     out.push(
       '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +

package/src/env/resolve.js

@@ -488,17 +488,26 @@ function assertPrimaryOnMain(config, git) {
  */
 function resolveSpecless(name, dir, config, entry = {}) {
   const { repo, repoSlug } = repoInfo(dir)
-  const slug = name
+  // AN AUTHORING RECORD RESOLVES AS THE SPEC IT WILL BE. `spec: true` marks a
+  // record written by `up --docs` for a spec not written yet (the `/spec`
+  // authoring lane), so type and slug come from the name's own prefix — the
+  // branch and worktree it answers with MUST equal what the written spec will
+  // later resolve to, or the confirm step lands in one tree and the documents
+  // in another. A plain `/no-spec` record keeps the whole name as its slug,
+  // byte-identical to before.
+  const authored = entry && entry.spec === true
+  const slug = authored ? splitPrefix(name).slug : name
   const tokens = { repo, repoSlug, slug }
   const spec = {
     folder: name,
     bucket: null,
     path: null,
-    type: (entry && entry.type) || 'chore',
+    type: authored ? splitPrefix(name).type : (entry && entry.type) || 'chore',
     slug,
     stack: 'worktree',
     baseRef: null,
     specless: true,
+    unwritten: authored,
   }
   const branch = (entry && entry.branch) || branchFor(spec, config)
   const worktreeRoot = expandTokens(config.worktree.root, tokens)
@@ -532,10 +541,14 @@ function resolveSpec(specArg, dir, config, opts = {}) {
     }
     // 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(
+    // The code is what lets `up --docs` catch exactly this refusal and open the
+    // authoring lane — matching on the message would make its wording API.
+    const err = new Error(
       `spec not found under specs/**: ${specArg} ` +
         `(searched: ${[...preferDirs, dir, ...searchDirs].join(', ')})`,
     )
+    err.code = 'SPEC_NOT_FOUND'
+    throw err
   }
 
   const { type, slug } = splitPrefix(found.folder)
@@ -643,7 +656,14 @@ function allSpecs(dir, config, worktreePaths, specless = {}) {
   // 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.
+  //
+  // A FOLDER SHADOWS ITS OWN RECORD. An authoring record (`up --docs` on an
+  // unwritten spec) shares its name with the folder `/spec` then writes, and
+  // once that folder exists it is the answer — listing the record beside it
+  // would show one spec twice.
+  const collected = new Set(specs.map((s) => s.folder))
   for (const name of Object.keys(specless).sort()) {
+    if (collected.has(name)) continue
     const spec = resolveSpecless(name, dir, config, specless[name])
     specs.push({
       folder: spec.folder,