@skitterbyte/skitterspec 22.3.1 → 22.3.2

package/assets/review/page.html

@@ -1044,10 +1044,43 @@ a.ticket:hover { border-color: var(--accent); }
     return bands
   }
 
+  // --- one order, for both columns -----------------------------------------
+  // The sidebar and the panes are two views of one list, and they must be the
+  // SAME list in the same order — a reader scrolling the panes watches the
+  // current-file mark walk the sidebar, and a mark that walks backwards is the
+  // whole reason this exists.
+  //
+  // The emitted order cannot be it. `review.js` collects tracked changes and
+  // untracked files in two passes, so a new file is appended after everything
+  // else however its path sorts; git's own order is not the tree's either.
+  //
+  // So the tree's order is the one order, settled here and used by both. It is
+  // expressed as a comparator rather than derived from the built tree because
+  // the panes are built long before the tree is, and a second traversal that
+  // had to agree with the first is the thing that went wrong.
+  function treeOrder(a, b) {
+    var A = a.split('/')
+    var B = b.split('/')
+    var n = Math.min(A.length, B.length)
+    for (var i = 0; i < n; i++) {
+      // A segment with anything after it is a directory. `renderTree` walks
+      // every directory at a level — label and subtree — before that level's
+      // files, so a directory sorts ahead of a file it ties with by name.
+      var aDir = i < A.length - 1
+      var bDir = i < B.length - 1
+      if (aDir !== bDir) return aDir ? -1 : 1
+      if (A[i] !== B[i]) return A[i].localeCompare(B[i])
+    }
+    return 0
+  }
+
+  // A copy: `data` is the emitted review, and the page is a view of it.
+  var files = data.files.slice().sort(function (a, b) { return treeOrder(a.path, b.path) })
+
   // --- per-file page state -------------------------------------------------
   // Band state lives HERE, never in the emitted data: the page is a view of an
   // immutable review, and expanding context is a property of this reading of it.
