@skitterbyte/skitterspec-jira 2.4.0 → 2.5.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.
@@ -35,6 +35,11 @@ exactly one):
35
35
  npx @skitterbyte/skitterspec-jira init
36
36
  ```
37
37
 
38
+ **A project in a subfolder of its repo** (a solution folder beside `Sql/`,
39
+ say) installs and runs exactly the same way, from that folder: install the
40
+ package there or above it, and run `spec-sync` from it. `specs/.core/env.config.md`
41
+ → *A project in a subfolder of its repo* has the details.
42
+
38
43
  ## 2. Credentials — an email + API-token pair
39
44
 
40
45
  Jira Cloud authenticates REST calls with basic auth: your Atlassian account
@@ -68,6 +68,8 @@ through to a documented conservative default; see the field notes below.
68
68
  "worktree": {
69
69
  "root": "../{repo}-wt", // dir that holds all spec worktrees; sibling of
70
70
  // the primary checkout, never nested inside it.
71
+ // Resolved against the REPO root, even for a
72
+ // project in a subfolder of its repo (below).
71
73
  "folderPattern": "{slug}" // per-spec worktree dir name.
72
74
  },
73
75
 
@@ -141,7 +143,8 @@ through to a documented conservative default; see the field notes below.
141
143
  // typechecks, builds and tests work immediately instead of failing on a
142
144
  // missing node_modules. An array, run in order, stopping at the first that
143
145
  // exits non-zero; [] = none. Each string is a shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
144
- // expand (the cwd is already the worktree, so {worktreePath} is usually
146
+ // expand (the cwd is already the worktree — the project folder inside it, for a
147
+ // project in a subfolder of its repo — so {worktreePath} is usually
145
148
  // redundant). Example: ["pnpm install --frozen-lockfile"].
146
149
  // An entry may also be { "run": "<cmd>", "when": ["<glob>", ...] }. `when` is
147
150
  // IGNORED here — a fresh worktree always runs every setup step — and exists
@@ -659,9 +662,57 @@ through to a documented conservative default; see the field notes below.
659
662
  }
660
663
  ```
661
664
 
