@skitterbyte/skitterspec 16.5.2 → 16.7.0

package/assets/rules/negative-checks.md

@@ -0,0 +1,69 @@
+# Checks That Accuse
+
+A check **accuses** when being wrong costs something: it deletes, it exits
+non-zero, or it tells the user their code is broken. Those checks earn the four
+rules below. An ordinary conditional does not — this is about the ones that act
+on what they conclude.
+
+Almost every accusation begins as an **absence**: a name not in a list, a
+directory not on disk, a version not in a response. An absence is evidence only
+once you have established that the lookup could have seen the thing. Three
+times in one day, in unrelated code, we established nothing and acted anyway:
+
+| Absence observed | Concluded | What had blinded the lookup |
+|------------------|-----------|-----------------------------|
+| ref not in the issue list | "it does not exist" | the query excluded archived issues, and capped at 250 |
+| version not in the registry's list | "the publish failed" | the registry is eventually consistent |
+| lifecycle folder not on disk | "half-installed" | git does not store an empty directory |
+
+The bills: 146 healthy refs accused, a valid release tag deleted, a non-zero
+exit on a healthy repo. Each blind spot was knowable in advance.
+
+## 1. Prefer a positive signal to an absence
+
+Assert something that must be **present**, not something that must not be
+missing. A positive signal fails loudly when you are wrong about it; an absence
+fails silently whenever the lookup was narrower than you assumed.
+
+The scaffold check above stopped asking "is the lifecycle folder there?" — a
+folder git drops as soon as it empties — and started asking whether the config
+folder the installer always writes into is there. Same intent, and the new
+question has an answer.
+
+Where no positive signal exists, widen the lookup until absence means
+something (include the archived rows, ask the API for the one id rather than
+scanning a page) — or do not conclude.
+
+## 2. Name the blind spot beside the check
+
+A comment naming what could make this lookup lie is what makes the next reader
+check it. Not what the code does — what would fool it:
+
+```js
+// A LIFECYCLE FOLDER IS NOT CHECKED, deliberately. git does not track empty
+// directories, so it disappears whenever the bucket empties and returns the
+// moment something lands in it.
+```
+
+Write it when you write the check, while you still know why it is safe.
+
+## 3. Pair every accusation with a stays-silent test
+
+For each accusing check, a test that feeds it a **healthy but unusual** input
+and asserts it says nothing: the empty bucket, the archived record, the
+just-published version, the file the user edited on purpose. The positive test
+proves the check can fire; only this one proves it does not fire at everyone
+else. All three incidents would have been caught by it, and prose alone had
+already failed to prevent them.
+
+## 4. Bias the unknown case toward inaction
+
+Three states, not two: yes, no, and *cannot tell*. Route the third to the
+harmless branch — skip, warn, keep, retry — never to the destructive one.
+
+The install manifest classifies a file whose hash it does not recognise as
+`customized` rather than stale, so a resync **keeps** it (`managedState`,
+`packages/common/src/init.js`). An unrecognised hash could mean a user's edit or
+a lost manifest; only one of those readings is safe to act on, so it takes that
+one. Being wrong there costs a redundant file on disk. The opposite default
+costs the user their work.

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

@@ -173,6 +173,13 @@ test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
 `00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
 Say so explicitly — don't fake green.
 
+**Then refresh the mirror (only if a provider is installed).** The Fix tasks are
+ticked, so the repo is now the truth about this fix — and this skill can take a
+bug all the way to green without `/spec-go` ever running. Without a provider this
+is a no-op.
+
+
+
 ## 6. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test

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

@@ -139,20 +139,20 @@ Before writing any code for this phase, get the workspace clean:
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
 
-## 3b. Sync with the tracker (only if a provider is installed)
-
-**Only when a ticketing provider is installed** and the spec is linked to the
-tracker. Otherwise skip this step — no provider means zero change to the flow
-below. Follow the provider's steps below (nothing to do here without one).
-
-
-
 ## 4. Implement the phase
 
 Identify the **first unfinished phase** from the `00-overview.md` phase index,
 then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
 started: set the phase-file heading to `🔄` and its `> **Status:**` to
 `In progress`, and flip the matching row in the overview phase index to `🔄`.
+
+**Then sync with the tracker (only if a provider is installed).** The phase has
+just changed state, so refresh the mirror before the build starts — that is what
+makes the phase show as in progress *while* it is being built rather than only
+once it is over. Without a provider this is a no-op and nothing below changes.
+
+
+
 Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
 
 - Work task by task through the phase file. Make focused edits that match
@@ -175,6 +175,12 @@ Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.m
 - If new work surfaced, add it as tasks to the appropriate phase file (or add a
   new phase file + index row) rather than doing it silently.
 
+**Then refresh the mirror (only if a provider is installed).** The phase is done
+in the repo now; leaving the tracker to catch up at `/spec-complete` is what makes
+a mirror lag a whole spec behind. Without a provider this is a no-op.
+
+
+
 ## 6. Report
 
 Summarise what was implemented, the test result (quote failures if any), and

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

@@ -180,6 +180,13 @@ narrative and decisions).
 - Commit the fix to the `hotfix/<slug>` branch (this commit is what gets tagged
   and cherry-picked). Tick the Fix tasks; add a Changelog line.
 
+**Then refresh the mirror (only if a provider is installed).** The Fix tasks are
+ticked, so the repo is now the truth about this fix — and this skill can take a
+bug all the way to green without `/spec-go` ever running. Without a provider this
+is a no-op.
+
+
+
 ## 7. Report
 
 Summarise: the base tag, root cause, the failing→passing test, the fix, and the

package/package.json

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

package/src/init.js

@@ -406,6 +406,11 @@ function installClaudeMd(dir, { mode }) {
 
 // True when the repo looks already set up: any managed file present, any spec
 // lifecycle folder, or the CLAUDE.md spec marker (Decision 1 — detect eagerly).
+// Is skitterspec already installed here? Matched on what we ACTUALLY install —
+// our managed files, our lifecycle folders, our CLAUDE.md marker — never on
+// `.claude/` merely existing: someone else's skills are not evidence of ours,
+// and reading them as ours would treat every Claude Code project as a
+// half-finished install.
 function isExistingSetup(dir) {
   if (managedTargets(dir).some((t) => fs.existsSync(t.abs))) return true
   if (SPEC_FOLDERS.some((f) => fs.existsSync(path.join(dir, 'specs', f)))) return true