spexcode 0.6.2 → 0.6.5

package/spec-cli/src/init.ts

@@ -1,258 +0,0 @@
-import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
-import { join, resolve, relative, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execFileSync } from 'node:child_process'
-import { readConfig, readJsonConfig } from './layout.js'
-import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
-import { gitBinary } from './git.js'
-
-// this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
-// launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
-const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
-const TEMPLATES = join(pkgRoot, 'templates')
-const MANAGED_HOOK_HEADER = '# spexcode-managed-hook-v1'
-
-function isManagedHook(path: string): boolean {
-  const source = readFileSync(path, 'utf8')
-  return source.split('\n').slice(0, 4).includes(MANAGED_HOOK_HEADER)
-}
-
-function replaceHook(source: string, dest: string): void {
-  const temp = `${dest}.spexcode-${process.pid}`
-  try {
-    copyFileSync(source, temp)
-    chmodSync(temp, 0o755)
-    renameSync(temp, dest)
-  } finally {
-    rmSync(temp, { force: true })
-  }
-}
-
-// the cumulative preset chain, lean → cautious (see [[init-preset]]). `default` is the live `.plugins`
-// instance set (planted from templates/spec); a higher tier would be a SEPARATE package under
-// templates/presets/<tier>/ that seeding stacks ON TOP — a superset. No non-default tier ships today
-// (the `careful` package was retired); the chain mechanism stays for when one earns its keep.
-// Selection matters ONLY here at seed time; the running repo just
-// walks whatever `.plugins` ended up planted, so there is no launcher-side preset gate.
-const PRESET_TIERS = ['default'] as const
-const presetRank = (name: string): number => (PRESET_TIERS as readonly string[]).indexOf(name)
-
-// recursively copy srcDir -> destDir, NEVER overwriting an existing file. Returns the repo-relative
-// paths of files actually written (so the caller can report exactly what was planted vs already there).
-function copyTreeNoClobber(srcDir: string, destDir: string, base: string): string[] {
-  const written: string[] = []
-  mkdirSync(destDir, { recursive: true })
-  for (const e of readdirSync(srcDir, { withFileTypes: true })) {
-    const src = join(srcDir, e.name)
-    const dest = join(destDir, e.name)
-    if (e.isDirectory()) {
-      written.push(...copyTreeNoClobber(src, dest, base))
-    } else if (existsSync(dest)) {
-      // additive only — a pre-existing file is the user's, leave it untouched.
-      continue
-    } else {
-      copyFileSync(src, dest)
-      written.push(relative(base, dest))
-    }
-  }
-  return written
-}
-
-// resolve the target repo's git hooks dir the same way scripts/install-hooks.sh does — the COMMON dir's
-// hooks/ (shared across all worktrees). Returns null (with a loud reason) when <dir> isn't a git repo.
-function resolveHooksDir(dir: string): string | null {
-  try {
-    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'], // swallow git's own "fatal: not a git repository" — our warning is the signal
-    }).trim()
-    return join(common, 'hooks')
-  } catch {
-    return null
-  }
-}
-
-// Detect once, at adoption, while the root checkout still names the branch being adopted. Steady-state
-// layout never re-derives trunk identity from a mutable checkout (an ordinary `git switch node/x` must not
-// turn that feature branch into trunk).
-function adoptionMainBranch(dir: string): string {
-  try {
-    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
-    const branch = execFileSync(gitBinary(process.env), ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
-    if (branch) return branch
-  } catch { /* render the one product-level repair below */ }
-  const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
-  error.name = 'ConfigError'
-  throw error
-}
-
-export async function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void> {
-  const targetDir = resolve(targetArg ?? process.cwd())
-
-  // the preset the NEW adopter gets — `--preset <name>` wins, else an existing target spexcode.json's
-  // `preset` field, else the lean `default`. Validated loudly against the chain (an unknown name would
-  // otherwise seed silently). A non-default tier stacks its template package on top of the default set below.
-  const selected = (presetArg ?? '').trim() || (readConfig(targetDir).preset ?? '').trim() || 'default'
-  if (!(PRESET_TIERS as readonly string[]).includes(selected)) {
-    console.error(`spex init: unknown preset '${selected}'. Valid presets (cumulative, lean→cautious): ${PRESET_TIERS.join(', ')}.`)
-    process.exit(1)
-  }
-
-  // SpexCode is git-backed: git IS the version database and the hooks live in `.git`. A non-git target
-  // would leave a HALF-STATE — specs on disk but no version history, no hooks, no harness shims, no
-  // sessions. So fail LOUD before writing anything, rather than seeding debris and warning past it. We do
-  // NOT `git init` for them: creating a repo is a side effect beyond init's remit (a subdir, a dir not
-  // meant as a repo root), and `git init` is one deliberate command.
-  try {
-    execFileSync(gitBinary(process.env), ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
-  } catch {
-    console.error(`spex init: ${targetDir} is not a git repository. SpexCode is git-backed (git is the version database; the hooks live in .git). Run \`git init\` there first, then \`spex init\`.`)
-    process.exit(1)
-  }
-
-  // the harness DELIVERY TARGET set ([[harness-select]]) is a REQUIRED, explicit choice — `--harness <ids>`
-  // stamps it into spexcode.json; absent the flag, a pre-existing explicit `harnesses` field IS the choice.
-  // Neither → abort BEFORE writing anything: with many harnesses, a silent "deliver to all" would litter the
-  // adopter's tree (and global tool configs) with artifacts for harnesses they never installed. Legality
-  // (unknown ids, plugin exclusivity, empty set) fails loud here too, not as a soft materialize warning.
-  const flagRaw = (harnessArg ?? '').trim() ? parseHarnessFlag(harnessArg!.trim()) : null
-  const chosenHarnesses = flagRaw ?? readConfig(targetDir).harnesses ?? null
-  if (chosenHarnesses === null) {
-    console.error(`spex init: --harness is required — name the harness(es) this repo delivers into, e.g. \`spex init --harness claude\`. Known native ids: ${NATIVE_HARNESS_IDS.join(', ')} (comma-separate several; a plugin bundle: --harness plugin:<folder>). A pre-existing spexcode.json "harnesses" field also satisfies this.`)
-    process.exit(1)
-  }
-  try {
-    resolveHarnessTargets(chosenHarnesses)
-  } catch (e) {
-    console.error(`spex init: ${(e as Error).message}`)
-    process.exit(1)
-  }
-
-  if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true })
-  console.log(`spex init → ${targetDir}`)
-
-  // 1. seed the spec tree: templates/spec/* -> <dir>/.spec/* (an existing .spec aborts this phase loudly).
-  const specDest = join(targetDir, '.spec')
-  if (existsSync(specDest)) {
-    console.warn(`• .spec already exists at ${specDest} — skipping spec scaffold (won't overwrite an existing tree).`)
-  } else {
-    const planted = copyTreeNoClobber(join(TEMPLATES, 'spec'), specDest, targetDir)
-    console.log(`✓ seeded ${planted.length} spec file(s) under .spec/ (root 'project' node + default .plugins)`)
-    // 1a. stack the selected preset's package(s) ON TOP of the default set — cumulative, so every tier from
-    // just above `default` up to the selection is planted. Each lives under templates/presets/<tier>/ mirroring
-    // the default layout (its `.plugins/<plugin>` lands in the seeded project node's `.plugins`). See [[init-preset]].
-    for (let r = 1; r <= presetRank(selected); r++) {
-      const tier = PRESET_TIERS[r]
-      const pkg = join(TEMPLATES, 'presets', tier)
-      if (!existsSync(pkg)) { console.warn(`• preset '${tier}' has no package at ${pkg} — skipped.`); continue }
-      const added = copyTreeNoClobber(pkg, join(specDest, 'project'), targetDir)
-      console.log(`✓ seeded preset '${tier}' (${added.length} file(s)) into .plugins`)
-    }
-  }
-
-  // 1b. plant a starter spexcode.json (the lint/layout knob) carrying the CHOSEN `harnesses` set. The
-  // template ships launchers for every native harness; seeding keeps only the SELECTED ones (a launcher for
-  // a tool the adopter didn't pick is exactly the litter --harness exists to prevent) — a plugin-only
-  // selection keeps them all, since the bundle serves the HOST agent while dispatched sessions still need a
-  // launcher. The success message reports values read back from the planted file, never restated literals.
-  const cfgDest = join(targetDir, 'spexcode.json')
-  const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
-  if (existsSync(cfgDest)) {
-    const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
-    const stampedBranch = typeof cfg.mainBranch !== 'string' || !cfg.mainBranch.trim()
-    if (stampedBranch) cfg.mainBranch = adoptionMainBranch(targetDir)
-    if (flagRaw) cfg.harnesses = flagRaw
-    if (flagRaw || stampedBranch) {
-      writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
-      console.log(`✓ stamped ${[
-        flagRaw ? `"harnesses": ${JSON.stringify(flagRaw)}` : '',
-        stampedBranch ? `"mainBranch": ${JSON.stringify(cfg.mainBranch)}` : '',
-      ].filter(Boolean).join(' and ')} into the existing spexcode.json (other fields untouched)`)
-    } else {
-      console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
-    }
-  } else {
-    const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
-    cfg.harnesses = chosenHarnesses
-    cfg.mainBranch = adoptionMainBranch(targetDir)
-    if (nativeChosen.length && cfg.sessions?.launchers) {
-      cfg.sessions.launchers = Object.fromEntries(
-        Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
-      const names = Object.keys(cfg.sessions.launchers)
-      if (names.length) cfg.sessions.defaultLauncher = names[0]
-    }
-    writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
-    const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-    console.log(`✓ planted spexcode.json — mainBranch ${JSON.stringify(cfg.mainBranch)}, harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
-  }
-
-  // 2. install the git hooks. Unknown existing hooks are user-owned and stay byte-identical. An exact
-  // SpexCode snapshot is refreshed because a multi-hook protocol cannot mix old and new generations.
-  const hooksDir = resolveHooksDir(targetDir)
-  if (!hooksDir) {
-    console.warn(`• ${targetDir} is not a git repository — skipped hook install. Run \`git init\` there, then \`spex init\` again (or \`npm run hooks\`).`)
-  } else {
-    mkdirSync(hooksDir, { recursive: true })
-    const hooksSrc = join(TEMPLATES, 'hooks')
-    const installed: string[] = []
-    const refreshed: string[] = []
-    for (const e of readdirSync(hooksSrc, { withFileTypes: true })) {
-      if (!e.isFile()) continue
-      const source = join(hooksSrc, e.name)
-      const dest = join(hooksDir, e.name)
-      if (existsSync(dest)) {
-        if (readFileSync(dest).equals(readFileSync(source))) continue
-        if (isManagedHook(dest)) {
-          replaceHook(source, dest)
-          refreshed.push(e.name)
-        } else {
-          console.warn(`• user hook ${e.name} already exists in ${hooksDir} — left untouched.`)
-        }
-        continue
-      }
-      copyFileSync(source, dest)
-      chmodSync(dest, 0o755)
-      installed.push(e.name)
-    }
-    if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
-    if (refreshed.length) console.log(`✓ refreshed SpexCode hook snapshots (${refreshed.join(', ')}) → ${hooksDir}`)
-  }
-
-  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched harness works with zero further
-  // steps. Runs with cwd = the target so the loaders read the just-seeded
-  // .plugins. Idempotent — the planted git hooks (pre-commit/post-checkout/post-merge) keep it fresh
-  // thereafter on the git-native anchors ([[commit-surgery]]); no harness event ever triggers a materialize.
-  const prevCwd = process.cwd()
-  try {
-    process.chdir(targetDir)
-    const { materialize } = await import('./materialize.js')
-    const result = materialize(targetDir)
-    const display = (path: string) => {
-      const local = relative(targetDir, path)
-      return local && local !== '..' && !local.startsWith('../') && !local.startsWith('..\\') ? local : path
-    }
-    console.log(`✓ materialized harness artifacts (${result.planted.map((a) => `${a.kind}: ${display(a.path)}`).join(', ')})`)
-  } catch (e) {
-    console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
-  } finally {
-    process.chdir(prevCwd)
-  }
-
-  // 3. next steps — what the human must do to bring the instance to life. The governedRoots line reads the
-  // LIVE value (the planted starter's, or a pre-existing config's) so it can never drift from what's on disk.
-  const rootsNow = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-  console.log(`
-Next steps:
-  1. The seeded .spec/ tree and spexcode.json are project source of truth: add and commit them. Generated
-     harness artifacts are machine-local and can stay untracked.
-  2. Edit .spec/project/spec.md to describe YOUR project, then grow child nodes beneath it.
-  3. lint.governedRoots in spexcode.json (currently ${rootsNow}) names what \`spex spec lint\` governs —
-     ["."] governs the whole git-tracked tree (tests excluded); narrow it to explicit source roots
-     when you want a curated graph.
-  4. Start the backend and open the dashboard:
-       spex serve                       # http://localhost:8787
-  5. \`spex spec lint\` should report 0 errors. Coverage warnings are your adoption TODO (source files no
-     spec node claims yet). You're adopting SpexCode — the spec tree is now ground truth.
-  (On a fresh CLONE, re-run \`spex init\` — git never clones .git/hooks/, and the harness shims are
-   gitignored machine-local files that regenerate per-machine.)`)
-}

package/spec-cli/src/issues-cli.ts

@@ -1,276 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { closeIssue, createIssue, findIssue, isRemark, mergedIssues, promote, type ForgeSlice, type Issue } from './issues.js'
-import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from '../../spec-forge/src/drivers.js'
-import { currentSession, issuesEnabled, reply, resolveRemark, retractRemark } from './localIssues.js'
-import { summarizeLoopIn } from './mentions.js'
-import { loadSpecsLite } from './specs.js'
-
-// @@@ issues-cli - the `spex issue` / `spex remark` CLI surface: argv parsing, console output, exit codes.
-// It lives ABOVE the eval layer, which is the whole point. These handlers used to sit in `issues.ts` and
-// `localIssues.ts` — modules the eval package imports — and a CLI surface is by definition the topmost layer,
-// so hosting one down there gave those files two altitudes at once. That is what held the spec/eval package
-// cycle: the loop-in's candidate resolution needs eval knowledge, its only callers were these handlers, and
-// they could not reach eval from below it. Nothing here is new logic; it is the same surface at its own height.
-//
-// It is NOT merged into `cli.ts`: that file is the thin dispatch hub ([[cli-surface]]) whose eighty lazy
-// `await import(...)` sites keep one invocation from loading every verb's module. Moving 265 lines of verb
-// implementation there would have traded one two-altitude module for another. The hub gains one lazy line
-// pointing here instead.
-
-const fl = (args: string[], name: string): string | undefined => {
-  const i = args.indexOf(`--${name}`)
-  return i >= 0 ? args[i + 1] : undefined
-}
-const hasFlag = (args: string[], name: string) => args.includes(`--${name}`)
-
-// the CLI's live forge pull — `ls` and `show` own their freshness (a live driver read), degrading LOUDLY
-// to local-only (one stderr note) when the forge is unreachable: local reading never hostages on a network.
-async function liveForgeSlice(verb: string): Promise<ForgeSlice | null> {
-  try {
-    const host = resolveForgeHost()
-    const driver = forgeDriverFor(host)
-    if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
-    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
-    return { host: driver.host, state: { issues, prs } }
-  } catch (e) {
-    console.error(`spex issue ${verb}: forge unreachable — local only (${e instanceof Error ? e.message.split('\n')[0] : e})`)
-    return null
-  }
-}
-
-// the single-issue read behind `spex issue show` AND `GET /api/issues/:id` — find the thread in the SAME
-// merged, eval-remark-free read every issue surface consumes (never a second lookup path: an eval-remark
-// thread is not an issue, so `show` can't see one either). A local id needs no forge slice; a forge id
-// (`<host>#<n>`) reads from the caller-supplied slice (live pull on the CLI, resident cache on the server).
-
-function renderIssue(t: Issue): string {
-  const L: string[] = []
-  L.push(`${t.concern}  [${t.id}]`)
-  L.push(`  ${[t.store, t.status, t.nodes.length ? `re: ${t.nodes.join(', ')}` : '', t.by ? `by ${t.by}` : '', t.created].filter(Boolean).join('  ·  ')}`)
-  if (t.url) L.push(`  ${t.url}`)
-  if (t.evidence.length) L.push(`  evidence: ${t.evidence.join(', ')}`)
-  L.push('', t.body)
-  for (const r of t.replies) {
-    L.push('', `── ${isRemark(r) ? `remark ${t.id}#${r.rid}${r.resolved ? ` (resolved by ${r.resolvedBy})` : ' (unresolved)'}` : 'reply'}: ${r.by} @ ${r.at} ──`)
-    L.push(r.body)
-  }
-  return L.join('\n')
-}
-
-// `spex issue <verb>` — the ONE issue surface, a noun drawer ([[cli-surface]]). `ls` is THE read over
-// every store: the drain view a supervisor/human works from, `[--node id] [--store local|<host>] [--all]
-// [--json]`; `show <id>` is the single-thread detail (the same read GET /api/issues/:id serves). The
-// write verbs (open|reply — localIssues.ts) are store-routed (`open --store <host>` / a `<host>#<n>` id
-// go through the driver); `close` is the store-routed lifecycle verb (the SAME closeIssue the dashboard's
-// Close button calls); `promote` is the one cross-store verb; `links` is the read-only forge→spec trace
-// (spec-forge). The list imposes NO salience ranking — replies are a signal the drain WEIGHS by judgment,
-// never an automatic priority order. The forge slice is a LIVE pull that degrades loudly to local-only.
-// (`nudge` left this drawer for `spex internal nudge` — only the post-merge hook calls it; the old
-// on|off|status toggle verbs are gone — the switch is the `issues.enabled` settings key.)
-export async function runIssues(args: string[]): Promise<number> {
-  // the drawer's READ verbs (ls/show) surface a store failure exactly as the writes do
-  // ([[issues-store-rename]]'s both-exist teeth): one clean `spex issue: <message>` line + exit 1, never a
-  // raw stack — the message carries the repair, the stack is internals. The verbs that already catch with
-  // a more specific prefix (open/reply/close/promote) return before this guard ever sees their errors.
-  try { return await issueVerbs(args) }
-  catch (e) { console.error(`spex issue: ${e instanceof Error ? e.message : e}`); return 1 }
-}
-async function issueVerbs(args: string[]): Promise<number> {
-  if (ISSUE_WRITE_SUBS.has(args[0])) return runIssueWrite(args)
-  if (args[0] === 'on' || args[0] === 'off' || args[0] === 'status') {
-    // v0.3.0 signpost — report the new home, never run ([[cli-surface]]: a removed spelling only points).
-    console.error(`spex: \`spex issue ${args[0]}\` was removed in v0.3.0 — the switch is the \`issues.enabled\` key in spexcode.json (edit the JSON; \`spex guide settings\` documents it, \`spex doctor\` reports its state)`)
-    return 2
-  }
-  if (args[0] === 'show') {
-    const id = args[1]
-    if (!id || id.startsWith('--')) { console.error('usage: spex issue show <issue-id> [--json]   (a local id, or a forge id like github#12)'); return 2 }
-    const nodeIds = loadSpecsLite().map((s) => s.id)
-    const t = findIssue(id, id.includes('#') ? await liveForgeSlice('show') : null, nodeIds)
-    if (!t) { console.error(`spex issue show: no issue '${id}' (see \`spex issue ls --all\`)`); return 1 }
-    console.log(hasFlag(args, 'json') ? JSON.stringify(t, null, 2) : renderIssue(t))
-    return 0
-  }
-  if (args[0] === 'links') {
-    const { runIssueLinks } = await import('../../spec-forge/src/cli.js')
-    return runIssueLinks(args.slice(1))
-  }
-  if (args[0] === 'close') {
-    // the CLI leg of the ONE close verb ([[issues]] closeIssue — the same routing POST /api/issues/:id/close
-    // runs): a local id resolves the thread `landed`, a forge id (`<host>#<n>`) closes the remote issue
-    // through the driver. Lifecycle on the issue object, never node state.
-    const id = args[1]
-    if (!id || id.startsWith('--')) { console.error('usage: spex issue close <issue-id>   (a local id, or a forge id like github#12)'); return 2 }
-    try {
-      const r = await closeIssue(id)
-      console.log(r.store === 'local'
-        ? `closed '${id}' — local thread landed`
-        : `closed '${id}' on ${r.store}${r.url ? `  ${r.url}` : ''}`)
-      return 0
-    } catch (e) {
-      console.error(`spex issue close: ${e instanceof Error ? e.message : e}`)
-      return 1
-    }
-  }
-  if (args[0] === 'promote') {
-    const id = args[1]
-    if (!id || id.startsWith('--')) { console.error('usage: spex issue promote <local-issue-id>'); return 2 }
-    try {
-      const r = await promote(id)
-      console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread closed landed (permalink recorded in its reply trail)`)
-      return 0
-    } catch (e) {
-      console.error(`spex issue promote: ${e instanceof Error ? e.message : e}`)
-      return 1
-    }
-  }
-  if (args[0] !== 'ls') {
-    console.error(`spex issue: unknown verb '${args[0]}' — ls | show | open | reply | close | promote | links  (spex help issue)`)
-    return 2
-  }
-  args = args.slice(1)
-  const nodeIds = loadSpecsLite().map((s) => s.id)
-  const forge = await liveForgeSlice('ls')
-  let issues = mergedIssues(forge, nodeIds)
-  const node = fl(args, 'node')
-  const store = fl(args, 'store')
-  if (node) issues = issues.filter((p) => p.nodes.includes(node))
-  if (store) issues = issues.filter((p) => p.store === store)
-  if (!hasFlag(args, 'all')) issues = issues.filter((p) => p.status === 'open')
-  if (hasFlag(args, 'json')) { console.log(JSON.stringify(issues, null, 2)); return 0 }
-  if (!issues.length) { console.log(node ? `no issues for node '${node}'` : 'no open issues'); return 0 }
-  console.log(`issues — ${issues.length} ${hasFlag(args, 'all') ? 'total' : 'open'}${store ? ` in '${store}'` : ''}${node ? ` for '${node}'` : ''}\n`)
-  for (const p of issues) {
-    const tags = [p.store, p.status !== 'open' ? `[${p.status}]` : '', p.nodes.length ? `re: ${p.nodes.join(', ')}` : '', p.by ? `by ${p.by}` : ''].filter(Boolean).join('  ·  ')
-    console.log(`• ${p.concern}  [${p.id}]`)
-    console.log(`    ${tags}`)
-    if (p.replies.length) console.log(`    ${p.replies.length} reply(ies) in thread`)
-    if (p.url) console.log(`    ${p.url}`)
-  }
-  if (!issuesEnabled()) console.log('\n(the issues workflow is OFF — set `"issues": { "enabled": true }` in spexcode.json to re-enable writes/nudges)')
-  return 0
-}
-
-const VALUE_FLAGS = new Set(['--node', '--body', '--evidence', '--scenario', '--code-sha', '--store'])
-// bare positionals, skipping flags + their values.
-function bare(args: string[]): string[] {
-  const out: string[] = []
-  for (let i = 0; i < args.length; i++) {
-    const t = args[i]
-    if (t.startsWith('--')) { if (VALUE_FLAGS.has(t)) i++; continue }
-    out.push(t)
-  }
-  return out
-}
-// `--body -` reads stdin; `--body "text"` is literal; absent → undefined.
-function readBody(args: string[]): string | undefined {
-  const v = fl(args, 'body')
-  if (v === undefined) return undefined
-  return v === '-' ? readFileSync(0, 'utf8') : v
-}
-// a repeatable value flag: every `--<name> <value>` pair, in order.
-const repeated = (args: string[], name: string): string[] =>
-  args.flatMap((a, i) => (a === `--${name}` ? [args[i + 1]] : [])).filter(Boolean) as string[]
-
-// the local-issue WRITE verbs of the issue drawer (`spex issue <verb>`): open "<concern>" [--store local|<host>] [--node id…]
-// [--evidence hash…] [--body -|text], and the id-based reply. Store is a property of the issue,
-// never a second command — open and reply route by it (issues.ts createIssue/replyIssue).
-export async function runIssueWrite(args: string[]): Promise<number> {
-  const sub = args[0]
-  try {
-    if (sub === 'reply') {
-      const id = bare(args.slice(1))[0]
-      const body = readBody(args)
-      if (!id || !body) { console.error('usage: spex issue reply <issue-id> --body -|<text> [--evidence <hash>…]'); return 2 }
-      // the ONE store-routed reply verb ([[issues]]): a forge id posts a real comment through the driver,
-      // a local id commits to the store — the same command either way (dynamic import: no static cycle).
-      const r = await (await import('./loop-in.js')).replyIssueWithLoopIn(id, body, { evidence: repeated(args, 'evidence') })
-      console.log(r.store === 'local'
-        ? `replied to '${id}' — ${r.replies?.length} post(s) in thread`
-        : `commented on '${id}' — ${r.url}`)
-      const s = summarizeLoopIn(r.loopIn)
-      if (s) console.log(`  ${s}`)
-      return 0
-    }
-    // `open`: start a new issue — STORE-ROUTED through the one creation port ([[issues]] createIssue, the
-    // same routine POST /api/issues runs): default local commits to the trunk store; `--store <host>`
-    // creates the real forge issue through that store's driver (no promote round-trip when the concern is
-    // born forge-visible). The concern is the bare positional(s) after the sub.
-    const concern = sub === 'open' ? bare(args.slice(1)).join(' ').trim() : ''
-    if (!concern) {
-      console.error('usage: spex issue open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]\n       spex issue reply|close|promote <issue-id> …')
-      return 2
-    }
-    const r = await (await import('./issues.js')).createIssue(concern, {
-      store: fl(args, 'store'),
-      nodes: repeated(args, 'node'),
-      body: readBody(args),
-      evidence: repeated(args, 'evidence'),
-    })
-    const re = r.nodes.length ? ` (re: ${r.nodes.join(', ')})` : ''
-    console.log(r.store === 'local'
-      ? `opened '${r.id}'${re} — committed to the local issue store; read it with \`spex issue ls\``
-      : `opened '${r.id}' on ${r.store}${re} — ${r.url}`)
-    return 0
-  } catch (e) {
-    console.error(`spex issue: ${e instanceof Error ? e.message : e}`)
-    return 1
-  }
-}
-
-// the first positionals runIssueWrite handles — the issue drawer routes these to it. Exported so the
-// router and the runner can never drift. (`nudge` is not here: it is machine plumbing, called only by the
-// post-merge hook as `spex internal nudge`; the on|off|status toggle verbs died in v0.3.0 — the switch is
-// the `issues.enabled` settings key.)
-export const ISSUE_WRITE_SUBS = new Set(['open', 'reply'])
-
-// ── remark CLI ([[remark-substrate]]) — CLI-first: the whole author→resolve→retract loop, no server needed ──
-// `spex remark add <issue-id | <node> --scenario <name>> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]`
-// host = a local issue id, OR a <node> with --scenario <name>. Records targetCodeSha (default: worktree HEAD).
-export async function runRemark(args: string[]): Promise<number> {
-  try {
-    const scenario = fl(args, 'scenario')
-    const positional = bare(args)[0]
-    const body = readBody(args)
-    if (!positional || !body) {
-      console.error('usage: spex remark add <issue-id | node --scenario name> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]')
-      return 2
-    }
-    // THE FLAG DECIDES THE PARSE ([[cli-surface]] §1): `--scenario` present ⇒ the positional is a NODE id
-    // (the remark pins to that node's scenario track); absent ⇒ it is an ISSUE id. Never type-sniffed —
-    // a node id and an issue id are both bare slugs, so any "looks like" guess would misroute; the flag
-    // is the one unambiguous discriminator, and a wrong host fails loud downstream (unknown issue/node).
-    const host = scenario ? { node: positional, scenario } : { issue: positional }
-    const r = await (await import('./loop-in.js')).remarkWithLoopIn(host, body, { codeSha: fl(args, 'code-sha'), evidence: repeated(args, 'evidence') })
-    console.log(`remark ${r.ref}  (against ${r.codeSha.slice(0, 7) || 'HEAD'}) — read it with \`spex issue ls --all\``)
-    const s = summarizeLoopIn(r.loopIn)
-    if (s) console.log(`  ${s}`)
-    return 0
-  } catch (e) {
-    console.error(`spex remark add: ${e instanceof Error ? e.message : e}`)
-    return 1
-  }
-}
-
-// `spex remark resolve <remark-ref>` — flip resolved=true (agent-only, never the author, monotonic — see resolveRemark).
-export async function runResolve(args: string[]): Promise<number> {
-  const ref = bare(args)[0]
-  if (!ref) { console.error('usage: spex remark resolve <remark-ref>   (the <thread-id>#<rid> `spex remark add` printed)'); return 2 }
-  try {
-    const by = currentSession()
-    resolveRemark(ref, by)
-    console.log(`resolved remark ${ref} — by ${by}`)
-    return 0
-  } catch (e) { console.error(`spex remark resolve: ${e instanceof Error ? e.message : e}`); return 1 }
-}
-
-// `spex remark retract <remark-ref>` — the author withdraws their OWN remark, removing it (author-only — see retractRemark).
-export async function runRetract(args: string[]): Promise<number> {
-  const ref = bare(args)[0]
-  if (!ref) { console.error('usage: spex remark retract <remark-ref>'); return 2 }
-  try {
-    retractRemark(ref, currentSession())
-    console.log(`retracted remark ${ref}`)
-    return 0
-  } catch (e) { console.error(`spex remark retract: ${e instanceof Error ? e.message : e}`); return 1 }
-}