@skitterbyte/skitterspec-linear 19.17.0 → 19.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/MIGRATION.md CHANGED
@@ -1,5 +1,56 @@
1
1
  # Migration guide
2
2
 
3
+ ## A PR-mode finish runs the `afterLand` entries its land matched (nothing to edit)
4
+
5
+ After the host merged a PR, `spec-env integrate` used to print `nothing to
6
+ run` and list every conditional `afterLand` entry under `skipped (nothing in
7
+ the land matched)`, whatever its `when` said. The range it read was the
8
+ branch's own (`origin/main...branch`), and a merged branch is already inside
9
+ `origin/main`, so that range was always empty.
10
+
11
+ The finish now reads what the primary checkout's base gains by catching up
12
+ (`main...origin/main`), so an entry whose glob matches a file in the land
13
+ runs, with `# <path> changed`. Where base was already caught up by hand,
14
+ nothing lies between the two refs. That range is treated as unknown, and the
15
+ conditional entries run with `# range unknown`.
16
+
17
+ Your globs were right: a leading `**/` already matched a top-level path. If
18
+ a PR-mode land skipped an install or a generate, run it by hand in the
19
+ primary checkout once. Later lands run it for you.
20
+
21
+ ## A local install stays local in a worktree (check for stray team files)
22
+
23
+ `update` run inside a worktree of a local install (`init --local`) used to run
24
+ as a **team** install. The manifest that records `"scope": "local"` is kept out
25
+ of git, and `spec-env bootstrap` did not seed it, so the worktree had none.
26
+ That run then:
27
+
28
+ - appended the `<!-- skitterspec:start -->` block to the **tracked**
29
+ `CLAUDE.md`,
30
+ - created an untracked `.claude/settings.json` holding skitterspec's hooks,
31
+ - listed unedited managed files as `customized (kept)`,
32
+ - and wrote the worktree a manifest with no `scope`.
33
+
34
+ Bootstrap now seeds the manifest with the other local-install files. `update`
35
+ also reads a local scope from the `.git/info/exclude` block when a worktree
36
+ has no manifest of its own, so a worktree bootstrapped before this release is
37
+ covered without re-bootstrapping. It reports
38
+ `local install (recorded in .git/info/exclude) — kept local`.
39
+
40
+ **If an earlier `update` already ran in such a worktree, revert it by hand.**
41
+ Nothing removes it for you, because a `CLAUDE.md` edit or a
42
+ `.claude/settings.json` might be yours:
43
+
44
+ ```
45
+ git checkout -- CLAUDE.md # drop the appended block
46
+ rm .claude/settings.json # only if skitterspec created it
47
+ rm specs/.core/.skitterspec-manifest.json # the scopeless one it wrote
48
+ skitterspec spec-env bootstrap <spec> # re-seeds the primary's manifest
49
+ ```
50
+
51
+ Run these in the worktree. A worktree that never ran `update` needs nothing.
52
+
53
+
3
54
  ## The tailnet is `remote`; publishing the review is retired (nothing to edit)
4
55
 
5
56
  The review stack's `remote:` line used to be a claude.ai page the review was
@@ -202,10 +202,13 @@ through to a documented conservative default; see the field notes below.
202
202
  // The changed files are what the land brings into the base branch:
203
203
  // `base...branch` for `integrate` (read before the rebase, so it is the
204
204
  // branch's own changes), and the carried fix commits — minus the release's
205
- // version commit — for `hotfix land`.
205
+ // version commit — for `hotfix land`. A PR-mode finish (the host has
206
+ // merged) reads `base...<remote>/<base>`: what the primary checkout's base
207
+ // gains by catching up, since the landed branch's own range is empty.
206
208
  // When that cannot be known, the conditional entries RUN. That is the
207
209
  // "already landed" plan (the land happened elsewhere, so its range is not
208
- // here) and any diff git would not answer. A redundant generate costs
210
+ // here), a PR-mode finish whose base was already caught up by hand, and
211
+ // any diff git would not answer. A redundant generate costs
209
212
  // seconds; a skipped one leaves the base red with nothing pointing at why.
210
213
  // A land that changed no files is known, not unknown, and skips them.
211
214
  // The plan says why for every entry: a matched one ends in
@@ -460,6 +460,47 @@ work on. A row that cannot be run spends the trust the position was designed to
460
460
  earn — and the two skills that got it wrong got it wrong independently, which is
461
461
  what makes it a missing constraint rather than two slips.
462
462
 
463
+ ### Open manual steps are rows
464
+
465
+ When the next action includes steps only a person can do — a manual test pass,
466
+ a check in the running app — and any are still open, `Next`
467
+ **lists every one of them, one per row**. The label sits on the first row
468
+ only, each step gets a row of its own with the label cell blank, and a closing
469
+ row names what comes after:
470
+
471
+ | | |
472
+ |---|---|
473
+ | **Follow-ups** | none |
474
+ | **Next** | `/spec-live`, then: |
475
+ | | 1. Open Settings → Business Unit Setup |
476
+ | | 2. Pick a business unit with gaps; each process shows ✗ with its gaps |
477
+ | | 3. Set one process up, press **Check again**; its card turns ✓ |
478
+ | | then `/spec-next` to finish phase 5 |
479
+
480
+ **A count is not a list.** `run the seven manual steps` names steps the reader
481
+ cannot see: the list it means is several messages up, or gone after a `/clear`.
482
+ Neither is the phase file's path — that sends the reader out of the terminal to
483
+ find out what to do, which is the failure `/spec-next`'s *Manual steps* exists
484
+ to fix.
485
+
486
+ **Copy them from the phase file, never from an earlier message.** The open
487
+ manual tasks there — and the numbered sub-tasks `/spec-next` writes under a
488
+ vague one — are the record. A run that did not list them (`/commit`,
489
+ `/spec-resume`) reads them there; one that did copies the same text. A
490
+ conversation is not durable, and steps re-made from memory drift from the ones
491
+ the reader was shown.
492
+
493
+ **It applies to every skill's block**, not only `/spec-next`'s. The report this
494
+ was written from came from `/commit`, after `/spec-next` had listed the steps
495
+ and been answered **Not yet**.
496
+
497
+ **It is an amendment, and it is argued from this section's own rule.** It adds
498
+ no row type and nothing after the block — `Next` stays last, and is the same
499
+ single next action, written out. A `Next` that counts steps out of sight is not
500
+ runnable from the state the run leaves behind; one row per step is what makes it
501
+ so, and seven steps in one cell are a paragraph nobody follows. A report with no
502
+ open manual steps keeps its one-row `Next`.
503
+
463
504
  ## Field vocabulary, in this order
