@skitterbyte/skitterspec-jira 2.17.0 → 2.18.1

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
@@ -36,6 +36,18 @@ finding one. They are marked `disable-model-invocation`, meaning
36
36
  **only you can run them** — a skill that wants one will tell you to type it
37
37
  rather than invoking it.
38
38
 
39
+ **A command finds the project itself, wherever the session stands.** Its line
40
+ runs in the session's current directory, which after a `cd` may be the git root
41
+ or a worktree's root rather than the project folder — and in a repo whose
42
+ project is a subfolder, a runner started there found no install and printed
43
+ npm's registry 404. So with a local install the line is a small `node -e`
44
+ launcher, written that way because both `/bin/sh` and cmd.exe can start it. It
45
+ runs in the current directory when the install is there, which is the usual case and unchanged. Otherwise
46
+ it runs in this checkout's project folder, using the subfolder recorded when
47
+ the command was installed and the primary checkout's install when a worktree
48
+ has none. Failing both, it refuses in one line naming the folder it expected.
49
+ `skitterspec update` rewrites the command files to this form.
50
+
39
51
  **The `spec-remote-review` command was retired** with the published review tier
40
52
  (feat-tailnet-remote-tier). It toggled whether a spec might publish its review
41
53
  as a claude.ai page — a second store no wait could watch, and a page this
@@ -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**
@@ -347,6 +347,13 @@ plain markdown list in the conversation — never fenced, and
347
347
  out of the terminal to find out what to do, which is the failure this exists to
348
348
  fix; the steps themselves are what they act on.
349
349
 
350
+ **Steps you had to write are saved first.** When the phase file holds only a
351
+ vague manual task — "check it on the running host" — and you wrote the steps
352
+ yourself, add them under that task as numbered sub-checkboxes **before** you
353
+ ask. The conversation does not survive a `/clear`, and a later run that makes
354
+ up its own set lists different steps from the ones the reader was shown. A
355
+ phase whose manual steps are already tasks is left as it is.
356
+
350
357
  Then ask one question, with three answers:
351
358
 
352
359
  - **All done** — tick those steps and carry on to the end of the phase.
@@ -365,6 +372,8 @@ needs no new shape in the report.
365
372
  tasks after an unconfirmed step are not built past it, and the phase did not
366
373
  end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
367
374
  End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
375
+ Its `Next` lists the open steps a row each, copied from the phase file —
376
+ `.claude/rules/spec-reports.md`, *Open manual steps are rows*.
368
377
 
369
378
  ## 4. Record progress
370
379
 
@@ -706,7 +715,8 @@ the shape; this section carries only what is specific here.
706
715
  - `⚠️` — built and green, with something worth knowing (a mirror that did not
707
716
  refresh, a deviation from the plan) — or stopped at manual steps answered
708
717
  **Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