-  var state = data.files.map(function (f) {
+  var state = files.map(function (f) {
     var rows = parsePatch(f.patch)
     var st = {
       file: f,
@@ -1717,7 +1750,16 @@ a.ticket:hover { border-color: var(--accent); }
   function renderTree(node) {
     var ul = el('ul')
     ;(function walk(n, depth) {
-      Object.keys(n.dirs).sort().forEach(function (name) {
+      // `treeOrder` above is the authority and these two sorts must match it,
+      // which is why the directories sort by `localeCompare` rather than by the
+      // default `.sort()`: that compares UTF-16 code units, so it puts every
+      // capitalised name ahead of every lowercase one and the panes would drift
+      // from the sidebar again on the first `README/` in a diff.
+      //
+      // Insertion order would be free — the list arrives sorted — but a key
+      // that looks like an array index (`2024/`) is enumerated first whatever
+      // order it was inserted in, and a dated directory is not exotic.
+      Object.keys(n.dirs).sort(function (a, b) { return a.localeCompare(b) }).forEach(function (name) {
         var li = el('li')
         li.appendChild(indent(el('span', 'dir', name + '/'), depth, 0.6))
         ul.appendChild(li)
@@ -1750,9 +1792,9 @@ a.ticket:hover { border-color: var(--accent); }
   }
 
   var tree = document.getElementById('tree')
-  tree.appendChild(renderTree(buildTree(data.files)))
+  tree.appendChild(renderTree(buildTree(files)))
   document.getElementById('tree-summary').textContent =
-    'Files (' + data.files.length + ')'
+    'Files (' + files.length + ')'
   if (window.matchMedia && !window.matchMedia('(min-width: 60rem)').matches) {
     document.getElementById('tree-wrap').open = false
   }

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

@@ -47,21 +47,49 @@ bug's **own branch**, never directly on `main`. Provision the worktree **now**,
 before the failing test, so the test, the fix, and the spec all land together and
 arrive as one reviewable PR.
 
-The engine resolves a spec by its folder, so seed a **minimal stub** for it to
-provision from — you'll flesh it out in §4:
-
-- From the base branch (`main`), create
-  `specs/in-progress/bug-<name>/00-overview.md` with just the header block and the
-  `## Symptom` you established above.
-- Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
-  the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
-  the worktree path, and any `in the worktree, run:` bootstrap steps.
-- Run the printed commands in order. The plan **commits the stub first** — the
-  worktree forks from `main`'s last commit, so the stub has to be in it — and
-  then adds the worktree. Nothing to move afterwards: the spec is already there.
-  The commit is planned, not silent; it appears in the printed plan above the
-  `git worktree add`, and `spec-env up` refuses outright if anything *other* than
-  this spec is uncommitted.
+**Provision before you write, not after.** §1 put nothing on disk and the bug's
+name is settled by the end of it, so this is the one moment where a worktree
+costs nothing to obtain and everything — the red test, the fix, the spec — is
+still ahead of it:
+
+```
+skitterspec spec-env up bug-<name> --docs
+```
+
+**The spec does not exist yet, and that is the lane.** `up` opens its authoring
+branch on exactly three signals — a spec it could not find, `--docs`, and a name
+shaped `bug-<something>` — records the branch so the name resolves from here on,
+and prints a `git worktree add … -b bug/<name>` forked from `main`. Run what it
+prints, then move this session into the worktree with a plain `cd`; the Bash
+working directory persists between calls, so from here on the test, the fix and
+the spec are all written on the bug's own branch. Confirm the move landed rather
+than reading silence as success (`.claude/rules/negative-checks.md` rule 1):
+`skitterspec spec-env resolve` with no argument must name this spec. If it does
+not, say so and stop rather than writing into a tree you cannot name.
+
+**Then run `up` again, without the flag:**
+
+```
+skitterspec spec-env up bug-<name>
+```
+
+`--docs` skips the `setup` commands — everything whose only purpose is making a
+tree *runnable* — because provisioning somewhere to write markdown should cost a
+`git worktree add` and nothing else. `/spec` leaves them to `/spec-start`, but
+**there is no `/spec-start` in a bug's life**: §3 runs the project's suite three
+steps from here, in this same tree, and
+**a tree that cannot run the suite cannot go red**.
+The flagless re-run re-attaches the worktree that now exists
+(no second `-b` fork) and prints the bootstrap steps the flag deferred.
+
+**Why the stub is no longer seeded on the base branch.** This step used to open
+by writing `specs/in-progress/bug-<name>/00-overview.md` in the primary checkout
+for the engine to resolve, and `main` is where work **lands**, not where it
+happens: where the project installs `.claude/hooks/main-guard.cjs` that write is
+refused, and the skill's documented first instruction becomes the one thing the
+repo will not do. Nothing is seeded and nothing is moved now — the spec is
+written in the worktree, at §4, on the branch it belongs to.
+
 - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
@@ -71,9 +99,10 @@ provision from — you'll flesh it out in §4:
   — run `/add-dir <trusted root>` before editing into the worktree, or the first
   edits will prompt.
 - **Do everything below in the worktree**, on the branch — the red test, the fix,
-  and the rest of the spec. Act on the worktree with absolute paths /
-  `git -C <worktreePath>`, or open a session rooted at the printed path. `main`
-  changes only when the branch merges (at `/spec-complete`).
+  and the rest of the spec. The `cd` above is what makes that the default rather
+  than something to remember; where a step has to reach out of the tree, use an
+  absolute path or `git -C <worktreePath>`. `main` changes only when the branch
+  merges (at `/spec-complete`).
 
 ## 3. Write the failing test FIRST (RED) — mandatory
 
@@ -89,8 +118,10 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
 
 ## 4. Write the Bug spec
 
-Fill in the spec's entry point `00-overview.md`. **When isolated**, you already
-seeded this stub in §2 and moved it into the worktree — flesh it out there.
+Write the spec's entry point `00-overview.md`. **When isolated**, you are already
+standing in this spec's own worktree — §2 provisioned it and moved you there, so
+create the folder and write it here, on the bug's branch. Nothing was seeded
+ahead of it and nothing is moved across.
 **When not isolated**, create the spec **folder**
 `specs/in-progress/bug-<kebab-name>/` with its entry point `00-overview.md` now
 (every spec is a folder — never a bare file). A bug is

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

@@ -55,39 +55,69 @@ Hotfixes are concrete — confirm, don't over-grill. Establish:
 - **Root cause:** read the code **at the base tag** and trace it to `file:line`.
   The fix belongs on the tag's line, so reason about that code, not `main`'s.
 
-## 3. Seed the stub, then provision the worktree from the tag
-
-The engine forks the worktree from the spec's `Base version`, so the stub — with
-that header — must exist **before** `spec-env up`:
-
-- From the base branch (`main`), create
-  `specs/in-progress/hotfix-<name>/00-overview.md` with the header block
-  (including `> **Type:** Hotfix` and `> **Base version:** <tag>`) and the
-  `## Symptom` you established. It starts in `in-progress` — work begins now.
-- Run `skitterspec spec-env up hotfix-<name>`. It prints a `git worktree add …
-  -b hotfix/<slug> <tag>` command (the branch forks from **the tag**, not
-  `main`), the worktree path, and any `in the worktree, run:` bootstrap steps.
-- Run the printed `git worktree add`, then **move the stub across yourself.**
-  This is where a hotfix differs from `/spec-bug`, which no longer needs the move:
-  that skill's worktree forks from `main`, so committing the stub puts it there,
-  while **this worktree is checked out at the tag** — a commit on `main` is not in
-  it and never will be. The move is not redundant here; keep it.
-  **Create the destination bucket first:**
-
-  ```
-  mkdir -p <worktreePath>/specs/in-progress
-  mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/
-  ```
-
-  The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
-  `specs/in-progress/` is **absent** from the worktree whenever nothing was in
-  progress at that point in history — and here that point is an
-  **old release tag**, where it is absent more often than not. `mv` into a
-  missing destination renames your spec folder **to** `specs/in-progress`,
-  silently: the spec's files end up one level too high, `00-overview.md` sits
-  where the bucket should be, and every later step still appears to work until
-  something cannot find the spec. Confirm the result before carrying on — you
-  want `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`. - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+## 3. Provision the worktree from the tag, then write in it
+
+**Provision before you write, not after.** §1 settled the tag and the name and
+§2 put nothing on disk, so this is the one moment where a worktree costs nothing
+to obtain and everything — the red test, the fix, the spec — is still ahead of
+it:
+
+```
+skitterspec spec-env up hotfix-<name> --docs --from <tag>
+```
+
+**`--from` is how the tag reaches the engine, and it is not the header twice.**
+Everywhere else `up` forks a hotfix from the spec's own
+`> **Base version:**` line — but here the spec that would carry it does not
+exist yet, which is the whole of what this lane is for. Without the flag the
+branch would fork from `main`: the fix gets written against code prod is not
+running, while the tag and the cherry-pick downstream go on believing it is on
+the release line, and nothing says otherwise until someone asks why the patch
+did not take. The engine refuses a ref git does not know rather than forking
+from somewhere else quietly; where git cannot answer at all it passes the ref
+through to `git worktree add`, which refuses far more loudly than a planner
+guessing from an absence.
+
+Run what it prints — the `git worktree add … -b hotfix/<slug> <tag>` is checked
+out **at the tag**, not at `main` — then move this session into the worktree
+with a plain `cd`; the Bash working directory persists between calls, so from
+here on the test, the fix and the spec are all written on the hotfix's own
+branch. Confirm the move landed rather than reading silence as success
+(`.claude/rules/negative-checks.md` rule 1): `skitterspec spec-env resolve` with
+no argument must name this spec. If it does not, say so and stop rather than
+writing into a tree you cannot name.
+
+**Then run `up` again, without the flags:**
+
+```
+skitterspec spec-env up hotfix-<name>
+```
+
+`--docs` skips the `setup` commands — everything whose only purpose is making a
+tree *runnable* — because provisioning somewhere to write markdown should cost a
+`git worktree add` and nothing else. A hotfix has no `/spec-start` to leave them
+to: §4 runs the project's suite in this same tree, and
+**a tree that cannot run the suite cannot go red**.
+The flagless re-run re-attaches the worktree that now exists (no second `-b`
+fork, and no fork point — the branch is already on the tag's line) and prints
+the bootstrap steps the flag deferred.
+
+**Why nothing is seeded on the base branch, and nothing is moved.** This step
+used to write `specs/in-progress/hotfix-<name>/00-overview.md` in the primary
+checkout for the engine to resolve, and then `mv` the folder across into a
+worktree checked out at a tag — a move with a hazard paragraph of its own, since
+`specs/in-progress/` is usually absent at an old release tag. Both halves are
+gone. `main` is where work **lands**, not where it happens: where the project
+installs `.claude/hooks/main-guard.cjs` that first write is refused outright,
+and a step whose documented opening the repo will not perform is not a step. The
+spec is written in the worktree at §5, on the branch it belongs to.
+
+**§5 records the same tag you passed to `--from`**, on the spec's
+`> **Base version:**` header. That is not bookkeeping: `/spec-complete` tags the
+new patch and cherry-picks off the header, so a worktree forked from one ref and
+a header naming another is this whole bug again with the halves swapped.
+
+- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
   anything else.
@@ -96,8 +126,9 @@ that header — must exist **before** `spec-env up`:
   — run `/add-dir <trusted root>` before editing into the worktree, or the first
   edits will prompt.
 - **Do everything below in the worktree**, on the `hotfix/<slug>` branch — the red
-  test, the fix, and the rest of the spec. Act with absolute paths /
-  `git -C <worktreePath>`, or open a fresh session rooted there. `main` changes
+  test, the fix, and the rest of the spec. The `cd` above is what makes that the
+  default rather than something to remember; where a step has to reach out of
+  the tree, use an absolute path or `git -C <worktreePath>`. `main` changes
   only at `/spec-complete` (via cherry-pick, not merge).
 
 ## 4. Write the failing test FIRST (RED) — mandatory
@@ -114,7 +145,8 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
 
 ## 5. Write the Hotfix spec
 
-Flesh out `00-overview.md` in the worktree (you seeded the stub in §3). A hotfix
+Write `00-overview.md` in the worktree — §3 provisioned it at the tag and moved
+you there, so create the folder and write it here. A hotfix
 is usually a single-pass fix, so the `## Fix` block can live directly in
 `00-overview.md`. Keep it lean:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.3.1",
+  "version": "22.3.2",
   "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

@@ -863,6 +863,9 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   // 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.
+  // `/spec-bug` takes the same lane and then re-runs `up` WITHOUT the flag for
+  // the `setup` commands it skipped — it has no `/spec-start` to defer them to,
+  // and its next step runs the suite in that tree.
   // 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
@@ -883,6 +886,19 @@ function specEnvUp(dir, config, specArg, flags = {}) {
     // 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.
+    // `--from <ref>` is the fork point for a spec whose own header cannot yet
+    // supply one. `/spec-hotfix` is the caller: its worktree belongs on the
+    // released line, and `> **Base version:**` is written INSIDE that tree.
+    // Everywhere else `spec.baseRef` comes off the spec and stays the
+    // authority — which is why passing this to a spec that resolves refuses
+    // below rather than quietly losing to the header.
+    if (flags.from !== undefined) {
+      const bad = badForkRef(dir, flags.from)
+      if (bad) {
+        process.stdout.write(bad)
+        return
+      }
+    }
     const beforeAuth = readRegistry(dir, config)
     const resolved = resolveSpecless(specArg, dir, config, { spec: true })
     writeRegistry(
@@ -891,9 +907,23 @@ function specEnvUp(dir, config, specArg, flags = {}) {
       recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
     )
     spec = resolved
+    if (flags.from !== undefined) spec.baseRef = flags.from
     authoring = true
   }
 
+  // A flag that cannot be honoured is refused, never ignored. The operator
+  // typed a fork point; silently forking from base instead would build a hotfix
+  // against `main`'s code while everything downstream believes it is on the
+  // release line — the exact silent failure this flag exists to prevent.
+  if (flags.from !== undefined && !authoring) {
+    process.stdout.write(
+      `spec-env up: --from applies to a spec that is not written yet. ` +
+        `${specArg} already exists, and its own \`> **Base version:**\` header is ` +
+        'the fork point — edit that instead.\n',
+    )
+    return
+  }
+
   // 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.
@@ -933,13 +963,24 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   const upGit = gitReader(dir)
   const upStatus = upGit(['status', '--porcelain'])
   const upDirtyPaths = dirtyPaths(upGit)
-  // 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)
+  // A spec with no document on disk 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 authoring 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.
+  //
+  // NOT `authoring`, which is only the run that OPENED the lane. The test-first
+  // skills re-run `up` without `--docs` for the setup commands before the spec
+  // is written, and that run resolves — off the registry record the lane left —
+  // so `authoring` is false while `spec.path` is still null. Asking git about a
+  // null path threw, which is a crash rather than a refusal: the condition is
+  // whether there is a document, and it always was.
+  const noDocument = authoring || !spec.path
+  const upOnFork = noDocument
+    ? { onFork: undefined, foundOn: null }
+    : specOnForkPoint(dir, upGit, spec)
+  const upSpecUntracked = noDocument ? 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
@@ -1031,9 +1072,15 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   // 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('  authoring: no spec document yet — the skill writes it in the worktree')
     out.push(`  recorded:  added to ${config.registry} until the spec is written`)
   }
+  // Only where one was NAMED. The fork point is otherwise base HEAD, which is
+  // the unremarkable case, and a line asserting it on every provision would
+  // make the one run that forked from a tag look like every other.
+  if (authoring && flags.from !== undefined) {
+    out.push(`  fork:      ${flags.from}  (the branch forks from here, not from base)`)
+  }
   if (trust.reason === 'malformed') {
     out.push(
       '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +
@@ -1084,6 +1131,38 @@ function speclessMap(dir, config) {
 }
 
 // A read-only git reader over `cwd`: returns trimmed stdout, or null on failure.
+/**
+ * Is `ref` a fork point git will accept? Returns a refusal string, or null.
+ *
+ * THIS IS AN ACCUSATION, so it fires only on a positive signal
+ * (`.claude/rules/negative-checks.md` rule 1). `rev-parse --verify` returning
+ * nothing means one of two very different things — the ref does not exist, or
+ * git could not answer at all — and only the first is evidence. So the control
+ * question is asked first: if git cannot even name its own directory, the ref
+ * is passed straight through and `git worktree add` refuses it far more loudly
+ * than a planner guessing from an absence ever could (rule 4).
+ *
+ * WHAT WOULD FOOL THIS: a ref that exists but is not a commit — an annotated
+ * tag object is peeled by `^{commit}`, so that case is covered, but a blob or
+ * tree ref would be rejected here and rejected by `git worktree add` too. Being
+ * wrong that way costs a refusal on something that could never have worked.
+ */
+function badForkRef(cwd, ref) {
+  const git = gitReader(cwd)
+  if (!ref) {
+    return 'spec-env up: --from needs a ref — the tag or commit to fork from.\n'
+  }
+  // The control question. No repo, no git, an unreadable directory — all land
+  // here, and none of them is evidence about the ref.
+  if (git(['rev-parse', '--git-dir']) === null) return null
+  if (git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]) !== null) return null
+  return (
+    `spec-env up: --from ${ref} — git does not know that ref here, so the ` +
+    'worktree would fork from somewhere else without saying so.\n' +
+    '  check the tag exists (git tag --list), or fetch it first.\n'
+  )
+}
+
 function gitReader(cwd) {
   return (argv) => {
     try {
@@ -5016,6 +5095,7 @@ async function specEnv(rest) {
     else if (args[i] === '--phase') flags.phase = args[++i]
     else if (args[i] === '--record-primary') flags.recordPrimary = true
     else if (args[i] === '--docs') flags.docs = true
+    else if (args[i] === '--from') flags.from = args[++i]
     else if (args[i] === '--session') flags.session = args[++i]
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])