@skitterbyte/skitterspec-linear 6.0.0 → 7.0.0

package/assets/rules/spec-planning.md

@@ -159,9 +159,11 @@ Every spec is a **folder** `specs/<bucket>/<name>/` — never a bare file, even
 simple changes. Inside it:
 
 - `00-overview.md` is the entry point / dashboard: header, Problem, Decisions,
-  Solution overview, the **phase index** (a table linking to each phase file with
-  its status), Open questions, State log, Changelog. **No per-phase task lists
-  live here.**
+  Solution overview, the **Impact map** (a `Surface | Change | Detail` table
+  naming the concrete surfaces the spec touches — endpoints, schemas, DB tables,
+  domain objects, routes, business rules — as the scannable blast radius), the
+  **phase index** (a table linking to each phase file with its status), Open
+  questions, State log, Changelog. **No per-phase task lists live here.**
 - **One file per phase** — `01-<phase-slug>.md`, `02-<phase-slug>.md`, … in
   execution order. Each holds that phase's goal, its task checkboxes (tests
   included), and any phase-specific notes. Even a single-phase spec gets `01-….md`

package/assets/skills/spec/SKILL.md

@@ -96,6 +96,26 @@ the spec — be specific.>
 <Short prose or bullets describing the chosen shape end-to-end. Optional small
 schema/grammar/output snippets where they remove ambiguity.>
 
+## Impact
+
+<The concrete surfaces this spec touches — the scannable blast radius, so a
+reader can eyeball where the spec got something wrong without reading prose.
+`Change` is `add` · `update` · `remove`. `Surface` is guided-but-open: use
+values like Endpoint, Route/UI, Schema/model, DB table/migration, Domain object,
+Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
+this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
+terse — names/signatures, not sentences. List **only** surfaces that actually
+change; the heading is always present, but if nothing external changes write the
+single line below instead of an empty table.>
+
+| Surface | Change | Detail |
+|---------|--------|--------|
+| <e.g. Endpoint> | add | <e.g. POST /orders> |
+| <e.g. DB> | update | <e.g. orders (+status col)> |
+
+<_No external surface changes — internal refactor only._ — use this line in
+place of the table when the spec touches no external surface.>
+
 ## Phases
 
 Each phase lives in its own file in this folder. Status: ⬜ not started ·
@@ -163,6 +183,13 @@ Rules for the spec body:
   phase index.
 - **Honour project conventions** when writing tasks — reference the relevant
   `.claude/rules/*.md` rather than re-explaining them.
+- **The `## Impact` table is derived from Phase A items 3 (Affected areas) & 5
+  (Data/API impact)** — a structured place to record what those already surface,
+  not new grilling. It is the scannable substitute for spelling impact out in
+  prose: name the surfaces (endpoints, schemas, DB tables, domain objects,
+  routes, business rules) instead of describing them, keep `Detail` terse, and
+  let it — not paragraphs — carry the blast radius. It complements the `Area:`
+  header (files) by naming behavioural surfaces.
 - **Changelog** is mandatory and lives in the spec. Every later decision or
   course-correction gets a dated one-line entry. Convert relative dates to
   absolute.

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

@@ -120,6 +120,26 @@ because work is already underway. Keep it lean:
       commands — confirm no regressions.
 - [ ] <any follow-up hardening, or "None">
 
+## Impact
+
+<The concrete surfaces this spec touches — the scannable blast radius, so a
+reader can eyeball where the spec got something wrong without reading prose.
+`Change` is `add` · `update` · `remove`. `Surface` is guided-but-open: use
+values like Endpoint, Route/UI, Schema/model, DB table/migration, Domain object,
+Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
+this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
+terse — names/signatures, not sentences. List **only** surfaces that actually
+change; the heading is always present, but if nothing external changes write the
+single line below instead of an empty table. A bug fix often changes no external
+surface — that's fine, use the one-liner.>
+
+| Surface | Change | Detail |
+|---------|--------|--------|
+| <e.g. Endpoint> | update | <e.g. GET /orders (fix null total)> |
+
+<_No external surface changes — internal refactor only._ — use this line in
+place of the table when the spec touches no external surface.>
+
 ## State log
 
 | Date | Status | Folder | By |

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

@@ -101,6 +101,16 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
    the normal landing plan. Commit any live fixes to the branch first; it refuses
    if the primary checkout is dirty, or if a *different* spec holds it (release that
    one with `/spec-live main`). Teardown (step 7) is unchanged.