709
- are open, and `Next` is `/commit, then /spec-next` to pick them up.
718
+ are open, and `Next` is `/commit`, then a row per open step, then
719
+ `/spec-next` to pick them up.
710
720
  - `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
711
721
  - `⏸` — no spec in flight, several in flight with this session in none of
712
722
  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-jira",
3
- "version": "2.17.0",
3
+ "version": "2.18.1",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
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
@@ -245,8 +245,88 @@ function renderExec(content, dir, env = process.env) {
245
245
  })
246
246
  }
247
247
 
248
- // The original name, kept because commands were the first thing rendered.
249
- const renderCommand = renderExec
248
+ // --- the command launcher (bug-commands-outside-project) -------------------
249
+ //
250
+ // A command file lives in the project folder's `.claude/commands/`, but its `!`
251
+ // line runs in whatever directory the SESSION is standing in. A runner resolves
252
+ // the install from there, so in a repo whose project is a subfolder a session
253
+ // that had cd'd to the git root — or to a worktree's root — got npm's registry
254
+ // 404 instead of the engine. So on the local rung a command's `{{exec}}` renders
255
+ // as a launcher that picks the folder first:
256
+ //
257
+ // 1. the cwd, walking up, when the install is there — the healthy path, run
258
+ // in the cwd exactly as before;
259
+ // 2. else this checkout's project folder (git toplevel + the prefix recorded
260
+ // here at render time), then the primary checkout's — a `--docs` worktree
261
+ // has no install of its own — run in THIS checkout's project folder, so a
262
+ // bare command still means the spec you are standing on;
263
+ // 3. else one line naming the folder it expected, exit 1.
264
+ //
265
+ // It is `node -e`, inline, rather than a script file beside the commands,
266
+ // because finding a file from an unknown cwd is the very problem being solved,
267
+ // and a local-scope install keeps `.claude/` out of git, so a worktree may not
268
+ // have one. Node runs the engine's JS entry directly (no `.bin` shim, no
269
+ // shell), which is the one form both `/bin/sh` and cmd.exe can start — vm-bridge
270
+ // runs these lines through cmd.
271
+ //
272
+ // WHAT WOULD BREAK IT: the line passes through two shells' quoting. It is one
273
+ // double-quoted word, so the script must hold no `"`, `$`, `` ` ``, `\`, `%` or
274
+ // `!` — and neither may anything substituted into it. A prefix holding one of
275
+ // those is cannot-tell and renders as `''` (rule 4): rungs 1 and 3 still hold.
276
+ const LAUNCHER = [
277
+ "const f=require('fs'),p=require('path'),c=require('child_process'),K='{{pkg}}',B='{{bin}}',P='{{prefix}}'",
278
+ "const g=a=>{try{return c.execFileSync('git',a,{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim()}catch(e){}}",
279
+ 'const w=d=>{for(let i=0;i<6;i++){const m=p.join(d,' +
280
+ "'node_modules',K,'package.json');if(f.existsSync(m)){const b=JSON.parse(f.readFileSync(m,'utf8')).bin;" +
281
+ "return p.join(p.dirname(m),typeof b=='string'?b:b[B])}const u=p.dirname(d);if(u==d)return;d=u}}",
282
+ 'let d=process.cwd(),e=w(d)',
283
+ "if(e==null){const t=g(['rev-parse','--show-toplevel']),m=g(['rev-parse','--git-common-dir']);" +
284
+ 'if(t){d=p.join(t,P);e=w(d)||m&&w(p.join(p.dirname(p.resolve(m)),P))}}',
285
+ "if(e==null){console.error(B+': not installed for '+d+' (no node_modules/'+K+' there or above) - install it there, or run from the project folder');process.exit(1)}",
286
+ "const r=c.spawnSync(process.execPath,[e,...process.argv.slice(1)],{cwd:d,stdio:'inherit'});process.exit(r.status==null?1:r.status)",
287
+ ].join(';')
288
+
289
+ const UNSAFE_IN_LAUNCHER = /["'$`\\%!]/
290
+
291
+ // The project's folder within its git repo, as a repo path — '' at the root,
292
+ // outside a repo, or when it cannot be carried safely in the launcher.
293
+ function launcherPrefix(dir) {
294
+ let top
295
+ try {
296
+ top = execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
297
+ encoding: 'utf8',
298
+ stdio: ['ignore', 'pipe', 'ignore'],
299
+ }).trim()
300
+ } catch {
301
+ return ''
302
+ }
303
+ const real = (p) => {
304
+ try {
305
+ return fs.realpathSync.native(p)
306
+ } catch {
307
+ return path.resolve(p)
308
+ }
309
+ }
310
+ const rel = path.relative(real(top), real(dir))
311
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return ''
312
+ const prefix = rel.split(path.sep).join('/')
313
+ return UNSAFE_IN_LAUNCHER.test(prefix) ? '' : prefix
314
+ }
315
+
316
+ function launcherFor(bin, dir) {
317
+ const script = LAUNCHER.replace('{{pkg}}', distributionPackage())
318
+ .replace('{{bin}}', bin)
319
+ .replace('{{prefix}}', launcherPrefix(dir))
320
+ return `node -e "${script}" --`
321
+ }
322
+
323
+ // What a command file's `!` line runs. Only the local rung changes: a global
324
+ // install and the `npx -p` fallback resolve the same from any directory.
325
+ function renderCommand(content, dir, env = process.env) {
326
+ if (!content.includes('{{exec}}')) return content
327
+ if (detectRunner(dir, env).rung !== 'local') return renderExec(content, dir, env)
328
+ return content.replace(EXEC_RE, (_m, _sp, bin) => (bin ? launcherFor(bin, dir) : 'node'))
329
+ }
250
330
 
251
331
  // Which managed files carry the token: markdown only. Hooks and JSON templates
252
332
  // are copied byte for byte.
@@ -318,6 +398,7 @@ const report = { created: [], updated: [], skipped: [], refused: [], removed: []
318
398
 
319
399
  function resetReport() {
320
400
  scope = 'team'
401
+ enabledOnFlush = null
321
402
  for (const k of Object.keys(report)) report[k].length = 0
322
403
  for (const k of Object.keys(writtenHashes)) delete writtenHashes[k]
323
404
  }
@@ -386,7 +467,7 @@ function managedTargets(dir) {
386
467
  })
387
468
  for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
388
469
  for (const name of COMMANDS)
389
- add(path.join('commands', name), path.join(dir, '.claude', 'commands', name))
470
+ add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
390
471
  for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
391
472
  for (const name of HOOKS) add(path.join('hooks', name), path.join(dir, '.claude', 'hooks', name))
392
473
  for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