464
505
 
465
506
  A skill emits only the fields it declares, in this order, skipping the rest.
@@ -484,7 +525,7 @@ behind it — say nothing rather than reporting that there was nothing to report
484
525
  | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
485
526
  | `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any alternates inline after their tier's URL (`also <url>`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
486
527
  | `Follow-ups` | **Always.** `none`, or one line each. |
487
- | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
528
+ | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. Open manual steps take a row each (*Open manual steps are rows*). |
488
529
 
489
530
  The order runs identity → context → what happened → where it went → what to do.
490
531
  **`Tracker` is first** because the id is what addresses this work outside the
@@ -533,7 +574,8 @@ silence.
533
574
 
534
575
  ## Where the block may grow
535
576
 
536
- One place only. A non-`✅` verdict adds a `Why` row, and quotes the output that
577
+ Two places. `Next` takes a row per open manual step (*Open manual steps are
578
+ rows*, above). And a non-`✅` verdict adds a `Why` row, and quotes the output that
537
579
  justifies it — the failing assertion, the conflict, the engine's refusal — in a
538
580
  fenced block **above** the table, where a fence means what a fence should mean:
539
581
 
@@ -601,6 +643,22 @@ the reasoning.
601
643
  | **Follow-ups** | Session expiry is read from two places; phase 4 leans on one |
602
644
  | **Next** | `/spec-next` → phase 4 (Docs) |
603
645
 
646
+ **`⚠️` — stopped at manual steps answered Not yet.**
647
+
648
+ ⚠️ **Phase 2 code built; manual check open** — `feat-orders`, 2 of 4
649
+
650
+ | | |
651
+ |---|---|
652
+ | **Branch** | `spec/feat-orders` · 3 commits, dirty |
653
+ | **Built** | Order form, POST /orders handler |
654
+ | **Tests** | 131 passed · npm test |
655
+ | **Notes** | Manual check answered **Not yet** — the phase stays `🔄` |
656
+ | **Follow-ups** | none |
657
+ | **Next** | `/commit`, then `/spec-live`, then: |
658
+ | | 1. Place an order with two lines; the confirmation lists both |
659
+ | | 2. Place one with a negative quantity; the form refuses it |
660
+ | | then `/spec-next` to finish phase 2 |
661
+
604
662
  **`⏸` — refused, nothing changed.**
605
663
 
606
664
  ⏸ **`/spec-next` refused — no spec in flight**
@@ -358,6 +358,13 @@ plain markdown list in the conversation — never fenced, and
358
358
  out of the terminal to find out what to do, which is the failure this exists to
359
359
  fix; the steps themselves are what they act on.
360
360
 
361
+ **Steps you had to write are saved first.** When the phase file holds only a
362
+ vague manual task — "check it on the running host" — and you wrote the steps
363
+ yourself, add them under that task as numbered sub-checkboxes **before** you
364
+ ask. The conversation does not survive a `/clear`, and a later run that makes
365
+ up its own set lists different steps from the ones the reader was shown. A
366
+ phase whose manual steps are already tasks is left as it is.
367
+
361
368
  Then ask one question, with three answers:
362
369
 
363
370
  - **All done** — tick those steps and carry on to the end of the phase.
@@ -376,6 +383,8 @@ needs no new shape in the report.
376
383
  tasks after an unconfirmed step are not built past it, and the phase did not
377
384
  end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
378
385
  End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
386
+ Its `Next` lists the open steps a row each, copied from the phase file —
387
+ `.claude/rules/spec-reports.md`, *Open manual steps are rows*.
379
388
 
380
389
  ## 4. Record progress
381
390
 
@@ -717,7 +726,8 @@ the shape; this section carries only what is specific here.
717
726
  - `⚠️` — built and green, with something worth knowing (a mirror that did not
718
727
  refresh, a deviation from the plan) — or stopped at manual steps answered
719
728
  **Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
720
- are open, and `Next` is `/commit, then /spec-next` to pick them up.
729
+ are open, and `Next` is `/commit`, then a row per open step, then
730
+ `/spec-next` to pick them up.
721
731
  - `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
722
732
  - `⏸` — no spec in flight, several in flight with this session in none of
723
733
  them, or the name given does not match the one that is.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.17.0",
3
+ "version": "19.18.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -5,7 +5,7 @@ const path = require('path')
5
5
  const os = require('os')
6
6
  const { pathToFileURL } = require('url')
7
7
  const { execFileSync } = require('child_process')