+   **Work-loss abort.** Before it ends the live session, `integrate` checks the
+   work is actually landable and **aborts loudly** rather than finalize a spec
+   having landed nothing. Two cases, both leaving the live session intact:
+   - *stranded commits* — commits sit on the worktree's **detached HEAD** (e.g. a
+     pre-fix `/spec-go` committed there instead of on the branch). It prints the
+     count, the sha, and a `git -C <worktree> branch <tmp> <sha>` recovery hint —
+     recover those commits onto the branch, then re-run.
+   - *no worktree* — the spec is live but its worktree is gone. Re-isolate it with
+     `skitterspec spec-env up <name>`, then re-run.
+   Relay the diagnostic to the user and **stop** — do not proceed to teardown.
 2. **Plan + execute.** Run `skitterspec spec-env integrate <name>` and run the
    printed commands **in order**:
    - `git -C <worktree> rebase <base>` — replay the branch onto base.

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

@@ -22,9 +22,24 @@ Diverting your browser to the spec is a separate explicit step — `/spec-connec
 
 ## 2. Move it into development
 
-**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists) and
-the spec doesn't already have a worktree, provision it **first**, so all the
-housekeeping below lands on the spec's branch and never on `main`:
+**Live check first (isolation only).** If per-spec isolation is enabled, before
+provisioning run `skitterspec spec-env live status <name>` and read its `live:`
+line. If it says **`live: yes`**, this spec is already checked out in the
+**primary checkout** (you took it live with `/spec-live`) — **do not provision,
+do not run `spec-env up`, and do not "work in the worktree"**. Its branch lives
+in the primary checkout and its worktree is on a **detached HEAD**, so a commit
+made in the worktree would strand on that detached HEAD and never reach the
+branch. Instead skip the provisioning bullets and step 2b, leave the spec where
+it is, and go straight to **step 4**, implementing the phase **in the primary
+checkout on the branch** — edits and commits there advance the branch, and
+`/spec-complete` lands them. (`spec-env up` refuses while live and says the same.
+To return to an isolated worktree instead, run `/spec-live main` first, then
+re-run `/spec-go`.)
+
+**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists), the
+spec **isn't already live** (the check above), and it doesn't already have a
+worktree, provision it **first**, so all the housekeeping below lands on the
+spec's branch and never on `main`:
 
 **Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
 place), skip the provisioning bullets below and build on the current branch — the

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

@@ -115,6 +115,26 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
       commands — confirm no regressions.
 - [ ] <any follow-up hardening, or "None">
 
+## Impact
+
+<The concrete surfaces this spec touches — the scannable blast radius, so a
+reader can eyeball where the spec got something wrong without reading prose.
+`Change` is `add` · `update` · `remove`. `Surface` is guided-but-open: use
+values like Endpoint, Route/UI, Schema/model, DB table/migration, Domain object,
+Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
+this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
+terse — names/signatures, not sentences. List **only** surfaces that actually
+change; the heading is always present, but if nothing external changes write the
+single line below instead of an empty table. A hotfix should be minimal — often
+no external surface changes; that's fine, use the one-liner.>
+
+| Surface | Change | Detail |
+|---------|--------|--------|
+| <e.g. Endpoint> | update | <e.g. GET /orders (fix null total)> |
+
+<_No external surface changes — internal refactor only._ — use this line in
+place of the table when the spec touches no external surface.>
+
 ## Landing
 
 - [ ] Deploy tag (patch bump of the base version) created at `/spec-complete`

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

@@ -26,6 +26,13 @@ trust the spec's own wording — verify:
 - **Referenced things still exist.** Grep/read for each `file:line`, module,
   function, route, model, type, or symbol the spec names. Flag anything renamed,
   moved, or deleted.
+- **Impact map matches reality.** Walk every row of the `## Impact` table and
+  verify against the code: does the named surface (endpoint, schema/model, DB
+  table/migration, domain object, route, business rule) exist, and does its
+  stated `Change` (add/update/remove) still hold? A stale Impact map is the
+  highest-signal drift — each row is a named, checkable surface, so a wrong row
+  is exactly the "obvious mistake" the map exists to surface. Flag/refresh stale
+  rows (and add rows for surfaces the spec now touches but omits).
 - **Tasks already done.** For each `- [ ]`, check whether the code already
   implements it (it may have landed via other work). Tick `- [x]` what's done.
 - **Decisions still valid.** Re-check each `## Decisions` entry against the
@@ -47,9 +54,9 @@ reading the code, do that instead of asking.
 
 ## 4. Update the spec
 
-- Rewrite stale **Decisions** / **Solution overview** in `00-overview.md` and
-  stale **tasks** in the phase files so they match the current code and the
-  resolved questions. Add/remove tasks within a phase file; add a new phase by
+- Rewrite stale **Decisions** / **Solution overview** and refresh the **Impact
+  map** in `00-overview.md`, and stale **tasks** in the phase files, so they
+  match the current code and the resolved questions. Add/remove tasks within a phase file; add a new phase by
   creating a `0N-<slug>.md` file **and** a matching overview index row, or drop a
   dead phase by removing both. Keep the index and files in sync; **preserve
   completed `[x]` history**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "Spec-driven development for Claude Code, with Linear hybrid-sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus git-like /spec-status · /spec-pull · /spec-push and the spec-sync CLI. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -185,6 +185,19 @@ function specEnvUp(dir, config, specArg) {
   }
   const spec = resolveSpec(specArg, dir, config)
 