665
+ ## A project in a subfolder of its repo
666
+
667
+ Most projects ARE their repo: `specs/` and `.claude/` sit at the git root. Some
668
+ cannot — a Visual Studio solution folder beside `Sql/` and a prototype or two,
669
+ where sessions start in the solution folder, so that is where `.claude/` must be
670
+ for its skills and hooks to load, and where `specs/` belongs. That works with no
671
+ configuration:
672
+
673
+ ```
674
+ C:\Code\LSC App\ ← git root
675
+ ├── FF.CSC.Solution\ ← the project: specs/, .claude/, run Claude here
676
+ ├── Sql\
677
+ └── Prototype\
678
+ C:\Code\LSC App-wt\<spec>\ ← each spec's worktree, beside the repo
679
+ ```
680
+
681
+ - **The project is found, not configured.** Every `spec-env` verb walks up from
682
+ where it is run to the nearest folder holding `specs/.core/`, stopping at the
683
+ git root. Found at the root, it behaves exactly as it always has; found in a
684
+ subfolder, that subfolder is the project — from inside it or anywhere beneath
685
+ it. `spec-env resolve` and `skitterspec status` print a
686
+ `subfolder: FF.CSC.Solution/ (in repo C:\Code\LSC App)` line when it is not
687
+ the root, and nothing extra when it is. Several projects in one repo are not
688
+ supported: the nearest `specs/.core/` wins.
689
+ - **Repo-level things resolve against the repo root**: `worktree.root`, `{repo}`
690
+ (`LSC App`, not the project folder's name) and therefore the worktree layout.
691
+ A spec's worktree is a checkout of the whole repo, with the project at the same
692
+ place inside it.
693
+ - **Everything in this file is project-relative**: `setup`, `dev`, seed files,
694
+ `docker.composeFile` and `docker.envFile`, `registry`, `spec.companionPaths`,
695
+ and the folder `/spec-start` moves the session into
696
+ (`<worktree>/FF.CSC.Solution`). Git commands run against the worktree.
697
+ - **The review page lists git paths**, so the project's files carry its folder
698
+ (`FF.CSC.Solution/specs/…`) and a change beside it (`Sql/…`) is shown as code.
699
+ - **The main guard covers the whole primary checkout**, not only the project
700
+ folder: a write to `Sql/` on the base branch is unreviewed work too.
701
+ - **Install skitterspec in the project folder or above it.** The hooks find the
702
+ engine by walking UP from the session's folder to a `node_modules/.bin`; an
703
+ install below the project (say an Angular `ClientApp/node_modules`) is not
704
+ found, and the hooks fall back to `skitterspec` on your PATH.
705
+ - **Run `spec-sync` from the project folder.** The tracker providers take the
706
+ project from where they are run (or `--dir`); `release.ignorePaths` are read
707
+ against the project, so `specs/` means the project's.
708
+ - **Windows**: git prints `/` and paths with spaces are quoted in every command
709
+ the engine prints. A deep spec folder inside a worktree can pass 260
710
+ characters — set `git config --global core.longpaths true` once.
711
+
662
712
  ## Token expansion
663
713
 
664
- - `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
714
+ - `{repo}` — the repo root's dir basename (e.g. `skitterspec`) — the primary
715
+ checkout's root, which for a project in a subfolder is the folder above it.
665
716
  - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
666
717
  (safe for a `COMPOSE_PROJECT_NAME`).
667
718
  - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
@@ -81,12 +81,22 @@ function readPayload() {
81
81
  * the local install is looked for by path first — walking up from the project,
82
82
  * because a git worktree's checkout has its own `node_modules`.
83
83
  */
84
- function findEngine(projectDir) {
84
+ const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
85
+
86
+ function findEngine(projectDir, platform = process.platform) {
85
87
  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
86
88
  let at = projectDir
87
89
  for (let i = 0; i < 6 && at; i++) {
88
- for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
89
- const candidate = path.join(at, 'node_modules', '.bin', name)
90
+ for (const name of ENGINES) {
91
+ // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
92
+ // shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
93
+ // `.cmd` beside it needs a shell — which a hook handing a tool's command
94
+ // line over as an argument must never use. Unreachable, the hook failed
95
+ // open, and every guard was silently off on Windows (chore-windows-ci).
96
+ const candidate =
97
+ platform === 'win32'
98
+ ? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
99
+ : path.join(at, 'node_modules', '.bin', name)
90
100
  if (fs.existsSync(candidate)) return candidate
91
101
  }
92
102
  const up = path.dirname(at)
@@ -96,6 +106,13 @@ function findEngine(projectDir) {
96
106
  return 'skitterspec'
97
107
  }
98
108
 
109
+ // How to run what `findEngine` found: a `.js` engine through this node, since
110
+ // Windows cannot execute one directly — anything else as itself, as before.
111
+ function engineCommand(projectDir, platform = process.platform) {
112
+ const engine = findEngine(projectDir, platform)
113
+ return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
114
+ }
115
+
99
116
  // The tools that write a file. A matcher is configured too, but a hook that is
100
117
  // reached some other way must still be inert rather than guessing.
101
118
  //
@@ -147,7 +164,8 @@ function main() {
147
164
  const target = writeTarget(payload.tool_input)
148
165
  if (target) argv.push('--path', target)
149
166
 
150
- const result = spawnSync(findEngine(cwd), argv, { cwd, encoding: 'utf8', timeout: 8000 })
167
+ const engine = engineCommand(cwd)
168
+ const result = spawnSync(engine.file, [...engine.args, ...argv], { cwd, encoding: 'utf8', timeout: 8000 })
151
169
 
152
170
  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
153
171
  // process never ran or was killed, and neither is a refusal.
@@ -175,4 +193,4 @@ if (require.main === module) {
175
193
  }
176
194
  }
177
195
 
178
- module.exports = { findEngine, WRITE_TOOLS, writeTarget, isRefusal }
196
+ module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
@@ -78,12 +78,22 @@ function readPayload() {
78
78
  * is the fallback for a global install, and `SKITTERSPEC_BIN` overrides
79
79
  * everything for anyone whose layout is neither.
80
80
  */
81
- function findEngine(projectDir) {
81
+ const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
82
+
83
+ function findEngine(projectDir, platform = process.platform) {
82
84
  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
83
85
  let at = projectDir
84
86
  for (let i = 0; i < 6 && at; i++) {
85
- for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
86
- const candidate = path.join(at, 'node_modules', '.bin', name)
87
+ for (const name of ENGINES) {
88
+ // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
89
+ // shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
90
+ // `.cmd` beside it needs a shell — which a hook handing a tool's command
91
+ // line over as an argument must never use. Unreachable, the hook failed
92
+ // open, and every guard was silently off on Windows (chore-windows-ci).
93
+ const candidate =
94
+ platform === 'win32'
95
+ ? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
96
+ : path.join(at, 'node_modules', '.bin', name)
87
97
  if (fs.existsSync(candidate)) return candidate
88
98
  }
89
99
  const up = path.dirname(at)
@@ -93,6 +103,13 @@ function findEngine(projectDir) {
93
103
  return 'skitterspec'
94
104
  }
95
105
 
106
+ // How to run what `findEngine` found: a `.js` engine through this node, since
107
+ // Windows cannot execute one directly — anything else as itself, as before.
108
+ function engineCommand(projectDir, platform = process.platform) {
109
+ const engine = findEngine(projectDir, platform)
110
+ return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
111
+ }
112
+
96
113
  // The engine's own refusal line, from `spec-env review gate --check`. Pure.
97
114
  //
98
115
  // WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
@@ -117,9 +134,10 @@ function main() {
117
134
  // its own checkout, and the answer differs per worktree.
118
135
  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
119
136
 
137
+ const engine = engineCommand(cwd)
120
138
  const result = spawnSync(
121
- findEngine(cwd),
122
- ['spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
139
+ engine.file,
140
+ [...engine.args, 'spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
123
141
  { cwd, encoding: 'utf8', timeout: 8000 },
124
142
  )
125
143
 
@@ -160,4 +178,4 @@ if (require.main === module) {
160
178
  }
161
179
  }
162
180
 
163
- module.exports = { findEngine, isRefusal }
181
+ module.exports = { findEngine, engineCommand, isRefusal }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-jira",
3
- "version": "2.4.0",
3
+ "version": "2.5.0",
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
@@ -67,7 +67,6 @@ const {
67
67
  liveWorktreePaths,
68
68
  collectSpecFolders,
69
69
  allSpecs,
70
- resolvePrimaryCheckout,
71
70
  assertPrimaryOnMain,
72
71
  currentBranch,
73
72
  repoInfo,
@@ -76,6 +75,17 @@ const {
76
75
  parseBaseVersion,
77
76
  BUCKETS,
78
77
  } = require('./env/resolve.js')
78
+ const {
79
+ primaryAnchor,
80
+ attachProject,
81
+ repoRootOf,
82
+ prefixOf,
83
+ toRepoPath,
84
+ projectRelative,
85
+ projectIn,
86
+ projectLine,
87
+ shellPath,
88
+ } = require('./env/project.js')
79
89
  const building = require('./env/building.js')
80
90
  const {
81
91
  readReceipt,
@@ -467,7 +477,12 @@ function provisionedSpecs(dir, config) {
467
477
  const worktreePaths = liveWorktreePaths(gitReader(dir))
468
478
  return (
469
479
  allSpecs(dir, config, worktreePaths, speclessMap(dir, config))
470
- .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath), specless: s.specless }))
480
+ .map((s) => ({
481
+ folder: s.folder,
482
+ wt: path.resolve(s.worktreePath),
483
+ project: path.resolve(s.projectPath),
484
+ specless: s.specless,
485
+ }))
471
486
  // The primary checkout is itself in `git worktree list`; a spec is
472
487
  // provisioned only when it has its OWN worktree, separate from it.
473
488
  .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
@@ -489,7 +504,7 @@ function specEnvStatus(dir, config) {
489
504
  const registry = readRegistry(dir, config)
490
505
  const rows = collectInFlight({ dir, provisioned })
491
506
  process.stdout.write('Provisioned specs:\n')
492
- for (const [i, { folder, wt, specless }] of provisioned.entries()) {
507
+ for (const [i, { folder, project, specless }] of provisioned.entries()) {
493
508
  const slot = registry.slots[folder]
494
509
  let ports = ''
495
510
  if (slot !== undefined) {
@@ -504,7 +519,8 @@ function specEnvStatus(dir, config) {
504
519
  // The worktree's own reading — bucket, progress, any legacy header — after
505
520
  // everything this line already carried, so the line is a superset of it.
506
521
  const detail = specless ? '' : ` ${detailOf(rows[i])}`
507
- process.stdout.write(` ${folder}${tag}${ports}${detail}\n ${path.relative(dir, wt) || wt}\n`)
522
+ // The project folder inside the worktree: where a session works on it.
523
+ process.stdout.write(` ${folder}${tag}${ports}${detail}\n ${path.relative(dir, project) || project}\n`)
508
524
  }
509
525
  process.stdout.write(waitingSection(dir, config))
510
526
  }
@@ -518,8 +534,10 @@ function inFlightStatus(argv) {
518
534
  const json = argv.includes('--json')
519
535
  const at = argv.indexOf('--dir')
520
536
  const from = path.resolve(at !== -1 && argv[at + 1] ? argv[at + 1] : process.cwd())
521
- const dir = resolvePrimaryCheckout(from, gitReader(from))
537
+ const anchor = primaryAnchor(from, gitReader(from))
538
+ const dir = anchor.dir
522
539
  const { config, present } = loadEnvConfig(dir)
540
+ attachProject(config, anchor)
523
541
  const rows = present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []
524
542
  if (json) {
525
543
  const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
@@ -530,7 +548,7 @@ function inFlightStatus(argv) {
530
548
  process.stdout.write('no specs in flight — isolation is not enabled here, so no spec has a worktree.\n')
531
549
  return
532
550
  }
533
- process.stdout.write(formatInFlight(rows, { dir }))
551
+ process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
534
552
  }
535
553
 
536
554
  // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -582,9 +600,14 @@ function specOnForkPoint(dir, git, spec, config) {
582
600
  // points outside this repo entirely (`../<repo>-wt/<slug>/specs/...`) — a path
583
601
  // no `cat-file` or `log` can ever match, which turned every in-flight spec
584
602
  // into "not committed" and silently emptied the `it is on <branch>` hint too.
603
+ //
604
+ // `<ref>:<path>` names a path from the REPO ROOT, while the `log` pathspec
605
+ // below is relative to `dir`, the project folder — so the first needs the
606
+ // project's prefix and the second must not have it (feat-subfolder-project).
585
607
  const rels = BUCKETS.map((bucket) => `specs/${bucket}/${spec.folder}`)
608
+ const prefix = prefixOf(config)
586
609
  for (const rel of rels) {
587
- if (git(['cat-file', '-e', `${spec.forkFrom || 'HEAD'}:${rel}/00-overview.md`]) !== null) {
610
+ if (git(['cat-file', '-e', `${spec.forkFrom || 'HEAD'}:${toRepoPath(rel, prefix)}/00-overview.md`]) !== null) {
588
611
  return { onFork: true, foundOn: null }
589
612
  }
590
613
  }
@@ -910,7 +933,7 @@ function specEnvNospec(dir, config, name, flags = {}) {
910
933
  `spec-env nospec: ${name} ` +
911
934
  (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
912
935
  '',
913
- ` worktree: ${spec.worktreePath}`,
936
+ ` worktree: ${spec.projectPath}`,
914
937
  ` branch: ${spec.branch}`,
915
938
  ' stack: worktree-only (no docker, no port block)',
916
939
  ` recorded: ${already ? 'already in' : 'added to'} ${config.registry} as a specless branch`,
@@ -930,8 +953,8 @@ function specEnvNospec(dir, config, name, flags = {}) {
930
953
  out.push(' to provision, run:')
931
954
  out.push(
932
955
  attached
933
- ? ` git worktree add ${spec.worktreePath} ${spec.branch}`
934
- : ` git worktree add ${spec.worktreePath} -b ${spec.branch}`,
956
+ ? ` git worktree add ${shellPath(spec.worktreePath)} ${spec.branch}`
957
+ : ` git worktree add ${shellPath(spec.worktreePath)} -b ${spec.branch}`,
935
958
  )
936
959
  const seeds = (config.seedFiles && config.seedFiles.files) || []
937
960
  if (seeds.length || (config.setup || []).length) out.push(...bootstrapLines(name))
@@ -1226,7 +1249,9 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1226
1249
  (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
1227
1250
  )
1228
1251
  out.push('')
1229
- out.push(` worktree: ${plan.worktreePath}`)
1252
+ // Where the session moves to: the project folder inside the worktree, which
1253
+ // is the worktree itself unless the project sits in a subfolder of its repo.
1254
+ out.push(` worktree: ${plan.projectPath}`)
1230
1255
  out.push(` branch: ${plan.branch}`)
1231
1256
  if (plan.slot !== null) {
1232
1257
  const hi = plan.portOffset + config.docker.portsPerSpec - 1
@@ -1404,7 +1429,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1404
1429
  if (json) {
1405
1430
  say(
1406
1431
  JSON.stringify(
1407
- { spec: name, worktree: spec.worktreePath, docs, planned: true, steps },
1432
+ { spec: name, worktree: spec.projectPath, docs, planned: true, steps },
1408
1433
  null,
1409
1434
  2,
1410
1435
  ),
@@ -1413,7 +1438,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1413
1438
  }
1414
1439
  say(`spec-env bootstrap: ${name} (plan — nothing run)`)
1415
1440
  say('')
1416
- say(` worktree: ${spec.worktreePath}`)
1441
+ say(` worktree: ${spec.projectPath}`)
1417
1442
  if (!steps.length) say(' steps: none — nothing configured to run')
1418
1443
  else steps.forEach((st, i) => say(` ${i + 1}. ${describeStep(st)}`))
1419
1444
  return
@@ -1421,10 +1446,13 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1421
1446
 
1422
1447
  if (!json) {
1423
1448
  say(`spec-env bootstrap: ${name}`)
1424
- say(` worktree: ${spec.worktreePath}`)
1449
+ say(` worktree: ${spec.projectPath}`)
1425
1450
  }
1451
+ // The project folder inside the worktree: setup, seeds and the env file are
1452
+ // all project-relative, as `env.config.json` is (feat-subfolder-project,
1453
+ // decision 5). `mainRoot` is the same folder in the primary checkout.
1426
1454
  const result = runBootstrap(steps, {
1427
- cwd: spec.worktreePath,
1455
+ cwd: spec.projectPath,
1428
1456
  mainRoot: dir,
1429
1457
  // Report lines go to stdout as plain text; under --json they are carried in
1430
1458
  // the payload instead, and spawned output is moved to stderr with them.
@@ -1437,7 +1465,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1437
1465
  JSON.stringify(
1438
1466
  {
1439
1467
  spec: name,
1440
- worktree: spec.worktreePath,
1468
+ worktree: spec.projectPath,
1441
1469
  docs,
1442
1470
  planned: false,
1443
1471
  ok: result.ok,
@@ -1489,7 +1517,7 @@ function bootstrapLines(name, { docs = false } = {}) {
1489
1517
  // the same directory. Cannot-tell (either missing) is "not the same".
1490
1518
  function sameDir(a, b) {
1491
1519
  try {
1492
- return fs.realpathSync(a) === fs.realpathSync(b)
1520
+ return fs.realpathSync.native(a) === fs.realpathSync.native(b)
1493
1521
  } catch {
1494
1522
  return false
1495
1523
  }
@@ -1947,7 +1975,7 @@ function provisionedSpecChoice(dir, config, cwd = process.cwd()) {
1947
1975
  // so a nested worktree is not shadowed by an ancestor one.
1948
1976
  let here
1949
1977
  try {
1950
- here = fs.realpathSync(path.resolve(cwd))
1978
+ here = fs.realpathSync.native(path.resolve(cwd))
1951
1979
  } catch {
1952
1980
  here = path.resolve(cwd)
1953
1981
  }
@@ -1993,10 +2021,11 @@ function resolveSpecWithWorktree(dir, config, specArg) {
1993
2021
  // one where a missing spec was previously a usage error.
1994
2022
  specArg = specArg || soleProvisionedSpec(dir, config)
1995
2023
  const { slug } = splitPrefix(path.basename(specArg))
1996
- const { repo, repoSlug } = repoInfo(dir)
2024
+ const root = repoRootOf(dir, config)
2025
+ const { repo, repoSlug } = repoInfo(root)
1997
2026
  const wtTokens = { repo, repoSlug, slug }
1998
2027
  const worktreeGuess = path.resolve(
1999
- dir,
2028
+ root,
2000
2029
  expandTokens(config.worktree.root, wtTokens),
2001
2030
  expandTokens(config.worktree.folderPattern, wtTokens),
2002
2031
  )
@@ -2073,7 +2102,7 @@ function specEnvPrune(dir, config, flags) {
2073
2102
  `spec-env prune: reaped a stale review-server pidfile (pid ${reapedPid} is gone).\n`,
2074
2103
  )
2075
2104
  }
2076
- const { repoSlug } = repoInfo(dir)
2105
+ const { repoSlug } = repoInfo(repoRootOf(dir, config))
2077
2106
 
2078
2107
  const vols = listRepoVolumes(repoSlug)
2079
2108
  if (!vols.ok) {
@@ -2260,7 +2289,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2260
2289
  process.stdout.write(
2261
2290
  `spec-env integrate: blocked — ${stranded} commit(s) are stranded on the detached ` +
2262
2291
  `HEAD of ${spec.worktreePath} (at ${head}), ahead of ${spec.branch}; re-isolating ` +
2263
- `would abandon them. Recover with \`git -C ${spec.worktreePath} branch <tmp> ${head}\`, ` +
2292
+ `would abandon them. Recover with \`git -C ${shellPath(spec.worktreePath)} branch <tmp> ${head}\`, ` +
2264
2293
  `reconcile onto ${spec.branch}, then re-run.\n`,
2265
2294
  )
