@skitterbyte/skitterspec-jira 2.4.0 → 2.5.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/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,
@@ -240,6 +250,8 @@ Usage:
240
250
  Docker stack (prints commands; creates nothing)
241
251
  --docs: a tree to write documents in — no
242
252
  setup commands, no Docker
253
+ --plan: write nothing, not even the trust
254
+ entry or the registry record
243
255
  bootstrap [spec] run the worktree's seeds, env file, setup
244
256
  and stack itself, in the worktree — after
245
257
  \`up\`'s worktree add (--docs: seeds only;
@@ -467,7 +479,12 @@ function provisionedSpecs(dir, config) {
467
479
  const worktreePaths = liveWorktreePaths(gitReader(dir))
468
480
  return (
469
481
  allSpecs(dir, config, worktreePaths, speclessMap(dir, config))
470
- .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath), specless: s.specless }))
482
+ .map((s) => ({
483
+ folder: s.folder,
484
+ wt: path.resolve(s.worktreePath),
485
+ project: path.resolve(s.projectPath),
486
+ specless: s.specless,
487
+ }))
471
488
  // The primary checkout is itself in `git worktree list`; a spec is
472
489
  // provisioned only when it has its OWN worktree, separate from it.
473
490
  .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
@@ -489,7 +506,7 @@ function specEnvStatus(dir, config) {
489
506
  const registry = readRegistry(dir, config)
490
507
  const rows = collectInFlight({ dir, provisioned })
491
508
  process.stdout.write('Provisioned specs:\n')
492
- for (const [i, { folder, wt, specless }] of provisioned.entries()) {
509
+ for (const [i, { folder, project, specless }] of provisioned.entries()) {
493
510
  const slot = registry.slots[folder]
494
511
  let ports = ''
495
512
  if (slot !== undefined) {
@@ -504,7 +521,8 @@ function specEnvStatus(dir, config) {
504
521
  // The worktree's own reading — bucket, progress, any legacy header — after
505
522
  // everything this line already carried, so the line is a superset of it.
506
523
  const detail = specless ? '' : ` ${detailOf(rows[i])}`
507
- process.stdout.write(` ${folder}${tag}${ports}${detail}\n ${path.relative(dir, wt) || wt}\n`)
524
+ // The project folder inside the worktree: where a session works on it.
525
+ process.stdout.write(` ${folder}${tag}${ports}${detail}\n ${path.relative(dir, project) || project}\n`)
508
526
  }
509
527
  process.stdout.write(waitingSection(dir, config))
510
528
  }
@@ -518,8 +536,10 @@ function inFlightStatus(argv) {
518
536
  const json = argv.includes('--json')
519
537
  const at = argv.indexOf('--dir')
520
538
  const from = path.resolve(at !== -1 && argv[at + 1] ? argv[at + 1] : process.cwd())
521
- const dir = resolvePrimaryCheckout(from, gitReader(from))
539
+ const anchor = primaryAnchor(from, gitReader(from))
540
+ const dir = anchor.dir
522
541
  const { config, present } = loadEnvConfig(dir)
542
+ attachProject(config, anchor)
523
543
  const rows = present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []
524
544
  if (json) {
525
545
  const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
@@ -530,7 +550,7 @@ function inFlightStatus(argv) {
530
550
  process.stdout.write('no specs in flight — isolation is not enabled here, so no spec has a worktree.\n')
531
551
  return
532
552
  }
533
- process.stdout.write(formatInFlight(rows, { dir }))
553
+ process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
534
554
  }
535
555
 
536
556
  // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -582,9 +602,14 @@ function specOnForkPoint(dir, git, spec, config) {
582
602
  // points outside this repo entirely (`../<repo>-wt/<slug>/specs/...`) — a path
583
603
  // no `cat-file` or `log` can ever match, which turned every in-flight spec
584
604
  // into "not committed" and silently emptied the `it is on <branch>` hint too.
605
+ //
606
+ // `<ref>:<path>` names a path from the REPO ROOT, while the `log` pathspec
607
+ // below is relative to `dir`, the project folder — so the first needs the
608
+ // project's prefix and the second must not have it (feat-subfolder-project).
585
609
  const rels = BUCKETS.map((bucket) => `specs/${bucket}/${spec.folder}`)
610
+ const prefix = prefixOf(config)
586
611
  for (const rel of rels) {
587
- if (git(['cat-file', '-e', `${spec.forkFrom || 'HEAD'}:${rel}/00-overview.md`]) !== null) {
612
+ if (git(['cat-file', '-e', `${spec.forkFrom || 'HEAD'}:${toRepoPath(rel, prefix)}/00-overview.md`]) !== null) {
588
613
  return { onFork: true, foundOn: null }
589
614
  }
590
615
  }
@@ -910,7 +935,7 @@ function specEnvNospec(dir, config, name, flags = {}) {
910
935
  `spec-env nospec: ${name} ` +
911
936
  (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
912
937
  '',
913
- ` worktree: ${spec.worktreePath}`,
938
+ ` worktree: ${spec.projectPath}`,
914
939
  ` branch: ${spec.branch}`,
915
940
  ' stack: worktree-only (no docker, no port block)',
916
941
  ` recorded: ${already ? 'already in' : 'added to'} ${config.registry} as a specless branch`,
@@ -930,8 +955,8 @@ function specEnvNospec(dir, config, name, flags = {}) {
930
955
  out.push(' to provision, run:')
931
956
  out.push(
932
957
  attached
933
- ? ` git worktree add ${spec.worktreePath} ${spec.branch}`
934
- : ` git worktree add ${spec.worktreePath} -b ${spec.branch}`,
958
+ ? ` git worktree add ${shellPath(spec.worktreePath)} ${spec.branch}`
959
+ : ` git worktree add ${shellPath(spec.worktreePath)} -b ${spec.branch}`,
935
960
  )
936
961
  const seeds = (config.seedFiles && config.seedFiles.files) || []
937
962
  if (seeds.length || (config.setup || []).length) out.push(...bootstrapLines(name))
@@ -1015,11 +1040,13 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1015
1040
  }
1016
1041
  const beforeAuth = readRegistry(dir, config)
1017
1042
  const resolved = resolveSpecless(specArg, dir, config, { spec: true })
1018
- writeRegistry(
1019
- dir,
1020
- config,
1021
- recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
1022
- )
1043
+ if (!flags.plan) {
1044
+ writeRegistry(
1045
+ dir,
1046
+ config,
1047
+ recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
1048
+ )
1049
+ }
1023
1050
  spec = resolved
1024
1051
  const fork = fromVersion || releaseFork
1025
1052
  if (fork) {
@@ -1149,8 +1176,12 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1149
1176
  // Trust the shared worktree root so edits into the freshly-provisioned worktree
1150
1177
  // don't prompt. One absolute entry (the root) covers every spec; self-heals on
1151
1178
  // every provision for teammates who only cloned and ran /spec-start.
1179
+ //
1180
+ // `--plan` is the dry run: every write below is asked and not made, and the
1181
+ // report says "would". It was parsed and ignored once, so a plan headed
1182
+ // "nothing created yet" still wrote this entry into the operator's settings.
1152
1183
  const worktreeRootAbs = path.dirname(spec.worktreePath)
1153
- const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
1184
+ const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs, { dryRun: !!flags.plan })
1154
1185
 
1155
1186
  // Documents mode brings no stack up, so a Docker spec provisioned this way is
1156
1187
  // a worktree-only run. Asked through `resolveStack`, which `planUp` also
@@ -1181,7 +1212,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1181
1212
  Object.prototype.hasOwnProperty.call(before.slots, spec.folder) || worktreeOnDisk
1182
1213
  const alloc = allocateSlot(before, spec.folder)
1183
1214
  slot = alloc.slot
1184
- writeRegistry(dir, config, alloc.registry) // the engine's only write (Docker path)
1215
+ if (!flags.plan) writeRegistry(dir, config, alloc.registry) // the engine's only write (Docker path)
1185
1216
  } else {
1186
1217
  attached = worktreeOnDisk
1187
1218
  }
@@ -1226,7 +1257,9 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1226
1257
  (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
1227
1258
  )
1228
1259
  out.push('')
1229
- out.push(` worktree: ${plan.worktreePath}`)
1260
+ // Where the session moves to: the project folder inside the worktree, which
1261
+ // is the worktree itself unless the project sits in a subfolder of its repo.
1262
+ out.push(` worktree: ${plan.projectPath}`)
1230
1263
  out.push(` branch: ${plan.branch}`)
1231
1264
  if (plan.slot !== null) {
1232
1265
  const hi = plan.portOffset + config.docker.portsPerSpec - 1
@@ -1266,7 +1299,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1266
1299
  // the lane working rather than something the engine failed to find.
1267
1300
  if (authoring) {
1268
1301
  out.push(' authoring: no spec document yet — the skill writes it in the worktree')
1269
- out.push(` recorded: added to ${config.registry} until the spec is written`)
1302
+ out.push(` recorded: ${flags.plan ? 'would add to' : 'added to'} ${config.registry} until the spec is written`)
1270
1303
  }
1271
1304
  // Only where one was NAMED. The fork point is otherwise base HEAD, which is
1272
1305
  // the unremarkable case, and a line asserting it on every provision would
@@ -1298,10 +1331,8 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1298
1331
  `\n add ${worktreeRootAbs} to permissions.additionalDirectories yourself`,
1299
1332
  )
1300
1333
  } else {
1301
- out.push(
1302
- ` trusted: ${worktreeRootAbs} ` +
1303
- `(${trust.changed ? 'added to' : 'already in'} .claude/settings.local.json)`,
1304
- )
1334
+ const verb = !trust.changed ? 'already in' : flags.plan ? 'would add to' : 'added to'
1335
+ out.push(` trusted: ${worktreeRootAbs} (${verb} .claude/settings.local.json)`)
1305
1336
  }
1306
1337
  out.push(...specCommitLines(plan, spec.folder))
1307
1338
  out.push(...untouchedLines(plan))
@@ -1404,7 +1435,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1404
1435
  if (json) {
1405
1436
  say(
1406
1437
  JSON.stringify(
1407
- { spec: name, worktree: spec.worktreePath, docs, planned: true, steps },
1438
+ { spec: name, worktree: spec.projectPath, docs, planned: true, steps },
1408
1439
  null,
1409
1440
  2,
1410
1441
  ),
@@ -1413,7 +1444,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1413
1444
  }
1414
1445
  say(`spec-env bootstrap: ${name} (plan — nothing run)`)
1415
1446
  say('')
1416
- say(` worktree: ${spec.worktreePath}`)
1447
+ say(` worktree: ${spec.projectPath}`)
1417
1448
  if (!steps.length) say(' steps: none — nothing configured to run')
1418
1449
  else steps.forEach((st, i) => say(` ${i + 1}. ${describeStep(st)}`))
1419
1450
  return
@@ -1421,10 +1452,13 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1421
1452
 
1422
1453
  if (!json) {
1423
1454
  say(`spec-env bootstrap: ${name}`)
1424
- say(` worktree: ${spec.worktreePath}`)
1455
+ say(` worktree: ${spec.projectPath}`)
1425
1456
  }
1457
+ // The project folder inside the worktree: setup, seeds and the env file are
1458
+ // all project-relative, as `env.config.json` is (feat-subfolder-project,
1459
+ // decision 5). `mainRoot` is the same folder in the primary checkout.
1426
1460
  const result = runBootstrap(steps, {
1427
- cwd: spec.worktreePath,
1461
+ cwd: spec.projectPath,
1428
1462
  mainRoot: dir,
1429
1463
  // Report lines go to stdout as plain text; under --json they are carried in
1430
1464
  // the payload instead, and spawned output is moved to stderr with them.
@@ -1437,7 +1471,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
1437
1471
  JSON.stringify(
1438
1472
  {
1439
1473
  spec: name,
1440
- worktree: spec.worktreePath,
1474
+ worktree: spec.projectPath,
1441
1475
  docs,
1442
1476
  planned: false,
1443
1477
  ok: result.ok,
@@ -1489,7 +1523,7 @@ function bootstrapLines(name, { docs = false } = {}) {
1489
1523
  // the same directory. Cannot-tell (either missing) is "not the same".
1490
1524
  function sameDir(a, b) {
1491
1525
  try {
1492
- return fs.realpathSync(a) === fs.realpathSync(b)
1526
+ return fs.realpathSync.native(a) === fs.realpathSync.native(b)
1493
1527
  } catch {
1494
1528
  return false
1495
1529
  }
@@ -1947,7 +1981,7 @@ function provisionedSpecChoice(dir, config, cwd = process.cwd()) {
1947
1981
  // so a nested worktree is not shadowed by an ancestor one.
1948
1982
  let here
1949
1983
  try {
1950
- here = fs.realpathSync(path.resolve(cwd))
1984
+ here = fs.realpathSync.native(path.resolve(cwd))
1951
1985
  } catch {
1952
1986
  here = path.resolve(cwd)
1953
1987
  }
@@ -1993,10 +2027,11 @@ function resolveSpecWithWorktree(dir, config, specArg) {
1993
2027
  // one where a missing spec was previously a usage error.
1994
2028
  specArg = specArg || soleProvisionedSpec(dir, config)
1995
2029
  const { slug } = splitPrefix(path.basename(specArg))
1996
- const { repo, repoSlug } = repoInfo(dir)
2030
+ const root = repoRootOf(dir, config)
2031
+ const { repo, repoSlug } = repoInfo(root)
1997
2032
  const wtTokens = { repo, repoSlug, slug }
1998
2033
  const worktreeGuess = path.resolve(
1999
- dir,
2034
+ root,
2000
2035
  expandTokens(config.worktree.root, wtTokens),
2001
2036
  expandTokens(config.worktree.folderPattern, wtTokens),
2002
2037
  )
@@ -2073,7 +2108,7 @@ function specEnvPrune(dir, config, flags) {
2073
2108
  `spec-env prune: reaped a stale review-server pidfile (pid ${reapedPid} is gone).\n`,
2074
2109
  )
2075
2110
  }
2076
- const { repoSlug } = repoInfo(dir)
2111
+ const { repoSlug } = repoInfo(repoRootOf(dir, config))
2077
2112
 
2078
2113
  const vols = listRepoVolumes(repoSlug)
2079
2114
  if (!vols.ok) {
@@ -2260,7 +2295,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2260
2295
  process.stdout.write(
2261
2296
  `spec-env integrate: blocked — ${stranded} commit(s) are stranded on the detached ` +
2262
2297
  `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}\`, ` +