@@ -424,20 +505,25 @@ function readManifest(dir) {
424
505
  // Absent means team: every manifest written before `--local` existed
425
506
  // reads exactly as it did.
426
507
  scope: parsed.scope === 'local' ? 'local' : 'team',
508
+ // Absent means enabled: only `disable` writes the field.
509
+ enabled: parsed.enabled !== false,
427
510
  }
428
511
  }
429
512
  } catch {
430
513
  /* missing or malformed → empty baseline */
431
514
  }
432
- return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team' }
515
+ return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team', enabled: true }
433
516
  }
434
517
 
435
- function writeManifest(dir, files, { local = false } = {}) {
518
+ function writeManifest(dir, files, { local = false, enabled = true } = {}) {
436
519
  const target = path.join(dir, MANIFEST_FILE)
437
520
  ensureDir(path.dirname(target))
438
521
  const sorted = {}
439
522
  for (const k of Object.keys(files).sort()) sorted[k] = files[k]
440
523
  const body = local ? { version: MANIFEST_VERSION, scope: 'local', files: sorted } : { version: MANIFEST_VERSION, files: sorted }
524
+ // Written only when false, so an enabled install's manifest reads exactly as
525
+ // every manifest written before `disable` existed.
526
+ if (!enabled) body.enabled = false
441
527
  fs.writeFileSync(target, JSON.stringify(body, null, 2) + '\n')
442
528
  }
443
529
 
@@ -499,7 +585,8 @@ function flushManifest(dir) {
499
585
  // env.config.json that installIsolation happens to write through writeFile).
500
586
  const managed = managedTargets(dir)
501
587
  const managedRel = new Set(managed.map((t) => t.relPath))
502
- const merged = { ...readManifest(dir).files, ...writtenHashes }
588
+ const prior = readManifest(dir)
589
+ const merged = { ...prior.files, ...writtenHashes }
503
590
  const next = {}
504
591
  for (const [relPath, hash] of Object.entries(merged)) {
505
592
  if (managedRel.has(relPath)) next[relPath] = hash
@@ -510,9 +597,13 @@ function flushManifest(dir) {
510
597
  for (const relPath of Object.keys(next)) {
511
598
  if (!fs.existsSync(path.join(dir, relPath))) delete next[relPath] // prune gone
512
599
  }
513
- writeManifest(dir, next, { local: scope === 'local' })
600
+ writeManifest(dir, next, { local: scope === 'local', enabled: enabledOnFlush === null ? prior.enabled : enabledOnFlush })
514
601
  }
515
602
 
603
+ // Set by a run that decides the install's switch: `init` turns it on, and
604
+ // `null` keeps whatever the manifest says (`update` on a disabled install).
605
+ let enabledOnFlush = null
606
+
516
607
  function writeFile(dir, target, content, { force }) {
517
608
  // A dangling symlink (its target no longer exists) is invisible to existsSync,
518
609
  // which follows the link — but the link itself is still on disk, so a plain
@@ -571,7 +662,8 @@ function writeFile(dir, target, content, { force }) {
571
662
 
572
663
  function copyAsset(dir, assetRelPath, targetAbs, opts) {
573
664
  const raw = fs.readFileSync(path.join(ASSETS, assetRelPath), 'utf8')
574
- const content = renderable(assetRelPath) ? renderExec(raw, dir) : raw
665
+ const render = assetRelPath.startsWith(`commands${path.sep}`) ? renderCommand : renderExec
666
+ const content = renderable(assetRelPath) ? render(raw, dir) : raw
575
667
  writeFile(dir, targetAbs, content, opts)
576
668
  }
577
669
 
@@ -1004,8 +1096,14 @@ function resync(dir, { force = false, claudeMd = true, diff = false, local = fal
1004
1096
  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
1005
1097
  // project, while reporting a file created. `init-review-gate-hook.test.js`
1006
1098
  // asserts over the entry points rather than over this call.
1007
- registerReviewGateHook(dir)
1008
- if (claudeMd) installClaudeMd(dir, { mode: 'update' })
1099
+ // A disabled install stays disabled through an update: the files refresh,
1100
+ // and the two things Claude reads from outside them are not written back.
1101
+ const disabled = scope === 'local' && !manifest.enabled
1102
+ if (disabled) report.skipped.push('hooks and CLAUDE.local.md block (disabled — skitterspec enable turns them on)')
1103
+ else {
1104
+ registerReviewGateHook(dir)
1105
+ if (claudeMd) installClaudeMd(dir, { mode: 'update' })
1106
+ }
1009
1107
  suggestReleaseWith(dir)
1010
1108
  flushManifest(dir)
1011
1109
  if (scope === 'local') writeLocalExcludes(dir)
@@ -1205,8 +1303,10 @@ function suggestReleaseWith(dir) {
1205
1303
  // Switching a local install back to team is out of scope and says so.
1206
1304
  function resolveScope(dir, local) {
1207
1305
  const recorded = readManifest(dir).scope
1208
- scope = local || recorded === 'local' ? 'local' : 'team'
1306
+ const excluded = !local && recorded !== 'local' && excludeNamesManifest(dir)
1307
+ scope = local || recorded === 'local' || excluded ? 'local' : 'team'
1209
1308
  if (!local && recorded === 'local') report.skipped.push('local install (recorded in the manifest) — kept local')
1309
+ if (excluded) report.skipped.push('local install (recorded in .git/info/exclude) — kept local')
1210
1310
  if (local && recorded !== 'local') {
1211
1311
  report.warnings.push(
1212
1312
  '--local keeps skitterspec on this machine: teammates get none of its skills, rules ' +
@@ -1243,11 +1343,16 @@ function localExcludes(dir) {
1243
1343
  }
1244
1344
 
1245
1345
  // 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.
1346
+ // paths, the two per-machine files and the manifest. A worktree is a fresh
1347
+ // checkout, and git carries none of it there. Empty for a team install, which
1348
+ // git carries.
1349
+ //
1350
+ // THE MANIFEST IS SEEDED because it is what records the scope: without it a
1351
+ // worktree's `update` read team and wrote the block into the tracked CLAUDE.md
1352
+ // and the hooks into a new .claude/settings.json (bug-local-scope-worktree).
1248
1353
  function localSeedFiles(dir) {
1249
1354
  if (readManifest(dir).scope !== 'local') return []
1250
- return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md']
1355
+ return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md', MANIFEST_FILE.replace(/\\/g, '/')]
1251
1356
  }
1252
1357
 
1253
1358
  const EXCLUDE_START = '# >>> skitterspec (local install)'
@@ -1288,6 +1393,31 @@ function writeLocalExcludes(dir) {
1288
1393
  report.updated.push('.git/info/exclude (skitterspec block)')
1289
1394
  }
1290
1395
 
1396
+ // Whether the shared `.git/info/exclude` block names THIS project's manifest —
1397
+ // the positive signal that a worktree with no manifest of its own belongs to a
1398
+ // local install. The exclude lives in the common dir, so every worktree sees
1399
+ // the block the primary checkout's install wrote; matching the prefixed
1400
+ // manifest path, not the bare block, keeps a second project in the same repo
1401
+ // from being read as local by a neighbour's install.
1402
+ //
1403
+ // WHAT WOULD FOOL IT: a block hand-edited to drop the manifest line, or git
1404
+ // unreachable. Both answer false — the scope the manifest recorded, as before.
1405
+ function excludeNamesManifest(dir) {
1406
+ try {
1407
+ const git = (...args) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
1408
+ const commonDir = path.resolve(dir, git('rev-parse', '--git-common-dir'))
1409
+ const prefix = git('rev-parse', '--show-prefix')
1410
+ const text = fs.readFileSync(path.join(commonDir, 'info', 'exclude'), 'utf8')
1411
+ const start = text.indexOf(EXCLUDE_START)
1412
+ const end = text.indexOf(EXCLUDE_END, start)
1413
+ if (start === -1 || end === -1) return false
1414
+ const entry = `/${prefix}${MANIFEST_FILE.replace(/\\/g, '/')}`
1415
+ return text.slice(start, end).split(/\r?\n/).some((l) => l.trim() === entry)
1416
+ } catch {
1417
+ return false
1418
+ }
1419
+ }
1420
+
1291
1421
  // Convert a COMMITTED (team) install into a local one, in place. Every step
1292
1422
  // leaves the files on disk and stages or edits only; it never commits — the
1293
1423
  // operator commits the removal, and teammates who pull it lose the install.
@@ -1469,11 +1599,360 @@ function hooksAt(read, ref) {
1469
1599
  .filter((h) => h && typeof h.command === 'string' && GATE_HOOKS.some((k) => k.re.test(h.command))).length
1470
1600
  }
1471
1601
 
1602
+ // DISABLE / ENABLE — switch whether this machine's Claude uses a local install,
1603
+ // without touching its files (feat-uninstall-local). Claude Code has no single
1604
+ // switch covering skills, commands, rules and hooks, so the install is switched
1605
+ // through three settings in `.claude/settings.local.json`:
1606
+ // - `skillOverrides: { <name>: "off" }` — every managed skill and command
1607
+ // (command files are skills to Claude Code). Exact names: no wildcard.
1608
+ // - `claudeMdExcludes: ["**/.claude/rules/<file>"]` — every managed rule, as
1609
+ // a glob so the one entry matches in every worktree.
1610
+ // - our hooks and the CLAUDE.local.md block are taken out, and written back
1611
+ // from the shipped assets by `enable`, so nothing has to be saved.
1612
+ // Only entries naming OUR paths are written or removed: an override or exclude
1613
+ // the developer wrote is never taken.
1614
+ function switchNames() {
1615
+ return [...SKILLS, ...COMMANDS.map((c) => c.replace(/\.md$/, ''))]
1616
+ }
1617
+
1618
+ function ruleExcludes() {
1619
+ return RULES.map((r) => `**/.claude/rules/${r}`)
1620
+ }
1621
+
1622
+ // The local settings, parsed — `{}` when absent, null when not valid JSON.
1623
+ function readLocalSettings(dir) {
1624
+ try {
1625
+ const parsed = JSON.parse(fs.readFileSync(path.join(dir, '.claude', 'settings.local.json'), 'utf8'))
1626
+ return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
1627
+ } catch (error) {
1628
+ return error.code === 'ENOENT' ? {} : null
1629
+ }
1630
+ }
1631
+
1632
+ function writeLocalSettings(dir, settings) {
1633
+ const file = path.join(dir, '.claude', 'settings.local.json')
1634
+ if (!Object.keys(settings).length) {
1635
+ if (fs.existsSync(file)) fs.unlinkSync(file)
1636
+ return
1637
+ }
1638
+ ensureDir(path.dirname(file))
1639
+ fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
1640
+ }
1641
+
1642
+ // Take our override and exclude entries out of the local settings. Returns
1643
+ // false when the file is not valid JSON (left untouched).
1644
+ function clearSwitches(dir) {
1645
+ const settings = readLocalSettings(dir)
1646
+ if (settings === null) return false
1647
+ const names = new Set(switchNames())
1648
+ const globs = new Set(ruleExcludes())
1649
+ if (settings.skillOverrides && typeof settings.skillOverrides === 'object') {
1650
+ for (const name of Object.keys(settings.skillOverrides)) {
1651
+ if (names.has(name) && settings.skillOverrides[name] === 'off') delete settings.skillOverrides[name]
1652
+ }
1653
+ if (!Object.keys(settings.skillOverrides).length) delete settings.skillOverrides
1654
+ }
1655
+ if (Array.isArray(settings.claudeMdExcludes)) {
1656
+ settings.claudeMdExcludes = settings.claudeMdExcludes.filter((g) => !globs.has(g))
1657
+ if (!settings.claudeMdExcludes.length) delete settings.claudeMdExcludes
1658
+ }
1659
+ writeLocalSettings(dir, settings)
1660
+ return true
1661
+ }
1662
+
1663
+ function stripLocalClaudeBlock(dir) {
1664
+ const file = path.join(dir, 'CLAUDE.local.md')
1665
+ if (!fs.existsSync(file)) return false
1666
+ const text = fs.readFileSync(file, 'utf8')
1667
+ const re = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
1668
+ if (!re.test(text)) return false
1669
+ const next = text.replace(re, '\n')
1670
+ if (next.trim()) fs.writeFileSync(file, next.replace(/^\n+/, ''))
1671
+ else fs.unlinkSync(file)
1672
+ return true
1673
+ }
1674
+
1675
+ function rewriteManifestEnabled(dir, enabled) {
1676
+ const manifest = readManifest(dir)
1677
+ writeManifest(dir, manifest.files, { local: manifest.scope === 'local', enabled })
1678
+ }
1679
+
1680
+ // Turn a local install off for this machine's Claude. Deletes nothing, so it
1681
+ // refuses nothing about work in flight; returns the exit code.
1682
+ function disable(dir, { log = (s) => process.stdout.write(s) } = {}) {
1683
+ if (!fs.existsSync(path.join(dir, MANIFEST_FILE))) {
1684
+ log('disable: no skitterspec install here (no manifest) — nothing to disable.\n')
1685
+ return 0
1686
+ }
1687
+ const manifest = readManifest(dir)
1688
+ if (manifest.scope !== 'local') {
1689
+ log(
1690
+ 'disable: refused — this is a team install. Its hooks are in the committed settings,\n' +
1691
+ ' so they cannot be switched off for one person. disable works on a local install (init --local).\n',
1692
+ )
1693
+ return 1
1694
+ }
1695
+ const settings = readLocalSettings(dir)
1696
+ if (settings === null) {
1697
+ log('disable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
1698
+ return 1
1699
+ }
1700
+ const overrides = settings.skillOverrides && typeof settings.skillOverrides === 'object' ? settings.skillOverrides : {}
1701
+ for (const name of switchNames()) overrides[name] = 'off'
1702
+ settings.skillOverrides = overrides
1703
+ const excludes = Array.isArray(settings.claudeMdExcludes) ? settings.claudeMdExcludes : []
1704
+ for (const glob of ruleExcludes()) if (!excludes.includes(glob)) excludes.push(glob)
1705
+ settings.claudeMdExcludes = excludes
1706
+ writeLocalSettings(dir, settings)
1707
+ const hooks = removeHooks(dir, { local: true })
1708
+ if (hooks.emptied) writeLocalSettings(dir, {})
1709
+ const block = stripLocalClaudeBlock(dir)
1710
+ rewriteManifestEnabled(dir, false)
1711
+ log(
1712
+ `disable: skitterspec is off for Claude on this machine (${dir})\n` +
1713
+ ` ${switchNames().length} skills and commands switched off · ${RULES.length} rules excluded\n` +
1714
+ ` ${hooks.removed} hook(s) removed${block ? ' · CLAUDE.local.md block removed' : ''}\n` +
1715
+ ' the files stay on disk — skitterspec enable turns it back on. Restart Claude Code to pick it up.\n',
1716
+ )
1717
+ return 0
1718
+ }
1719
+
1720
+ // Turn a local install back on — and install it when there is nothing here to
1721
+ // turn on, since asking to use it has one meaning then.
1722
+ async function enable(dir, { log = (s) => process.stdout.write(s) } = {}) {
1723
+ const manifest = readManifest(dir)
1724
+ const present = fs.existsSync(path.join(dir, MANIFEST_FILE))
1725
+ const filesHere = managedTargets(dir).some((t) => !t.relPath.startsWith('specs') && fs.existsSync(t.abs))
1726
+ if (!present || (manifest.scope === 'local' && !filesHere)) {
1727
+ log('enable: no local install here — installing it (init --local).\n')
1728
+ // `update` mode installs the files and switches them on, and leaves the
1729
+ // project's committed config (isolation, gating) exactly as it is.
1730
+ await init({ dir, force: false, claudeMd: true, mode: 'update', local: true })
1731
+ return 0
1732
+ }
1733
+ if (manifest.scope !== 'local') {
1734
+ log('enable: refused — this is a team install, which is always on. enable works on a local install (init --local).\n')
1735
+ return 1
1736
+ }
1737
+ if (!clearSwitches(dir)) {
1738
+ log('enable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
1739
+ return 1
1740
+ }
1741
+ resetReport()
1742
+ scope = 'local'
1743
+ registerReviewGateHook(dir)
1744
+ installClaudeMd(dir, { mode: 'init' })
1745
+ rewriteManifestEnabled(dir, true)
1746
+ log(
1747
+ `enable: skitterspec is on for Claude on this machine (${dir})\n` +
1748
+ ' skills, commands and rules switched back on · hooks registered · CLAUDE.local.md block written\n' +
1749
+ ' Restart Claude Code to pick it up.\n',
1750
+ )
1751
+ return 0
1752
+ }
1753
+
1754
+ // UNINSTALL — take a local install (`init --local`) back off this machine,
1755
+ // exactly: the managed files, our hooks in settings.local.json, the block in
1756
+ // CLAUDE.local.md, the exclude block, `.spec-env/` and the manifest. Nothing
1757
+ // under `specs/` is touched — it is committed and shared. Plans by default and
1758
+ // acts only with `yes`; returns the exit code.
1759
+ //
1760
+ // A file is deleted only when it is PRISTINE. An unrecognised hash is either
1761
+ // the developer's edit or a lost record, and only one of those is safe to
1762
+ // delete, so it is kept (`.claude/rules/negative-checks.md` rule 4) — but kept
1763
+ // under `.claude/` it would still be loaded, so it is PARKED in
1764
+ // `<git-common-dir>/skitterspec-kept/`: outside the tree, so git status is
1765
+ // unchanged, and never over an earlier parked copy.
1766
+ //
1767
+ // `inFlight` is the caller's list of provisioned specs and a held live overlay;
1768
+ // any entry refuses, because each worktree carries a seeded copy of the install
1769
+ // and a torn-down primary leaves nothing to finish them with. `cannotTell` is
1770
+ // the caller failing to read that list, which also refuses: deleting is the
1771
+ // destructive branch, so the unknown case does not get it.
1772
+ function uninstall(dir, { yes = false, inFlight = [], cannotTell = null, log = (s) => process.stdout.write(s) } = {}) {
1773
+ const manifestAbs = path.join(dir, MANIFEST_FILE)
1774
+ if (!fs.existsSync(manifestAbs)) {
1775
+ log('uninstall: no skitterspec install here (no manifest) — nothing to do.\n')
1776
+ return 0
1777
+ }
1778
+ const manifest = readManifest(dir)
1779
+ if (manifest.scope !== 'local') {
1780
+ log(
1781
+ 'uninstall: refused — this is a team install, committed for everyone.\n' +
1782
+ ' Removing it is a commit for the team to make, not one machine\'s command.\n' +
1783
+ ' uninstall only takes a local install (init --local) back off.\n',
1784
+ )
1785
+ return 1
1786
+ }
1787
+ if (cannotTell) {
1788
+ log(`uninstall: refused — cannot tell whether a spec is in flight (${cannotTell}).\n Nothing changed.\n`)
1789
+ return 1
1790
+ }
1791
+ if (inFlight.length) {
1792
+ log(
1793
+ 'uninstall: refused — work is still in flight here, and its worktrees carry a copy of the install:\n' +
1794
+ inFlight.map((f) => ` ${f.spec} ${f.where}\n`).join('') +
1795
+ ' Finish each with /spec-complete, drop it with /spec-cancel (or spec-env down <name>),\n' +
1796
+ ' and hand a live spec back with /spec-live main. Nothing changed.\n',
1797
+ )
1798
+ return 1
1799
+ }
1800
+
1801
+ // The files: every managed target outside specs/, plus any manifest entry
1802
+ // the package no longer ships (a retired skill is still a skill on disk).
1803
+ const targets = new Map()
1804
+ for (const t of managedTargets(dir)) targets.set(t.relPath.split(path.sep).join('/'), t.bundled)
1805
+ for (const k of Object.keys(manifest.files)) if (!targets.has(k)) targets.set(k, undefined)
1806
+ const remove = []
1807
+ const keep = []
1808
+ const exclude = localExcludeFile(dir)
1809
+ const parkRoot = exclude && path.join(path.dirname(path.dirname(exclude.file)), 'skitterspec-kept')
1810
+ const parkFor = (relPath) => {
1811
+ let target = path.join(parkRoot, relPath)
1812
+ for (let n = 2; fs.existsSync(target); n++) target = path.join(parkRoot, `${relPath}.${n}`)
1813
+ return target
1814
+ }
1815
+ for (const [relPath, bundled] of [...targets].sort(([a], [b]) => a.localeCompare(b))) {
1816
+ if (relPath.startsWith('specs/')) continue
1817
+ const state = managedState(dir, relPath, manifest, bundled)
1818
+ if (state === 'pristine') remove.push(relPath)
1819
+ else if (state !== 'missing') keep.push({ relPath, parked: parkRoot ? parkFor(relPath) : null })
1820
+ }
1821
+
1822
+ const hooks = removeHooks(dir, { local: true, dryRun: true })
1823
+ const switches = readLocalSettings(dir)
1824
+ const hasSwitches =
1825
+ switches !== null &&
1826
+ (Object.keys(switches.skillOverrides || {}).some((n) => switchNames().includes(n)) ||
1827
+ (Array.isArray(switches.claudeMdExcludes) && switches.claudeMdExcludes.some((g) => ruleExcludes().includes(g))))
1828
+ const claudeLocal = path.join(dir, 'CLAUDE.local.md')
1829
+ const blockRe = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
1830
+ const claudeText = fs.existsSync(claudeLocal) ? fs.readFileSync(claudeLocal, 'utf8') : null
1831
+ const hasBlock = claudeText !== null && blockRe.test(claudeText)
1832
+ const hasExclude = exclude !== null && exclude.text.includes(EXCLUDE_START)
1833
+ const specEnv = path.join(dir, '.spec-env')
1834
+
1835
+ const lines = []
1836
+ const say = (label, items) => {
1837
+ if (!items.length) return
1838
+ lines.push(`\n${label}:\n`)
1839
+ for (const it of items) lines.push(` ${it}\n`)
1840
+ }
1841
+ say(yes ? 'removed' : 'would remove', [
1842
+ ...remove,
1843
+ ...(hooks.reason === 'removed' ? [`.claude/settings.local.json (${hooks.removed} skitterspec hook(s)${hooks.emptied ? ', then the emptied file' : ''})`] : []),
1844
+ ...(hasSwitches ? ['.claude/settings.local.json (skitterspec disable switches)'] : []),
1845
+ ...(hasBlock ? ['CLAUDE.local.md (spec workflow block)'] : []),
1846
+ ...(hasExclude ? [`${path.relative(dir, exclude.file).split(path.sep).join('/')} (skitterspec block)`] : []),
1847
+ ...(fs.existsSync(specEnv) ? ['.spec-env/'] : []),
1848
+ MANIFEST_FILE.split(path.sep).join('/'),
1849
+ ])
1850
+ say(
1851
+ yes ? 'parked — edited since install, moved out of Claude\'s reach' : 'would park — edited since install',
1852
+ keep.map((k) => (k.parked ? `${k.relPath} → ${k.parked}` : `${k.relPath} (kept in place — no git dir to park it in)`)),
1853
+ )
1854
+ const warnings = []
1855
+ if (hooks.reason === 'malformed') warnings.push('.claude/settings.local.json is not valid JSON — skitterspec hooks left in it; remove them by hand')
1856
+ if (exclude === null) warnings.push('not a git repository — no exclude block to remove')
1857
+ say('warnings', warnings)
1858
+
1859
+ if (!yes) {
1860
+ log(`uninstall: plan — nothing changed (${dir})\n${lines.join('')}\n re-run with --yes to remove the local install.\n`)
1861
+ return 0
1862
+ }
1863
+
1864
+ const managedSet = new Set(targets.keys())
1865
+ const parents = new Set()
1866
+ for (const relPath of remove) {
1867
+ assertSafeToDelete(relPath, managedSet)
1868
+ fs.unlinkSync(path.join(dir, relPath))
1869
+ parents.add(path.dirname(path.join(dir, relPath)))
1870
+ }
1871
+ for (const k of keep) {
1872
+ if (!k.parked) continue
1873
+ fs.mkdirSync(path.dirname(k.parked), { recursive: true })
1874
+ try {
1875
+ fs.renameSync(path.join(dir, k.relPath), k.parked)
1876
+ } catch (error) {
1877
+ if (error.code !== 'EXDEV') throw error
1878
+ fs.copyFileSync(path.join(dir, k.relPath), k.parked)
1879
+ fs.unlinkSync(path.join(dir, k.relPath))
1880
+ }
1881
+ parents.add(path.dirname(path.join(dir, k.relPath)))
1882
+ }
1883
+ // Folders our files left empty — a skill's own, then .claude/<kind>/ — and
1884
+ // never one that still holds something of the developer's.
1885
+ const stop = path.join(dir, '.claude')
1886
+ for (const start of parents) {
1887
+ for (let at = start; at.startsWith(stop + path.sep); at = path.dirname(at)) {
1888
+ try {
1889
+ if (fs.readdirSync(at).length) break
1890
+ fs.rmdirSync(at)
1891
+ } catch {
1892
+ break
1893
+ }
1894
+ }
1895
+ }
1896
+ // A disabled install's switches go too, or they would outlive what they name.
1897
+ clearSwitches(dir)
1898
+ if (hooks.reason === 'removed') {
1899
+ const done = removeHooks(dir, { local: true })
1900
+ if (done.emptied) fs.unlinkSync(path.join(dir, '.claude', 'settings.local.json'))
1901
+ }
1902
+ if (hasBlock) {
1903
+ const next = claudeText.replace(blockRe, '\n')
1904
+ if (next.trim()) fs.writeFileSync(claudeLocal, next.replace(/^\n+/, ''))
1905
+ else fs.unlinkSync(claudeLocal)
1906
+ }
1907
+ if (hasExclude) {
1908
+ const start = exclude.text.indexOf(EXCLUDE_START)
1909
+ const end = exclude.text.indexOf(EXCLUDE_END, start)
1910
+ if (end !== -1) {
1911
+ fs.writeFileSync(exclude.file, exclude.text.slice(0, start) + exclude.text.slice(end + EXCLUDE_END.length).replace(/^\n/, ''))
1912
+ }
1913
+ }
1914
+ fs.rmSync(specEnv, { recursive: true, force: true })
1915
+ fs.unlinkSync(manifestAbs)
1916
+
1917
+ log(
1918
+ `uninstall: done (${dir})\n${lines.join('')}\n` +
1919
+ ` the CLI itself is still installed — npm uninstall -g ${distributionPackage()} removes it.\n`,
1920
+ )
1921
+ return 0
1922
+ }
1923
+
1924
+ // The git common dir's info/exclude, read — null when this is not a git repo.
1925
+ function localExcludeFile(dir) {
1926
+ let commonDir
1927
+ try {
1928
+ commonDir = path.resolve(
1929
+ dir,
1930
+ execFileSync('git', ['-C', dir, 'rev-parse', '--git-common-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(),
1931
+ )
1932
+ } catch {
1933
+ return null
1934
+ }
1935
+ const file = path.join(commonDir, 'info', 'exclude')
1936
+ let text = ''
1937
+ try {
1938
+ text = fs.readFileSync(file, 'utf8')
1939
+ } catch {
1940
+ /* no exclude file */
1941
+ }
1942
+ return { file, text }
1943
+ }
1944
+
1472
1945
  async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating, project, local = false }) {
1473
1946
  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
1474
1947
  resetReport()
1475
1948
  resolveScope(dir, local)
1476
1949
  if (scope === 'local') convertCommitted(dir)
1950
+ // Installing is enabling: a disabled install comes back on.
1951
+ if (scope === 'local' && !readManifest(dir).enabled) {
1952
+ clearSwitches(dir)
1953
+ report.updated.push('.claude/settings.local.json (skitterspec enabled)')
1954
+ }
1955
+ enabledOnFlush = true
1477
1956
 
1478
1957
  installSkills(dir, { force })
1479
1958
  installCommands(dir, { force })
@@ -1517,6 +1996,9 @@ module.exports = {
1517
1996
  isExistingSetup,
1518
1997
  resync,
1519
1998
  reset,
1999
+ uninstall,
2000
+ disable,
2001
+ enable,
1520
2002
  assertSafeToDelete,
1521
2003
  assertComposedAssets,
1522
2004
  detectPackageManager,