8
- const { init, resync, reset, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
8
+ const { init, resync, reset, uninstall, disable, enable, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
9
9
  const {
10
10
  detectReleaseTooling,
11
11
  removeReleaseTooling,
@@ -287,6 +287,16 @@ Usage:
287
287
  edits (--force to overwrite). Leaves specs/ + live
288
288
  .core config alone. --check reports what it would
289
289
  change and writes nothing.
290
+ skitterspec uninstall [dir] Take a local install (init --local) back off this
291
+ machine: managed files, hooks, the CLAUDE.local.md
292
+ block, the git excludes. Prints the plan; --yes
293
+ acts. Edited files are kept; specs/ is untouched.
294
+ Refuses a team install, or while a spec is in flight.
295
+ skitterspec disable [dir] Switch a local install off for this machine's
296
+ Claude — skills, commands, rules, hooks, the
297
+ CLAUDE.local.md block — leaving the files on disk.
298
+ skitterspec enable [dir] Switch it back on; installs it (init --local) when
299
+ there is nothing here to switch on.
290
300
  skitterspec spec-env <cmd> Per-spec isolation engine (opt-in; needs
291
301
  specs/.core/env.config.json). Subcommands:
292
302
  up <spec> print the plan to provision a worktree +
@@ -3472,7 +3482,9 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
3472
3482
  // branch's own range — remote image first, local base as the fallback
3473
3483
  // when the remote ref is not here.
3474
3484
  primaryPath: dir,
3475
- changedFiles: landRange(git, `${remote}/${base}`, spec.branch) || landRange(git, base, spec.branch),
3485
+ changedFiles: aheadOfRemoteBase === false
3486
+ ? catchUpRange(git, base, `${remote}/${base}`)
3487
+ : landRange(git, `${remote}/${base}`, spec.branch) || landRange(git, base, spec.branch),
3476
3488
  worktreeState: { dirty },
3477
3489
  base,
3478
3490
  remote,
@@ -3723,6 +3735,21 @@ function landRange(git, base, branch) {
3723
3735
  return out.split('\n').map((l) => l.trim()).filter(Boolean)
3724
3736
  }
3725
3737
 
3738
+ // The range of a PR-mode finish: what local base gains by catching up with the
3739
+ // remote image the host merged into. The branch's own range cannot answer once
3740
+ // it has landed — it is inside `<remote>/<base>`, so `<remote>/<base>...branch`
3741
+ // is empty, and an empty known range skipped every conditional entry
3742
+ // (bug-pr-afterland-range).
3743
+ //
3744
+ // WHAT WOULD FOOL IT: a base already caught up by hand (`git pull`), which
3745
+ // leaves nothing between the two refs while the afterLand those files wanted
3746
+ // never ran. Empty therefore reads as unknown, which runs the conditional
3747
+ // entries (`.claude/rules/negative-checks.md` rule 4).
3748
+ function catchUpRange(git, base, remoteBase) {
3749
+ const range = landRange(git, base, remoteBase)
3750
+ return range && range.length ? range : null
3751
+ }
3752
+
3726
3753
  // The `afterLand` commands, as a section printed after a land plan — or after
3727
3754
  // integrate's already-landed line. Empty string when none apply, so a project
3728
3755
  // without the key sees exactly the output it always has, and one of plain
@@ -8530,6 +8557,36 @@ async function run(argv) {
8530
8557
  resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
8531
8558
  await cleanupReleaseTooling(dir, opts)
8532
8559
  break
8560
+ case 'uninstall': {
8561
+ // What is in flight is read here, where the spec machinery lives, and
8562
+ // handed to the engine: every provisioned worktree (specless ones too)
8563
+ // and a live overlay holding the primary checkout. A read that throws is
8564
+ // cannot-tell, and the engine refuses on it rather than deleting.
8565
+ const inFlight = []
8566
+ let cannotTell = null
8567
+ try {
8568
+ // Anchored as spec-env anchors, so a project in a subfolder of its
8569
+ // repo, or a run from inside a worktree, reads the same registry.
8570
+ const anchor = primaryAnchor(dir, gitReader(dir))
8571
+ const { config } = loadEnvConfig(anchor.dir)
8572
+ attachProject(config, anchor)
8573
+ for (const w of provisionedSpecChoice(anchor.dir, config, anchor.dir, { lastLive: false }).worktrees) {
8574
+ inFlight.push({ spec: w.spec, where: `(worktree ${w.worktree})` })
8575
+ }
8576
+ const receipt = readReceipt(anchor.dir, config)
8577
+ if (receipt && receipt.spec) inFlight.push({ spec: String(receipt.spec), where: '(live in the primary checkout)' })
8578
+ } catch (error) {
8579
+ cannotTell = error.message
8580
+ }
8581
+ process.exitCode = uninstall(dir, { yes: opts.yes, inFlight, cannotTell })
8582
+ break
8583
+ }
8584
+ case 'disable':
8585
+ process.exitCode = disable(dir)
8586
+ break
8587
+ case 'enable':
8588
+ process.exitCode = await enable(dir)
8589
+ break
8533
8590
  default:
8534
8591
  throw new Error(unknownCommand(cmd))
8535
8592
  }
package/src/env/hooks.js CHANGED
@@ -225,12 +225,15 @@ function ensureHooks(dir, { local = false } = {}) {
225
225
  * group left with no hooks is dropped, then an empty `PreToolUse`, then an empty
226
226
  * `hooks`. Every other key — and every other event — is untouched.
227
227
  *
228
+ * `local` reads `settings.local.json` instead, for `uninstall` taking a local
229
+ * install back off; `dryRun` counts what would go and writes nothing.
230
+ *
228
231
  * Returns `{ removed, emptied, reason }`. `emptied` is true when nothing is left
229
232
  * but `{}`: the caller deletes the file then, since a committed `{}` is noise.
230
233
  * A missing file is `absent`; an unparseable one is `malformed` and untouched.
231
234
  */
232
- function removeHooks(dir) {
233
- const file = settingsPath(dir)
235
+ function removeHooks(dir, { local = false, dryRun = false } = {}) {
236
+ const file = settingsPath(dir, { local })
234
237
  let parsed
235
238
  try {
236
239
  parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
@@ -259,7 +262,7 @@ function removeHooks(dir) {
259
262
  else delete parsed.hooks.PreToolUse
260
263
  if (!Object.keys(parsed.hooks).length) delete parsed.hooks
261
264
  const emptied = !Object.keys(parsed).length
262
- if (!emptied) writeSettings(file, parsed)
265
+ if (!emptied && !dryRun) writeSettings(file, parsed)
263
266
  return { removed, emptied, reason: 'removed' }
264
267
  }
265
268
 
package/src/init.js CHANGED
@@ -318,6 +318,7 @@ const report = { created: [], updated: [], skipped: [], refused: [], removed: []
318
318
 
319
319
  function resetReport() {
320
320
  scope = 'team'
321
+ enabledOnFlush = null
321
322
  for (const k of Object.keys(report)) report[k].length = 0
322
323
  for (const k of Object.keys(writtenHashes)) delete writtenHashes[k]
323
324
  }
@@ -424,20 +425,25 @@ function readManifest(dir) {
424
425
  // Absent means team: every manifest written before `--local` existed
425
426
  // reads exactly as it did.
426
427
  scope: parsed.scope === 'local' ? 'local' : 'team',
428
+ // Absent means enabled: only `disable` writes the field.
429
+ enabled: parsed.enabled !== false,
427
430
  }
428
431
  }
429
432
  } catch {
430
433
  /* missing or malformed → empty baseline */
431
434
  }
432
- return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team' }
435
+ return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team', enabled: true }
433
436
  }
434
437
 
435
- function writeManifest(dir, files, { local = false } = {}) {
438
+ function writeManifest(dir, files, { local = false, enabled = true } = {}) {
436
439
  const target = path.join(dir, MANIFEST_FILE)
437
440
  ensureDir(path.dirname(target))
438
441
  const sorted = {}
439
442
  for (const k of Object.keys(files).sort()) sorted[k] = files[k]
440
443
  const body = local ? { version: MANIFEST_VERSION, scope: 'local', files: sorted } : { version: MANIFEST_VERSION, files: sorted }
444
+ // Written only when false, so an enabled install's manifest reads exactly as
445
+ // every manifest written before `disable` existed.
446
+ if (!enabled) body.enabled = false
441
447
  fs.writeFileSync(target, JSON.stringify(body, null, 2) + '\n')
442
448
  }
443
449
 
@@ -499,7 +505,8 @@ function flushManifest(dir) {
499
505
  // env.config.json that installIsolation happens to write through writeFile).
500
506
  const managed = managedTargets(dir)
501
507
  const managedRel = new Set(managed.map((t) => t.relPath))
502
- const merged = { ...readManifest(dir).files, ...writtenHashes }
508
+ const prior = readManifest(dir)
509
+ const merged = { ...prior.files, ...writtenHashes }
503
510
  const next = {}
504
511
  for (const [relPath, hash] of Object.entries(merged)) {
505
512
  if (managedRel.has(relPath)) next[relPath] = hash
@@ -510,9 +517,13 @@ function flushManifest(dir) {
510
517
  for (const relPath of Object.keys(next)) {
511
518
  if (!fs.existsSync(path.join(dir, relPath))) delete next[relPath] // prune gone
512
519
  }
513
- writeManifest(dir, next, { local: scope === 'local' })
520
+ writeManifest(dir, next, { local: scope === 'local', enabled: enabledOnFlush === null ? prior.enabled : enabledOnFlush })
514
521
  }
515
522
 
523
+ // Set by a run that decides the install's switch: `init` turns it on, and
524
+ // `null` keeps whatever the manifest says (`update` on a disabled install).
525
+ let enabledOnFlush = null
526
+
516
527
  function writeFile(dir, target, content, { force }) {
517
528
  // A dangling symlink (its target no longer exists) is invisible to existsSync,
518
529
  // which follows the link — but the link itself is still on disk, so a plain
@@ -1004,8 +1015,14 @@ function resync(dir, { force = false, claudeMd = true, diff = false, local = fal
1004
1015
  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
1005
1016
  // project, while reporting a file created. `init-review-gate-hook.test.js`
1006
1017
  // asserts over the entry points rather than over this call.
1007
- registerReviewGateHook(dir)
1008
- if (claudeMd) installClaudeMd(dir, { mode: 'update' })
1018
+ // A disabled install stays disabled through an update: the files refresh,
1019
+ // and the two things Claude reads from outside them are not written back.
1020
+ const disabled = scope === 'local' && !manifest.enabled
1021
+ if (disabled) report.skipped.push('hooks and CLAUDE.local.md block (disabled — skitterspec enable turns them on)')
1022
+ else {
1023
+ registerReviewGateHook(dir)
1024
+ if (claudeMd) installClaudeMd(dir, { mode: 'update' })
1025
+ }
1009
1026
  suggestReleaseWith(dir)
1010
1027
  flushManifest(dir)
1011
1028
  if (scope === 'local') writeLocalExcludes(dir)
@@ -1205,8 +1222,10 @@ function suggestReleaseWith(dir) {
1205
1222
  // Switching a local install back to team is out of scope and says so.
1206
1223
  function resolveScope(dir, local) {
1207
1224
  const recorded = readManifest(dir).scope
1208
- scope = local || recorded === 'local' ? 'local' : 'team'
1225
+ const excluded = !local && recorded !== 'local' && excludeNamesManifest(dir)
1226
+ scope = local || recorded === 'local' || excluded ? 'local' : 'team'
1209
1227
  if (!local && recorded === 'local') report.skipped.push('local install (recorded in the manifest) — kept local')
1228
+ if (excluded) report.skipped.push('local install (recorded in .git/info/exclude) — kept local')
1210
1229
  if (local && recorded !== 'local') {
1211
1230
  report.warnings.push(
1212
1231
  '--local keeps skitterspec on this machine: teammates get none of its skills, rules ' +
@@ -1243,11 +1262,16 @@ function localExcludes(dir) {
1243
1262
  }
1244
1263
 
1245
1264
  // What `spec-env bootstrap` seeds into a local install's worktrees: the managed
1246
- // paths plus the two per-machine files. A worktree is a fresh checkout, and
1247
- // git carries none of it there. Empty for a team install, which git carries.
1265
+ // paths, the two per-machine files and the manifest. A worktree is a fresh
1266
+ // checkout, and git carries none of it there. Empty for a team install, which
1267
+ // git carries.
1268
+ //
1269
+ // THE MANIFEST IS SEEDED because it is what records the scope: without it a
1270
+ // worktree's `update` read team and wrote the block into the tracked CLAUDE.md
1271
+ // and the hooks into a new .claude/settings.json (bug-local-scope-worktree).
1248
1272
  function localSeedFiles(dir) {
1249
1273
  if (readManifest(dir).scope !== 'local') return []
1250
- return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md']
1274
+ return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md', MANIFEST_FILE.replace(/\\/g, '/')]
1251
1275
  }
1252
1276
 
1253
1277
  const EXCLUDE_START = '# >>> skitterspec (local install)'
@@ -1288,6 +1312,31 @@ function writeLocalExcludes(dir) {
1288
1312
  report.updated.push('.git/info/exclude (skitterspec block)')
1289
1313
  }
1290
1314
 
1315
+ // Whether the shared `.git/info/exclude` block names THIS project's manifest —
1316
+ // the positive signal that a worktree with no manifest of its own belongs to a
1317
+ // local install. The exclude lives in the common dir, so every worktree sees
1318
+ // the block the primary checkout's install wrote; matching the prefixed
1319
+ // manifest path, not the bare block, keeps a second project in the same repo
1320
+ // from being read as local by a neighbour's install.
1321
+ //
1322
+ // WHAT WOULD FOOL IT: a block hand-edited to drop the manifest line, or git
1323
+ // unreachable. Both answer false — the scope the manifest recorded, as before.
1324
+ function excludeNamesManifest(dir) {
1325
+ try {
1326
+ const git = (...args) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
1327
+ const commonDir = path.resolve(dir, git('rev-parse', '--git-common-dir'))
1328
+ const prefix = git('rev-parse', '--show-prefix')
1329
+ const text = fs.readFileSync(path.join(commonDir, 'info', 'exclude'), 'utf8')
1330
+ const start = text.indexOf(EXCLUDE_START)
1331
+ const end = text.indexOf(EXCLUDE_END, start)
1332
+ if (start === -1 || end === -1) return false
1333
+ const entry = `/${prefix}${MANIFEST_FILE.replace(/\\/g, '/')}`
1334
+ return text.slice(start, end).split(/\r?\n/).some((l) => l.trim() === entry)
1335
+ } catch {
1336
+ return false
1337
+ }
1338
+ }
1339
+
1291
1340
  // Convert a COMMITTED (team) install into a local one, in place. Every step
1292
1341
  // leaves the files on disk and stages or edits only; it never commits — the
1293
1342
  // operator commits the removal, and teammates who pull it lose the install.
@@ -1469,11 +1518,360 @@ function hooksAt(read, ref) {
1469
1518
  .filter((h) => h && typeof h.command === 'string' && GATE_HOOKS.some((k) => k.re.test(h.command))).length
1470
1519
  }
1471
1520
 
1521
+ // DISABLE / ENABLE — switch whether this machine's Claude uses a local install,
1522
+ // without touching its files (feat-uninstall-local). Claude Code has no single
1523
+ // switch covering skills, commands, rules and hooks, so the install is switched
1524
+ // through three settings in `.claude/settings.local.json`:
1525
+ // - `skillOverrides: { <name>: "off" }` — every managed skill and command
1526
+ // (command files are skills to Claude Code). Exact names: no wildcard.
1527
+ // - `claudeMdExcludes: ["**/.claude/rules/<file>"]` — every managed rule, as
1528
+ // a glob so the one entry matches in every worktree.
1529
+ // - our hooks and the CLAUDE.local.md block are taken out, and written back
1530
+ // from the shipped assets by `enable`, so nothing has to be saved.
1531
+ // Only entries naming OUR paths are written or removed: an override or exclude
1532
+ // the developer wrote is never taken.
1533
+ function switchNames() {
1534
+ return [...SKILLS, ...COMMANDS.map((c) => c.replace(/\.md$/, ''))]
1535
+ }
1536
+
1537
+ function ruleExcludes() {
1538
+ return RULES.map((r) => `**/.claude/rules/${r}`)
1539
+ }
1540
+
1541
+ // The local settings, parsed — `{}` when absent, null when not valid JSON.
1542
+ function readLocalSettings(dir) {
1543
+ try {
1544
+ const parsed = JSON.parse(fs.readFileSync(path.join(dir, '.claude', 'settings.local.json'), 'utf8'))
1545
+ return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
1546
+ } catch (error) {
1547
+ return error.code === 'ENOENT' ? {} : null
1548
+ }
1549
+ }
1550
+
1551
+ function writeLocalSettings(dir, settings) {
1552
+ const file = path.join(dir, '.claude', 'settings.local.json')
1553
+ if (!Object.keys(settings).length) {
1554
+ if (fs.existsSync(file)) fs.unlinkSync(file)
1555
+ return
1556
+ }
1557
+ ensureDir(path.dirname(file))
1558
+ fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
1559
+ }
1560
+
1561
+ // Take our override and exclude entries out of the local settings. Returns
1562
+ // false when the file is not valid JSON (left untouched).
1563
+ function clearSwitches(dir) {
1564
+ const settings = readLocalSettings(dir)
1565
+ if (settings === null) return false
1566
+ const names = new Set(switchNames())
1567
+ const globs = new Set(ruleExcludes())
1568
+ if (settings.skillOverrides && typeof settings.skillOverrides === 'object') {
1569
+ for (const name of Object.keys(settings.skillOverrides)) {
1570
+ if (names.has(name) && settings.skillOverrides[name] === 'off') delete settings.skillOverrides[name]
1571
+ }
1572
+ if (!Object.keys(settings.skillOverrides).length) delete settings.skillOverrides
1573
+ }
1574
+ if (Array.isArray(settings.claudeMdExcludes)) {
1575
+ settings.claudeMdExcludes = settings.claudeMdExcludes.filter((g) => !globs.has(g))
1576
+ if (!settings.claudeMdExcludes.length) delete settings.claudeMdExcludes
1577
+ }
1578
+ writeLocalSettings(dir, settings)
1579
+ return true
1580
+ }
1581
+
1582
+ function stripLocalClaudeBlock(dir) {
1583
+ const file = path.join(dir, 'CLAUDE.local.md')
1584
+ if (!fs.existsSync(file)) return false
1585
+ const text = fs.readFileSync(file, 'utf8')
1586
+ const re = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
1587
+ if (!re.test(text)) return false
1588
+ const next = text.replace(re, '\n')
1589
+ if (next.trim()) fs.writeFileSync(file, next.replace(/^\n+/, ''))
1590
+ else fs.unlinkSync(file)
1591
+ return true
1592
+ }
1593
+
1594
+ function rewriteManifestEnabled(dir, enabled) {
1595
+ const manifest = readManifest(dir)
1596
+ writeManifest(dir, manifest.files, { local: manifest.scope === 'local', enabled })
1597
+ }
1598
+
1599
+ // Turn a local install off for this machine's Claude. Deletes nothing, so it
1600
+ // refuses nothing about work in flight; returns the exit code.
1601
+ function disable(dir, { log = (s) => process.stdout.write(s) } = {}) {
1602
+ if (!fs.existsSync(path.join(dir, MANIFEST_FILE))) {
1603
+ log('disable: no skitterspec install here (no manifest) — nothing to disable.\n')
1604
+ return 0
1605
+ }
1606
+ const manifest = readManifest(dir)
1607
+ if (manifest.scope !== 'local') {
1608
+ log(
1609
+ 'disable: refused — this is a team install. Its hooks are in the committed settings,\n' +
1610
+ ' so they cannot be switched off for one person. disable works on a local install (init --local).\n',
1611
+ )
1612
+ return 1
1613
+ }
1614
+ const settings = readLocalSettings(dir)
1615
+ if (settings === null) {
1616
+ log('disable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
1617
+ return 1
1618
+ }
1619
+ const overrides = settings.skillOverrides && typeof settings.skillOverrides === 'object' ? settings.skillOverrides : {}
1620
+ for (const name of switchNames()) overrides[name] = 'off'
1621
+ settings.skillOverrides = overrides
1622
+ const excludes = Array.isArray(settings.claudeMdExcludes) ? settings.claudeMdExcludes : []
1623
+ for (const glob of ruleExcludes()) if (!excludes.includes(glob)) excludes.push(glob)
1624
+ settings.claudeMdExcludes = excludes
1625
+ writeLocalSettings(dir, settings)
1626
+ const hooks = removeHooks(dir, { local: true })
1627
+ if (hooks.emptied) writeLocalSettings(dir, {})
1628
+ const block = stripLocalClaudeBlock(dir)
1629
+ rewriteManifestEnabled(dir, false)
1630
+ log(
1631
+ `disable: skitterspec is off for Claude on this machine (${dir})\n` +
1632
+ ` ${switchNames().length} skills and commands switched off · ${RULES.length} rules excluded\n` +
1633
+ ` ${hooks.removed} hook(s) removed${block ? ' · CLAUDE.local.md block removed' : ''}\n` +
1634
+ ' the files stay on disk — skitterspec enable turns it back on. Restart Claude Code to pick it up.\n',
1635
+ )
1636
+ return 0
1637
+ }
1638
+
1639
+ // Turn a local install back on — and install it when there is nothing here to
1640
+ // turn on, since asking to use it has one meaning then.
1641
+ async function enable(dir, { log = (s) => process.stdout.write(s) } = {}) {
1642
+ const manifest = readManifest(dir)
1643
+ const present = fs.existsSync(path.join(dir, MANIFEST_FILE))
1644
+ const filesHere = managedTargets(dir).some((t) => !t.relPath.startsWith('specs') && fs.existsSync(t.abs))
1645
+ if (!present || (manifest.scope === 'local' && !filesHere)) {
1646
+ log('enable: no local install here — installing it (init --local).\n')
1647
+ // `update` mode installs the files and switches them on, and leaves the
1648
+ // project's committed config (isolation, gating) exactly as it is.
1649
+ await init({ dir, force: false, claudeMd: true, mode: 'update', local: true })
1650
+ return 0
1651
+ }
1652
+ if (manifest.scope !== 'local') {
1653
+ log('enable: refused — this is a team install, which is always on. enable works on a local install (init --local).\n')
1654
+ return 1
1655
+ }
1656
+ if (!clearSwitches(dir)) {
1657
+ log('enable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
1658
+ return 1
1659
+ }
1660
+ resetReport()
1661
+ scope = 'local'
1662
+ registerReviewGateHook(dir)
1663
+ installClaudeMd(dir, { mode: 'init' })
1664
+ rewriteManifestEnabled(dir, true)
1665
+ log(
1666
+ `enable: skitterspec is on for Claude on this machine (${dir})\n` +
1667
+ ' skills, commands and rules switched back on · hooks registered · CLAUDE.local.md block written\n' +
1668
+ ' Restart Claude Code to pick it up.\n',
1669
+ )
1670
+ return 0
1671
+ }
1672
+
1673
+ // UNINSTALL — take a local install (`init --local`) back off this machine,
1674
+ // exactly: the managed files, our hooks in settings.local.json, the block in
1675
+ // CLAUDE.local.md, the exclude block, `.spec-env/` and the manifest. Nothing
1676
+ // under `specs/` is touched — it is committed and shared. Plans by default and
1677
+ // acts only with `yes`; returns the exit code.
1678
+ //
1679
+ // A file is deleted only when it is PRISTINE. An unrecognised hash is either
1680
+ // the developer's edit or a lost record, and only one of those is safe to
1681
+ // delete, so it is kept (`.claude/rules/negative-checks.md` rule 4) — but kept
1682
+ // under `.claude/` it would still be loaded, so it is PARKED in
1683
+ // `<git-common-dir>/skitterspec-kept/`: outside the tree, so git status is
1684
+ // unchanged, and never over an earlier parked copy.
1685
+ //
1686
+ // `inFlight` is the caller's list of provisioned specs and a held live overlay;
1687
+ // any entry refuses, because each worktree carries a seeded copy of the install
1688
+ // and a torn-down primary leaves nothing to finish them with. `cannotTell` is
1689
+ // the caller failing to read that list, which also refuses: deleting is the
1690
+ // destructive branch, so the unknown case does not get it.
1691
+ function uninstall(dir, { yes = false, inFlight = [], cannotTell = null, log = (s) => process.stdout.write(s) } = {}) {
1692
+ const manifestAbs = path.join(dir, MANIFEST_FILE)
1693
+ if (!fs.existsSync(manifestAbs)) {
1694
+ log('uninstall: no skitterspec install here (no manifest) — nothing to do.\n')
1695
+ return 0
1696
+ }
1697
+ const manifest = readManifest(dir)
1698
+ if (manifest.scope !== 'local') {
1699
+ log(
1700
+ 'uninstall: refused — this is a team install, committed for everyone.\n' +
1701
+ ' Removing it is a commit for the team to make, not one machine\'s command.\n' +
1702
+ ' uninstall only takes a local install (init --local) back off.\n',
1703
+ )
1704
+ return 1
1705
+ }
1706
+ if (cannotTell) {
1707
+ log(`uninstall: refused — cannot tell whether a spec is in flight (${cannotTell}).\n Nothing changed.\n`)
1708
+ return 1
1709
+ }
1710
+ if (inFlight.length) {
1711
+ log(
1712
+ 'uninstall: refused — work is still in flight here, and its worktrees carry a copy of the install:\n' +
1713
+ inFlight.map((f) => ` ${f.spec} ${f.where}\n`).join('') +
1714
+ ' Finish each with /spec-complete, drop it with /spec-cancel (or spec-env down <name>),\n' +
1715
+ ' and hand a live spec back with /spec-live main. Nothing changed.\n',
1716
+ )
1717
+ return 1
1718
+ }
1719
+
1720
+ // The files: every managed target outside specs/, plus any manifest entry
1721
+ // the package no longer ships (a retired skill is still a skill on disk).
1722
+ const targets = new Map()
1723
+ for (const t of managedTargets(dir)) targets.set(t.relPath.split(path.sep).join('/'), t.bundled)
1724
+ for (const k of Object.keys(manifest.files)) if (!targets.has(k)) targets.set(k, undefined)
1725
+ const remove = []
1726
+ const keep = []
1727
+ const exclude = localExcludeFile(dir)
1728
+ const parkRoot = exclude && path.join(path.dirname(path.dirname(exclude.file)), 'skitterspec-kept')
1729
+ const parkFor = (relPath) => {
1730
+ let target = path.join(parkRoot, relPath)
1731
+ for (let n = 2; fs.existsSync(target); n++) target = path.join(parkRoot, `${relPath}.${n}`)
1732
+ return target
1733
+ }
1734
+ for (const [relPath, bundled] of [...targets].sort(([a], [b]) => a.localeCompare(b))) {
1735
+ if (relPath.startsWith('specs/')) continue
1736
+ const state = managedState(dir, relPath, manifest, bundled)
1737
+ if (state === 'pristine') remove.push(relPath)
1738
+ else if (state !== 'missing') keep.push({ relPath, parked: parkRoot ? parkFor(relPath) : null })
1739
+ }
1740
+
1741
+ const hooks = removeHooks(dir, { local: true, dryRun: true })
1742
+ const switches = readLocalSettings(dir)
1743
+ const hasSwitches =
1744
+ switches !== null &&
1745
+ (Object.keys(switches.skillOverrides || {}).some((n) => switchNames().includes(n)) ||
1746
+ (Array.isArray(switches.claudeMdExcludes) && switches.claudeMdExcludes.some((g) => ruleExcludes().includes(g))))
1747
+ const claudeLocal = path.join(dir, 'CLAUDE.local.md')
1748
+ const blockRe = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
1749
+ const claudeText = fs.existsSync(claudeLocal) ? fs.readFileSync(claudeLocal, 'utf8') : null
1750
+ const hasBlock = claudeText !== null && blockRe.test(claudeText)
1751
+ const hasExclude = exclude !== null && exclude.text.includes(EXCLUDE_START)
1752
+ const specEnv = path.join(dir, '.spec-env')
1753
+
1754
+ const lines = []
1755
+ const say = (label, items) => {
1756
+ if (!items.length) return
1757
+ lines.push(`\n${label}:\n`)
1758
+ for (const it of items) lines.push(` ${it}\n`)
1759
+ }
1760
+ say(yes ? 'removed' : 'would remove', [
1761
+ ...remove,
1762
+ ...(hooks.reason === 'removed' ? [`.claude/settings.local.json (${hooks.removed} skitterspec hook(s)${hooks.emptied ? ', then the emptied file' : ''})`] : []),
1763
+ ...(hasSwitches ? ['.claude/settings.local.json (skitterspec disable switches)'] : []),
1764
+ ...(hasBlock ? ['CLAUDE.local.md (spec workflow block)'] : []),
1765
+ ...(hasExclude ? [`${path.relative(dir, exclude.file).split(path.sep).join('/')} (skitterspec block)`] : []),
1766
+ ...(fs.existsSync(specEnv) ? ['.spec-env/'] : []),
1767
+ MANIFEST_FILE.split(path.sep).join('/'),
1768
+ ])
1769
+ say(
1770
+ yes ? 'parked — edited since install, moved out of Claude\'s reach' : 'would park — edited since install',
1771
+ keep.map((k) => (k.parked ? `${k.relPath} → ${k.parked}` : `${k.relPath} (kept in place — no git dir to park it in)`)),
1772
+ )
1773
+ const warnings = []
1774
+ if (hooks.reason === 'malformed') warnings.push('.claude/settings.local.json is not valid JSON — skitterspec hooks left in it; remove them by hand')
1775
+ if (exclude === null) warnings.push('not a git repository — no exclude block to remove')
1776
+ say('warnings', warnings)
1777
+
1778
+ if (!yes) {
1779
+ log(`uninstall: plan — nothing changed (${dir})\n${lines.join('')}\n re-run with --yes to remove the local install.\n`)
1780
+ return 0
1781
+ }
1782
+
1783
+ const managedSet = new Set(targets.keys())
1784
+ const parents = new Set()
1785
+ for (const relPath of remove) {
1786
+ assertSafeToDelete(relPath, managedSet)
1787
+ fs.unlinkSync(path.join(dir, relPath))
1788
+ parents.add(path.dirname(path.join(dir, relPath)))
1789
+ }
1790
+ for (const k of keep) {
1791
+ if (!k.parked) continue
1792
+ fs.mkdirSync(path.dirname(k.parked), { recursive: true })
1793
+ try {
1794
+ fs.renameSync(path.join(dir, k.relPath), k.parked)
1795
+ } catch (error) {
1796
+ if (error.code !== 'EXDEV') throw error
1797
+ fs.copyFileSync(path.join(dir, k.relPath), k.parked)
1798
+ fs.unlinkSync(path.join(dir, k.relPath))
1799
+ }
1800
+ parents.add(path.dirname(path.join(dir, k.relPath)))
1801
+ }
1802
+ // Folders our files left empty — a skill's own, then .claude/<kind>/ — and
1803
+ // never one that still holds something of the developer's.
1804
+ const stop = path.join(dir, '.claude')
1805
+ for (const start of parents) {
1806
+ for (let at = start; at.startsWith(stop + path.sep); at = path.dirname(at)) {
1807
+ try {
1808
+ if (fs.readdirSync(at).length) break
1809
+ fs.rmdirSync(at)
1810
+ } catch {
1811
+ break
1812
+ }
1813
+ }
1814
+ }
1815
+ // A disabled install's switches go too, or they would outlive what they name.
1816
+ clearSwitches(dir)
1817
+ if (hooks.reason === 'removed') {
1818
+ const done = removeHooks(dir, { local: true })
1819
+ if (done.emptied) fs.unlinkSync(path.join(dir, '.claude', 'settings.local.json'))
1820
+ }
1821
+ if (hasBlock) {
1822
+ const next = claudeText.replace(blockRe, '\n')
1823
+ if (next.trim()) fs.writeFileSync(claudeLocal, next.replace(/^\n+/, ''))
1824
+ else fs.unlinkSync(claudeLocal)
1825
+ }
1826
+ if (hasExclude) {
1827
+ const start = exclude.text.indexOf(EXCLUDE_START)
1828
+ const end = exclude.text.indexOf(EXCLUDE_END, start)
1829
+ if (end !== -1) {
1830
+ fs.writeFileSync(exclude.file, exclude.text.slice(0, start) + exclude.text.slice(end + EXCLUDE_END.length).replace(/^\n/, ''))
1831
+ }
1832
+ }
1833
+ fs.rmSync(specEnv, { recursive: true, force: true })
1834
+ fs.unlinkSync(manifestAbs)
1835
+
1836
+ log(
1837
+ `uninstall: done (${dir})\n${lines.join('')}\n` +
1838
+ ` the CLI itself is still installed — npm uninstall -g ${distributionPackage()} removes it.\n`,
1839
+ )
1840
+ return 0
1841
+ }
1842
+
1843
+ // The git common dir's info/exclude, read — null when this is not a git repo.
1844
+ function localExcludeFile(dir) {
1845
+ let commonDir
1846
+ try {
1847
+ commonDir = path.resolve(
1848
+ dir,
1849
+ execFileSync('git', ['-C', dir, 'rev-parse', '--git-common-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(),
1850
+ )
1851
+ } catch {
1852
+ return null
1853
+ }
1854
+ const file = path.join(commonDir, 'info', 'exclude')
1855
+ let text = ''
1856
+ try {
1857
+ text = fs.readFileSync(file, 'utf8')
1858
+ } catch {
1859
+ /* no exclude file */
1860
+ }
1861
+ return { file, text }
1862
+ }
1863
+
1472
1864
  async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating, project, local = false }) {
1473
1865
  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
1474
1866
  resetReport()
1475
1867
  resolveScope(dir, local)
1476
1868
  if (scope === 'local') convertCommitted(dir)
1869
+ // Installing is enabling: a disabled install comes back on.
1870
+ if (scope === 'local' && !readManifest(dir).enabled) {
1871
+ clearSwitches(dir)
1872
+ report.updated.push('.claude/settings.local.json (skitterspec enabled)')
1873
+ }
1874
+ enabledOnFlush = true
1477
1875
 
1478
1876
  installSkills(dir, { force })
1479
1877
  installCommands(dir, { force })
@@ -1517,6 +1915,9 @@ module.exports = {
1517
1915
  isExistingSetup,
1518
1916
  resync,
1519
1917
  reset,
1918
+ uninstall,
1919
+ disable,
1920
+ enable,
1520
1921
  assertSafeToDelete,
1521
1922
  assertComposedAssets,
1522
1923
  detectPackageManager,