2298
+ `would abandon them. Recover with \`git -C ${shellPath(spec.worktreePath)} branch <tmp> ${head}\`, ` +
2264
2299
  `reconcile onto ${spec.branch}, then re-run.\n`,
2265
2300
  )
2266
2301
  return
@@ -2519,7 +2554,7 @@ function specEnvHandoff(dir, config, specArg, flags = {}) {
2519
2554
  let phases = []
2520
2555
  if (worktree) {
2521
2556
  for (const bucket of BUCKETS) {
2522
- const folder = path.join(spec.worktreePath, 'specs', bucket, spec.folder)
2557
+ const folder = path.join(spec.projectPath, 'specs', bucket, spec.folder)
2523
2558
  if (!fs.existsSync(path.join(folder, '00-overview.md'))) continue
2524
2559
  phases = fs
2525
2560
  .readdirSync(folder)
@@ -2577,7 +2612,7 @@ function specEnvHandoff(dir, config, specArg, flags = {}) {
2577
2612
 
2578
2613
  function specEnvDisposition(dir, config, specArg, flags = {}) {
2579
2614
  const spec = resolveSpecWithWorktree(dir, config, specArg)
2580
- const tree = spec.worktreePath && fs.existsSync(spec.worktreePath) ? spec.worktreePath : dir
2615
+ const tree = spec.projectPath && fs.existsSync(spec.projectPath) ? spec.projectPath : dir
2581
2616
  let folder = null
2582
2617
  for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
2583
2618
  const p = path.join(tree, 'specs', bucket, spec.folder)
@@ -2794,14 +2829,14 @@ function hotfixFinish(dir, config, specArg, flags) {
2794
2829
  const cwd = process.cwd()
2795
2830
  const inside = (() => {
2796
2831
  try {
2797
- const rel = path.relative(fs.realpathSync(spec.worktreePath), fs.realpathSync(cwd))
2832
+ const rel = path.relative(fs.realpathSync.native(spec.worktreePath), fs.realpathSync.native(cwd))
2798
2833
  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
2799
2834
  } catch {
2800
2835
  return false
2801
2836
  }
2802
2837
  })()
2803
2838
  if (inside) {
2804
- refuse([`this shell is inside the worktree — \`cd ${dir}\` first, then re-run`])
2839
+ refuse([`this shell is inside the worktree — \`cd ${shellPath(dir)}\` first, then re-run`])
2805
2840
  return
2806
2841
  }
2807
2842
 
@@ -3089,8 +3124,8 @@ function specEnvHotfix(dir, config, positional, flags) {
3089
3124
  say('')
3090
3125
  say(` prod tag: ${tag} (cut locally — not pushed, nothing carried yet)`)
3091
3126
  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}`)
3127
+ say(` git -C ${shellPath(spec.worktreePath)} push ${remote} ${spec.branch}`)
3128
+ say(` git -C ${shellPath(spec.worktreePath)} push ${remote} ${tag}`)
3094
3129
  say(` then re-run \`skitterspec spec-env hotfix land ${spec.folder}\` to carry the fix.`)
3095
3130
  } else if (result.ok) {
3096
3131
  say('')
@@ -3334,7 +3369,7 @@ function hotfixLandBranch(dir, config, spec, flags, { say, refuse, json }) {
3334
3369
  say(` held: nothing pushed — the push to ${remote} is what ${strategy === 'pr' ? 'opens the PR' : 'lands the fix'}.`)
3335
3370
  say(' re-run with --push, or run:')
3336
3371
  for (const ref of refs) {
3337
- say(` git -C ${spec.worktreePath} push ${st.force ? '--force-with-lease -u ' : ''}${remote} ${ref}`)
3372
+ say(` git -C ${shellPath(spec.worktreePath)} push ${st.force ? '--force-with-lease -u ' : ''}${remote} ${ref}`)
3338
3373
  }
3339
3374
  say(` then re-run \`skitterspec spec-env hotfix land ${spec.folder}\`.`)
3340
3375
  } else if (result.ok) {
@@ -3356,8 +3391,10 @@ function hotfixLandBranch(dir, config, spec, flags, { say, refuse, json }) {
3356
3391
  // anchored on the primary checkout by the dispatcher, so this reads the tree the
3357
3392
  // build must not be writing into. See env/building.js for why this is two
3358
3393
  // content-based queries rather than one `status --porcelain`.
3359
- function primaryPaths(dir) {
3360
- const git = gitReader(dir)
3394
+ // Read from the repo ROOT, so a build that leaked outside a subfolder project —
3395
+ // into `Sql/`, say — is still seen (feat-subfolder-project).
3396
+ function primaryPaths(dir, config) {
3397
+ const git = gitReader(repoRootOf(dir, config))
3361
3398
  return building.mergePaths(
3362
3399
  git(['diff', '--name-only', 'HEAD']),
3363
3400
  git(['ls-files', '--others', '--exclude-standard']),
@@ -3371,7 +3408,7 @@ function recordPrimary(dir, config, r) {
3371
3408
  spec: r.folder,
3372
3409
  worktreePath: r.worktreePath,
3373
3410
  primary: dir,
3374
- paths: primaryPaths(dir),
3411
+ paths: primaryPaths(dir, config),
3375
3412
  })
3376
3413
  fs.mkdirSync(path.dirname(file), { recursive: true })
3377
3414
  fs.writeFileSync(file, JSON.stringify(baseline, null, 2) + '\n')
@@ -3399,7 +3436,7 @@ function assertPrimaryClean(dir, config, r) {
3399
3436
  } catch {
3400
3437
  baseline = null
3401
3438
  }
3402
- const result = building.compare(baseline, primaryPaths(dir), {
3439
+ const result = building.compare(baseline, primaryPaths(dir, config), {
3403
3440
  spec: r.folder,
3404
3441
  worktreePath: r.worktreePath,
3405
3442
  primary: dir,
@@ -3445,8 +3482,9 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
3445
3482
  `spec: ${r.folder} (${r.specless ? 'no spec' : r.bucket})\n` +
3446
3483
  `type/slug: ${r.type} / ${r.slug}\n` +
3447
3484
  `branch: ${r.branch}\n` +
3448
- `worktree: ${r.worktreePath}\n` +
3449
- `project: ${r.projectName}\n`,
3485
+ `worktree: ${r.projectPath}\n` +
3486
+ `project: ${r.projectName}\n` +
3487
+ projectLine(config.project),
3450
3488
  )
3451
3489
  }
3452
3490
 
@@ -3611,7 +3649,10 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
3611
3649
  // is scoped to its cwd, so reading from a subdirectory would list only that
3612
3650
  // subdirectory's untracked files and report the rest of the spec as absent.
3613
3651
  const git = gitReader(invokedFrom)
3614
- const tree = git(['rev-parse', '--show-toplevel']) || invokedFrom
3652
+ // `path.resolve`d: git prints the toplevel with `/` on every platform
3653
+ // (`C:/Users/…` on Windows), and every other path here is an OS path.
3654
+ const top = git(['rev-parse', '--show-toplevel'])
3655
+ const tree = top ? path.resolve(top) : invokedFrom
3615
3656
  const paths = dirtyPaths(gitReader(tree))
3616
3657
 
3617
3658
  // Three states, not two (`.claude/rules/negative-checks.md` rule 4). A null
@@ -3637,16 +3678,23 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
3637
3678
  return
3638
3679
  }
3639
3680
 
3640
- const { owned, foreign } = classifyDirtyTree(spec, paths, config)
3681
+ // Classified as git paths from the tree's ROOT, reported relative to the
3682
+ // PROJECT folder in it — what a pathspec is when run from where a session
3683
+ // stands. The same thing at the root of a repo (feat-subfolder-project).
3684
+ const prefix = prefixOf(config)
3685
+ const split = classifyDirtyTree(spec, paths, config)
3686
+ const owned = split.owned.map((p) => projectRelative(p, prefix))
3687
+ const foreign = split.foreign.map((p) => projectRelative(p, prefix))
3688
+ const treeShown = prefix ? projectIn(tree, prefix) : tree
3641
3689
 
3642
3690
  if (flags.json) {
3643
- process.stdout.write(JSON.stringify({ spec: spec.folder, tree, owned, foreign }) + '\n')
3691
+ process.stdout.write(JSON.stringify({ spec: spec.folder, tree: treeShown, owned, foreign }) + '\n')
3644
3692
  return
3645
3693
  }
3646
3694
 
3647
3695
  const out = [
3648
3696
  `spec-env stage: ${spec.folder} — ${owned.length} owned, ${foreign.length} foreign`,
3649
- ` tree: ${tree}`,
3697
+ ` tree: ${treeShown}`,
3650
3698
  ]
3651
3699
  // An empty list is omitted rather than printed under its heading: a heading
3652
3700
  // with nothing beneath it reads as a finding.
@@ -3692,7 +3740,10 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
3692
3740
  */
3693
3741
  function resolveSpecDocs(config, spec, invokedFrom) {
3694
3742
  const git = gitReader(invokedFrom)
3695
- const tree = git(['rev-parse', '--show-toplevel']) || invokedFrom
3743
+ // `path.resolve`d: git prints the toplevel with `/` on every platform
3744
+ // (`C:/Users/…` on Windows), and every other path here is an OS path.
3745
+ const top = git(['rev-parse', '--show-toplevel'])
3746
+ const tree = top ? path.resolve(top) : invokedFrom
3696
3747
  // THE CLASSIFICATION IS SHARED with the review server's route for the same
3697
3748
  // spec (`specDocsIn`), so the served page and the written page cannot
3698
3749
  // disagree about which files they show. This function adds only the wording.
@@ -4061,7 +4112,7 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
4061
4112
  if (flags.forCommand !== undefined && judged.state === 'armed') {
4062
4113
  const inside = (child, parent) => {
4063
4114
  try {
4064
- const rel = path.relative(fs.realpathSync(parent), fs.realpathSync(child))
4115
+ const rel = path.relative(fs.realpathSync.native(parent), fs.realpathSync.native(child))
4065
4116
  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
4066
4117
  } catch {
4067
4118
  return false
@@ -4616,7 +4667,9 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4616
4667
  }),
4617
4668
  )
4618
4669
 
4619
- const readFrom = docs ? docs.tree : live.state === 'on' ? dir : spec.worktreePath
4670
+ // Always a git ROOT, so every path the reader prints is root-relative and
4671
+ // every pathspec it is handed means the same thing (feat-subfolder-project).
4672
+ const readFrom = docs ? docs.tree : live.state === 'on' ? repoRootOf(dir, config) : spec.worktreePath
4620
4673
  const git = rawGitReader(readFrom)
4621
4674
  const trimmed = gitReader(readFrom)
4622
4675
 
@@ -5262,7 +5315,9 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5262
5315
  // The paths a committing verdict on this page must commit, so the
5263
5316
  // skill that routes on it never recomputes the set the reader saw.
5264
5317
  // Absent for every other mode, which keeps their output identical.
5265
- ...(docs ? { docs: { paths: docs.owned } } : {}),
5318
+ // Project-relative: the pathspec `/commit` is handed runs from the
5319
+ // project folder.
5320
+ ...(docs ? { docs: { paths: docs.owned.map((p) => projectRelative(p, prefixOf(config))) } } : {}),
5266
5321
  out,
5267
5322
  publishCopy,
5268
5323
  reader: reader.reader,
@@ -5474,7 +5529,7 @@ async function specEnvDev(dir, config, positional) {
5474
5529
  if (action === 'up') {
5475
5530
  const out = [`spec-env dev up: ${spec.folder} slot ${slot} (ports from ${plan.portOffset})`]
5476
5531
  for (const proc of plan.procs) {
5477
- const res = startProcess(proc, { cwd: spec.worktreePath, rootDir: dir })
5532
+ const res = startProcess(proc, { cwd: spec.projectPath, rootDir: dir })
5478
5533
  let health = ''
5479
5534
  if (proc.health) {
5480
5535
  health = (await waitHealthy(proc.health)) ? ' health: ok' : ' health: TIMEOUT'
@@ -5562,7 +5617,9 @@ function proxyProcFor(config, routesFileAbs) {
5562
5617
  const sdir = stateDirLabel(config)
5563
5618
  return {
5564
5619
  name: 'proxy',
5565
- command: `node ${path.join(__dirname, 'env', 'proxy.js')} ${routesFileAbs}`,
5620
+ // Quoted: this runs through `sh -c`, which eats a Windows path's
5621
+ // backslashes and splits any path with a space (chore-windows-ci).
5622
+ command: `node ${shellPath(path.join(__dirname, 'env', 'proxy.js'))} ${shellPath(routesFileAbs)}`,
5566
5623
  env: {},
5567
5624
  logFile: `${sdir}/logs/proxy.log`,
5568
5625
  pidFile: `${sdir}/pids/proxy.pid`,
@@ -5630,7 +5687,9 @@ function serveProcFor(config, settingsFileAbs, { root = null } = {}) {
5630
5687
  const sdir = stateDirLabel(config)
5631
5688
  return {
5632
5689
  name: 'review-serve',
5633
- command: `node ${daemonScript(root)} ${settingsFileAbs}`,
5690
+ // Quoted: this runs through `sh -c`, which eats a Windows path's
5691
+ // backslashes and splits any path with a space (chore-windows-ci).
5692
+ command: `node ${shellPath(daemonScript(root))} ${shellPath(settingsFileAbs)}`,
5634
5693
  script: daemonScript(root),
5635
5694
  env: {},
5636
5695
  logFile: `${sdir}/logs/review-serve.log`,
@@ -6818,11 +6877,15 @@ async function specEnv(rest) {
6818
6877
  // those two ask about the tree in front of you, and the two differ inside a
6819
6878
  // worktree.
6820
6879
  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))
6880
+ // Anchor on the project folder in the primary checkout so every subcommand
6881
+ // resolves {repo}, worktree paths, and the registry identically whether run
6882
+ // from main or a worktree — and from a project that sits in a subfolder of
6883
+ // its repo (env/project.js).
6884
+ const anchor = primaryAnchor(dir, gitReader(dir))
6885
+ dir = anchor.dir
6824
6886
 
6825
6887
  const { config, present, unknown, badReviewers } = loadEnvConfig(dir)
6888
+ attachProject(config, anchor)
6826
6889
  if (!present) {
6827
6890
  process.stdout.write(
6828
6891
  'spec-env: isolation not enabled (no specs/.core/env.config.json).\n' +
@@ -61,7 +61,7 @@ function lstatOrNull(fs, p) {
61
61
  * The target is tested with `lstat`, which does not: an existing link, even a
62
62
  * dangling one, is somebody's deliberate state and is left alone.
63
63
  */
64
- function runSeed(step, { cwd, mainRoot, fs }) {
64
+ function runSeed(step, { cwd, mainRoot, fs, platform = process.platform }) {
65
65
  const src = path.join(mainRoot, step.file)
66
66
  const dst = path.join(cwd, step.file)
67
67
  if (!fs.existsSync(src)) {
@@ -71,8 +71,26 @@ function runSeed(step, { cwd, mainRoot, fs }) {
71
71
  return { outcome: 'skipped', line: `seed ${step.file}: exists — skipped` }
72
72
  }
73
73
  fs.mkdirSync(path.dirname(dst), { recursive: true })
74
- if (step.mode === 'copy') fs.copyFileSync(src, dst)
75
- else fs.symlinkSync(src, dst)
74
+ if (step.mode === 'copy') {
75
+ fs.copyFileSync(src, dst)
76
+ return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
77
+ }
78
+ // WINDOWS WITHOUT DEVELOPER MODE CANNOT CREATE A SYMLINK (EPERM), and a
79
+ // seed is what makes a fresh worktree runnable at all (chore-windows-ci). A
80
+ // directory takes a junction there, which needs no privilege; a file that
81
+ // still cannot be linked is copied — said, because a copy does not follow
82
+ // later edits to the primary checkout's file the way a link would.
83
+ const dir = fs.statSync(src).isDirectory()
84
+ try {
85
+ fs.symlinkSync(src, dst, dir && platform === 'win32' ? 'junction' : undefined)
86
+ } catch (err) {
87
+ if (dir || !(err && (err.code === 'EPERM' || err.code === 'EACCES'))) throw err
88
+ fs.copyFileSync(src, dst)
89
+ return {
90
+ outcome: 'seeded',
91
+ line: `seeded ${step.file} → ${src} (copied — this machine cannot create symlinks)`,
92
+ }
93
+ }
76
94
  return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
77
95
  }
78
96
 
@@ -157,6 +175,7 @@ function runBootstrap(steps, io) {
157
175
  cwd: io.cwd,
158
176
  mainRoot: io.mainRoot,
159
177
  fs: io.fs || realFs,
178
+ platform: io.platform || process.platform,
160
179
  spawn: io.spawn || spawnSync,
161
180
  childStdout: io.childStdout || 'inherit',
162
181
  }
@@ -17,6 +17,7 @@
17
17
 
18
18
  const path = require('node:path')
19
19
  const { BUCKETS, expandTokens, readFrontmatterField } = require('./resolve.js')
20
+ const { fromRepoPath, prefixOf } = require('./project.js')
20
21
 
21
22
  // git reports repo-relative, forward-slashed paths; an untracked directory comes
22
23
  // back with a trailing slash. Normalise both away so comparisons are exact.
@@ -66,7 +67,9 @@ function expandCompanion(pattern, spec, config) {
66
67
  /**
67
68
  * Split `dirtyPaths` into the ones that belong to `spec` and the ones that do
68
69
  * not. Repo-relative paths in, repo-relative paths out; nothing is read from git
69
- * and nothing is written.
70
+ * and nothing is written. The spec's folders and companion paths are
71
+ * PROJECT-relative, so each path is converted with the config's prefix before it
72
+ * is compared — a path outside a subfolder project is never the spec's.
70
73
  *
71
74
  * Owned:
72
75
  * - anything inside `specs/<bucket>/<folder>/` for ANY bucket. Every bucket is
@@ -89,11 +92,13 @@ function classifyDirtyTree(spec, dirtyPaths, config) {
89
92
  if (expanded) companions.add(expanded)
90
93
  }
91
94
 
95
+ const prefix = prefixOf(config)
92
96
  for (const raw of dirtyPaths || []) {
93
97
  const p = normalize(raw)
94
98
  if (!p) continue
95
- const inFolder = folders.some((f) => p === f || p.startsWith(`${f}/`))
96
- if (inFolder || companions.has(p)) owned.push(p)
99
+ const rel = fromRepoPath(p, prefix)
100
+ const inFolder = rel !== null && folders.some((f) => rel === f || rel.startsWith(`${f}/`))
101
+ if (inFolder || (rel !== null && companions.has(rel))) owned.push(p)
97
102
  else foreign.push(p)
98
103
  }
99
104
  return { owned, foreign }
@@ -129,7 +134,10 @@ function unquotePath(p) {
129
134
  function dirtyPaths(git) {
130
135
  const lists = [
131
136
  git(['diff', '--name-only', 'HEAD']),
132
- git(['ls-files', '--others', '--exclude-standard']),
137
+ // `--full-name`: `ls-files` answers relative to its cwd, `diff` from the repo
138
+ // root. Read from a subfolder project they disagreed, and every untracked
139
+ // spec document was classified as somebody else's.
140
+ git(['ls-files', '--others', '--exclude-standard', '--full-name']),
133
141
  ]
134
142
  if (lists.every((l) => l === null)) return null
135
143
  const out = []
package/src/env/config.js CHANGED
@@ -61,7 +61,7 @@
61
61
 
62
62
  const { createHash } = require('node:crypto')
63
63
  const { readFileSync, realpathSync } = require('node:fs')
64
- const { join, resolve } = require('node:path')
64
+ const { join, resolve, sep } = require('node:path')
65
65
 
66
66
  const CONFIG_FILE = join('specs', '.core', 'env.config.json')
67
67
 
@@ -891,7 +891,7 @@ function loadEnvConfig(dir = process.cwd()) {
891
891
  try {
892
892
  parsed = JSON.parse(raw)
893
893
  } catch (error) {
894
- throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
894
+ throw new Error(`Invalid ${CONFIG_FILE.split(sep).join('/')}: ${error.message}`)
895
895
  }
896
896
 
897
897
  return {
@@ -15,6 +15,7 @@
15
15
  */
16
16
 
17
17
  const { phaseProgress, progressText } = require('./phases.js')
18
+ const { shellPath } = require('./project.js')
18
19
 
19
20
  // Uncommitted work cannot travel with a push, so a hand-over would silently
20
21
  // leave it behind in the old worktree. The engine declares the way out rather
@@ -55,7 +56,7 @@ function planHandoff(f) {
55
56
  // unpublished branch and a stale one both need it, and a remote that could
56
57
  // not be asked is planned as if it does (a redundant push is harmless).
57
58
  const published = Boolean(f.headSha && f.remoteSha && f.remoteSha === f.headSha)
58
- const commands = published ? [] : [`git -C ${spec.worktreePath} push -u ${f.remote} ${spec.branch}`]
59
+ const commands = published ? [] : [`git -C ${shellPath(spec.worktreePath)} push -u ${f.remote} ${spec.branch}`]
59
60
  const sha = (f.headSha || '').slice(0, 12)
60
61
  const note = [
61
62
  `**Handed over** — the work is on \`${spec.branch}\` at \`${sha}\` (${f.remote}), ${progressText(progress)}.`,