spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void>;

package/node_modules/@spexcode/spec-cli/dist/init.js

@@ -0,0 +1,284 @@
+import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, 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 { gitBinary, parseFrontmatter, readConfig, readJsonConfig, templateConfigPath } from '@spexcode/spec-core';
+import { resolveHarnessTargets, partitionHarnesses, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.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) {
+    const source = readFileSync(path, 'utf8');
+    return source.split('\n').slice(0, 4).includes(MANAGED_HOOK_HEADER);
+}
+function replaceHook(source, dest) {
+    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'];
+const presetRank = (name) => PRESET_TIERS.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, destDir, base, includeDir = () => true) {
+    if (!includeDir(srcDir))
+        return [];
+    const written = [];
+    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, includeDir));
+        }
+        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;
+}
+function seedableForEvents(dir, reachableEvents) {
+    const spec = join(dir, 'spec.md');
+    if (!existsSync(spec))
+        return true;
+    const { fm } = parseFrontmatter(readFileSync(spec, 'utf8'));
+    const values = (value) => Array.isArray(value) ? value : value ? [value] : [];
+    const surfaces = values(fm.surface).flatMap((value) => value.split(',')).map((value) => value.trim());
+    if (!surfaces.includes('hook'))
+        return true;
+    const events = values(fm.events).flatMap((value) => value.split(',')).map((value) => value.trim()).filter(Boolean);
+    return !events.length || events.some((event) => reachableEvents.has(event));
+}
+// 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) {
+    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) {
+    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, presetArg, harnessArg) {
+    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.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);
+    }
+    let selectedNativeEvents = null;
+    try {
+        const targets = resolveHarnessTargets(chosenHarnesses);
+        const native = partitionHarnesses(targets).selected;
+        if (native.length)
+            selectedNativeEvents = new Set(native.flatMap((h) => h.events));
+    }
+    catch (e) {
+        console.error(`spex init: ${e.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 includeSeedDir = (dir) => selectedNativeEvents === null || seedableForEvents(dir, selectedNativeEvents);
+        const planted = copyTreeNoClobber(join(TEMPLATES, 'spec'), specDest, targetDir, includeSeedDir);
+        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, includeSeedDir);
+            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.filter((m) => typeof m === 'string');
+    if (existsSync(cfgDest)) {
+        const cfg = (readJsonConfig(cfgDest) ?? {});
+        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(templateConfigPath) ?? {});
+        cfg.harnesses = chosenHarnesses;
+        cfg.mainBranch = adoptionMainBranch(targetDir);
+        if (nativeChosen.length && cfg.sessions?.launchers) {
+            cfg.sessions.launchers = Object.fromEntries(Object.entries(cfg.sessions.launchers).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 = [];
+        const refreshed = [];
+        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) => {
+            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.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/node_modules/@spexcode/spec-cli/dist/issues-cli.d.ts

@@ -0,0 +1,6 @@
+export declare function runIssues(args: string[]): Promise<number>;
+export declare function runIssueWrite(args: string[]): Promise<number>;
+export declare const ISSUE_WRITE_SUBS: Set<string>;
+export declare function runRemark(args: string[]): Promise<number>;
+export declare function runResolve(args: string[]): Promise<number>;
+export declare function runRetract(args: string[]): Promise<number>;

package/node_modules/@spexcode/spec-cli/dist/issues-cli.js

@@ -0,0 +1,334 @@
+import { readFileSync } from 'node:fs';
+import { closeIssue, findIssue, isRemark, mergedIssues, promote } from './issues.js';
+import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from '@spexcode/spec-forge/drivers';
+import { currentSession, issuesEnabled, resolveRemark, retractRemark } from './localIssues.js';
+import { summarizeDispatch, summarizeLoopIn } from './mentions.js';
+import { loadSpecsLite } from '@spexcode/spec-core';
+// @@@ 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, name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+const hasFlag = (args, name) => 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) {
+    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) {
+    const L = [];
+    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) {
+    // 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) {
+    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('@spexcode/spec-forge/cli');
+        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) {
+    const out = [];
+    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) {
+    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, name) => args.flatMap((a, i) => (a === `--${name}` ? [args[i + 1]] : [])).filter(Boolean);
+// 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) {
+    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 dispatched = summarizeDispatch(r.outcomes);
+            if (dispatched)
+                console.log(`  ${dispatched}`);
+            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}`);
+        const dispatched = summarizeDispatch(r.outcomes);
+        if (dispatched)
+            console.log(`  ${dispatched}`);
+        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) {
+    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 dispatched = summarizeDispatch(r.outcomes);
+        if (dispatched)
+            console.log(`  ${dispatched}`);
+        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) {
+    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) {
+    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;
+    }
+}