+  // Live-safe: if this spec is already live on the primary checkout (its branch was
+  // branch-switched in by `live take`), a `git worktree add` would fail — the branch
+  // is checked out there. Point the operator at the primary checkout rather than
+  // emit a plan that can't run (see spec feat-live-spec-flow).
+  const primaryUp = assertPrimaryOnMain(config, gitReader(dir))
+  if (!primaryUp.onBase && primaryUp.branch === spec.branch) {
+    process.stdout.write(
+      `spec-env up: ${spec.folder} is live in the primary checkout — work there directly ` +
+        '(its branch is checked out), or run `/spec-live main` first to re-isolate its worktree.\n',
+    )
+    return
+  }
+
   // 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
   // every provision for teammates who only cloned and ran /spec-go.
@@ -567,6 +580,33 @@ function specEnvIntegrate(dir, config, specArg) {
       )
       return
     }
+    // Work-loss guard — runs BEFORE the destructive `checkout base` that ends the
+    // live session. Ending the session must leave landable work behind; if it
+    // wouldn't, abort loudly instead of silently finalizing the spec with nothing
+    // landed (see spec feat-live-spec-flow).
+    if (!fs.existsSync(spec.worktreePath)) {
+      process.stdout.write(
+        `spec-env integrate: blocked — ${spec.folder} is live but has no worktree to land ` +
+          `from. Re-isolate it with \`skitterspec spec-env up ${spec.folder}\`, then re-run.\n`,
+      )
+      return
+    }
+    const liveWtGit = gitReader(spec.worktreePath)
+    if (liveWtGit(['symbolic-ref', '--short', 'HEAD']) === null) {
+      // Detached worktree HEAD: any commits ahead of the branch ref (e.g. made by a
+      // non-live-aware /spec-go) would be abandoned by the re-isolate `switch` below.
+      const stranded = liveWtGit(['rev-list', '--count', `${spec.branch}..HEAD`])
+      const head = liveWtGit(['rev-parse', '--short', 'HEAD'])
+      if (stranded !== null && Number(stranded) > 0) {
+        process.stdout.write(
+          `spec-env integrate: blocked — ${stranded} commit(s) are stranded on the detached ` +
+            `HEAD of ${spec.worktreePath} (at ${head}), ahead of ${spec.branch}; re-isolating ` +
+            `would abandon them. Recover with \`git -C ${spec.worktreePath} branch <tmp> ${head}\`, ` +
+            `reconcile onto ${spec.branch}, then re-run.\n`,
+        )
+        return
+      }
+    }
     const co = runGit(dir, ['checkout', base])
     if (!co.ok) {
       process.stdout.write(`spec-env integrate: could not check out ${base} — ${co.err}\n`)
@@ -912,7 +952,7 @@ async function specEnvLive(dir, config, positional) {
   const action = positional[0] || 'status'
   switch (action) {
     case 'status':
-      specEnvLiveStatus(dir, config)
+      specEnvLiveStatus(dir, config, positional[1])
       break
     case 'take':
       await specEnvLiveTake(dir, config, positional[1])
@@ -1146,8 +1186,28 @@ async function specEnvLiveAbort(dir, config) {
   )
 }
 
-function specEnvLiveStatus(dir, config) {
+function specEnvLiveStatus(dir, config, specArg) {
   const { onBase, branch, baseBranch } = assertPrimaryOnMain(config, gitReader(dir))
+
+  // Per-spec query (`live status <spec>`): a clear yes/no verdict the /spec-go
+  // skill branches on to decide whether to skip worktree provisioning and work in
+  // the primary checkout. The stable `live:      yes|no` line is the machine seam.
+  if (specArg) {
+    const spec = resolveSpecWithWorktree(dir, config, specArg)
+    const live = !onBase && branch === spec.branch
+    process.stdout.write(
+      `spec-env live status: ${spec.folder}\n` +
+        `  spec:      ${spec.folder}  (branch ${spec.branch})\n` +
+        `  primary:   ${branch || '(detached)'}\n` +
+        `  live:      ${
+          live
+            ? `yes — ${spec.folder} holds the primary checkout; work there`
+            : `no — primary is on ${branch || '(detached)'}`
+        }\n`,
+    )
+    return
+  }
+
   const receipt = readReceipt(dir, config)
   const state = onBase
     ? 'on base — free'