2266
2295
  return
@@ -2519,7 +2548,7 @@ function specEnvHandoff(dir, config, specArg, flags = {}) {
2519
2548
  let phases = []
2520
2549
  if (worktree) {
2521
2550
  for (const bucket of BUCKETS) {
2522
- const folder = path.join(spec.worktreePath, 'specs', bucket, spec.folder)
2551
+ const folder = path.join(spec.projectPath, 'specs', bucket, spec.folder)
2523
2552
  if (!fs.existsSync(path.join(folder, '00-overview.md'))) continue
2524
2553
  phases = fs
2525
2554
  .readdirSync(folder)
@@ -2577,7 +2606,7 @@ function specEnvHandoff(dir, config, specArg, flags = {}) {
2577
2606
 
2578
2607
  function specEnvDisposition(dir, config, specArg, flags = {}) {
2579
2608
  const spec = resolveSpecWithWorktree(dir, config, specArg)
2580
- const tree = spec.worktreePath && fs.existsSync(spec.worktreePath) ? spec.worktreePath : dir
2609
+ const tree = spec.projectPath && fs.existsSync(spec.projectPath) ? spec.projectPath : dir
2581
2610
  let folder = null
2582
2611
  for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
2583
2612
  const p = path.join(tree, 'specs', bucket, spec.folder)
@@ -2794,14 +2823,14 @@ function hotfixFinish(dir, config, specArg, flags) {
2794
2823
  const cwd = process.cwd()
2795
2824
  const inside = (() => {
2796
2825
  try {
2797
- const rel = path.relative(fs.realpathSync(spec.worktreePath), fs.realpathSync(cwd))
2826
+ const rel = path.relative(fs.realpathSync.native(spec.worktreePath), fs.realpathSync.native(cwd))
2798
2827
  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
2799
2828
  } catch {
2800
2829
  return false
2801
2830
  }
2802
2831
  })()
2803
2832
  if (inside) {
2804
- refuse([`this shell is inside the worktree — \`cd ${dir}\` first, then re-run`])
2833
+ refuse([`this shell is inside the worktree — \`cd ${shellPath(dir)}\` first, then re-run`])
2805
2834
  return
2806
2835
  }
2807
2836
 
@@ -3089,8 +3118,8 @@ function specEnvHotfix(dir, config, positional, flags) {
3089
3118
  say('')
3090
3119
  say(` prod tag: ${tag} (cut locally — not pushed, nothing carried yet)`)
3091
3120
  say(` to deploy, push the branch, then the tag — re-run with --push, or run:`)
3092
- say(` git -C ${spec.worktreePath} push ${remote} ${spec.branch}`)
3093
- say(` git -C ${spec.worktreePath} push ${remote} ${tag}`)
3121
+ say(` git -C ${shellPath(spec.worktreePath)} push ${remote} ${spec.branch}`)
3122
+ say(` git -C ${shellPath(spec.worktreePath)} push ${remote} ${tag}`)
3094
3123
  say(` then re-run \`skitterspec spec-env hotfix land ${spec.folder}\` to carry the fix.`)
3095
3124
  } else if (result.ok) {
3096
3125
  say('')
@@ -3334,7 +3363,7 @@ function hotfixLandBranch(dir, config, spec, flags, { say, refuse, json }) {
3334
3363
  say(` held: nothing pushed — the push to ${remote} is what ${strategy === 'pr' ? 'opens the PR' : 'lands the fix'}.`)
3335
3364
  say(' re-run with --push, or run:')
3336
3365
  for (const ref of refs) {
3337
- say(` git -C ${spec.worktreePath} push ${st.force ? '--force-with-lease -u ' : ''}${remote} ${ref}`)
3366
+ say(` git -C ${shellPath(spec.worktreePath)} push ${st.force ? '--force-with-lease -u ' : ''}${remote} ${ref}`)
3338
3367
  }
3339
3368
  say(` then re-run \`skitterspec spec-env hotfix land ${spec.folder}\`.`)
3340
3369
  } else if (result.ok) {
@@ -3356,8 +3385,10 @@ function hotfixLandBranch(dir, config, spec, flags, { say, refuse, json }) {
3356
3385
  // anchored on the primary checkout by the dispatcher, so this reads the tree the
3357
3386
  // build must not be writing into. See env/building.js for why this is two
3358
3387
  // content-based queries rather than one `status --porcelain`.
3359
- function primaryPaths(dir) {
3360
- const git = gitReader(dir)
3388
+ // Read from the repo ROOT, so a build that leaked outside a subfolder project —
3389
+ // into `Sql/`, say — is still seen (feat-subfolder-project).
3390
+ function primaryPaths(dir, config) {
3391
+ const git = gitReader(repoRootOf(dir, config))
3361
3392
  return building.mergePaths(
3362
3393
  git(['diff', '--name-only', 'HEAD']),
3363
3394
  git(['ls-files', '--others', '--exclude-standard']),
@@ -3371,7 +3402,7 @@ function recordPrimary(dir, config, r) {
3371
3402
  spec: r.folder,
3372
3403
  worktreePath: r.worktreePath,
3373
3404
  primary: dir,
3374
- paths: primaryPaths(dir),
3405
+ paths: primaryPaths(dir, config),
3375
3406
  })
3376
3407
  fs.mkdirSync(path.dirname(file), { recursive: true })
3377
3408
  fs.writeFileSync(file, JSON.stringify(baseline, null, 2) + '\n')
@@ -3399,7 +3430,7 @@ function assertPrimaryClean(dir, config, r) {
3399
3430
  } catch {
3400
3431
  baseline = null
3401
3432
  }
3402
- const result = building.compare(baseline, primaryPaths(dir), {
3433
+ const result = building.compare(baseline, primaryPaths(dir, config), {
3403
3434
  spec: r.folder,
3404
3435
  worktreePath: r.worktreePath,
3405
3436
  primary: dir,
@@ -3445,8 +3476,9 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
3445
3476
  `spec: ${r.folder} (${r.specless ? 'no spec' : r.bucket})\n` +
3446
3477
  `type/slug: ${r.type} / ${r.slug}\n` +
3447
3478
  `branch: ${r.branch}\n` +
3448
- `worktree: ${r.worktreePath}\n` +
3449
- `project: ${r.projectName}\n`,
3479
+ `worktree: ${r.projectPath}\n` +
3480
+ `project: ${r.projectName}\n` +
3481
+ projectLine(config.project),
3450
3482
  )
3451
3483
  }
3452
3484
 
@@ -3611,7 +3643,10 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
3611
3643
  // is scoped to its cwd, so reading from a subdirectory would list only that
3612
3644
  // subdirectory's untracked files and report the rest of the spec as absent.
3613
3645
  const git = gitReader(invokedFrom)
3614
- const tree = git(['rev-parse', '--show-toplevel']) || invokedFrom
3646
+ // `path.resolve`d: git prints the toplevel with `/` on every platform
3647
+ // (`C:/Users/…` on Windows), and every other path here is an OS path.
3648
+ const top = git(['rev-parse', '--show-toplevel'])
3649
+ const tree = top ? path.resolve(top) : invokedFrom
3615
3650
  const paths = dirtyPaths(gitReader(tree))
3616
3651
 
3617
3652
  // Three states, not two (`.claude/rules/negative-checks.md` rule 4). A null
@@ -3637,16 +3672,23 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
3637
3672
  return
3638
3673
  }
3639
3674
 
3640
- const { owned, foreign } = classifyDirtyTree(spec, paths, config)
3675
+ // Classified as git paths from the tree's ROOT, reported relative to the
3676
+ // PROJECT folder in it — what a pathspec is when run from where a session
3677
+ // stands. The same thing at the root of a repo (feat-subfolder-project).
3678
+ const prefix = prefixOf(config)
3679
+ const split = classifyDirtyTree(spec, paths, config)
3680
+ const owned = split.owned.map((p) => projectRelative(p, prefix))
3681
+ const foreign = split.foreign.map((p) => projectRelative(p, prefix))
3682
+ const treeShown = prefix ? projectIn(tree, prefix) : tree
3641
3683
 
3642
3684
  if (flags.json) {
3643
- process.stdout.write(JSON.stringify({ spec: spec.folder, tree, owned, foreign }) + '\n')
3685
+ process.stdout.write(JSON.stringify({ spec: spec.folder, tree: treeShown, owned, foreign }) + '\n')
3644
3686
  return
3645
3687
  }
3646
3688
 
3647
3689
  const out = [
3648
3690
  `spec-env stage: ${spec.folder} — ${owned.length} owned, ${foreign.length} foreign`,
3649
- ` tree: ${tree}`,
3691
+ ` tree: ${treeShown}`,
3650
3692
  ]
3651
3693
  // An empty list is omitted rather than printed under its heading: a heading
3652
3694
  // with nothing beneath it reads as a finding.
@@ -3692,7 +3734,10 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
3692
3734
  */
3693
3735
  function resolveSpecDocs(config, spec, invokedFrom) {
3694
3736
  const git = gitReader(invokedFrom)
3695
- const tree = git(['rev-parse', '--show-toplevel']) || invokedFrom
3737
+ // `path.resolve`d: git prints the toplevel with `/` on every platform
3738
+ // (`C:/Users/…` on Windows), and every other path here is an OS path.
3739
+ const top = git(['rev-parse', '--show-toplevel'])
3740
+ const tree = top ? path.resolve(top) : invokedFrom
3696
3741
  // THE CLASSIFICATION IS SHARED with the review server's route for the same
3697
3742
  // spec (`specDocsIn`), so the served page and the written page cannot
3698
3743
  // disagree about which files they show. This function adds only the wording.
@@ -4061,7 +4106,7 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
4061
4106
  if (flags.forCommand !== undefined && judged.state === 'armed') {
4062
4107
  const inside = (child, parent) => {
4063
4108
  try {
4064
- const rel = path.relative(fs.realpathSync(parent), fs.realpathSync(child))
4109
+ const rel = path.relative(fs.realpathSync.native(parent), fs.realpathSync.native(child))
4065
4110
  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
4066
4111
  } catch {
4067
4112
  return false
@@ -4616,7 +4661,9 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4616
4661
  }),
4617
4662
  )
4618
4663
 
4619
- const readFrom = docs ? docs.tree : live.state === 'on' ? dir : spec.worktreePath
4664
+ // Always a git ROOT, so every path the reader prints is root-relative and
4665
+ // every pathspec it is handed means the same thing (feat-subfolder-project).
4666
+ const readFrom = docs ? docs.tree : live.state === 'on' ? repoRootOf(dir, config) : spec.worktreePath
4620
4667
  const git = rawGitReader(readFrom)
4621
4668
  const trimmed = gitReader(readFrom)
4622
4669
 
@@ -5262,7 +5309,9 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5262
5309
  // The paths a committing verdict on this page must commit, so the
5263
5310
  // skill that routes on it never recomputes the set the reader saw.
5264
5311
  // Absent for every other mode, which keeps their output identical.
5265
- ...(docs ? { docs: { paths: docs.owned } } : {}),
5312
+ // Project-relative: the pathspec `/commit` is handed runs from the
5313
+ // project folder.
5314
+ ...(docs ? { docs: { paths: docs.owned.map((p) => projectRelative(p, prefixOf(config))) } } : {}),
5266
5315
  out,
5267
5316
  publishCopy,
5268
5317
  reader: reader.reader,
@@ -5474,7 +5523,7 @@ async function specEnvDev(dir, config, positional) {
5474
5523
  if (action === 'up') {
5475
5524
  const out = [`spec-env dev up: ${spec.folder} slot ${slot} (ports from ${plan.portOffset})`]
5476
5525
  for (const proc of plan.procs) {
5477
- const res = startProcess(proc, { cwd: spec.worktreePath, rootDir: dir })
5526
+ const res = startProcess(proc, { cwd: spec.projectPath, rootDir: dir })
5478
5527
  let health = ''
5479
5528
  if (proc.health) {
5480
5529
  health = (await waitHealthy(proc.health)) ? ' health: ok' : ' health: TIMEOUT'
@@ -5562,7 +5611,9 @@ function proxyProcFor(config, routesFileAbs) {
5562
5611
  const sdir = stateDirLabel(config)
5563
5612
  return {
5564
5613
  name: 'proxy',
5565
- command: `node ${path.join(__dirname, 'env', 'proxy.js')} ${routesFileAbs}`,
5614
+ // Quoted: this runs through `sh -c`, which eats a Windows path's
5615
+ // backslashes and splits any path with a space (chore-windows-ci).
5616
+ command: `node ${shellPath(path.join(__dirname, 'env', 'proxy.js'))} ${shellPath(routesFileAbs)}`,
5566
5617
  env: {},
5567
5618
  logFile: `${sdir}/logs/proxy.log`,
5568
5619
  pidFile: `${sdir}/pids/proxy.pid`,
@@ -5630,7 +5681,9 @@ function serveProcFor(config, settingsFileAbs, { root = null } = {}) {
5630
5681
  const sdir = stateDirLabel(config)
5631
5682
  return {
5632
5683
  name: 'review-serve',
5633
- command: `node ${daemonScript(root)} ${settingsFileAbs}`,
5684
+ // Quoted: this runs through `sh -c`, which eats a Windows path's
5685
+ // backslashes and splits any path with a space (chore-windows-ci).
5686
+ command: `node ${shellPath(daemonScript(root))} ${shellPath(settingsFileAbs)}`,
5634
5687
  script: daemonScript(root),
5635
5688
  env: {},
5636
5689
  logFile: `${sdir}/logs/review-serve.log`,
@@ -6818,11 +6871,15 @@ async function specEnv(rest) {
6818
6871
  // those two ask about the tree in front of you, and the two differ inside a
6819
6872
  // worktree.
6820
6873
  const invokedFrom = dir
6821
- // Anchor on the primary checkout so every subcommand resolves {repo}, worktree
6822
- // paths, and the registry identically whether run from main or a worktree.
6823
- dir = resolvePrimaryCheckout(dir, gitReader(dir))
6874
+ // Anchor on the project folder in the primary checkout so every subcommand
6875
+ // resolves {repo}, worktree paths, and the registry identically whether run
6876
+ // from main or a worktree — and from a project that sits in a subfolder of
6877
+ // its repo (env/project.js).
6878
+ const anchor = primaryAnchor(dir, gitReader(dir))
6879
+ dir = anchor.dir
6824
6880
 
6825
6881
  const { config, present, unknown, badReviewers } = loadEnvConfig(dir)
6882
+ attachProject(config, anchor)
6826
6883
  if (!present) {
6827
6884
  process.stdout.write(
6828
6885
  'spec-env: isolation not enabled (no specs/.core/env.config.json).\n' +